@deepseek-ai/dsh-sdk-client 0.2.1-alpha.1 → 0.2.1-alpha.3

package/README.i18n.yaml

@@ -15,14 +15,14 @@
   en: d152484eb41ac6b4
   zh: 09388d293f9be9cb
 /deepseek-ai-dsh-sdk-client/use-this-package:
-  en: 3c21c7ec64d17346
-  zh: c6ba1b632b8a4d72
+  en: ff421f12a5db28a4
+  zh: 2ca9b71a3458b5e0
 /deepseek-ai-dsh-sdk-client/use-this-package/running-agent-turns-with-deepseekharness:
   en: 01c58dddd7e62de2
   zh: 6dbd46e244f3f135
 /deepseek-ai-dsh-sdk-client/use-this-package/lower-level-control-with-harnessclient:
-  en: 8e7eb3a9b3f91404
-  zh: 277a722586dcb549
+  en: 8778901987da6e59
+  zh: 3d09fe4b0b393a15
 /deepseek-ai-dsh-sdk-client/understand-the-implementation:
   en: 8773f50c51da85f0
   zh: 4649ebc69357deb0

package/README.md

@@ -25,6 +25,10 @@ English | [中文](README.zh.md)
 <a id="use-this-package"></a>
 ## Use this package
 
+`await harness.resumeSession(savedId)` restores a persisted session from the configured `dshHome` and returns a `HarnessSession` ready for `run()`. Save the original session id and reuse its home and workspace. Restoration preserves conversation history and its directory, repairs an interrupted final turn, and sends no new input. Missing, unreadable, incompatible, or occupied sessions reject without creating a replacement. `session(id)` remains a lazy handle for an in-process session; it does not request persisted restoration. Shell, browser, and other external processes are not restored by this API.
+
+`HarnessSession.getWorkingDirectory()` reads the effective directory; `setWorkingDirectory(path)` changes it and returns the validated absolute path. Either method creates an unknown Session without starting a model turn. Relative paths use the Session's current directory. Origin metadata, permissions, and existing processes remain unchanged. `HarnessClient` exposes the same methods with a leading `sessionId` argument.
+
 Use this client when TypeScript code must drive a complete Harness runtime from another process and you can name the runtime executable explicitly. The common path is minimal: construct a `DeepSeekHarness` with a launch spec, run prompts, and close it so the child process is always reaped.
 
 ### Running agent turns with DeepSeekHarness
@@ -51,6 +55,8 @@ The subprocess starts lazily on first use and stays owned by the instance across
 
 `HarnessClient` is the protocol client under the run API: explicit `start()`, `initialize()`, `prompt()`, `request()`, and `close()`, plus notification subscriptions. `prompt()` returns the queued message id as soon as the runtime accepts it and never waits for agent activity. `subscribe(filter?)` returns a `NotificationSubscription` (awaitable `next()`, non-blocking `tryNext()`, async iteration); `subscribeSessionTree(id)` scopes to one session and the descendants discovered from `subagent.started` lineage edges — the runtime notifies for every session in its context, and scoping is client-side, exactly like the Python SDK.
 
