@flowy-agent-store/sdk 0.1.0-beta.4 → 0.1.0-beta.6

package/README.md

@@ -3,32 +3,35 @@
 Node.js host for the Agent Store runtime (`docs/agent-store/12-sdk-packaging.md P1-3`): spawn `agent-store`, wait for its stdout readiness line, connect over loopback with `@flowy-agent-store/client`.
 
 ```ts
-import { launchClient } from "@flowy-agent-store/sdk";
+import { launchHarness } from "@flowy-agent-store/sdk";
 
-const session = await launchClient({
+const harness = await launchHarness({
   client: { name: "my-app", version: "0.1.0" },
 });
 
 // 获取：浏览 / 搜索目录（含每个条目的安装状态）
-const items = await session.client.store.search("software");
+const items = await harness.store.search("software");
 
 // 安装：导入 + 注册，并等到组件真的可用（默认 waitForReady: true）
-const outcome = await session.client.store.install(items[0]);
+const outcome = await harness.store.install(items[0]);
 if (outcome.readyIssue === "authorization_required") {
-  await session.client.connectors.authStart(outcome.readyComponentId!);
+  await harness.connectors.authStart(outcome.readyComponentId!);
 }
 
 // 禁用 / 启用：连接器改 mcp_servers.enabled，专家/专家团改 Preset.enabled
-await session.client.store.setEnabled(items[0], false);
+await harness.store.setEnabled(items[0], false);
 
 // 卸载：真的释放运行时产物（技能目录 / Preset / MCP server 行），再清记录
-const released = await session.client.store.uninstall(items[0]);
+const released = await harness.store.uninstall(items[0]);
 if (!released.ok) console.warn(released.components.filter((c) => !c.ok));
 
-await session.close();
+// 一次 close 收掉传输与子进程（退订 → 关传输 → 杀进程 → 删临时 data-dir）
+await harness.close();
 ```
 
-五个动词都在 SDK 里可用，但**都不在 `@flowy-agent-store/sdk` 这个包里**：本包只负责进程与传输，方法来自 `@flowy-agent-store/client`，其中 `store` 子客户端把 `install` / `uninstall` / `setEnabled` 编排成一条状态机（`search → install → … → uninstall`）。这样分层是刻意的——见 `docs/agent-store/12-sdk-packaging.md` §2 的职责划分。
+**`launchHarness` 解析出的对象就是那个 client**（`docs/agent-store/31` §5 方案 B）：`harness.store` / `harness.conversations` / `harness.models` 直接可用，没有 `.client` 一跳；子进程是 `harness.server`（`readiness` / `dataDir` / `exited`），握手响应是 `harness.handshake`。
+
+五个动词都在 SDK 里可用，但**它们不是 `@flowy-agent-store/sdk` 自己实现的**：本包只负责进程与传输，返回的对象就是一个 `@flowy-agent-store/client` 的 `AppServerClient`（sdk 另挂 `server` / `handshake` / `close()`），其中 `store` 子客户端把 `install` / `uninstall` / `setEnabled` 编排成一条状态机（`search → install → … → uninstall`）。这样分层是刻意的——见 `docs/agent-store/12-sdk-packaging.md` §2 的职责划分。
 
 几条使用上的事实（都是实测结论，不是约定）：
 
