GooDAnDReaDY/dsh-goal

---

⚡ Overview & The Problem

Complex engineering tasks require multi-step autonomy: decomposing high-level objectives into sequential milestones, executing iterations without requiring manual user re-prompting, and maintaining clear visibility into task progress.

Without an autonomous tracking framework, agents can lose context across turns, stall in passive loops, or fail to notify users when complex workflows stall.

@goodandready/dsh-goal introduces Goal Mode to DeepSeek Harness:

• 💡 Live Steering & Nudge (Added in v0.2.0): Dynamically clarify, amend, or guide the agent's active objective on the fly without aborting the loop.
• 🔔 Native Browser Notifications (Added in v0.2.0): Zero-dependency desktop push notifications via HTML5 Notification API when long-running goals complete or require attention.
• 📑 10 Quick Launch Presets (Added in v0.2.0): Ready-to-use engineering prompt chips (Fix Bug, Refactor YAGNI, Tests & Coverage, Code Review, Security Audit, New Feature, Docs, Upgrade Deps, Dead Code Cleanup, Performance).
• 🛡️ Tool-Failure Breaker (Added in v0.2.0): Configurable consecutive tool error limit (consecutiveToolFailureLimit, default: 3) to halt loops upon repetitive tool crashes and prevent token burn.
• 📌 Git Checkpoint Snapshot (Added in v0.2.0): Automatically captures start commit hash (git rev-parse --short HEAD) with 1-click git diff / rollback command in details modal.
• 🐙 GitHub & Gitea PR Comment Export (Added in v0.2.0): One-click formatted comment generator with collapsible <details><summary> milestone cards and token telemetry.
• 🎯 Sticky Top Goal Banner: Pinned header over composer dock with live elapsed timer (• 2s, • 1m 45s), real-time status badge (RUNNING, PAUSED, COMPLETED), active goal title, and control actions.
• ⏸️ Play / Pause / Resume / Cancel: Instantly pause the autonomous loop or resume execution on demand via buttons or /goal command.
• 📋 Milestone Breakdown & ETA: Interactive checklist showing sub-tasks, completion status (pending, in_progress, completed, failed), progress bar, and dynamic completion ETA.
• 🌐 Multi-Language Auto-Detection (Added in v0.1.9): Prompt injection, autonomous follow-ups, and UI badges automatically follow the user's input language (English by default, Chinese, or Russian when entered in Cyrillic).
• 🔘 Quick Launch Button (Added in v0.1.8): Fast goal launcher docked above the message input with instant objective prompt modal. Toggleable in settings.
• 📊 Token Usage Tracking & Markdown Export (Added in v0.1.7): Accumulated prompt, completion, and total tokens tracked per session with one-click Markdown summary export.
• 🤖 Autonomous Agent Contract: Provides goal_set_milestones, goal_update_progress, and goal_finish tools directly to the agent.
• 🔄 Core DSH Goal Tools Interception (Added in v0.1.10): Seamless drop-in compatibility for models calling built-in DSH goal tools (update_goal, get_goal, create_goal). Intercepts actions (complete, pause, resume, edit, blocked), bypasses rigid authority restrictions that caused crashes (complete and blocked require a direct human turn), and routes all state updates directly to GoalEngine.
• 🛡️ Safety Guardrails: Configurable maxIterations safety limit and Smart Progress Guard to catch and pause idle turns without progress.
• 🔔 Web Audio Chimes: Pleasant synthesized audio feedback on goal completion or failure via Web Audio API.

---

🏛️ Architecture