+Task-owning consumers can subscribe before `prompt()`, then call `request('session/wait', { sessionId })` and drain queued notifications with `tryNext()`. This waits for managed descendants and their root summary turns; `HarnessSession.run()` retains its next-idle interval. `validatedSessionEvent()` validates the event envelope and the assistant/turn fields consumed by SDK readers before they enter an output fold.
+
 The client exports typed errors for every failure mode: `JsonRpcResponseError` (a wire error response, code and data preserved), `RequestTimeoutError` (a configured bound elapsed), `SdkProtocolError` (a response outside the documented protocol), and `TransportClosedError` (the runtime is gone — the message carries the exit code and a bounded stderr tail). `close()` requests protocol `shutdown` (bounded by `shutdownTimeoutMs`, default 1000 ms), then walks a stdin-EOF → SIGTERM → SIGKILL ladder until the process has exited; it is idempotent, and a closed client refuses reuse. `HarnessClientOptions.env` replaces the child environment entirely when given (`undefined` inherits the parent's); callers own credential policy — `scrubbedParentEnv` from `dsh-subprocess` is the shared scrub base for isolation-minded launches.
 
 -----

package/README.zh.md

@@ -25,6 +25,10 @@ kind: "package-library"
 <a id="use-this-package"></a>
 ## 使用本包
 
+`await harness.resumeSession(savedId)` 从配置的 `dshHome` 恢复持久化会话，并返回可调用 `run()` 的 `HarnessSession`。请保存原会话 id，并沿用其 home 和工作区。恢复会保留对话历史及其目录、修复最后一个被中断的轮次，且不发送新输入。会话缺失、不可读、不兼容或被占用时，请求失败且不创建替代会话。`session(id)` 仍是当前进程内会话的惰性句柄，不会请求持久化恢复。此 API 不恢复 shell、浏览器或其他外部进程。
+
+`HarnessSession.getWorkingDirectory()` 读取有效目录；`setWorkingDirectory(path)` 修改目录并返回校验后的绝对路径。两个方法都可创建未知 Session，而不启动模型轮次。相对路径以 Session 当前目录解析。起始目录元数据、权限与已有进程保持不变。`HarnessClient` 提供同名方法，并以 `sessionId` 作为首个参数。
+
 当 TypeScript 代码需要从另一进程驱动完整 Harness 运行时、且你能显式指名运行时可执行文件时，使用本客户端。常用路径极简：用启动规格构造 `DeepSeekHarness`，运行提示词，然后关闭它，使子进程总能被回收。
 
 ### 用 DeepSeekHarness 运行 agent 轮次
@@ -51,6 +55,8 @@ console.log(result.finalResponse)
 
 `HarnessClient` 是运行 API 之下的协议客户端：显式 `start()`、`initialize()`、`prompt()`、`request()` 与 `close()`，外加通知订阅。`prompt()` 在运行时接受排队消息后立即返回该消息的 id，绝不等待 agent 活动。`subscribe(filter?)` 返回 `NotificationSubscription`（可等待的 `next()`、非阻塞 `tryNext()`、异步迭代）；`subscribeSessionTree(id)` 把范围限定到一个会话及从 `subagent.started` 血缘边发现的后代——运行时对上下文内每个会话都发通知，范围限定在客户端完成，与 Python SDK 完全一致。
 
+拥有完整任务的消费者可以先订阅，再调用 `prompt()`，随后调用 `request('session/wait', { sessionId })`，并通过 `tryNext()` 取完已排队的通知。这会等待受管理后代及其触发的根 Agent 摘要轮次；`HarnessSession.run()` 仍以首次空闲作为活动区间终点。`validatedSessionEvent()` 在事件进入输出折叠前，校验事件封装及 SDK 读取方使用的 assistant／turn 字段。
+
 本客户端为每种失败模式导出类型化错误：`JsonRpcResponseError`（协议错误响应，保留 code 与 data）、`RequestTimeoutError`（配置的时限已到）、`SdkProtocolError`（响应超出文档化协议）、`TransportClosedError`（运行时已消失——消息携带退出码与有界 stderr 尾部）。`close()` 先请求协议 `shutdown`（受 `shutdownTimeoutMs` 约束，默认 1000 毫秒），然后走 stdin-EOF → SIGTERM → SIGKILL 阶梯直到进程退出；幂等，已关闭的客户端拒绝复用。`HarnessClientOptions.env` 给定时整体替换子进程环境（`undefined` 原样继承父进程环境）；凭据策略归调用方——`dsh-subprocess` 的 `scrubbedParentEnv` 是面向隔离启动的共享擦除基底。
 
 -----

package/lib/index.js

@@ -441,6 +441,39 @@ var HarnessClient = class {
 		return result.messageId;
 	}
 	/**
+	* Restore persisted history without sending a prompt; failures propagate without creating a session.
+	* @param sessionId - persisted identity in this runtime's configured persistence store.
+	* @returns after the session is ready for prompts.
+	*/
+	async resumeSession(sessionId) {
+		await this.request("session/resume", { sessionId });
+	}
+	/**
+	* Read a Session's effective working directory, recovering it if missing.
+	* @param sessionId - target Session; an unknown id creates it.
+	* @returns the absolute effective directory.
+	*/
+	getWorkingDirectory(sessionId) {
+		return this.workingDirectoryRequest("session/working-directory/get", { sessionId });
+	}
+	/**
+	* Change a Session's effective directory without changing origin or permissions.
+	* @param sessionId - target Session; an unknown id creates it.
+	* @param path - absolute or Session-current-directory-relative path.
+	* @returns the validated absolute directory.
+	*/
+	setWorkingDirectory(sessionId, path) {
+		return this.workingDirectoryRequest("session/working-directory/set", {
+			sessionId,
+			path
+		});
+	}
+	async workingDirectoryRequest(method, params) {
+		const result = await this.request(method, params);
+		if (!isRecord(result) || typeof result.cwd !== "string") throw new SdkProtocolError(`${method} returned no working directory: ${JSON.stringify(result)}`);
+		return result.cwd;
+	}
+	/**
 	* Send one JSON-RPC request and await its result.
 	* @param method - the wire method name.
 	* @param params - the params object; omitted params send `{}`.
@@ -682,7 +715,7 @@ var DeepSeekHarness = class {
 	}
 	/**
 	* Open a session handle (no wire traffic; the runtime creates the session
-	* on its first prompt).
+	* on its first prompt or working-directory operation).
 	* @param sessionId - explicit id to reuse; omitted mints a fresh one.
 	* @returns the session handle.
 	*/
@@ -690,6 +723,17 @@ var DeepSeekHarness = class {
 		return new HarnessSession(this, sessionId ?? `session-${randomUUID().replaceAll("-", "")}`);
 	}
 	/**
+	* Start the runtime and restore a persisted session without sending input.
+	* The configured Harness home must contain its history; missing or occupied sessions reject.
+	* @param sessionId - exact persisted identity to continue.
+	* @returns a handle ready to run new prompts on the restored history.
+	*/
+	async resumeSession(sessionId) {
+		await this.start();
+		await this.client.resumeSession(sessionId);
+		return new HarnessSession(this, sessionId);
+	}
+	/**
 	* Run one prompt on a fresh (or named) session.
 	* @param input - prompt text, or content blocks sent verbatim.
 	* @param options - optional session id and per-notification observer.
@@ -730,6 +774,23 @@ var HarnessSession = class {
 		this.id = id;
 	}
 	/**
+	* Read the effective directory and recover a missing directory to the Session origin.
+	* @returns the absolute directory used by new independent operations.
+	*/
+	async getWorkingDirectory() {
+		await this.harness.start();
+		return this.harness.client.getWorkingDirectory(this.id);
+	}
+	/**
+	* Change the effective directory without moving existing processes or changing permissions.
+	* @param path - absolute or Session-current-directory-relative directory.
+	* @returns the validated absolute directory.
+	*/
+	async setWorkingDirectory(path) {
+		await this.harness.start();
+		return this.harness.client.setWorkingDirectory(this.id, path);
+	}
+	/**
 	* Queue one prompt, then observe the whole session through its next idle.
 	* @param input - prompt text, or content blocks sent verbatim.
 	* @param options - optional per-notification observer.
@@ -806,7 +867,11 @@ function validatedTurnEndReason(value) {
 	}
 	return value;
 }
-/** Validate the fields in a wire `session.event` envelope before returning the typed result. */
+/**
+* Validate the event envelope and assistant/turn fields consumed by SDK readers.
+* @param value - the raw `session.event` event payload.
+* @returns the event, or throws a protocol error for malformed consumed fields.
+*/
 function validatedSessionEvent(value) {
 	if (!isRecord(value) || typeof value.type !== "string") throw new SdkProtocolError(`session.event carried no event envelope: ${JSON.stringify(value)}`);
 	if (value.type === "assistant/message") {
@@ -841,4 +906,4 @@ function finalResponse(events) {
 	return "";
 }
 //#endregion
-export { DeepSeekHarness, HarnessClient, HarnessSession, JsonRpcResponseError, RequestTimeoutError, SdkProtocolError, TransportClosedError };
+export { DeepSeekHarness, HarnessClient, HarnessSession, JsonRpcResponseError, RequestTimeoutError, SdkProtocolError, TransportClosedError, validatedSessionEvent };

package/lib/types/api.d.ts

@@ -48,11 +48,18 @@ export declare class DeepSeekHarness implements AsyncDisposable {
     start(): Promise<void>;
     /**
      * Open a session handle (no wire traffic; the runtime creates the session
-     * on its first prompt).
+     * on its first prompt or working-directory operation).
      * @param sessionId - explicit id to reuse; omitted mints a fresh one.
      * @returns the session handle.
      */
     session(sessionId?: string): HarnessSession;
+    /**
+     * Start the runtime and restore a persisted session without sending input.
+     * The configured Harness home must contain its history; missing or occupied sessions reject.
+     * @param sessionId - exact persisted identity to continue.
+     * @returns a handle ready to run new prompts on the restored history.
+     */
+    resumeSession(sessionId: string): Promise<HarnessSession>;
     /**
      * Run one prompt on a fresh (or named) session.
      * @param input - prompt text, or content blocks sent verbatim.
@@ -92,6 +99,17 @@ export declare class HarnessSession {
      * @param id - the wire session id this handle runs on.
      */
     constructor(harness: DeepSeekHarness, id: string);
+    /**
+     * Read the effective directory and recover a missing directory to the Session origin.
+     * @returns the absolute directory used by new independent operations.
+     */
+    getWorkingDirectory(): Promise<string>;
+    /**
+     * Change the effective directory without moving existing processes or changing permissions.
+     * @param path - absolute or Session-current-directory-relative directory.
+     * @returns the validated absolute directory.
+     */
+    setWorkingDirectory(path: string): Promise<string>;
     /**
      * Queue one prompt, then observe the whole session through its next idle.
      * @param input - prompt text, or content blocks sent verbatim.
@@ -107,6 +125,12 @@ export declare class HarnessSession {
  * @returns the content blocks to send.
  */
 export declare function normalizeInput(input: string | SdkPromptContentBlock[]): SdkPromptContentBlock[];
+/**
+ * Validate the event envelope and assistant/turn fields consumed by SDK readers.
+ * @param value - the raw `session.event` event payload.
+ * @returns the event, or throws a protocol error for malformed consumed fields.
+ */
+export declare function validatedSessionEvent(value: unknown): SessionEvent;
 /**
  * Extract the concatenated text of the last assistant message.
  * @param events - the activity interval's `session.event` payloads in wire order.

package/lib/types/client.d.ts

@@ -96,6 +96,26 @@ export declare class HarnessClient {
      * @returns the queued message id.
      */
     prompt(sessionId: string, contentBlocks: SdkPromptContentBlock[]): Promise<string>;
+    /**
+     * Restore persisted history without sending a prompt; failures propagate without creating a session.
+     * @param sessionId - persisted identity in this runtime's configured persistence store.
+     * @returns after the session is ready for prompts.
+     */
+    resumeSession(sessionId: string): Promise<void>;
+    /**
+     * Read a Session's effective working directory, recovering it if missing.
+     * @param sessionId - target Session; an unknown id creates it.
+     * @returns the absolute effective directory.
+     */
+    getWorkingDirectory(sessionId: string): Promise<string>;
+    /**
+     * Change a Session's effective directory without changing origin or permissions.
+     * @param sessionId - target Session; an unknown id creates it.
+     * @param path - absolute or Session-current-directory-relative path.
+     * @returns the validated absolute directory.
+     */
+    setWorkingDirectory(sessionId: string, path: string): Promise<string>;
+    private workingDirectoryRequest;
     /**
      * Send one JSON-RPC request and await its result.
      * @param method - the wire method name.

package/lib/types/index.d.ts

@@ -8,7 +8,7 @@
  *
  * @module @deepseek-ai/dsh-sdk-client
  */
-export { DeepSeekHarness, HarnessSession } from './api.ts';
+export { DeepSeekHarness, HarnessSession, validatedSessionEvent } from './api.ts';
 export type { RunOptions } from './api.ts';
 export { HarnessClient, RequestTimeoutError, SdkProtocolError, TransportClosedError, } from './client.ts';
 export type { NotificationSubscription } from './client.ts';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sdk-client",
   "description": "TypeScript client SDK for driving a DeepSeek Harness runtime subprocess over stdio JSON-RPC: the DeepSeekHarness high-level turns API and the lower-level HarnessClient",
-  "version": "0.2.1-alpha.1",
+  "version": "0.2.1-alpha.3",
   "publishConfig": {
     "access": "public"
   },
@@ -26,18 +26,19 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/dsh": "0.2.1-alpha.1"
+    "@deepseek-ai/dsh": "0.2.1-alpha.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-llm": "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/cordis": "~4.0.5-alpha.1"
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sdk-protocol": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-llm": "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/cordis": "~4.0.5-alpha.1"
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sdk-protocol": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@deepseek-ai/dsh-experimental-translator": "0.2.1-alpha.3"
   }
 }