@deepseek-ai/dsh-sdk-client 0.2.0-rc.2 → 0.2.1-alpha.2

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: 316b142489dd050f
+  zh: 2b37ae57b2a52b5e
 /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
@@ -30,8 +30,8 @@
   en: 6632c06d819233cc
   zh: 207d55d8217ec6b1
 /deepseek-ai-dsh-sdk-client/understand-the-implementation/source-map:
-  en: f8a986c22b7a2953
-  zh: 35937eb44e1ee909
+  en: a3c7978a80f5aba3
+  zh: fdc4dfdafd2eccfa
 /deepseek-ai-dsh-sdk-client/understand-the-implementation/owned-activity-flow:
   en: 94a42babac5f1c7d
   zh: df9e42ed02f7d002

package/README.md

@@ -25,6 +25,8 @@ English | [中文](README.zh.md)
 <a id="use-this-package"></a>
 ## Use this package
 
+`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 +53,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.
 
 -----
@@ -76,7 +80,6 @@ The client is two layers over one wire: `DeepSeekHarness` (owned runs) over `Har
 | [`src/dispose.ts`](src/dispose.ts) | Private teardown ladder: stdin EOF → SIGTERM → SIGKILL to actual exit |
 | [`src/types.ts`](src/types.ts) | Launch and timeout options, notification shapes, `RunResult` |
 | [`src/index.ts`](src/index.ts) | Consumer interface: the two client layers and caller-facing types |
-| — | No runtime invariant companion is published; this client library runs outside any harness context (its peer is a separate runtime process); the runtime's own packages own the event-stream relations. |
 
 ### Owned activity flow
 

package/README.zh.md

@@ -25,6 +25,8 @@ kind: "package-library"
 <a id="use-this-package"></a>
 ## 使用本包
 
+`HarnessSession.getWorkingDirectory()` 读取有效目录；`setWorkingDirectory(path)` 修改目录并返回校验后的绝对路径。两个方法都可创建未知 Session，而不启动模型轮次。相对路径以 Session 当前目录解析。起始目录元数据、权限与已有进程保持不变。`HarnessClient` 提供同名方法，并以 `sessionId` 作为首个参数。
+
 当 TypeScript 代码需要从另一进程驱动完整 Harness 运行时、且你能显式指名运行时可执行文件时，使用本客户端。常用路径极简：用启动规格构造 `DeepSeekHarness`，运行提示词，然后关闭它，使子进程总能被回收。
 
 ### 用 DeepSeekHarness 运行 agent 轮次
@@ -51,6 +53,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` 是面向隔离启动的共享擦除基底。
 
 -----
@@ -76,7 +80,6 @@ console.log(result.finalResponse)
 | [`src/dispose.ts`](src/dispose.ts) | 私有关闭阶梯：stdin EOF → SIGTERM → SIGKILL 直到真正退出 |
 | [`src/types.ts`](src/types.ts) | 启动与超时选项、通知结构、`RunResult` |
 | [`src/index.ts`](src/index.ts) | 消费方接口：两层客户端与面向调用方的类型 |
-| — | 不发布运行时不变式伴生入口；本客户端库运行在任何 harness 上下文之外（其对端是独立运行时进程）；运行时自身的包负责维护事件流关系。 |
 
 ### 自有活动流程
 

package/lib/index.js

@@ -441,6 +441,31 @@ var HarnessClient = class {
 		return result.messageId;
 	}
 	/**
+	* 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 +707,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.
 	*/
@@ -730,6 +755,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 +848,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 +887,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,7 +48,7 @@ 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.
      */
@@ -92,6 +92,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 +118,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,20 @@ export declare class HarnessClient {
      * @returns the queued message id.
      */
     prompt(sessionId: string, contentBlocks: SdkPromptContentBlock[]): Promise<string>;
+    /**
+     * 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.0-rc.2",
+  "version": "0.2.1-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -26,18 +26,19 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/dsh": "0.2.0-rc.2"
+    "@deepseek-ai/dsh": "0.2.1-alpha.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-sdk-protocol": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
-    "@deepseek-ai/cordis": "~4.0.4"
+    "@deepseek-ai/dsh-llm": "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/cordis": "~4.0.5-alpha.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-sdk-protocol": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
-    "@deepseek-ai/cordis": "~4.0.4"
+    "@deepseek-ai/dsh-llm": "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/cordis": "~4.0.5-alpha.1",
+    "@deepseek-ai/dsh-experimental-translator": "0.2.1-alpha.2"
   }
 }