@stackstackstack/dsh-command-goal 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/goal/command-goal/README.md
+README.md: 504c0034e1a117a144221400bcc69d5c0fea49f3
+README.zh.md: eac4cfda3d951d4404baf86b76ebb9f0d6aa5cfd

package/README.md

@@ -0,0 +1,58 @@
+# @stackstackstack/dsh-command-goal
+
+English | [中文](README.zh.md)
+
+Human-facing `/goal` control over [`ctx.goals`](../goal/README.md). The plugin registers one global command through [`ctx.commands`](../../interaction/commands/README.md), so every composed command adapter discovers and executes it without a model turn. The [human goal-command Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md) owns the UX and composition decisions.
+
+## Command contract
+
+| Input | Result |
+|---|---|
+| `/goal` | Show the current objective, durable phase, round count/cap, process-local activation, and valid next commands; a blocked goal also shows its policy code and explanation, while no goal shows usage. |
+| `/goal <objective>` | Create and arm a goal, or replace a completed goal with a fresh identity. An unfinished goal is never replaced without an explicit clear. |
+| `/goal edit <objective>` | Edit the current objective without changing its phase or activation. Editing a completed goal creates a fresh active goal. |
+| `/goal pause` | Pause an active goal and disarm continuation. |
+| `/goal resume` | Resume a stopped goal or rearm an active goal after session resume/fork, subject to its remaining round cap. |
+| `/goal clear` | Clear the current pointer while retaining its durable history and tombstone. |
+
+Control words are case-insensitive only when they occupy the complete input. Every other non-empty suffix is an objective, so `/goal pause after verification` creates that literal objective. The goal domain trims and validates objectives. Because the generic command plane has no modal editor or confirmation primitive, `edit` takes its replacement inline and an unfinished replacement returns a direct error instructing the user to edit or clear.
+
+Expected domain rejections become stable direct command errors without exposing branded ids or revisions. Unexpected implementation failures still reject dispatch so adapters can report them as command failures. Generic command text and output remain live UI state; `dsh-goal` persists every accepted mutation through its own durable `goal/change` event.
+
+## Composition
+
+The producer injects `commands` and `goals`. A custom app mounts their owners plus this plugin; automatic continuation remains an independent choice:
+
+```yaml
+- id: commands
+  name: '@stackstackstack/dsh-commands'
+- id: goal
+  name: '@stackstackstack/dsh-goal'
+- id: command-goal
+  name: '@stackstackstack/dsh-command-goal'
+```
+
+The shipped `dsh` base enables the persisted-goal stack and this command; the Web client provides its interactive adapter. The ACP automation app enables the domain and model tools without a command adapter; `goals: false` removes that stack. The UI-less `agent-spine-demo` requires an explicit `goals: {}` so headless one-shot callers do not silently change from one physical turn to a multi-round operation.
+
+## Model Experience
+
+### Human `/goal` control
+
+#### What the model sees
+
+The slash input, mutation, and direct status/error output are absent from model requests. The goal domain records the mutation as `goal/change`; an enabled same-session driver may expose the resulting state in a later continuation prompt. Presentation text is never logged.
+
+#### Token effect
+
+Reading status, mutating a goal, or receiving a direct command error adds no model tokens. An enabled same-session driver may add later goal-round prompts.
+
+#### KV Cache effect
+
+Command discovery, mutations, and direct output do not affect the cache. Later continuation prompts follow the driver's ordinary request history.
+
+## Known Limitations and Deferred Work
+
+- **Plain-text interaction only** — the generic command registry has no modal edit form or replacement-confirmation callback; inline edit and explicit clear keep destructive intent deterministic across adapters.
+- **No per-command round-cap argument** — `defaultMaxGoalRounds` remains deployment config, while a direct human request may ask the model to edit `max_goal_rounds` through the separately authorized goal tool.
+- **No continuous status widget** — bare `/goal` is the portable observation API; adapter-specific badges and reconnectable command output remain future UI work.
+- **Web command adapter only in the shipped apps** — headless, ACP automation, and JSON-RPC adapters do not consume `ctx.commands`. Ordinary prompts can still authorize model-facing goal tools when those are composed.

