@deepseek-ai/dsh-sdk-jsonrpc-server 0.2.1-alpha.1 → 0.2.1-alpha.2

package/README.i18n.yaml

@@ -15,8 +15,8 @@
   en: d152484eb41ac6b4
   zh: 09388d293f9be9cb
 /deepseek-ai-dsh-sdk-jsonrpc-server/use-this-package:
-  en: 7abbf9c04a04b16c
-  zh: dc18b716ed3807d5
+  en: ab5b719668e746f2
+  zh: 971c2fdaa9e7d351
 /deepseek-ai-dsh-sdk-jsonrpc-server/use-this-package/wiring:
   en: 47a33e9397e36e15
   zh: e6d173820f9ea6e5
@@ -27,8 +27,8 @@
   en: 784b68b5a498f2d5
   zh: 2c3c5a1490845179
 /deepseek-ai-dsh-sdk-jsonrpc-server/use-this-package/what-sdk-clients-can-do:
-  en: 2b1b52a7467c557e
-  zh: 31f58d32469f9d50
+  en: b4351b6b407fe65f
+  zh: 52d711d554d2ad33
 /deepseek-ai-dsh-sdk-jsonrpc-server/use-this-package/shutdown-and-exit:
   en: 08c3858f53090f39
   zh: dfae960e11515b06
@@ -45,8 +45,8 @@
   en: 2658804b2f90b135
   zh: 085aa00c8f0bbbcd
 /deepseek-ai-dsh-sdk-jsonrpc-server/understand-the-implementation/teardown:
-  en: 81786b3bd70b389f
-  zh: da80b4f50f16a098
+  en: 7e4403a7b1da7ff4
+  zh: ef75ee9411486b90
 /deepseek-ai-dsh-sdk-jsonrpc-server/further-exploration:
   en: cea854984c56c75a
   zh: 1ee5eaab8305e10d

package/README.md

@@ -25,6 +25,8 @@ English | [中文](README.zh.md)
 <a id="use-this-package"></a>
 ## Use this package
 
+`session/working-directory/get` accepts `{ sessionId }`; `session/working-directory/set` accepts `{ sessionId, path }`. Both return `{ cwd }` and create an unknown Session without starting a model turn. Reads recover missing directories through the working-directory service; changes preserve origin metadata and permissions, and reach the model through logged user context.
+
 Mount this plugin when a runtime must serve SDK clients: add it to a `cordis.yml` that composes the agent service, boot the runtime, and clients connect over stdio. The common path is explicit — the plugin needs the `agents` service; every other capability comes from the surrounding tree.
 
 ### Wiring
@@ -47,6 +49,8 @@ Stdout carries only JSON-RPC frames, so clients can parse every byte; diagnostic
 
 `initialize` is the runtime-readiness boundary: when the server is mounted by a Loader composition, it waits for the current plugin tree to settle before replying, so async sibling capabilities such as initial MCP tool discovery are visible to the first prompt. The handshake returns the wire-stable identity `deepseek-harness-sdk-runtime`. The server validates the provider/model route and optional non-empty `reasoningEffort` through the selected adapter before it stores them; omission stores no effort, so the model retains its own default. An optional positive `maxTokens` becomes the request output cap of each SDK-created agent and its in-process descendants, while omission applies the selected adapter or provider route default. JSON-RPC requests may dispatch concurrently, so `session/prompt` rejects until one `initialize` has completed successfully; clients must await the handshake before sending prompts. An accepted prompt queues one identified user message and immediately returns `{ messageId }`; the server then streams every durable fact as `session.event` and every whole-agent lifecycle transition as `session.status`. It does not assign an assistant message or `turn/end` to a prompt, and independent requests may enqueue more work on the same session. Persistence roots and persona come from the surrounding composition.
 
