@flowy-agent-store/sdk 0.1.0-beta.2 → 0.1.0-beta.3

package/dist/index.cjs

@@ -10,7 +10,7 @@ let node_readline = require("node:readline");
 let _flowy_agent_store_protocol = require("@flowy-agent-store/protocol");
 //#region src/bin.ts
 /**
-* Locate the `agent-store` runtime binary.
+* Locate the `flowy-agent-store` runtime binary.
 *
 * Order (docs/agent-store/12 §6):
 *   1. explicit `bin` argument (skips every other lookup)
@@ -18,13 +18,13 @@ let _flowy_agent_store_protocol = require("@flowy-agent-store/protocol");
 *   3. platform runtime package (`@flowy-agent-store/runtime-<platform>-<arch>`,
 *      an optionalDependency of `@flowy-agent-store/sdk`) resolved via
 *      `createRequire(import.meta.url).resolve` — the binary ships inside the
-*      package (`vendor/agent-store[.exe]`)
-*   4. `agent-store[.exe]` on `PATH`
+*      package (`vendor/flowy-agent-store[.exe]`)
+*   4. `flowy-agent-store[.exe]` on `PATH`
 *
 * Anything else is a hard error — the SDK never downloads or guesses.
 */
 const VENDOR_DIR = "vendor";
-const BIN_NAMES = ["agent-store", "agent-store.exe"];
+const BIN_NAMES = ["flowy-agent-store", "flowy-agent-store.exe"];
 function resolveAppServerBin(explicit) {
 	if (explicit && (0, node_fs.existsSync)(explicit)) return explicit;
 	const candidates = [];
@@ -38,7 +38,7 @@ function resolveAppServerBin(explicit) {
 		if (found) candidates.push(found);
 	}
 	const hit = candidates.find((candidate) => (0, node_fs.existsSync)(candidate));
-	if (!hit) throw new Error(`cannot find the agent-store runtime binary: pass \`bin\`, set AGENT_STORE_BIN, install @flowy-agent-store/runtime-${process.platform}-${process.arch} alongside @flowy-agent-store/sdk, or put agent-store[.exe] on PATH`);
+	if (!hit) throw new Error(`cannot find the flowy-agent-store runtime binary: pass \`bin\`, set AGENT_STORE_BIN, install @flowy-agent-store/runtime-${process.platform}-${process.arch} alongside @flowy-agent-store/sdk, or put flowy-agent-store[.exe] on PATH`);
 	return hit;
 }
 /** Probe the platform runtime package for a vendored binary (optional dep). */
