@deepseek-ai/dsh-plan-mode 0.1.0-rc.7 → 0.1.0-rc.8

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/plan/plan-mode/README.md
-README.md: 7171997406ea43487762d9947d07426df400c78a
-README.zh.md: 5c04cdabc293c9abda6bb5e77f596715ee137c6f
+README.md: 3eabe2cb3f04b434b7f908f7beca869f1022a59e
+README.zh.md: f7d6a1f8e9f5ba95f8aad9457f3dde5fc415fdcf

package/README.md

@@ -16,13 +16,13 @@ While active, `plan:policy` renders the configured `section`. The plugin always
 
 The review question declares the `plan-review` presentation intent, naming `Approve` as the label that approves it, so a capable UI presents the plan as a decision instead of a generic question; the answer the tool reads is the same either way. A dismissed review — the user closing the request to speak instead — is reported to the model as such, telling it to stay in plan mode and wait for the message; every other review failure keeps the seam's own message.
 
-When `ctx.commands` is composed, the package registers `/plan [message]` and reserves the exact argument `off` for direct exit. Bare `/plan` selects plan mode; any other non-empty argument selects it first and is then submitted through `agent.steer()`, so it becomes the next step's ordinary logged user message under plan guidance. `/plan off` selects inactive without sending model input; it also cancels a pending entry before plan mode reaches a request.
+When `ctx.commands` is composed, the package registers `/plan [message]` and reserves the exact argument `off` for direct exit. Bare `/plan` selects plan mode; any other non-empty argument selects it first and is then submitted through `agent.steer()`, so it becomes the next step's ordinary logged user message under plan guidance. `/plan off` selects inactive without sending model input; it also cancels a pending entry before plan mode reaches a request. The command declares `input.images`: composer image attachments ride the steered message ahead of its text block. Bare `/plan` with images steers an image-only user message, while `/plan off` with images returns a direct error before any mode change so the composer keeps them.
 
 The Web client consumes the plugin-owned `/plan` command; other entry points may drive the same service directly without defining a second mode vocabulary.
 
 ## Session projection
 
-When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `plan` projection unit under an injected child. The unit folds two event kinds: a `command/run` record named `plan` with recorded `args` sets the wanted target (`off` → inactive, anything else → active), and `plan/mode` commits the logged state and clears it; every other event returns the same state reference. `view` derives `{ active, pending }`, where `pending` is true only while an outstanding selection differs from the logged state — a pure replay quantity, so host restarts, other tabs, and cold reads all recover it from the log alone (the `/plan` handler calls `set()` before any failing path, so a failed handler cannot leave a recorded command without its plan selection). The key merges into `SessionProjectionMap` from `src/types.ts` (served to host consumers via `./types` and client aggregates via `./client`); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected.
+When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `plan` projection unit under an injected child. A `command/run` record named `plan` with recorded `args` starts a candidate target (`off` → inactive, anything else → active); its paired `command/done` retains a successful selection and drops an error; `plan/mode` commits the logged state and clears the retained selection. Every other event returns the same state reference. `view` derives `{ active, pending }`, where `pending` is true only while an unsettled or successful selection differs from the logged state. This remains a pure replay quantity, so host restarts, other tabs, and cold reads recover it from the log alone, and a rejected `/plan off` with images cannot leave a pending exit. The key merges into `SessionProjectionMap` from `src/types.ts` (served to host consumers via `./types` and client aggregates via `./client`); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected.
 
 ## Configuration
 
@@ -65,11 +65,11 @@ The section is stable within plan mode, but entering or leaving changes the syst
 
 #### What the model sees
 
-`/plan`, `/plan off`, and their terminal results stay outside model history. A non-empty suffix other than the exact `off` argument becomes one trimmed user text block through `agent.steer()` after plan mode is selected. An active `/plan off` selection contributes the standard logged user-switch notice only when the last request header described plan mode; cancelling a pending entry contributes none because no request observed it.
+`/plan`, `/plan off`, and their terminal results stay outside model history. A non-empty suffix other than the exact `off` argument becomes one user message through `agent.steer()` after plan mode is selected: any admitted image attachments as leading image blocks, then the trimmed text block. Bare `/plan` with admitted images steers one user message containing only those image blocks. An active `/plan off` selection contributes the standard logged user-switch notice only when the last request header described plan mode; cancelling a pending entry contributes none because no request observed it.
 
 #### Token effect
 
-The optional message costs the same history tokens as submitting that text separately; bare `/plan` and `/plan off` add none. A narrated active exit adds the small retained switch notice.
+The optional message costs the same history tokens as submitting that content separately. Bare `/plan` without images and `/plan off` add none; bare `/plan` with images has the normal image-prompt cost. A narrated active exit adds the small retained switch notice.
 
 #### KV Cache effect
 