+`session/wait` observes an existing SDK-owned session through managed descendant completion and any resulting root turns. It rejects unknown or retired roots, never creates a session, and responds after the root stays idle across the descendant check. Idle children with parked inbox messages remain resident but do not delay this response; later waking input can resume them. Session notifications emitted before completion precede the response on the stdio transport. A live Agent failure remains associated with that exact session until a later committed `turn/end` accounts for the outcome; otherwise the wait rejects, including when the failure preceded the wait request. Errors already represented by a terminal remain in Session events, and later successful activity clears an earlier live failure.
+
 ### Shutdown and exit
 
 The plugin answers `shutdown`, flushes the response, disposes the root context so SDK-owned agents, subscriptions, and persistence reach quiescence, then exits 0. EOF and signal exits belong to the app bin, which also disposes the root context. Unloading only this plugin stops serving without exiting the process.
@@ -78,7 +82,7 @@ Each protocol method validates its inputs and resolves the owning state before a
 
 ### Teardown
 
-`server.shutdown()` disposes only what the server owns — the surrounding context stays running when just this plugin is unloaded. Protocol `shutdown` instead disposes the root fiber so persistence and the whole runtime reach quiescence before the process exits.
+`server.shutdown()` closes descendant admission below its exact root Agents and drains their managed descendants child-first before releasing the root handles and adapter. It removes its subscriptions while unrelated parent trees and the surrounding context stay running when just this plugin is unloaded. A descendant drain failure is reported after the remaining root and adapter teardown completes. Protocol `shutdown` instead disposes the root fiber so persistence and the whole runtime reach quiescence before the process exits.
 
 </details>
 

package/README.zh.md

@@ -25,6 +25,8 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
+`session/working-directory/get` 接收 `{ sessionId }`；`session/working-directory/set` 接收 `{ sessionId, path }`。两者均返回 `{ cwd }`，并可创建未知 Session，而不启动模型轮次。读取通过工作目录服务恢复缺失目录；修改保留起始目录元数据与权限，并通过已记录的用户上下文告知模型。
+
 当运行时必须服务 SDK 客户端时挂载本插件：把它加入组合了 agent 服务的 `cordis.yml`，启动运行时，客户端即可通过 stdio 连接。常用路径是显式的——插件需要 `agents` 服务；其余每个能力都来自外围插件树。
 
 ### 组装
@@ -47,6 +49,8 @@ Stdout 只承载 JSON-RPC 帧，客户端可以逐字节解析；诊断信息应
 
 `initialize` 是运行时就绪边界：服务器由 Loader 组合挂载时，会等待当前插件树完成所有加载任务后再响应，因此首次提示词能够看到 MCP 初始工具发现等异步同级能力。握手返回协议稳定标识 `deepseek-harness-sdk-runtime`。服务器会通过所选适配器校验提供方／模型路由与可选的非空 `reasoningEffort`，再保存这些值；省略时不会保存推理强度，因此模型保留自身默认值。可选的正整数 `maxTokens` 会成为每个 SDK 创建的 agent 及其进程内后代的请求输出上限，省略时则应用所选适配器或提供方路由的默认值。JSON-RPC 请求可能并发分派，因此在一次 `initialize` 成功完成之前，`session/prompt` 会拒绝；客户端必须等待握手完成后再发送提示词。已接受的提示词会把一条带标识的用户消息排入队列，并立即返回 `{ messageId }`；服务器随后把每个持久事实作为 `session.event`、把整个 agent 生命周期的每次状态转换作为 `session.status` 流式发出。它不会把某条助手消息或 `turn/end` 归属于某个提示词，同一会话上的独立请求可以继续排入更多工作。持久化根目录与 persona 来自外围组合。
 
+`session/wait` 观察已有 SDK 会话，直到受管理后代及其触发的根 Agent 后续轮次完成。它拒绝未知或已释放的根 Agent，不会创建会话，并在后代检查期间根 Agent 持续空闲后响应。收件箱消息处于停放状态的空闲子级继续驻留，但不延迟此响应；后续唤醒输入可使其继续运行。完成前发出的会话通知在 stdio 传输上先于响应到达。Agent 的运行时错误会保留在对应的确切会话中，直到后续提交的 `turn/end` 记录结果；否则等待请求会失败，即使错误发生在等待请求之前。终止事件已经记录的错误仍通过会话事件表达，后续成功的活动会清除较早的运行时错误。
+
 ### 关闭与退出
 
 插件应答 `shutdown`，刷新响应并 dispose 根上下文，使 SDK 持有的 agent、订阅与持久化达到完全停稳，然后以 0 退出。EOF 与信号退出归 app bin 负责，后者也会 dispose 根上下文。仅卸载此插件会停止服务，但不会退出进程。
