@flowy-agent-store/sdk 0.1.0-beta.10

package/dist/index.mjs

@@ -0,0 +1,467 @@
+import { createRequire } from "node:module";
+import { AppServerClient, WebSocketTransport, isLoopbackUrl } from "@flowy-agent-store/client";
+import { existsSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { createInterface } from "node:readline";
+import { APP_SERVER_PROTOCOL_VERSION } from "@flowy-agent-store/protocol";
+//#region src/bin.ts
+/**
+* Locate the `flowy-agent-store` runtime binary.
+*
+* Order (docs/agent-store/12 §6):
+*   1. explicit `bin` argument (skips every other lookup)
+*   2. `AGENT_STORE_BIN` environment variable
+*   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/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 = ["flowy-agent-store", "flowy-agent-store.exe"];
+function resolveAppServerBin(explicit) {
+	if (explicit && existsSync(explicit)) return explicit;
+	const candidates = [];
+	if (explicit) candidates.push(explicit);
+	const fromEnv = process.env["AGENT_STORE_BIN"];
+	if (fromEnv) candidates.push(fromEnv);
+	const fromRuntimePackage = findInRuntimePackage();
+	if (fromRuntimePackage) candidates.push(fromRuntimePackage);
+	for (const name of BIN_NAMES) {
+		const found = findOnPath(name);
+		if (found) candidates.push(found);
+	}
+	const hit = candidates.find((candidate) => existsSync(candidate));
+	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). */
+function findInRuntimePackage() {
+	const pkg = `@flowy-agent-store/runtime-${process.platform}-${process.arch}`;
+	try {
+		const pkgRoot = createRequire(import.meta.url).resolve(`${pkg}/package.json`).slice(0, -12);
+		for (const name of BIN_NAMES) {
+			const candidate = join(pkgRoot, VENDOR_DIR, name);
+			if (existsSync(candidate)) return candidate;
+		}
+		return;
+	} catch {
+		return;
+	}
+}
+function findOnPath(name) {
+	const pathEnv = process.env["PATH"] ?? process.env["Path"] ?? "";
+	for (const dir of pathEnv.split(delimiter)) {
+		if (!dir) continue;
+		const full = join(dir, name);
+		try {
+			if (existsSync(full)) return full;
+		} catch {}
+	}
+}
+//#endregion
+//#region src/export.ts
+/**
+* Export an expert (single agent) or an expert **team** together with its
+* skills and its package-level assets, written out as a directory (docs `35`
+* and `38`).
+*
+* The wire face (`agent/export` / `team/export`, docs/agent-store/32) carries
+* skills **by reference** — `{name, id}`, never bytes — and, since
+* `pack_format 2`, the plugin-level **assets** by reference too (`{path, kind,
+* size, digest}`, doc 38). "Export the team" therefore means: walk the pack,
+* fetch every referenced skill through `skill/files` + `skill/file`, fetch
+* every asset through `import/assets` + `import/asset`, and write the whole
+* thing to a directory the *caller* owns. Doc `32` §6.5 originally shipped
+* this as an 11-line recipe in prose; doc `35` promoted it into these
+* functions (and records why the earlier decision against an SDK helper was
+* reversed); doc `38` extends the layout with the package's own files.
+*
+* Everything here runs in the caller's process. The host never writes a byte:
+* there is no server-side directory-writing endpoint by design (doc `32` §2
+* item 7), which is why this file is allowed to import `node:fs` — the same
+* privilege `spawn.ts` already has — while `@flowy-agent-store/client` must
+* never gain it.
+*/
+/**
+* Reject a caller-supplied relative path lexically, before touching the disk.
+*
+* The server already rejects traversal on both the skill and the asset faces
+* (docs/agent-store/24 §4.4, 38 §2.3); this second gate keeps a hostile
+* *inventory* from turning `join(dir, path)` into a write outside the target
+* directory. Same rules as the server's lexical pass: no `..`, no absolute
+* paths, no backslashes, no drive/UNC prefixes.
+*/
+function rejectUnsafeRelative(path) {
+	if (path.length === 0 || path.includes("\\") || path.startsWith("/") || path.includes(":")) throw new Error(`unsafe asset path from the host: ${path}`);
+	if (path.split("/").some((segment) => segment === "..")) throw new Error(`unsafe asset path from the host: ${path}`);
+}
+/**
+* Write an in-hand pack to `dir` as a real directory (docs `35` §5 and `38`
+* §3.5). "Materialize" here means exactly that: the in-memory pack object plus
+* the skill and asset bytes it references become files on disk; the pack data
+* itself is unchanged.
+*
+* ```text
+* <dir>/expert-pack.json     # the wire pack, byte-for-byte (JSON.stringify(_, 2))
+* <dir>/persona.md           # kind === "agent" only: pack.persona.instructions
+* <dir>/members/<id>/persona.md  # kind === "team" only, one per member
+* <dir>/skills/<name>/…      # every referenced skill's files, deduplicated by id
+* <dir>/avatars/…            # pack.assets, kind === "avatar", at their snapshot paths
+* <dir>/bin/… · scripts/…    # pack.assets, kind === "script" (doc 38 D5)
+* ```
+*
+* Error semantics (doc `35` §6): the pack is fetched **before** anything is
+* written, so a failed wire export leaves no directory behind; a `skill/files`
+* rejection lands in {@link ExportResult.danglingSkills} and the loop
+* continues; a `skill/file` or `import/asset` rejection after a successful
+* listing **throws** — that is a host I/O failure, and swallowing it would
+* produce a directory that lists files it does not contain. No rollback on
+* mid-write failure.
+*/
+async function materializePack(deps, pack, dir) {
+	await mkdir(dir, { recursive: true });
+	await writeFile(join(dir, "expert-pack.json"), JSON.stringify(pack, null, 2));
+	if (pack.kind === "agent") await writeFile(join(dir, "persona.md"), pack.persona.instructions);
+	for (const member of pack.team?.members ?? []) {
+		const target = join(dir, "members", member.id, "persona.md");
+		await mkdir(dirname(target), { recursive: true });
+		await writeFile(target, member.persona.instructions);
+	}
+	const refs = [...pack.skills, ...(pack.team?.members ?? []).flatMap((m) => m.skills)];
+	const seen = /* @__PURE__ */ new Set();
+	const writtenSkills = [];
+	const danglingSkills = [];
+	for (const ref of refs) {
+		if (seen.has(ref.id)) continue;
+		seen.add(ref.id);
+		let files;
+		try {
+			files = (await deps.skills.files(ref.id)).files;
+		} catch (error) {
+			danglingSkills.push({
+				id: ref.id,
+				error: String(error)
+			});
+			continue;
+		}
+		for (const file of files) {
+			const target = join(dir, "skills", ref.name, file.path);
+			await mkdir(dirname(target), { recursive: true });
+			await writeFile(target, await deps.skills.readFile(ref.id, file.path));
+		}
+		writtenSkills.push(ref.name);
+	}
+	const writtenAssets = [];
+	for (const asset of pack.assets) {
+		rejectUnsafeRelative(asset.path);
+		const target = join(dir, asset.path);
+		await mkdir(dirname(target), { recursive: true });
+		await writeFile(target, await deps.readImportAsset(pack.provenance.snapshot_id, asset.path));
+		writtenAssets.push(asset.path);
+	}
+	return {
+		pack,
+		dir,
+		writtenSkills,
+		writtenAssets,
+		danglingSkills
+	};
+}
+/**
+* Export one single-agent expert and write it out as a directory.
+*
+* Same preconditions as the wire method: the expert must be installed and
+* enabled, or the host answers `agent_not_installed` / `agent_disabled` /
+* `preset_disabled`; a host whose `[expert_export]` table refuses the id
+* answers `policy_denied` (the capability bit only reports the seam). Check
+* `capabilities.expert_export` for the seam, not for this id.
+*/
+async function exportAgent(deps, agentId, dir) {
+	return materializePack(deps, await deps.agents.export(agentId), dir);
+}
+/**
+* Export one expert team and write it out as a directory, leader first.
+*
+* All-or-nothing stays on the server: if any member is uninstalled, disabled,
+* or refused by policy, the whole call fails and nothing is written. A pack
+* over 1 MiB fails with `response_too_large` rather than being truncated.
+* `teamVersion` is an optional pin; a mismatch is `version_mismatch`.
+*/
+async function exportTeam(deps, teamId, dir, teamVersion) {
+	return materializePack(deps, await deps.teams.export(teamId, teamVersion), dir);
+}
+//#endregion
+//#region src/readiness.ts
+/** Parse one stdout line; `null` when it is not the readiness line. */
+function parseReadinessLine(line) {
+	let parsed;
+	try {
+		parsed = JSON.parse(line);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null) return null;
+	const record = parsed;
+	if (record["agent_store"] !== "listening") return null;
+	const { host, port, url, protocol_version, version, auth } = record;
+	if (typeof host !== "string" || typeof port !== "number" || typeof url !== "string" || typeof protocol_version !== "string" || typeof version !== "string" || typeof auth !== "string") return null;
+	return {
+		host,
+		port,
+		url,
+		protocol_version,
+		version,
+		auth
+	};
+}
+//#endregion
+//#region src/spawn.ts
+/**
+* Spawn the `agent-store` runtime as a child process and wait for its
+* readiness line (docs/agent-store/12 P0-1 / P1-3).
+*
+* The child is always loopback-only (`--host 127.0.0.1 --no-open`) with its
+* own data directory (SDK独占, P0-3): a fresh temp dir by default, or an
+* explicit one the caller owns. A server-side single-instance lock fails the
+* spawn fast when the directory is already held — that error propagates.
+*/
+const DEFAULT_READY_TIMEOUT_MS = 12e4;
+const STDERR_TAIL_LINES = 50;
+const KILL_GRACE_MS = 2e3;
+/** Fail when the runtime speaks a different wire protocol (§7 acceptance). */
+function assertProtocolCompatible(runtimeVersion) {
+	if (runtimeVersion !== APP_SERVER_PROTOCOL_VERSION) throw new Error(`protocol version mismatch: runtime speaks ${runtimeVersion}, SDK expects ${APP_SERVER_PROTOCOL_VERSION}`);
+}
+/**
+* The host-policy environment the typed options above expand to.
+*
+* The spawned host cannot be handed backend CLI flags: `apps/agent-store` parses
+* its own argv (`--host` / `--port` / `--data-dir` / `--no-open`) and has no
+* `--agent-store-config`, so a flag would make clap exit before the readiness
+* line. The parent environment is therefore the only channel a launcher has —
+* the same conclusion `NOMI_LOG_LEVEL` already documents for the log filter.
+*/
+function hostPolicyEnv(options) {
+	const env = {};
+	if (options.marketDownload !== void 0) env["AGENT_STORE_MARKET_DOWNLOAD"] = options.marketDownload;
+	if (options.configPath !== void 0) env["AGENT_STORE_CONFIG"] = options.configPath;
+	return env;
+}
+async function spawnAppServer(options = {}) {
+	const bin = resolveAppServerBin(options.bin);
+	const ownedDir = options.dataDir === void 0;
+	const dataDir = ownedDir ? await mkdtemp(join(tmpdir(), "agent-store-sdk-")) : options.dataDir;
+	const port = options.port ?? 0;
+	const policyEnv = {
+		...hostPolicyEnv(options),
+		...options.env
+	};
+	const { child, exited } = spawnRuntimeChild(bin, [
+		"--host",
+		"127.0.0.1",
+		"--port",
+		String(port),
+		"--data-dir",
+		dataDir,
+		"--no-open",
+		...options.extraArgs ?? []
+	], {
+		...Object.keys(policyEnv).length > 0 ? { env: policyEnv } : {},
+		cwd: options.cwd,
+		onExit: options.onExit
+	});
+	const stderrTail = [];
+	child.stderr?.on("data", (chunk) => {
+		for (const line of String(chunk).split(/\r?\n/)) {
+			if (line.length === 0) continue;
+			stderrTail.push(line);
+			if (stderrTail.length > STDERR_TAIL_LINES) stderrTail.shift();
+		}
+	});
+	const stopChild = async () => {
+		if (child.exitCode !== null || child.signalCode !== null) return;
+		child.kill();
+		if (!await new Promise((resolve) => {
+			const timer = setTimeout(() => resolve(false), KILL_GRACE_MS);
+			child.once("exit", () => {
+				clearTimeout(timer);
+				resolve(true);
+			});
+		})) child.kill("SIGKILL");
+	};
+	const fail = async (message) => {
+		await stopChild();
+		if (ownedDir) await rm(dataDir, {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+		const tail = stderrTail.length > 0 ? `\nstderr tail:\n${stderrTail.join("\n")}` : "";
+		throw new Error(`${message}${tail}`);
+	};
+	try {
+		const readiness = await waitForReadiness(child, options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS);
+		try {
+			assertProtocolCompatible(readiness.protocol_version);
+		} catch (error) {
+			await fail(error.message);
+		}
+		let closed = false;
+		return {
+			readiness,
+			dataDir,
+			exited,
+			close: async () => {
+				if (closed) return;
+				closed = true;
+				await stopChild();
+				if (ownedDir) await rm(dataDir, {
+					recursive: true,
+					force: true
+				}).catch(() => void 0);
+			}
+		};
+	} catch (error) {
+		await stopChild();
+		if (ownedDir) await rm(dataDir, {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+		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 stdout = child.stdout;
+		const lines = createInterface({ input: stdout });
+		let settled = false;
+		const fail = (error) => {
+			if (settled) return;
+			settled = true;
+			lines.close();
+			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) return;
+			settled = true;
+			clearTimeout(timer);
+			lines.close();
+			stdout.resume();
+			resolve(readiness);
+		});
+		child.once("error", (error) => {
+			fail(/* @__PURE__ */ new Error(`failed to spawn the runtime: ${error.message}`));
+		});
+		child.once("exit", (code) => {
+			fail(/* @__PURE__ */ new Error(`runtime exited before reporting readiness (code ${code})`));
+		});
+	});
+}
+//#endregion
+//#region src/index.ts
+/**
+* `@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 launchHarness(options) {
+	const server = await spawnAppServer(options);
+	const wsUrl = `ws://${server.readiness.host}:${server.readiness.port}/api/app-server/ws`;
+	if (!isLoopbackUrl(wsUrl)) {
+		await server.close();
+		throw new Error(`refusing to connect outside loopback: ${wsUrl}`);
+	}
+	const client = new AppServerClient({
+		transport: new WebSocketTransport(wsUrl, {
+			requestTimeoutMs: options.requestTimeoutMs,
+			token: options.token
+		}),
+		client: options.client,
+		capabilities: options.capabilities
+	});
+	const closeTransport = client.close.bind(client);
+	try {
+		const handshake = await client.connect();
+		let closed = false;
+		return Object.assign(client, {
+			server,
+			handshake,
+			close: async () => {
+				if (closed) return;
+				closed = true;
+				closeTransport();
+				await server.close();
+			}
+		});
+	} catch (error) {
+		client.close();
+		await server.close();
+		throw error;
+	}
+}
+//#endregion
+export { assertProtocolCompatible, exportAgent, exportTeam, launchHarness, materializePack, parseReadinessLine, resolveAppServerBin, spawnAppServer };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@flowy-agent-store/sdk",
+  "version": "0.1.0-beta.10",
+  "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.10",
+    "@flowy-agent-store/protocol": "0.1.0-beta.10"
+  },
+  "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.10",
+    "@flowy-agent-store/runtime-linux-x64": "0.1.0-beta.10",
+    "@flowy-agent-store/runtime-linux-arm64": "0.1.0-beta.10",
+    "@flowy-agent-store/runtime-darwin-x64": "0.1.0-beta.10",
+    "@flowy-agent-store/runtime-darwin-arm64": "0.1.0-beta.10"
+  }
+}