graph LR
    subgraph UserInterface ["User Interface & Interaction"]
        Cmd["Slash Command: /goal <objective>"]
        Dock["Sticky Goal Banner (conversation.input.dock)"]
        Modal["Goal Details & Milestone Modal"]
        QuickLaunch["Quick Launch Goal Button"]
    end

    subgraph GoalEngineCore ["Goal Engine Core (lib/goal-engine.js)"]
        State["State Manager (IDLE, RUNNING, PAUSED, COMPLETED)"]
        Milestones["Milestone Tracker & ETA Calculation"]
        DiskStore["Persistence Store (goal-state.json)"]
        LangDetector["detectLanguage (en, zh, ru)"]
    end

    subgraph AutonomousLoop ["Autonomous Drive & Turn Coordinator (lib/index.js)"]
        TurnHook["ctx.on('turn/end') AutoDrive"]
        Guard["Smart Progress Guard & Iteration Limiter"]
        PromptInject["getStatePromptInjection"]
    end

    subgraph AgentTools ["Cordis Registered Tools"]
        ToolSet["goal_set_milestones"]
        ToolProgress["goal_update_progress"]
        ToolFinish["goal_finish"]
    end

    Cmd --> GoalEngineCore
    Dock --> GoalEngineCore
    QuickLaunch --> GoalEngineCore
    GoalEngineCore --> DiskStore
    GoalEngineCore --> AutonomousLoop
    AutonomousLoop --> PromptInject
    GoalEngineCore --> Modal
    AgentTools --> GoalEngineCore
    AutonomousLoop --> Guard

---

✨ Features & Module Breakdown

1. lib/goal-engine.js — State Engine

Zero external dependency core managing session goals, milestone states, elapsed time calculations, ETA forecasts, token accumulators, and crash recovery hydration.

• Auto Language Detection: Automatically analyzes goal title and parameters (detectLanguage) to select English (en), Chinese (zh), or Russian (ru).
• ETA Estimator: Predicts remaining time based on average milestone velocity: $$\text{ETA} = \frac{\text{elapsed}}{\text{completedMilestones}} \times \text{remainingMilestones}$$
• Low-Latency State Serialization: Synchronous debounced atomic file persistence to prevent data loss on crashes.

2. lib/command-handler.js — Slash Commands

Handles /goal commands and subcommands:

• /goal <objective>: Starts a new autonomous goal.
• /goal pause: Pauses current goal and halts agent turn.
• /goal resume: Resumes execution and triggers agent continuation.
• /goal clear: Resets session goal to IDLE.
• /goal: Shows status, elapsed time, ETA, iterations, tokens, and active milestones.

3. lib/index.js — DSH Cordis Lifecycle Coordinator

• Registers REST API endpoints (GET /dsh-goal/state, POST /dsh-goal/action, GET /dsh-goal/events SSE stream).
• Subscribes to turn/end for zero-latency turn-to-turn auto-drive using setImmediate.
• Listens to approval/asked to automatically pause goal when operator confirmation is needed.
• Registers agent tools: goal_set_milestones, goal_update_progress, goal_finish.
• Seamlessly shadows core DSH goal tools: update_goal, get_goal, create_goal with zero collision and full GOAL_OUTPUT schema compliance.

4. lib/client.js — Frontend Web UI

• Sticky Top Banner: Mounts via slot conversation.input.dock with live timer, status badge, pause/resume, and details button.
• Goal Details Modal: Full milestone list, progress bar, token statistics, and 📋 Markdown Report Copy.
• Quick Launch Button: Floating launcher for rapid goal formulation without typing slash commands.
• Plugin Settings Card: Schemastery-backed settings UI registered via settings.plugin.item.