@@ -44,7 +47,7 @@ await session.close();
 - 工具面不用改宿主自己的 `~/.agent-store/config.toml`：`env.AGENT_STORE_TOOLS` 直接指定，值是 JSON（形状同 `[tools]` 表），**整份替换**文件里的策略，`{}` = 全开。它只在 Store 宿主生效（桌面 / Web 宿主不采纳 `[tools]`），且子进程启动时读一次。
 
   ```ts
-  const session = await launchClient({
+  const harness = await launchHarness({
     client: { name: "my-app", version: "0.1.0" },
     env: {
       // 只要基础能力：关掉桌面控制/浏览器与几个域
@@ -61,4 +64,4 @@ await session.close();
 - 二进制定位：`bin` 参数 → `AGENT_STORE_BIN` → 平台 runtime 包的 `vendor/` → `PATH`；找不到直接报错（**不下载**，见 P2）。
 - 就绪行 `protocol_version` 与 SDK 不一致时杀掉子进程并报错（含两端版本）。该值是**契约指纹**，不是版本号：任何 wire 变更都会 bump。
 
-不在本包范围内（`07-typescript-sdk.md` §非目标）：`config/*` 与 `skill/*` 写面。它们的**类型**在 `@flowy-agent-store/protocol`（wire 上存在的方法就有形状），但**没有** typed 方法——因为这些面跟着宿主自己的设置文件与技能目录走，是最易变的部分。这是可发现性边界，不是权限边界：`client.transport` 是公开的，服务端按磁盘归属判定可写性。要用就直连 `transport.request`，并自担变动。
+不在本包范围内（`07-typescript-sdk.md` §非目标）：`config/*` 与 `skill/*` 写面。它们的**类型**在 `@flowy-agent-store/protocol`（wire 上存在的方法就有形状），但**没有** typed 方法——因为这些面跟着宿主自己的设置文件与技能目录走，是最易变的部分。这是可发现性边界，不是权限边界：`harness.transport` 是公开的，服务端按磁盘归属判定可写性。要用就直连 `transport.request`，并自担变动。

package/dist/index.cjs

@@ -260,13 +260,21 @@ function waitForReadiness(child, timeoutMs) {
 /**
 * `@flowy-agent-store/sdk` — spawn the runtime, connect over loopback, hand back
 * a ready `AppServerClient`.
+*
+* The object `launchHarness` resolves to **is** that client (doc `31`): the
+* `conversations` / `store` / `agents` surface sits on it directly, and the
+* process it owns is reachable as `server` / `handshake` / `close()`. That is
+* the shape both external references use — Codex's
+* `with Codex(...) as codex: codex.thread_start(...)` and Kimi Code's
+* `const harness = createKimiHarness(...); harness.createSession(...)` — the
+* factory returns the main object, lifecycle included, with no `.client` hop.
 */
 /**
 * Spawn a loopback runtime with its own data dir and return a connected,
 * initialized client. Rejects non-loopback contact outright (P0-4): this
 * entry point only ever dials the process it just spawned.
 */