package/README.zh.md

@@ -16,13 +16,13 @@
 
 评审问题声明 `plan-review` 呈现意图，并指名 `Approve` 为表示批准的标签，因此有能力的 UI 会把计划呈现为一次决定而非通用问题；两种情况下该工具读到的回答完全相同。放弃审阅——用户关闭请求，转而发言——会如实报告给模型，要求它留在 plan mode 中等待那条消息；其余每一种评审失败都保留 seam 自身的消息。
 
-组合 `ctx.commands` 时，该包会注册 `/plan [message]`，并将参数恰好为 `off` 的情况保留给直接退出。不带参数的 `/plan` 会启用 plan mode；任何其他非空参数都会先启用 plan mode，再通过 `agent.steer()` 提交，因此它会在 plan 引导下成为下一步骤的常规已记录用户消息。`/plan off` 会选择停用状态，不发送模型输入；它还可以在启用 plan mode 的待处理选择由轮内 pre-step 追加之前将其取消。
+组合 `ctx.commands` 时，该包会注册 `/plan [message]`，并将参数恰好为 `off` 的情况保留给直接退出。不带参数的 `/plan` 会启用 plan mode；任何其他非空参数都会先启用 plan mode，再通过 `agent.steer()` 提交，因此它会在 plan 引导下成为下一步骤的常规已记录用户消息。`/plan off` 会选择停用状态，不发送模型输入；它还可以在启用 plan mode 的待处理选择由轮内 pre-step 追加之前将其取消。该命令声明了 `input.images`：composer 图片附件会随被 steer 的消息一起提交，位于文本块之前。不带参数的 `/plan` 若附有图片，会 steer 一条只含图片的用户消息；`/plan off` 若附有图片，会在任何模式变更前直接返回错误，composer 保留图片。
 
 Web 客户端使用该插件提供的 `/plan` 命令；其他入口可以直接驱动同一服务，无需定义第二套 mode 词汇。
 
 ## 会话投影
 
-当组合挂载 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)）时，本包会在一个注入的子插件中注册 `plan` 投影单元。该单元折叠两类事件：名为 `plan` 且携带已记录 `args` 的 `command/run` 记录会设置目标状态（`off` → 未激活，其余 → 激活），`plan/mode` 会提交已记录状态并清除该目标；其他任何事件都返回同一个状态引用。`view` 推导 `{ active, pending }`，其中 `pending` 仅在尚未落实的选择与已记录状态不同时为 true。该值完全由日志回放得出，因此 host 重启、其他标签页和冷读都能仅凭日志恢复它。`/plan` 处理器会在任何可能失败的路径之前调用 `set()`，因此处理器失败时不会留下缺少对应 plan 选择的已记录命令。key 由 `src/types.ts` 通过声明合并加入 `SessionProjectionMap`：host 消费方经 `./types` 获取，client 聚合经 `./client` 获取。框架负责驱动该单元，载体通过历史尾页和 `session/projection` 推送帧提供其值。未挂载注册表的组合不受影响。
+当组合挂载 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)）时，本包会在一个注入的子插件中注册 `plan` 投影单元。名为 `plan` 且携带已记录 `args` 的 `command/run` 记录会开始一个候选目标（`off` → 未激活，其余 → 激活）；与它配对的 `command/done` 保留成功选择并丢弃错误选择；`plan/mode` 提交已记录状态并清除已保留的选择。其他任何事件都返回同一个状态引用。`view` 推导 `{ active, pending }`，其中 `pending` 仅在未结算或已成功的选择与已记录状态不同时为 true。该值仍完全由日志回放得出，因此 host 重启、其他标签页和冷读都能仅凭日志恢复它，被拒绝的带图 `/plan off` 也不会留下待退出状态。key 由 `src/types.ts` 通过声明合并加入 `SessionProjectionMap`：host 消费方经 `./types` 获取，client 聚合经 `./client` 获取。框架负责驱动该单元，载体通过历史尾页和 `session/projection` 推送帧提供其值。未挂载注册表的组合不受影响。
 
 ## 配置
 
@@ -65,11 +65,11 @@ You are in plan mode. Explore and design before presenting the complete plan thr
 
 #### 模型所见内容
 