5. Two-Phase Goal Execution: Plan Mode ⇄ Act Mode (#162)

6. Acceptance Gate & Critic Verification (#163)

• Automated Phase Verification: Attach an optional verificationCommand (e.g. npm test, pytest, cargo test) to any milestone.

• Failure Blocking & Diagnostic Feedback: When the agent attempts to complete a milestone via goal_milestones action: 'complete' or goal_update_progress status: 'completed', the command executes inside confined safeCwd. If tests fail (exitCode !== 0), completion is blocked, the milestone remains open, and diagnostic failure output is returned as actionable feedback to the agent.

• Atomic Completion & Snapshots: Git checkpoint snapshotting and issue checklist synchronization only trigger once the verification command passes with exit code 0.

• UI Visual Badges: Visual indicator 🛡️ <command> and failure alerts rendered in the Goal Details modal.

• Plan Mode (Read-Only Planning Phase): The agent explores the codebase, searches the web, and decomposes tasks into structured milestones and checklists. All file mutating tools (write_to_file, replace_file_content, mutating shell commands) are strictly blocked by lib/tool-guard.js.

• Act Mode (Implementation Phase): The operator reviews and approves the plan directly via the banner or details modal with «Approve & Execute», unlocking mutating capabilities and resuming the agent.

• REST API & Quick Launch: Toggle modes on demand via POST /dsh-goal/action (set_mode, approve_plan), or select initial mode directly in the Quick Launch dialog.

---

📦 Installation

dsh plugin --profile web add @goodandready/dsh-goal

Restart your DeepSeek Harness instance and refresh the browser.

---

💬 Usage & Quick Start

1. Start a Goal via Chat

Simply enter the /goal slash command:

/goal Refactor authentication middleware and cover with unit tests

The agent will immediately:

1. Establish a structured milestone plan via goal_set_milestones.
2. Advance through milestones, marking each in_progress and completed via goal_update_progress.
3. Conclude with a full summary via goal_finish.

2. Quick Launch Button

Click the Start Goal button directly above the message input box, type your objective, and click Start Goal.

3. REST API Control

Control goals programmatically via HTTP:

# Start a goal
curl -X POST http://localhost:3080/dsh-goal/action \
  -H "Content-Type: application/json" \
  -d '{"action":"start","title":"Implement automated backup pipeline"}'

# Pause
curl -X POST http://localhost:3080/dsh-goal/action \
  -H "Content-Type: application/json" \
  -d '{"action":"pause"}'

# Resume
curl -X POST http://localhost:3080/dsh-goal/action \
  -H "Content-Type: application/json" \
  -d '{"action":"resume"}'

# Inspect live state
curl http://localhost:3080/dsh-goal/state

---

⚙️ Configuration Reference (settings.yaml)

Configure settings in settings.yaml or through the Settings → Plugins → Goal Mode UI card:

dsh-goal:
  maxIterations: 25
  autoDrive: true
  enableSound: true
  showQuickLaunchButton: true
  consecutiveToolFailureLimit: 3
  enableBrowserNotifications: true
  maxTokenBudget: 0
  budgetWarningThreshold: 80
  autoCheckpointOnMilestone: false

Parameter	Type	Default	Description
maxIterations	number	25	Safety limit: maximum autonomous turns per goal
autoDrive	boolean	true	Keep the autonomous agent loop running between turns
enableSound	boolean	true	Play audio chime when a goal completes or fails
showQuickLaunchButton	boolean	true	Show the quick launch goal button above the composer dock
consecutiveToolFailureLimit	number	3	Auto-pause goal if N consecutive turns hit tool execution errors (0 to disable)
enableBrowserNotifications	boolean	true	Show native desktop push notifications on goal completion or failure
maxTokenBudget	number	0	Safety token ceiling (0 = disabled); triggers soft-pause when exceeded
budgetWarningThreshold	number	80	Percentage of budget consumed before warning model to wrap up
autoCheckpointOnMilestone	boolean	false	Automatically create git snapshot commits upon milestone completion

---

🧪 Testing

Run unit and integration tests:

npm test

---

---

📦 Release Notes

v0.2.6

• Token Budget Guard: Safety ceiling with proactive model guidance at threshold (default 80%) and soft pause (PAUSED_BUDGET_EXCEEDED) with 1-click +50k extension.
• Sub-milestones & Checklists: Granular sub-tasks per milestone (checklist: [{ text, done }]) with real-time UI toggling and model prompt synchronization.
• Auto Git Checkpoints: Optional automatic git snapshotting upon milestone completion with one-click rollback in the details modal.
• Run Artifact Export: One-click export of structured execution runs to .dsh/goals/<timestamp>-<slug>.md (with .dsh/ git-ignored).
• Compact Dock Mode: Minimizable dock banner switching to sleek status pill, state persisted in localStorage.

v0.2.3

• Auto-Updater: Integrated one-click update API endpoint at /api/dsh-goal/update with fail-closed origin checks.
• Modular Architecture: Decomposed server codebase into focused submodules (<600 lines each) for routes, tools, store, reports, and updater.
• Strict i18n Separation: Purged hardcoded internal Russian strings/branches from lib/*.js; canonical English and Chinese core with Russian provided via @goodandready/dsh-russian-lang.
• Reliability & Resilience: Eliminated all empty catch blocks, added contextual logging on deferred tool completions, and prune dead SSE streams on error.
• Design System Fidelity: Replaced foreign CSS classes and hardcoded RGBA colors with native DSH theme design tokens (--dsw-alias-*).
• Settings Scope Protection: Resolved null/loading status handling in the settings card to prevent false ready state.

📄 License

MIT © GooDAnDReaDY