@@ -78,7 +82,7 @@ Stdout 只承载 JSON-RPC 帧，客户端可以逐字节解析；诊断信息应
 
 ### 清理
 
-`server.shutdown()` 只 dispose 服务器自身持有的内容——仅卸载本插件时，外围上下文保持运行。协议 `shutdown` 则 dispose 根 fiber，使持久化与整个运行时在进程退出前达到完全停稳。
+`server.shutdown()` 关闭其精确根 Agent 下的后代准入，按子级优先顺序排空托管后代，再释放根句柄与适配器。它移除自身订阅，而仅卸载本插件时，无关父级树与外围上下文保持运行。后代排空失败会在其余根句柄与适配器的清理完成后报告。协议 `shutdown` 则 dispose 根 fiber，使持久化与整个运行时在进程退出前达到完全停稳。
 
 </details>
 

package/lib/index.js

@@ -66,12 +66,22 @@ var HarnessSdkJsonRpcServer = class {
 		this.options = options;
 		const serverOptions = this.options;
 		this.disposers.push(ctx.on("session/event", (session, event) => {
+			const record = this.sessions.get(session.id);
+			if (event.type === "turn/end" && record?.handle.agent.session === session && record.failure !== void 0 && event.seq >= record.failure.atOffset) record.failure = void 0;
 			const payload = {
 				sessionId: String(session.id),
 				event
 			};
 			this.transport.notify("session.event", payload);
 		}));
+		this.disposers.push(ctx.on("agent/error", ({ agent, error }) => {
+			const record = this.sessions.get(agent.session.id);
+			if (record?.handle.agent !== agent) return;
+			record.failure = {
+				error,
+				atOffset: agent.session.seq
+			};
+		}));
 		this.disposers.push(ctx.on("agent/status", ({ agent, status }) => {
 			this.transport.notify("session.status", {
 				sessionId: String(agent.session.id),
@@ -153,11 +163,61 @@ var HarnessSdkJsonRpcServer = class {
 		rec.handle.agent.followup(message);
 		return { messageId: message.id };
 	}
+	/**
+	* Wait for an existing owned Agent and its managed descendants to finish.
+	* The response follows all Session notifications emitted during the wait.
+	* Rejects a live Agent failure that has no subsequent durable terminal.
+	* @param params - the SDK-owned session to observe without creating one.
+	* @returns an empty result after the root stays idle across the descendant check.
+	*/
+	async wait(params) {
+		if (!this.initialized) throw new Error("SDK server is not initialized");
+		const rec = this.sessions.get(params.sessionId);
+		if (rec === void 0) throw new Error(`unknown SDK session: ${params.sessionId}`);
+		const agent = rec.handle.agent;
+		const subagents = this.ctx.get("subagents");
+		while (true) {
+			this.assertLiveAgent(rec, params.sessionId);
+			await agent.whenIdle();
+			const idleSeq = agent.session.seq;
+			const children = await subagents?.waitForChildren(agent);
+			this.assertLiveAgent(rec, params.sessionId);
+			if (!children && agent.status === "idle" && agent.session.seq === idleSeq) {
+				if (rec.failure !== void 0) throw rec.failure.error;
+				return {};
+			}
+		}
+	}
 	assertLiveAgent(rec, sessionId) {
 		if (this.ctx.agents.get(rec.handle.agent.id) !== rec.handle.agent) throw new Error(`session agent was disposed outside the server: ${sessionId}`);
 	}
 	/**
+	* Read a Session's effective directory, recovering a missing directory to its origin.
+	* @param params - target Session; an unknown id creates it.
+	* @returns the absolute effective directory.
+	*/
+	async getWorkingDirectory(params) {
+		const agent = await this.workingDirectoryAgent(params.sessionId);
+		return { cwd: await this.ctx.workingDirectory.ensure(agent) };
+	}
+	/**
+	* Change a Session's directory and queue its model-visible transition.
+	* @param params - target Session and absolute or current-directory-relative path.
+	* @returns the validated absolute directory; origin and permissions are unchanged.
+	*/
+	async setWorkingDirectory(params) {
+		const agent = await this.workingDirectoryAgent(params.sessionId);
+		return { cwd: await this.ctx.workingDirectory.set(agent, params.path) };
+	}
+	async workingDirectoryAgent(sessionId) {
+		if (!this.initialized) throw new Error("SDK server is not initialized");
+		const rec = await this.getOrCreateSession(sessionId);
+		this.assertLiveAgent(rec, sessionId);
+		return rec.handle.agent;
+	}
+	/**
 	* Dispose server-owned agents, adapter, and subscriptions to quiescence.
+	* Managed descendants drain before the root Agent handles and adapter are released.
 	* The surrounding context remains running.
 	* @returns empty JSON-RPC result.
 	*/
@@ -178,6 +238,11 @@ var HarnessSdkJsonRpcServer = class {
 		} catch (error) {
 			failures.push(error);
 		}
+		try {
+			await this.ctx.get("subagents")?.drainDescendants(records.map((rec) => rec.handle.agent));
+		} catch (error) {
+			failures.push(error);
+		}
 		const teardownResults = await Promise.allSettled([...records.map((rec) => Promise.resolve().then(() => rec.handle.dispose())), ...this.llmFiber === void 0 ? [] : [Promise.resolve().then(() => this.llmFiber?.dispose())]]);
 		this.llmFiber = void 0;
 		failures.push(...teardownResults.filter((result) => result.status === "rejected").map((result) => result.reason));
@@ -196,6 +261,20 @@ var HarnessSdkJsonRpcServer = class {
 		switch (method) {
 			case "initialize": return this.initialize(params);
 			case "session/prompt": return this.prompt(params);
+			case "session/wait": {
+				const sessionId = params?.sessionId;
+				if (typeof sessionId !== "string") throw new TypeError("session/wait requires a sessionId string");
+				return this.wait({ sessionId });
+			}
+			case "session/working-directory/get":
+			case "session/working-directory/set":
+				if (typeof params?.sessionId !== "string" || params.sessionId.length === 0) throw new TypeError("working-directory requests require a non-empty sessionId");
+				if (method === "session/working-directory/get") return this.getWorkingDirectory({ sessionId: params.sessionId });
+				if (typeof params.path !== "string") throw new TypeError("working-directory set requires a path string");
+				return this.setWorkingDirectory({
+					sessionId: params.sessionId,
+					path: params.path
+				});
 			case "shutdown": return this.shutdown();
 			default: throw new Error(`unknown DeepSeek Harness SDK runtime method: ${method}`);
 		}
@@ -216,16 +295,19 @@ var HarnessSdkJsonRpcServer = class {
 		return creation;
 	}
 	async createSession(sessionId) {
-		const rec = { handle: await this.ctx.agents.create({
-			sessionId: brandString(sessionId),
-			meta: { cwd: this.cwd },
-			agentOptions: {
-				provider: this.provider,
-				model: this.model,
-				...this.reasoningEffort === void 0 ? {} : { reasoningEffort: this.reasoningEffort },
-				...this.maxTokens === void 0 ? {} : { maxTokens: this.maxTokens }
-			}
-		}) };
+		const rec = {
+			handle: await this.ctx.agents.create({
+				sessionId: brandString(sessionId),
+				meta: { cwd: this.cwd },
+				agentOptions: {
+					provider: this.provider,
+					model: this.model,
+					...this.reasoningEffort === void 0 ? {} : { reasoningEffort: this.reasoningEffort },
+					...this.maxTokens === void 0 ? {} : { maxTokens: this.maxTokens }
+				}
+			}),
+			failure: void 0
+		};
 		this.sessions.set(sessionId, rec);
 		return rec;
 	}
@@ -246,7 +328,7 @@ var HarnessSdkJsonRpcServer = class {
 * @module @deepseek-ai/dsh-sdk-jsonrpc-server
 */
 const name = "sdk-jsonrpc-server";
-const inject = ["agents"];
+const inject = ["agents", "workingDirectory"];
 const Config = Schema.object({ maxTokensAsSuccess: Schema.boolean().default(false) });
 /**
 * Serve SDK requests over the configured streams. Effect disposal shuts down

package/lib/types/server.d.ts

@@ -5,7 +5,7 @@
  * @module @deepseek-ai/dsh-sdk-jsonrpc-server/server
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { InitializeParams, InitializeResult, JsonRpcTransportPeer, SessionPromptParams, SessionPromptResult } from '@deepseek-ai/dsh-sdk-protocol';
+import type { InitializeParams, InitializeResult, JsonRpcTransportPeer, SessionPromptParams, SessionPromptResult, SessionWaitParams, SessionWorkingDirectoryParams, SessionWorkingDirectorySetParams, SessionWorkingDirectoryResult } from '@deepseek-ai/dsh-sdk-protocol';
 /** Deployment-specific status mapping for SDK turn and subagent outcomes. */
 export interface HarnessSdkJsonRpcServerOptions {
     /** Report max-token termination as an accepted result instead of an infrastructure error. */
@@ -45,9 +45,31 @@ export declare class HarnessSdkJsonRpcServer {
      * @returns the durable message identity.
      */
     prompt(params: SessionPromptParams): Promise<SessionPromptResult>;
+    /**
+     * Wait for an existing owned Agent and its managed descendants to finish.
+     * The response follows all Session notifications emitted during the wait.
+     * Rejects a live Agent failure that has no subsequent durable terminal.
+     * @param params - the SDK-owned session to observe without creating one.
+     * @returns an empty result after the root stays idle across the descendant check.
+     */
+    wait(params: SessionWaitParams): Promise<Record<string, never>>;
     private assertLiveAgent;
+    /**
+     * Read a Session's effective directory, recovering a missing directory to its origin.
+     * @param params - target Session; an unknown id creates it.
+     * @returns the absolute effective directory.
+     */
+    getWorkingDirectory(params: SessionWorkingDirectoryParams): Promise<SessionWorkingDirectoryResult>;
+    /**
+     * Change a Session's directory and queue its model-visible transition.
+     * @param params - target Session and absolute or current-directory-relative path.
+     * @returns the validated absolute directory; origin and permissions are unchanged.
+     */
+    setWorkingDirectory(params: SessionWorkingDirectorySetParams): Promise<SessionWorkingDirectoryResult>;
+    private workingDirectoryAgent;
     /**
      * Dispose server-owned agents, adapter, and subscriptions to quiescence.
+     * Managed descendants drain before the root Agent handles and adapter are released.
      * The surrounding context remains running.
      * @returns empty JSON-RPC result.
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sdk-jsonrpc-server",
   "description": "Stdio JSON-RPC server plugin for out-of-process DeepSeek Harness SDK clients",
-  "version": "0.2.1-alpha.1",
+  "version": "0.2.1-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,34 +27,36 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/dsh-brand": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-brand": "0.2.1-alpha.2",
     "@deepseek-ai/schemastery": "~3.18.5-alpha.1"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-attachment": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-llm": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-llm-deepseek-api-key": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-scope": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-sdk-protocol": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-subagent": "0.2.1-alpha.1",
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-attachment": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-llm-deepseek-api-key": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-sdk-protocol": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-subagent": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-working-directory": "0.2.1-alpha.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "~4.0.5-alpha.1",
     "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.1",
-    "@deepseek-ai/dsh-agent": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-agent-loop": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-attachment": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-llm": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-llm-deepseek-api-key": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-subagent": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-scope": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-sdk-protocol": "0.2.1-alpha.1"
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-agent-loop": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-attachment": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-llm-deepseek-api-key": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-sdk-protocol": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-subagent": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-working-directory": "0.2.1-alpha.2"
   }
 }