-`/plan`、`/plan off` 及其终端结果留在模型历史之外。除恰好为 `off` 以外的非空后缀会在选择 plan mode 后，通过 `agent.steer()` 成为一个已去除首尾空白的用户文本块。plan mode 已激活时，选择 `/plan off` 只会在最后一个请求头描述了 plan mode 的情况下追加标准的已记录用户切换通知；取消待生效进入不会贡献通知，因为没有请求观测到它。
+`/plan`、`/plan off` 及其终端结果留在模型历史之外。除恰好为 `off` 以外的非空后缀会在选择 plan mode 后，通过 `agent.steer()` 成为一条用户消息：任何已准入的图片附件作为前置图片块，之后是已去除首尾空白的文本块。不带参数的 `/plan` 若带有已准入图片，会 steer 一条只含这些图片块的用户消息。plan mode 已激活时，选择 `/plan off` 只会在最后一个请求头描述了 plan mode 的情况下追加标准的已记录用户切换通知；取消待生效进入不会贡献通知，因为没有请求观测到它。
 
 #### Token 影响
 
-可选消息的历史 token 成本与单独提交该文本相同；不带参数的 `/plan` 和 `/plan off` 不增加 token。一次带有切换通知的已激活状态退出会追加一条简短且会保留的通知。
+可选消息的历史 token 成本与单独提交该内容相同。不带图片和参数的 `/plan` 与 `/plan off` 不增加 token；不带参数但带图的 `/plan` 产生常规图片提示词成本。一次带有切换通知的已激活状态退出会追加一条简短且会保留的通知。
 
 #### KV Cache 影响
 

package/lib/index.js