-async function launchClient(options) {
+async function launchHarness(options) {
 	const server = await spawnAppServer(options);
 	const wsUrl = `ws://${server.readiness.host}:${server.readiness.port}/api/app-server/ws`;
 	if (!(0, _flowy_agent_store_client.isLoopbackUrl)(wsUrl)) {
@@ -281,20 +289,20 @@ async function launchClient(options) {
 		client: options.client,
 		capabilities: options.capabilities
 	});
+	const closeTransport = client.close.bind(client);
 	try {
-		const initializeResult = await client.connect();
+		const handshake = await client.connect();
 		let closed = false;
-		return {
+		return Object.assign(client, {
 			server,
-			client,
-			initializeResult,
+			handshake,
 			close: async () => {
 				if (closed) return;
 				closed = true;
-				client.close();
+				closeTransport();
 				await server.close();
 			}
-		};
+		});
 	} catch (error) {
 		client.close();
 		await server.close();
@@ -303,7 +311,7 @@ async function launchClient(options) {
 }
 //#endregion
 exports.assertProtocolCompatible = assertProtocolCompatible;
-exports.launchClient = launchClient;
+exports.launchHarness = launchHarness;
 exports.parseReadinessLine = parseReadinessLine;
 exports.resolveAppServerBin = resolveAppServerBin;
 exports.spawnAppServer = spawnAppServer;

package/dist/index.d.cts

@@ -65,17 +65,46 @@ interface SpawnedServer {
 export declare function spawnAppServer(options?: SpawnOptions): Promise<SpawnedServer>;
 //#endregion
 //#region src/index.d.ts
-export interface LaunchOptions extends SpawnOptions {
+export interface HarnessOptions extends SpawnOptions {
   client: ClientInfo;
   capabilities?: ClientCapabilities;
   token?: string;
   requestTimeoutMs?: number;
 }
-export interface LaunchedClient {
-  server: SpawnedServer;
-  client: AppServerClient;
-  initializeResult: InitializeResult;
-  /** Disconnect and terminate the spawned runtime. */
+/**
+ * A connected `AppServerClient` that **owns the runtime process it spawned**
+ * (doc `31` §5 方案 B).
+ *
+ * Every `AppServerClient` member is available directly — `conversations`,
+ * `store`, `agents`, `onNotification`, … — because a factory that returned a
+ * *wrapper* was the lie this shape removes.
+ *
+ * Named after the external reference this shape follows (doc `31` §3.2):
+ * Kimi Code's `const harness = createKimiHarness(...)` hands back a `harness`
+ * you keep for the whole life of the run, not a one-shot launcher.
+ */
+export interface Harness extends AppServerClient {
+  /** The child process: `readiness` / `dataDir` / `exited` / `close`. */
+  readonly server: SpawnedServer;
+  /**
+   * The handshake response captured at launch (**never null**).
+   *
+   * Not named `initializeResult`: that is a private field of the base class
+   * (`client.ts`), and the base's public `initializeInfo` is the *current*
+   * connection state — it goes back to `null` after `close()`. This member is
+   * the snapshot that proves which protocol fingerprint the session was
+   * admitted under.
+   */
+  readonly handshake: InitializeResult;
+  /**
+   * Unsubscribe → close the transport → terminate the child → remove an
+   * auto-created data dir. Idempotent.
+   *
+   * Deliberately widens the base's synchronous `close(): void`: awaiting a
+   * void-returning call is legal, so callers holding a plain `AppServerClient`
+   * are unaffected, while a launched session needs the promise to know the
+   * process is actually gone.
+   */
   close(): Promise<void>;
 }
 /**
@@ -83,6 +112,6 @@ export interface LaunchedClient {
  * initialized client. Rejects non-loopback contact outright (P0-4): this
  * entry point only ever dials the process it just spawned.
  */
-export declare function launchClient(options: LaunchOptions): Promise<LaunchedClient>;
+export declare function launchHarness(options: HarnessOptions): Promise<Harness>;
 //#endregion
 export type { ReadinessInfo, SpawnExitInfo, SpawnOptions, SpawnedServer };

package/dist/index.d.mts

@@ -65,17 +65,46 @@ interface SpawnedServer {
 export declare function spawnAppServer(options?: SpawnOptions): Promise<SpawnedServer>;
 //#endregion
 //#region src/index.d.ts
-export interface LaunchOptions extends SpawnOptions {
+export interface HarnessOptions extends SpawnOptions {
   client: ClientInfo;
   capabilities?: ClientCapabilities;
   token?: string;
   requestTimeoutMs?: number;
 }
-export interface LaunchedClient {
-  server: SpawnedServer;
-  client: AppServerClient;
-  initializeResult: InitializeResult;
-  /** Disconnect and terminate the spawned runtime. */
+/**
+ * A connected `AppServerClient` that **owns the runtime process it spawned**
+ * (doc `31` §5 方案 B).
+ *
+ * Every `AppServerClient` member is available directly — `conversations`,
+ * `store`, `agents`, `onNotification`, … — because a factory that returned a
+ * *wrapper* was the lie this shape removes.
+ *
+ * Named after the external reference this shape follows (doc `31` §3.2):
+ * Kimi Code's `const harness = createKimiHarness(...)` hands back a `harness`
+ * you keep for the whole life of the run, not a one-shot launcher.
+ */
+export interface Harness extends AppServerClient {
+  /** The child process: `readiness` / `dataDir` / `exited` / `close`. */
+  readonly server: SpawnedServer;
+  /**
+   * The handshake response captured at launch (**never null**).
+   *
+   * Not named `initializeResult`: that is a private field of the base class
+   * (`client.ts`), and the base's public `initializeInfo` is the *current*
+   * connection state — it goes back to `null` after `close()`. This member is
+   * the snapshot that proves which protocol fingerprint the session was
+   * admitted under.
+   */
+  readonly handshake: InitializeResult;
+  /**
+   * Unsubscribe → close the transport → terminate the child → remove an
+   * auto-created data dir. Idempotent.
+   *
+   * Deliberately widens the base's synchronous `close(): void`: awaiting a
+   * void-returning call is legal, so callers holding a plain `AppServerClient`
+   * are unaffected, while a launched session needs the promise to know the
+   * process is actually gone.
+   */
   close(): Promise<void>;
 }
 /**
@@ -83,6 +112,6 @@ export interface LaunchedClient {
  * initialized client. Rejects non-loopback contact outright (P0-4): this
  * entry point only ever dials the process it just spawned.
  */
-export declare function launchClient(options: LaunchOptions): Promise<LaunchedClient>;
+export declare function launchHarness(options: HarnessOptions): Promise<Harness>;
 //#endregion
 export type { ReadinessInfo, SpawnExitInfo, SpawnOptions, SpawnedServer };

package/dist/index.mjs

@@ -259,13 +259,21 @@ function waitForReadiness(child, timeoutMs) {
 /**
 * `@flowy-agent-store/sdk` — spawn the runtime, connect over loopback, hand back
 * a ready `AppServerClient`.
+*
+* The object `launchHarness` resolves to **is** that client (doc `31`): the
+* `conversations` / `store` / `agents` surface sits on it directly, and the
+* process it owns is reachable as `server` / `handshake` / `close()`. That is
+* the shape both external references use — Codex's
+* `with Codex(...) as codex: codex.thread_start(...)` and Kimi Code's
+* `const harness = createKimiHarness(...); harness.createSession(...)` — the
+* factory returns the main object, lifecycle included, with no `.client` hop.
 */
 /**
 * Spawn a loopback runtime with its own data dir and return a connected,
 * initialized client. Rejects non-loopback contact outright (P0-4): this
 * entry point only ever dials the process it just spawned.
 */
-async function launchClient(options) {
+async function launchHarness(options) {
 	const server = await spawnAppServer(options);
 	const wsUrl = `ws://${server.readiness.host}:${server.readiness.port}/api/app-server/ws`;
 	if (!isLoopbackUrl(wsUrl)) {
@@ -280,20 +288,20 @@ async function launchClient(options) {
 		client: options.client,
 		capabilities: options.capabilities
 	});
+	const closeTransport = client.close.bind(client);
 	try {
-		const initializeResult = await client.connect();
+		const handshake = await client.connect();
 		let closed = false;
-		return {
+		return Object.assign(client, {
 			server,
-			client,
-			initializeResult,
+			handshake,
 			close: async () => {
 				if (closed) return;
 				closed = true;
-				client.close();
+				closeTransport();
 				await server.close();
 			}
-		};
+		});
 	} catch (error) {
 		client.close();
 		await server.close();
@@ -301,4 +309,4 @@ async function launchClient(options) {
 	}
 }
 //#endregion
-export { assertProtocolCompatible, launchClient, parseReadinessLine, resolveAppServerBin, spawnAppServer };
+export { assertProtocolCompatible, launchHarness, parseReadinessLine, resolveAppServerBin, spawnAppServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowy-agent-store/sdk",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "description": "Node.js host for the Agent Store App Server: spawn the runtime binary and connect over loopback (docs/agent-store/12 P1-3)",
   "type": "module",
   "license": "Apache-2.0",
@@ -25,8 +25,8 @@
     "dist"
   ],
   "dependencies": {
-    "@flowy-agent-store/client": "0.1.0-beta.4",
-    "@flowy-agent-store/protocol": "0.1.0-beta.4"
+    "@flowy-agent-store/client": "0.1.0-beta.6",
+    "@flowy-agent-store/protocol": "0.1.0-beta.6"
   },
   "scripts": {
     "build": "tsdown",
@@ -40,10 +40,10 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "optionalDependencies": {
-    "@flowy-agent-store/runtime-win32-x64": "0.1.0-beta.4",
-    "@flowy-agent-store/runtime-linux-x64": "0.1.0-beta.4",
-    "@flowy-agent-store/runtime-linux-arm64": "0.1.0-beta.4",
-    "@flowy-agent-store/runtime-darwin-x64": "0.1.0-beta.4",
-    "@flowy-agent-store/runtime-darwin-arm64": "0.1.0-beta.4"
+    "@flowy-agent-store/runtime-win32-x64": "0.1.0-beta.6",
+    "@flowy-agent-store/runtime-linux-x64": "0.1.0-beta.6",
+    "@flowy-agent-store/runtime-linux-arm64": "0.1.0-beta.6",
+    "@flowy-agent-store/runtime-darwin-x64": "0.1.0-beta.6",
+    "@flowy-agent-store/runtime-darwin-arm64": "0.1.0-beta.6"
   }
 }