package/README.zh.md

@@ -0,0 +1,58 @@
+# @stackstackstack/dsh-command-goal
+
+[English](README.md) | 中文
+
+面向用户的 `/goal` 控制，基于 [`ctx.goals`](../goal/README.md) 实现。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。[用户 goal 命令 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md) 负责用户体验与组合决策。
+
+## 命令约定
+
+| 输入 | 结果 |
+|---|---|
+| `/goal` | 显示当前目标、持久 phase、Round 计数／上限、进程本地续行启用状态与有效的下一步命令；被阻塞的 goal 还会显示策略代码和说明，没有 goal 时则显示用法。 |
+| `/goal <objective>` | 创建 goal 并启用续行，或用全新身份替换已完成 goal。未完成 goal 绝不会在没有显式 clear 的情况下被替换。 |
+| `/goal edit <objective>` | 编辑当前目标，不改变其 phase 或续行启用状态。编辑已完成 goal 会创建新的 active goal。 |
+| `/goal pause` | 暂停 active goal，并停用续行。 |
+| `/goal resume` | 恢复已停止 goal，或在会话 resume／fork 后为 active goal 重新启用续行；仍受剩余 Round 上限约束。 |
+| `/goal clear` | 清除当前指针，同时保留其持久历史和 tombstone。 |
+
+只有控制词占据完整输入时才不区分大小写。其他任何非空后缀都属于目标，因此 `/goal pause after verification` 会创建该字面目标。goal 领域会去除目标首尾空白并进行验证。由于通用命令平面没有模态编辑器或确认原语，`edit` 会内联接收替换内容；若试图替换未完成的 goal，则直接返回错误，提示用户执行 edit 或 clear。
+
+可预期的领域拒绝会变成稳定的直接命令错误，不公开带品牌类型的 id 或 revision。意外实现失败仍会 reject 分发，使适配器能将其报告为命令失败。通用命令文本和输出仍属于实时 UI 状态；`dsh-goal` 通过自有的持久 `goal/change` 事件记录每项已接受变更。
+
+## 组合
+
+生产方注入 `commands` 和 `goals`。自定义应用会挂载它们的所有者与此插件；自动续行仍是独立选择：
+
+```yaml
+- id: commands
+  name: '@stackstackstack/dsh-commands'
+- id: goal
+  name: '@stackstackstack/dsh-goal'
+- id: command-goal
+  name: '@stackstackstack/dsh-command-goal'
+```
+
+随附 `dsh` 基础配置启用持久 goal 栈和此命令；Web 客户端提供其交互适配器。ACP（Agent Client Protocol）自动化应用启用领域与模型工具，但不挂载命令适配器；`goals: false` 会移除该栈。无 UI 的 `agent-spine-demo` 必须显式配置 `goals: {}`，避免无头单次调用方在不知情时从一个物理轮次变为包含多个 Round 的操作。
+
+## 模型体验
+
+### 用户 `/goal` 控制
+
+#### 模型看到的内容
+
+斜杠输入、变更以及直接状态／错误输出不会进入模型请求。goal 领域把变更记录为 `goal/change`；已启用的同会话驱动器可以在后续继续执行提示词中暴露结果状态。呈现文本绝不会记录到日志中。
+
+#### Token 影响
+
+读取状态、变更 goal 或收到直接命令错误不会增加模型 token。已启用的同会话驱动器可能增加后续 Goal Round 提示词。
+
+#### KV Cache 影响
+
+命令发现、变更与直接输出不会影响缓存。后续继续执行提示词遵循驱动器的普通请求历史。
+
+## 已知限制与暂缓事项
+
+- **仅纯文本交互**：通用命令注册表没有模态编辑表单或替换确认回调；内联 edit 与显式 clear 能在不同适配器中保持明确且一致的破坏性意图。
+- **没有逐命令 Round 上限参数**：`defaultMaxGoalRounds` 仍是部署配置；用户直接请求时，可以要求模型通过另行授权的 goal 工具编辑 `max_goal_rounds`。
+- **没有持续状态组件**：裸 `/goal` 是可移植的观察接口；适配器专用徽标和重连后可恢复的命令输出仍属于未来 UI 工作。
+- **随附应用中只有 Web 命令适配器使用此命令**：无头、ACP 自动化和 JSON-RPC 适配器不消费 `ctx.commands`。如果组合中包含面向模型的 goal 工具，普通提示词仍能授权它们。