@@ -155,37 +155,60 @@ var PlanModeController = class extends Service {
 				schema: planProjectionSchema,
 				init: () => ({
 					active: false,
-					wanted: null
+					wanted: null,
+					running: null
 				}),
 				apply: (state, event) => {
 					if (event.type === "command/run" && event.data.name === "plan") {
 						if (event.data.args === void 0) return state;
 						const wanted = event.data.args.trim() !== "off";
-						return wanted === state.wanted ? state : {
-							active: state.active,
-							wanted
+						return {
+							...state,
+							running: {
+								commandId: event.data.commandId,
+								wanted
+							}
+						};
+					}
+					if (event.type === "command/done" && event.data.commandId === state.running?.commandId) {
+						const wanted = event.data.kind === "success" && state.running.wanted !== state.active ? state.running.wanted : null;
+						return {
+							...state,
+							wanted,
+							running: null
 						};
 					}
 					if (event.type === "plan/mode") return {
+						...state,
 						active: event.data.active,
 						wanted: null
 					};
 					return state;
 				},
-				view: (state) => ({
-					active: state.active,
-					pending: state.wanted !== null && state.wanted !== state.active
-				}),
-				stateVersion: 1
+				view: (state) => {
+					const wanted = state.running?.wanted ?? state.wanted;
+					return {
+						active: state.active,
+						pending: wanted !== null && wanted !== state.active
+					};
+				},
+				stateVersion: 2
 			});
 		});
 		ctx.inject(["commands"], (commandCtx) => {
 			commandCtx.commands.register({
 				name: "plan",
 				description: "Enter or leave plan mode",
-				input: { hint: "[off|message]" },
-				handler: ({ agent, rawInput }) => {
+				input: {
+					hint: "[off|message]",
+					images: true
+				},
+				handler: ({ agent, rawInput, attachments }) => {
 					const message = rawInput.trim();
+					if (message === "off" && attachments.length > 0) return {
+						kind: "error",
+						text: "Image attachments cannot accompany /plan off."
+					};
 					if (message === "off") switch (this.set(agent, false)) {
 						case "committed": return {
 							kind: "success",
@@ -208,11 +231,11 @@ var PlanModeController = class extends Service {
 						};
 					}
 					const outcome = this.set(agent, true);
-					if (message !== "") agent.steer(createUserMessage({
-						content: [{
+					if (message !== "" || attachments.length > 0) agent.steer(createUserMessage({
+						content: [...attachments, ...message === "" ? [] : [{
 							type: "text",
 							text: message
-						}],
+						}]],
 						source: { kind: "user" }
 					}));
 					return {

package/lib/types/index.js

@@ -172,12 +172,11 @@ export class PlanModeController extends Service {
                 return (pending?.active ?? foldPlanMode(context.agent.session.events)) ? this.section : '';
             },
         });
-        // The plan projection unit (session-projection RFC): a pure double-event
-        // fold serving clients the whole {active, pending} value. `command/run`
-        // records the user's logged /plan selection (the handler calls `set()`
-        // before any failing path, so a failed handler cannot leave the recorded
-        // command without its plan selection); `plan/mode` records that selection
-        // and clears it. Pending is thereby a pure
+        // The plan projection unit (session-projection RFC): a pure event fold
+        // serving clients the whole {active, pending} value. `command/run`
+        // records the user's logged /plan selection, its paired `command/done`
+        // keeps only successful selections, and `plan/mode` records that
+        // selection and clears it. Pending is thereby a pure
         // replay quantity: host restarts, other tabs, and cold reads all recover
         // it from the log alone. The unit child activates only when a projection
         // registry is composed (headless assemblies stay unaffected).
@@ -185,24 +184,30 @@ export class PlanModeController extends Service {
             projectionCtx.sessionProjections.register({
                 key: 'plan',
                 schema: planProjectionSchema,
-                init: () => ({ active: false, wanted: null }),
+                init: () => ({ active: false, wanted: null, running: null }),
                 apply: (state, event) => {
                     if (event.type === 'command/run' && event.data.name === 'plan') {
                         if (event.data.args === undefined)
                             return state;
                         const wanted = event.data.args.trim() !== 'off';
-                        return wanted === state.wanted ? state : { active: state.active, wanted };
+                        return { ...state, running: { commandId: event.data.commandId, wanted } };
+                    }
+                    if (event.type === 'command/done' && event.data.commandId === state.running?.commandId) {
+                        const wanted = event.data.kind === 'success' && state.running.wanted !== state.active
+                            ? state.running.wanted
+                            : null;
+                        return { ...state, wanted, running: null };
                     }
                     if (event.type === 'plan/mode') {
-                        return { active: event.data.active, wanted: null };
+                        return { ...state, active: event.data.active, wanted: null };
                     }
                     return state;
                 },
-                view: state => ({
-                    active: state.active,
-                    pending: state.wanted !== null && state.wanted !== state.active,
-                }),
-                stateVersion: 1,
+                view: (state) => {
+                    const wanted = state.running?.wanted ?? state.wanted;
+                    return { active: state.active, pending: wanted !== null && wanted !== state.active };
+                },
+                stateVersion: 2,
             });
         });
         // The command child activates only when a command registry is composed.
@@ -210,9 +215,12 @@ export class PlanModeController extends Service {
             commandCtx.commands.register({
                 name: 'plan',
                 description: 'Enter or leave plan mode',
-                input: { hint: '[off|message]' },
-                handler: ({ agent, rawInput }) => {
+                input: { hint: '[off|message]', images: true },
+                handler: ({ agent, rawInput, attachments }) => {
                     const message = rawInput.trim();
+                    if (message === 'off' && attachments.length > 0) {
+                        return { kind: 'error', text: 'Image attachments cannot accompany /plan off.' };
+                    }
                     if (message === 'off') {
                         switch (this.set(agent, false)) {
                             case 'committed':
@@ -231,8 +239,15 @@ export class PlanModeController extends Service {
                         }
                     }
                     const outcome = this.set(agent, true);
-                    if (message !== '')
-                        agent.steer(createUserMessage({ content: [{ type: 'text', text: message }], source: { kind: 'user' } }));
+                    if (message !== '' || attachments.length > 0) {
+                        agent.steer(createUserMessage({
+                            content: [
+                                ...attachments,
+                                ...(message === '' ? [] : [{ type: 'text', text: message }]),
+                            ],
+                            source: { kind: 'user' },
+                        }));
+                    }
                     return {
                         kind: 'success',
                         text: outcome === 'committed'

package/lib/types/types.d.ts

@@ -10,9 +10,10 @@
 /**
  * The plan projection's wire value. `active` is the logged state in force
  * (the last `plan/mode`, inactive before the first); `pending` is true while
- * a logged `/plan` selection (`command/run`) targets a state other than
- * `active` and no later `plan/mode` event has recorded that state. Capability
- * absence (plan-mode not composed) is the key's absence, never a value.
+ * a logged `/plan` selection targets a state other than `active`, has not
+ * failed through its paired `command/done`, and no later `plan/mode` event has
+ * recorded that state. Capability absence (plan-mode not composed) is the
+ * key's absence, never a value.
  */
 export interface PlanProjection {
     active: boolean;
@@ -20,7 +21,7 @@ export interface PlanProjection {
 }
 declare module '@deepseek-ai/dsh-session-projection/types' {
     interface SessionProjectionMap {
-        /** Plan collaboration state folded from `command/run` (name `plan`) and `plan/mode` events. */
+        /** Plan collaboration state folded from the plan command lifecycle and `plan/mode` events. */
         plan: PlanProjection;
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-plan-mode",
   "description": "Logged per-agent plan mode with deployment guidance, a direct slash command, and a user-reviewed exit",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
   "publishConfig": {
     "access": "public"
   },
@@ -41,16 +41,16 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-commands": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.7",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.8",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-commands": {
@@ -61,17 +61,17 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-code-runtime": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-commands": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-code-runtime": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.8",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.7"
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8"
   }
 }