@@ -112,7 +112,7 @@ async function spawnAppServer(options = {}) {
 	const ownedDir = options.dataDir === void 0;
 	const dataDir = ownedDir ? await (0, node_fs_promises.mkdtemp)((0, node_path.join)((0, node_os.tmpdir)(), "agent-store-sdk-")) : options.dataDir;
 	const port = options.port ?? 0;
-	const child = (0, node_child_process.spawn)(bin, [
+	const { child, exited } = spawnRuntimeChild(bin, [
 		"--host",
 		"127.0.0.1",
 		"--port",
@@ -121,14 +121,7 @@ async function spawnAppServer(options = {}) {
 		dataDir,
 		"--no-open",
 		...options.extraArgs ?? []
-	], {
-		stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		],
-		windowsHide: true
-	});
+	], options);
 	const stderrTail = [];
 	child.stderr?.on("data", (chunk) => {
 		for (const line of String(chunk).split(/\r?\n/)) {
@@ -168,6 +161,7 @@ async function spawnAppServer(options = {}) {
 		return {
 			readiness,
 			dataDir,
+			exited,
 			close: async () => {
 				if (closed) return;
 				closed = true;
@@ -187,31 +181,77 @@ async function spawnAppServer(options = {}) {
 		throw error;
 	}
 }
+/**
+* Spawn the runtime process and start tracking its exit.
+*
+* Internal (not part of the package entry): exported so the lifecycle and
+* `env` / `cwd` passthrough contract can be exercised with a synthetic child,
+* which is what the managed CLI args normally make impossible to inject.
+*/
+function spawnRuntimeChild(bin, args, options = {}) {
+	const child = (0, node_child_process.spawn)(bin, args, {
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		windowsHide: true,
+		...options.env ? { env: {
+			...process.env,
+			...options.env
+		} } : {},
+		...options.cwd ? { cwd: options.cwd } : {}
+	});
+	return {
+		child,
+		exited: new Promise((resolve) => {
+			child.once("exit", (code, signal) => {
+				const info = {
+					code,
+					signal
+				};
+				resolve(info);
+				try {
+					options.onExit?.(info);
+				} catch {}
+			});
+		})
+	};
+}
+/** Internal: exported for the stdout-backpressure regression test only. */
 function waitForReadiness(child, timeoutMs) {
 	return new Promise((resolve, reject) => {
 		if (!child.stdout) {
 			reject(/* @__PURE__ */ new Error("spawned runtime has no stdout pipe"));
 			return;
 		}
-		const lines = (0, node_readline.createInterface)({ input: child.stdout });
-		const timer = setTimeout(() => {
+		const stdout = child.stdout;
+		const lines = (0, node_readline.createInterface)({ input: stdout });
+		let settled = false;
+		const fail = (error) => {
+			if (settled) return;
+			settled = true;
 			lines.close();
-			reject(/* @__PURE__ */ new Error(`timed out after ${timeoutMs}ms waiting for the runtime readiness line`));
-		}, timeoutMs);
-		const done = (fn) => {
-			clearTimeout(timer);
-			lines.close();
-			fn();
+			reject(error);
 		};
+		const timer = setTimeout(() => {
+			fail(/* @__PURE__ */ new Error(`timed out after ${timeoutMs}ms waiting for the runtime readiness line`));
+		}, timeoutMs);
 		lines.on("line", (line) => {
+			if (settled) return;
 			const readiness = parseReadinessLine(line);
-			if (readiness) done(() => resolve(readiness));
+			if (!readiness) return;
+			settled = true;
+			clearTimeout(timer);
+			lines.close();
+			stdout.resume();
+			resolve(readiness);
 		});
 		child.once("error", (error) => {
-			done(() => reject(/* @__PURE__ */ new Error(`failed to spawn the runtime: ${error.message}`)));
+			fail(/* @__PURE__ */ new Error(`failed to spawn the runtime: ${error.message}`));
 		});
 		child.once("exit", (code) => {
-			done(() => reject(/* @__PURE__ */ new Error(`runtime exited before reporting readiness (code ${code})`)));
+			fail(/* @__PURE__ */ new Error(`runtime exited before reporting readiness (code ${code})`));
 		});
 	});
 }
@@ -262,6 +302,7 @@ async function launchClient(options) {
 	}
 }
 //#endregion
+exports.assertProtocolCompatible = assertProtocolCompatible;
 exports.launchClient = launchClient;
 exports.parseReadinessLine = parseReadinessLine;
 exports.resolveAppServerBin = resolveAppServerBin;

package/dist/index.d.cts

@@ -23,6 +23,8 @@ interface ReadinessInfo {
 export declare function parseReadinessLine(line: string): ReadinessInfo | null;
 //#endregion
 //#region src/spawn.d.ts
+/** Fail when the runtime speaks a different wire protocol (§7 acceptance). */
+export declare function assertProtocolCompatible(runtimeVersion: string): void;
 interface SpawnOptions {
   /** Explicit binary path (overrides `AGENT_STORE_BIN` / `PATH`). */
   bin?: string;
@@ -34,10 +36,29 @@ interface SpawnOptions {
   extraArgs?: string[];
   /** How long to wait for the readiness line. Defaults to 120s (cold DB init). */
   readyTimeoutMs?: number;
+  /** Extra environment variables, merged over the parent's `process.env`. */
+  env?: Record<string, string | undefined>;
+  /** Working directory for the child. Defaults to the parent's cwd. */
+  cwd?: string;
+  /** Called once when the child exits, for any reason (crash included). */
+  onExit?: (info: SpawnExitInfo) => void;
+}
+/** How a spawned runtime process ended. */
+interface SpawnExitInfo {
+  /** Exit code, or `null` when the process was terminated by a signal. */
+  code: number | null;
+  /** Terminating signal, or `null` on a normal exit. */
+  signal: string | null;
 }
 interface SpawnedServer {
   readonly readiness: ReadinessInfo;
   readonly dataDir: string;
+  /**
+   * Settles when the runtime process exits — including an unexpected crash,
+   * which is otherwise indistinguishable from "still starting up". Never
+   * rejects: inspect `code` / `signal`.
+   */
+  readonly exited: Promise<SpawnExitInfo>;
   /** Terminate the child and remove the data dir when it was auto-created. */
   close(): Promise<void>;
 }
@@ -64,4 +85,4 @@ export interface LaunchedClient {
  */
 export declare function launchClient(options: LaunchOptions): Promise<LaunchedClient>;
 //#endregion
-export type { ReadinessInfo, SpawnOptions, SpawnedServer };
+export type { ReadinessInfo, SpawnExitInfo, SpawnOptions, SpawnedServer };

package/dist/index.d.mts

@@ -23,6 +23,8 @@ interface ReadinessInfo {
 export declare function parseReadinessLine(line: string): ReadinessInfo | null;
 //#endregion
 //#region src/spawn.d.ts
+/** Fail when the runtime speaks a different wire protocol (§7 acceptance). */
+export declare function assertProtocolCompatible(runtimeVersion: string): void;
 interface SpawnOptions {
   /** Explicit binary path (overrides `AGENT_STORE_BIN` / `PATH`). */
   bin?: string;
@@ -34,10 +36,29 @@ interface SpawnOptions {
   extraArgs?: string[];
   /** How long to wait for the readiness line. Defaults to 120s (cold DB init). */
   readyTimeoutMs?: number;
+  /** Extra environment variables, merged over the parent's `process.env`. */
+  env?: Record<string, string | undefined>;
+  /** Working directory for the child. Defaults to the parent's cwd. */
+  cwd?: string;
+  /** Called once when the child exits, for any reason (crash included). */
+  onExit?: (info: SpawnExitInfo) => void;
+}
+/** How a spawned runtime process ended. */
+interface SpawnExitInfo {
+  /** Exit code, or `null` when the process was terminated by a signal. */
+  code: number | null;
+  /** Terminating signal, or `null` on a normal exit. */
+  signal: string | null;
 }
 interface SpawnedServer {
   readonly readiness: ReadinessInfo;
   readonly dataDir: string;
+  /**
+   * Settles when the runtime process exits — including an unexpected crash,
+   * which is otherwise indistinguishable from "still starting up". Never
+   * rejects: inspect `code` / `signal`.
+   */
+  readonly exited: Promise<SpawnExitInfo>;
   /** Terminate the child and remove the data dir when it was auto-created. */
   close(): Promise<void>;
 }
@@ -64,4 +85,4 @@ export interface LaunchedClient {
  */
 export declare function launchClient(options: LaunchOptions): Promise<LaunchedClient>;
 //#endregion
-export type { ReadinessInfo, SpawnOptions, SpawnedServer };
+export type { ReadinessInfo, SpawnExitInfo, SpawnOptions, SpawnedServer };

package/dist/index.mjs

@@ -9,7 +9,7 @@ import { createInterface } from "node:readline";
 import { APP_SERVER_PROTOCOL_VERSION } from "@flowy-agent-store/protocol";
 //#region src/bin.ts
 /**
-* Locate the `agent-store` runtime binary.
+* Locate the `flowy-agent-store` runtime binary.
 *
 * Order (docs/agent-store/12 §6):
 *   1. explicit `bin` argument (skips every other lookup)
@@ -17,13 +17,13 @@ import { APP_SERVER_PROTOCOL_VERSION } from "@flowy-agent-store/protocol";
 *   3. platform runtime package (`@flowy-agent-store/runtime-<platform>-<arch>`,
 *      an optionalDependency of `@flowy-agent-store/sdk`) resolved via
 *      `createRequire(import.meta.url).resolve` — the binary ships inside the
-*      package (`vendor/agent-store[.exe]`)
-*   4. `agent-store[.exe]` on `PATH`
+*      package (`vendor/flowy-agent-store[.exe]`)
+*   4. `flowy-agent-store[.exe]` on `PATH`
 *
 * Anything else is a hard error — the SDK never downloads or guesses.
 */
 const VENDOR_DIR = "vendor";
-const BIN_NAMES = ["agent-store", "agent-store.exe"];
+const BIN_NAMES = ["flowy-agent-store", "flowy-agent-store.exe"];
 function resolveAppServerBin(explicit) {
 	if (explicit && existsSync(explicit)) return explicit;
 	const candidates = [];
@@ -37,7 +37,7 @@ function resolveAppServerBin(explicit) {
 		if (found) candidates.push(found);
 	}
 	const hit = candidates.find((candidate) => existsSync(candidate));
-	if (!hit) throw new Error(`cannot find the agent-store runtime binary: pass \`bin\`, set AGENT_STORE_BIN, install @flowy-agent-store/runtime-${process.platform}-${process.arch} alongside @flowy-agent-store/sdk, or put agent-store[.exe] on PATH`);
+	if (!hit) throw new Error(`cannot find the flowy-agent-store runtime binary: pass \`bin\`, set AGENT_STORE_BIN, install @flowy-agent-store/runtime-${process.platform}-${process.arch} alongside @flowy-agent-store/sdk, or put flowy-agent-store[.exe] on PATH`);
 	return hit;
 }
 /** Probe the platform runtime package for a vendored binary (optional dep). */
@@ -111,7 +111,7 @@ async function spawnAppServer(options = {}) {
 	const ownedDir = options.dataDir === void 0;
 	const dataDir = ownedDir ? await mkdtemp(join(tmpdir(), "agent-store-sdk-")) : options.dataDir;
 	const port = options.port ?? 0;
-	const child = spawn(bin, [
+	const { child, exited } = spawnRuntimeChild(bin, [
 		"--host",
 		"127.0.0.1",
 		"--port",
@@ -120,14 +120,7 @@ async function spawnAppServer(options = {}) {
 		dataDir,
 		"--no-open",
 		...options.extraArgs ?? []
-	], {
-		stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		],
-		windowsHide: true
-	});
+	], options);
 	const stderrTail = [];
 	child.stderr?.on("data", (chunk) => {
 		for (const line of String(chunk).split(/\r?\n/)) {
@@ -167,6 +160,7 @@ async function spawnAppServer(options = {}) {
 		return {
 			readiness,
 			dataDir,
+			exited,
 			close: async () => {
 				if (closed) return;
 				closed = true;
@@ -186,31 +180,77 @@ async function spawnAppServer(options = {}) {
 		throw error;
 	}
 }
+/**
+* Spawn the runtime process and start tracking its exit.
+*
+* Internal (not part of the package entry): exported so the lifecycle and
+* `env` / `cwd` passthrough contract can be exercised with a synthetic child,
+* which is what the managed CLI args normally make impossible to inject.
+*/
+function spawnRuntimeChild(bin, args, options = {}) {
+	const child = spawn(bin, args, {
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		windowsHide: true,
+		...options.env ? { env: {
+			...process.env,
+			...options.env
+		} } : {},
+		...options.cwd ? { cwd: options.cwd } : {}
+	});
+	return {
+		child,
+		exited: new Promise((resolve) => {
+			child.once("exit", (code, signal) => {
+				const info = {
+					code,
+					signal
+				};
+				resolve(info);
+				try {
+					options.onExit?.(info);
+				} catch {}
+			});
+		})
+	};
+}
+/** Internal: exported for the stdout-backpressure regression test only. */
 function waitForReadiness(child, timeoutMs) {
 	return new Promise((resolve, reject) => {
 		if (!child.stdout) {
 			reject(/* @__PURE__ */ new Error("spawned runtime has no stdout pipe"));
 			return;
 		}
-		const lines = createInterface({ input: child.stdout });
-		const timer = setTimeout(() => {
+		const stdout = child.stdout;
+		const lines = createInterface({ input: stdout });
+		let settled = false;
+		const fail = (error) => {
+			if (settled) return;
+			settled = true;
 			lines.close();
-			reject(/* @__PURE__ */ new Error(`timed out after ${timeoutMs}ms waiting for the runtime readiness line`));
-		}, timeoutMs);
-		const done = (fn) => {
-			clearTimeout(timer);
-			lines.close();
-			fn();
+			reject(error);
 		};
+		const timer = setTimeout(() => {
+			fail(/* @__PURE__ */ new Error(`timed out after ${timeoutMs}ms waiting for the runtime readiness line`));
+		}, timeoutMs);
 		lines.on("line", (line) => {
+			if (settled) return;
 			const readiness = parseReadinessLine(line);
-			if (readiness) done(() => resolve(readiness));
+			if (!readiness) return;
+			settled = true;
+			clearTimeout(timer);
+			lines.close();
+			stdout.resume();
+			resolve(readiness);
 		});
 		child.once("error", (error) => {
-			done(() => reject(/* @__PURE__ */ new Error(`failed to spawn the runtime: ${error.message}`)));
+			fail(/* @__PURE__ */ new Error(`failed to spawn the runtime: ${error.message}`));
 		});
 		child.once("exit", (code) => {
-			done(() => reject(/* @__PURE__ */ new Error(`runtime exited before reporting readiness (code ${code})`)));
+			fail(/* @__PURE__ */ new Error(`runtime exited before reporting readiness (code ${code})`));
 		});
 	});
 }
@@ -261,4 +301,4 @@ async function launchClient(options) {
 	}
 }
 //#endregion
-export { launchClient, parseReadinessLine, resolveAppServerBin, spawnAppServer };
+export { assertProtocolCompatible, launchClient, parseReadinessLine, resolveAppServerBin, spawnAppServer };

package/package.json

@@ -1,40 +1,49 @@
-{
-  "name": "@flowy-agent-store/sdk",
-  "version": "0.1.0-beta.2",
-  "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",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.mts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist"
-  ],
-  "dependencies": {
-    "@flowy-agent-store/client": "0.1.0-beta.2",
-    "@flowy-agent-store/protocol": "0.1.0-beta.2"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "prepack": "tsdown"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.mts",
-  "optionalDependencies": {
-    "@flowy-agent-store/runtime-win32-x64": "0.1.0-beta.2",
-    "@flowy-agent-store/runtime-linux-x64": "0.1.0-beta.2",
-    "@flowy-agent-store/runtime-linux-arm64": "0.1.0-beta.2",
-    "@flowy-agent-store/runtime-darwin-x64": "0.1.0-beta.2",
-    "@flowy-agent-store/runtime-darwin-arm64": "0.1.0-beta.2"
-  }
-}
+{
+  "name": "@flowy-agent-store/sdk",
+  "version": "0.1.0-beta.3",
+  "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",
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Michael-Lfx/allo.git",
+    "directory": "web/packages/sdk"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@flowy-agent-store/client": "0.1.0-beta.3",
+    "@flowy-agent-store/protocol": "0.1.0-beta.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "optionalDependencies": {
+    "@flowy-agent-store/runtime-win32-x64": "0.1.0-beta.3",
+    "@flowy-agent-store/runtime-linux-x64": "0.1.0-beta.3",
+    "@flowy-agent-store/runtime-linux-arm64": "0.1.0-beta.3",
+    "@flowy-agent-store/runtime-darwin-x64": "0.1.0-beta.3",
+    "@flowy-agent-store/runtime-darwin-arm64": "0.1.0-beta.3"
+  }
+}