|
|
@@ -35,8 +35,8 @@ Time-based `/loop` or scheduled execution is a third policy and is not implement
|
|
|
|
|
|
| Package | Repository category | Owned structures and verbs |
|
|
|
|---|---|---|
|
|
|
-| `@deepseek-ai/dsh-goal` | `packages/goal/goal/`, domain service | Owns `GoalId`, compare-and-set `GoalRef`, `GoalSnapshot`, `GoalPhase`, process-local `GoalActivation`, replay folding, and `get`, `create`, `edit`, `pause`, `resume`, `complete`, `block`, `markUsageLimited`, `markBudgetLimited`, `clear`, and `disarm` verbs. |
|
|
|
-| `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`, model-facing consumer | Registers exclusive `get_goal`, `create_goal`, and `update_goal`; authenticates live turn provenance and narrows autonomous-round authority to completion or blocking reports. |
|
|
|
+| `@deepseek-ai/dsh-goal` | `packages/goal/goal/`, domain service | Owns `GoalId`, compare-and-set `GoalRef`, `GoalSnapshot`, four-state `GoalPhase`, structured `GoalBlockReason`, process-local `GoalActivation`, replay folding, and `get`, `create`, `edit`, `pause`, `resume`, `complete`, `block`, `clear`, and `disarm` verbs. |
|
|
|
+| `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`, model-facing consumer | Registers exclusive `get_goal`, `create_goal`, and `update_goal`; authenticates live turn provenance and narrows autonomous-round authority to completion or blocking reports with machine-routable reason codes. |
|
|
|
| `@deepseek-ai/dsh-goal-session` | `packages/goal/goal-session/`, continuation policy | Reserves, fences, admits, attributes, settles, cancels, and quiescently drains same-session goal rounds without importing the concrete loop. |
|
|
|
| `@deepseek-ai/dsh-commands` | `packages/ui/commands/`, UI registry | Owns `CommandDefinition`, discovery, scoped registration, direct dispatch, `CommandResult`, and request cancellation for human-only commands. |
|
|
|
| `@deepseek-ai/dsh-command-goal` | `packages/goal/command-goal/`, human-command producer | Registers `/goal` status, creation, edit, pause, resume, and clear over the goal domain for TUI and ACP. |
|
|
|
@@ -48,7 +48,7 @@ The detailed contracts live in the [goal-domain](2026-07-19-persisted-same-sessi
|
|
|
|
|
|
One session has at most one current goal. Every non-clear mutation appends a full, versioned, model-visible goal snapshot through `Agent.inject()`; clear appends a revisioned tombstone. The session log is the only durable source of truth, so normal persistence, resume, compaction semantics, and `SessionStore.fork()` carry the goal without a second database or an artificial cancellation record.
|
|
|
|
|
|
-Durable phases are `active`, `paused`, `blocked`, `usage-limited`, `budget-limited`, and `complete`. Separate activation is `armed` or `disarmed` and is never persisted. Creation and explicit resume arm a goal; stop transitions, session start, fork replay, driver replacement, and driver teardown leave it disarmed.
|
|
|
+Durable phases are only `active`, `paused`, `blocked`, and `complete`. A blocked goal carries a required `GoalBlockReason` with a stable lower-kebab-case `code` and a non-empty human-readable `message`; usage limits, round exhaustion, model failures, and policy rejection are reason codes rather than extra lifecycle phases. Separate activation is `armed` or `disarmed` and is never persisted. Creation and explicit resume arm a goal; stop transitions, session start, fork replay, driver replacement, and driver teardown leave it disarmed.
|
|
|
|
|
|
This separation makes session restoration observable and unsurprising. Reopening a session never starts goal work by itself. A later human prompt such as “continue”, “resume the goal”, or an equivalent request in any language gives the runtime-root model a new turn in which it may read the goal and call `update_goal(..., action: 'resume')`. `/goal resume` is the direct human-command path. The runtime authenticates that the request came from a live direct-human turn; prompt policy lets the model interpret whether the wording semantically authorizes creation or resumption.
|
|
|
|
|
|
@@ -62,7 +62,7 @@ The goal-round driver owns at most one pending reservation per exact live agent.
|
|
|
|
|
|
Only the durable goal-sourced `user/message` charges a round. Stale reservations become rejected zero-step turns without consuming the cap. A concurrent goal revision wins over settlement from an older round.
|
|
|
|
|
|
-Normal turn completion schedules another round only while the goal remains active, armed, and below its cap. Cancellation pauses; rate limiting records `usage-limited`; cap exhaustion records `budget-limited`; other errors, max-token stops, policy rejections, and unknown terminal results block for inspection. The driver never invents an automatic retry after an abnormal outcome. A human can later authorize resume through ordinary language or `/goal resume`.
|
|
|
+Normal turn completion schedules another round only while the goal remains active, armed, and below its cap. Cancellation pauses. Rate limiting blocks with code `usage-limited`; cap exhaustion blocks with `round-limit`; queue failure uses `queue-failed`; turn errors, max-token stops, policy rejection, and unknown terminal results use their corresponding blocker codes. The driver never invents an automatic retry after an abnormal outcome. A human can later authorize resume through ordinary language or `/goal resume`.
|
|
|
|
|
|
### Human and model surfaces
|
|
|
|
|
|
@@ -70,7 +70,7 @@ The human UX follows the compact Codex shape in the [public OpenAI Codex TUI dis
|
|
|
|
|
|
The model receives only `get_goal`, `create_goal`, and `update_goal`. It may create a goal when a direct human request clearly asks for substantial multi-round work, and it may infer that intent in any language. It must not turn routine one-turn work into a goal. Direct-human provenance is enforced in code; semantic interpretation remains model judgment. An autonomous goal round may report `complete` or `blocked` for the exact current goal round but cannot edit, pause, resume, or replace the human objective.
|
|
|
|
|
|
-TUI and ACP mount the shared command registry and complete goal stack by default and expose `/goal` through one producer. The UI-less agent spine is opt-in so one-shot callers do not silently become multi-round operations. Line-oriented stdio does not consume the command plane; its ordinary human text can still authorize model goal tools when that stack is mounted.
|
|
|
+TUI and ACP mount the shared command registry and complete goal stack by default and expose `/goal` through one producer. Every effective registered command is discoverable and invocable through every composed command adapter; a plugin incompatible with an application omits its command producer from that composition rather than relying on registry-level surface masks. The UI-less agent spine is opt-in so one-shot callers do not silently become multi-round operations. Line-oriented stdio does not consume the command plane; its ordinary human text can still authorize model goal tools when that stack is mounted.
|
|
|
|
|
|
### Fresh-agent Ralph execution
|
|
|
|
|
|
@@ -94,7 +94,7 @@ External products are comparators, not compatibility targets. The local source s
|
|
|
|
|
|
### Verification
|
|
|
|
|
|
-The six owning Agent Notes record unit, integration, process, snapshot, cancellation, replay, and built-runtime coverage. The stack exercises strict goal-record folding, compare-and-set races, session fork inheritance, disarmed restoration, natural-language direct-human authority, configurable caps and blocked thresholds, exact goal-round attribution, command discovery in TUI/ACP, and ACP transcript isolation. Ralph's keyless real stack—worker-thread engine, spawn provider, structured-output runtime, and agent loop—covers distinct unseeded children, exact bounded handoff, completion, blocker and round-limit outcomes, malformed and oversized reports, ordinary child failure with the last good handoff, one phase event, and cancellation to child quiescence. Package sources remain under the repository's per-file 100% coverage gate, and the assembled applications are pinned by keyless replay snapshots and built-binary tests.
|
|
|
+The six owning Agent Notes record unit, integration, process, snapshot, cancellation, replay, and built-runtime coverage. The stack exercises strict goal-record folding, compare-and-set races, session fork inheritance, disarmed restoration, natural-language direct-human authority, configurable caps and blocked thresholds, exact goal-round attribution, adapter-wide command discovery, and transcript isolation. Shipped keyless snapshots cover model goal creation/inspection through the headless app, multi-round same-session lifecycle and cancellation through ACP, direct `/goal` status without a model turn, and two real Ralph rounds through the headless app. The Ralph snapshot boots the worker-thread engine, spawn provider, structured-output runtime, and agent loop, then inspects distinct unseeded child logs and exact one-way bounded handoff while pinning the parent stream. Focused real-stack tests additionally cover completion, blocker and round-limit outcomes, malformed and oversized reports, ordinary child failure with the last good handoff, one phase event, and cancellation to child quiescence. Package sources remain under the repository's per-file 100% coverage gate, and built-binary tests cover installed-artifact resolution. The implementation experience is recorded in the root testing policy: every non-trivial model- or human-visible change must carry a real-example keyless snapshot in the same PR rather than relying on package or echo-agent coverage.
|
|
|
|
|
|
## Alternatives considered
|
|
|
|
Tianyi Cui