package/lib/index.js

@@ -0,0 +1,151 @@
+import { GoalError } from "@stackstackstack/dsh-goal";
+//#region lib/types/index.js
+/**
+* Human-facing `/goal` command over the persisted same-session goal domain.
+* @module @stackstackstack/dsh-command-goal
+*/
+const name = "command-goal";
+const inject = ["commands", "goals"];
+const USAGE = "Usage: /goal [<objective>|clear|edit <objective>|pause|resume]";
+/** Fail loudly if a locally closed union gains an unhandled member. */
+/* v8 ignore start -- closed-union backstop is unreachable without violating the TypeScript contract */
+function assertNever(value, label) {
+	throw new TypeError(`unknown ${label}: ${String(value)}`);
+}
+/* v8 ignore stop */
+/** Parse only the grammar owned by `/goal`; arbitrary other input is an objective. */
+function parseGoalCommand(rawInput) {
+	const input = rawInput.trim();
+	if (input.length === 0) return { kind: "show" };
+	const control = input.toLowerCase();
+	if (control === "clear") return { kind: "clear" };
+	if (control === "pause") return { kind: "pause" };
+	if (control === "resume") return { kind: "resume" };
+	if (control === "edit") return { kind: "invalid-edit" };
+	if (/^edit(?=\s)/iu.test(input)) return {
+		kind: "edit",
+		objective: input.slice(4).trim()
+	};
+	return {
+		kind: "create",
+		objective: input
+	};
+}
+/** Human label for one durable goal phase. */
+function phaseLabel(phase) {
+	switch (phase) {
+		case "active": return "active";
+		case "paused": return "paused";
+		case "blocked": return "blocked";
+		case "complete": return "complete";
+		/* v8 ignore next 2 -- GoalPhase is closed and every member is handled above */
+		default: return assertNever(phase, "goal phase");
+	}
+}
+/** Commands that are meaningful from one exact live state. */
+function commandHint(goal) {
+	if (goal.phase === "active") return goal.activation === "armed" ? "/goal edit <objective>, /goal pause, /goal clear" : "/goal edit <objective>, /goal resume, /goal clear";
+	switch (goal.phase) {
+		case "paused":
+		case "blocked": return "/goal edit <objective>, /goal resume, /goal clear";
+		case "complete": return "/goal <objective>, /goal clear";
+		/* v8 ignore next 2 -- the active branch and every non-active phase are handled above */
+		default: return assertNever(goal.phase, "goal phase");
+	}
+}
+/** Render direct UI output without exposing compare-and-set internals. */
+function renderGoal(title, goal) {
+	const reason = goal.phase === "blocked" ? goal.blockedReason : void 0;
+	/* v8 ignore next -- durable replay guarantees every blocked goal carries its validated reason */
+	if (goal.phase === "blocked" && reason === void 0) throw new TypeError("blocked goal is missing its reason");
+	const blocker = reason === void 0 ? [] : [`Blocker: ${reason.code}: ${reason.message}`];
+	return {
+		kind: "success",
+		text: [
+			title,
+			`Status: ${phaseLabel(goal.phase)}`,
+			...blocker,
+			`Objective: ${goal.objective}`,
+			`Rounds: ${goal.roundsStarted}/${goal.maxGoalRounds}`,
+			`Activation: ${goal.activation}`,
+			"",
+			`Commands: ${commandHint(goal)}`
+		].join("\n")
+	};
+}
+/** Exact current compare-and-set ref. */
+function goalRef(goal) {
+	return {
+		id: goal.id,
+		revision: goal.revision
+	};
+}
+/** Direct error for an operation that requires a current goal. */
+function missingGoal(action) {
+	return {
+		kind: "error",
+		text: `No goal is currently set; /goal ${action} requires one. ${USAGE}`
+	};
+}
+/** Execute one parsed human command through the domain that owns persistence. */
+function executeGoalCommand(ctx, invocation) {
+	const command = parseGoalCommand(invocation.rawInput);
+	try {
+		const current = ctx.goals.get(invocation.agent);
+		switch (command.kind) {
+			case "show": return current === void 0 ? {
+				kind: "success",
+				text: `No goal is currently set.\n${USAGE}`
+			} : renderGoal("Goal", current);
+			case "invalid-edit": return {
+				kind: "error",
+				text: `Goal editing requires a replacement objective.\n${USAGE}`
+			};
+			case "create":
+				if (current !== void 0 && current.phase !== "complete") return {
+					kind: "error",
+					text: `A goal is already ${phaseLabel(current.phase)}. Use /goal edit <objective> to change it or /goal clear before replacing it.`
+				};
+				return renderGoal("Goal created", ctx.goals.create(invocation.agent, { objective: command.objective }));
+			case "edit":
+				if (current === void 0) return missingGoal("edit");
+				if (current.phase === "complete") return renderGoal("Goal created", ctx.goals.create(invocation.agent, { objective: command.objective }));
+				return renderGoal("Goal updated", ctx.goals.edit(invocation.agent, goalRef(current), { objective: command.objective }));
+			case "pause":
+				if (current === void 0) return missingGoal("pause");
+				return renderGoal("Goal paused", ctx.goals.pause(invocation.agent, goalRef(current)));
+			case "resume":
+				if (current === void 0) return missingGoal("resume");
+				return renderGoal("Goal resumed", ctx.goals.resume(invocation.agent, goalRef(current)));
+			case "clear":
+				if (current === void 0) return {
+					kind: "success",
+					text: "No goal to clear."
+				};
+				ctx.goals.clear(invocation.agent, goalRef(current));
+				return {
+					kind: "success",
+					text: "Goal cleared."
+				};
+			/* v8 ignore next 2 -- GoalCommand is closed and every member is handled above */
+			default: return assertNever(command, "goal command");
+		}
+	} catch (error) {
+		if (error instanceof GoalError) return {
+			kind: "error",
+			text: "The goal command is not valid for the current state. Run /goal to view available commands."
+		};
+		throw error;
+	}
+}
+/** Register the Codex-shaped `/goal` command for every composed command adapter. */
+function apply(ctx) {
+	ctx.commands.register({
+		name: "goal",
+		description: "set or view the goal for a long-running task",
+		input: { hint: "[<objective>|clear|edit <objective>|pause|resume]" },
+		handler: (invocation) => executeGoalCommand(ctx, invocation)
+	});
+}
+//#endregion
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@stackstackstack/dsh-command-goal`.
+* @module @stackstackstack/dsh-command-goal/invariant
+*/
+const PACKAGE_NAME = "@stackstackstack/dsh-command-goal";
+/** Cordis companion plugin name. */
+const name = "command-goal-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this command adapter owns no event stream or state projection; accepted
+* mutations are checked by the goal domain and command dispatch behavior is covered by package tests.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Human-facing `/goal` command over the persisted same-session goal domain.
+ * @module @stackstackstack/dsh-command-goal
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "command-goal";
+export declare const inject: string[];
+/** Register the Codex-shaped `/goal` command for every composed command adapter. */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@stackstackstack/dsh-command-goal`.
+ * @module @stackstackstack/dsh-command-goal/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "command-goal-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@stackstackstack/dsh-command-goal",
+  "description": "Human-facing slash command for persisted same-session goals",
+  "version": "0.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/goal/command-goal"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@stackstackstack/dsh-commands": "^0.1.5",
+    "@stackstackstack/dsh-goal": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@stackstackstack/dsh-goal": "^0.1.5",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-commands": "^0.1.5",
+    "@stackstackstack/dsh-llm": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}