@flowy-agent-store/sdk 0.1.0-beta.7 → 0.1.0-beta.8

package/README.md

@@ -15,7 +15,17 @@ const items = await harness.store.search("software");
 // 安装：导入 + 注册，并等到组件真的可用（默认 waitForReady: true）
 const outcome = await harness.store.install(items[0]);
 if (outcome.readyIssue === "authorization_required") {
-  await harness.connectors.authStart(outcome.readyComponentId!);
+  const id = outcome.readyComponentId!;
+  // 失败有两条通道，别只看一条：浏览器**之前**的失败由 authStart 同步回
+  // state:"error"；**之后**的失败（换 token 被拒、回调超时、被限流）只会出现在
+  // authStatus 的 error 里，state 一直停在 not_authenticated。
+  // waitForAuth 把第二条通道包成一次调用，并在结束时说清原因。
+  const started = await harness.connectors.authStart(id);
+  if (started.state === "error") throw new Error(started.error ?? "authorization failed to start");
+  const auth = await harness.connectors.waitForAuth(id);
+  if (auth.state !== "authenticated") {
+    throw new Error(auth.state === "error" ? auth.error : "timed out in the browser");
+  }
 }
 
 // 禁用 / 启用：连接器改 mcp_servers.enabled，专家/专家团改 Preset.enabled
@@ -29,14 +39,49 @@ if (!released.ok) console.warn(released.components.filter((c) => !c.ok));
 await harness.close();
 ```
 
+## 导出专家 / 专家团并写到目录（`exportAgent` / `exportTeam` / `materializePack`）
+
+`agents.export` / `teams.export` 只给**定义**（`ExpertPack`），技能是**引用**（`{name, id}`，没有字节）。
+下面三个函数把「定义 + 技能字节」一次**写成一个目录**（`docs/agent-store/35`；它把 doc `32` §6.5 的
+11 行配方提升成了 API）：
+
+```ts
+import { exportTeam } from "@flowy-agent-store/sdk";
+
+// 多 agent 的专家团：递归展开 + 整包失败（成员缺一即失败并点名），leader 在首位
+const result = await exportTeam(harness, teamId, "./frontend-backend-experts");
+// 单 agent 专家用 exportAgent(harness, agentId, dir)
+// 已有 pack（比如缓存/网络传来的）用 materializePack(harness, pack, dir) 只写目录
+
+result.pack;                 // ExpertPack —— 内存里也拿得到，不落盘也能用
+result.writtenSkills;        // 实际写入的技能名（去重后）
+result.danglingSkills;       // 声明了但本机取不到的技能：{ id, error }，如实上报，不静默跳过
+```
+
+写出的布局：
+
+```text
+<dir>/
+  expert-pack.json           # 线上 pack 逐字节
+  persona.md                 # 仅 agent 形态（团没有自己的 persona）
+  members/<id>/persona.md    # 仅 team 形态，每个成员一个
+  skills/<name>/…            # 成员声明去重后的技能字节
+```
+
+错误语义：wire 导出失败（`agent_not_installed` / `agent_disabled` / `policy_denied` /
+`version_mismatch` / `response_too_large`…）**先于任何写盘**，不留半成品目录；`skill/files`
+失败进 `danglingSkills` 并继续；`skill/file` 在列文件成功后失败则**抛出**——那是宿主 I/O 错误，
+吞掉会造出「列了文件却缺内容」的残目录。
+
 **`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 的职责划分。
 
 几条使用上的事实（都是实测结论，不是约定）：
 
-- `store.install` 默认**等到可用**才 resolve。技能拷完即可用，连接器不然：它注册出来是 **disabled** 的（安装器的既定默认），所以就绪检查会先把它 enable，再跑一次探针——只轮询状态永远到不了 `connected`，因为状态派生自上一次探针。
+- `store.install` 默认**等到可用**才 resolve。技能拷完即可用，连接器不然：它注册出来是 **disabled** 的（安装器的既定默认），所以就绪检查会先把它 enable，再跑一次探针——只轮询状态永远到不了 `connected`，因为状态派生自上一次探针。探针**有节奏**：首轮（以及之后每 `readyProbeMs`，默认 5s）真连一次，其余轮次只读状态。这是刻意的：一次探针会解析已存 token（临近过期就刷新，401 再刷新一次），按 400ms 的轮询间隔去探针，30 秒预算里能对连接器及其授权服务器打出约 10 次连接 / 最多约 20 次 token 请求，而没有任何人点过按钮。
 - 就绪超时**不会丢掉安装结果**：返回成功的安装 + `ready: false` / `readyIssue: "ready_timeout"`。需要 OAuth 的连接器立刻返回 `authorization_required`，不把超时预算烧光。
+- `connectors.waitForAuth(id)` 是「等授权完成」的写法：它轮询 `authStatus`，一拿到 `error` 就立刻带原因返回（`{state:"error", error}`），成功返回 `{state:"authenticated"}`，预算用完返回 `{state:"timeout"}`；只有状态读本身失败才 reject。手写 `while (state !== "authenticated")` 循环的典型结局是「它就是没变成 authenticated」——而原因（换 token 被拒、回调超时、`slow_down` 限流）早就躺在它每次读到的 `error` 里。
 - 没有「更新」动词。`store.checkUpdates()` 只报告哪些条目有新版，`store.updateHint(item)` 告诉你该怎么做——当前是 `"uninstall_reinstall"`：卸载后重装，安装路径会按版本漂移重新导入，取到市场当前版本。
 - 卸载是**可重入**的：产物已不在算成功。部分失败时那些组件保持已安装、`ok: false` 且点名到组件，重试有意义。
 - `store.setEnabled(item, false)` 对技能只翻一个目录层标记，返回 `code: "skill_disable_flag_only"`——技能语料没有启用状态，要让技能离开运行时只能 `uninstall`。这个 code 会原样透出，不会被吞。
@@ -64,4 +109,8 @@ await harness.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 方法——因为这些面跟着宿主自己的设置文件与技能目录走，是最易变的部分。这是可发现性边界，不是权限边界：`harness.transport` 是公开的，服务端按磁盘归属判定可写性。要用就直连 `transport.request`，并自担变动。
+不在本包范围内（`07-typescript-sdk.md` §非目标）：`config/*` 与 `skill/*` **写**面。它们的**类型**在
+`@flowy-agent-store/protocol`（wire 上存在的方法就有形状），但**没有** typed 方法——因为这些面跟着
+宿主自己的设置文件与技能目录走，是最易变的部分。**技能的读面是例外**：`skill/files` / `skill/file`
+有 typed 方法（`harness.skills.*`），且被上面的导出函数消费。这是可发现性边界，不是权限边界：
+`harness.transport` 是公开的，服务端按磁盘归属判定可写性。要用就直连 `transport.request`，并自担变动。

package/dist/index.cjs

@@ -3,8 +3,8 @@ let _flowy_agent_store_client = require("@flowy-agent-store/client");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
 let node_path = require("node:path");
-let node_child_process = require("node:child_process");
 let node_fs_promises = require("node:fs/promises");
+let node_child_process = require("node:child_process");
 let node_os = require("node:os");
 let node_readline = require("node:readline");
 let _flowy_agent_store_protocol = require("@flowy-agent-store/protocol");
@@ -66,6 +66,109 @@ function findOnPath(name) {
 	}
 }
 //#endregion
+//#region src/export.ts
+/**
+* Export an expert (single agent) or an expert **team** together with its
+* skills, written out as a directory (doc `35`).
+*
+* The wire face (`agent/export` / `team/export`, docs/agent-store/32) carries
+* skills **by reference** — `{name, id}`, never bytes — so "export the team's
+* skills" means: walk the pack, fetch every referenced skill through
+* `skill/files` + `skill/file`, 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` promotes it into these three functions (and records why the
+* earlier decision against an SDK helper was reversed).
+*
+* 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.
+*/
+/**
+* Write an in-hand pack to `dir` as a real directory (doc `35` §5 layout).
+* "Materialize" here means exactly that: the in-memory pack object plus the
+* skill 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
+* ```
+*
+* 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` 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 (0, node_fs_promises.mkdir)(dir, { recursive: true });
+	await (0, node_fs_promises.writeFile)((0, node_path.join)(dir, "expert-pack.json"), JSON.stringify(pack, null, 2));
+	if (pack.kind === "agent") await (0, node_fs_promises.writeFile)((0, node_path.join)(dir, "persona.md"), pack.persona.instructions);
+	for (const member of pack.team?.members ?? []) {
+		const target = (0, node_path.join)(dir, "members", member.id, "persona.md");
+		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(target), { recursive: true });
+		await (0, node_fs_promises.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 = (0, node_path.join)(dir, "skills", ref.name, file.path);
+			await (0, node_fs_promises.mkdir)((0, node_path.dirname)(target), { recursive: true });
+			await (0, node_fs_promises.writeFile)(target, await deps.skills.readFile(ref.id, file.path));
+		}
+		writtenSkills.push(ref.name);
+	}
+	return {
+		pack,
+		dir,
+		writtenSkills,
+		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) {
@@ -311,7 +414,10 @@ async function launchHarness(options) {
 }
 //#endregion
 exports.assertProtocolCompatible = assertProtocolCompatible;
+exports.exportAgent = exportAgent;
+exports.exportTeam = exportTeam;
 exports.launchHarness = launchHarness;
+exports.materializePack = materializePack;
 exports.parseReadinessLine = parseReadinessLine;
 exports.resolveAppServerBin = resolveAppServerBin;
 exports.spawnAppServer = spawnAppServer;

package/dist/index.d.cts

@@ -1,8 +1,90 @@
 import { AppServerClient } from "@flowy-agent-store/client";
-import { ClientCapabilities, ClientInfo, InitializeResult } from "@flowy-agent-store/protocol";
+import { ClientCapabilities, ClientInfo, ExpertPack, InitializeResult } from "@flowy-agent-store/protocol";
 //#region src/bin.d.ts
 export declare function resolveAppServerBin(explicit?: string): string;
 //#endregion
+//#region src/export.d.ts
+/**
+ * The three wire faces this module needs, narrowed from {@link Harness} on
+ * purpose: unit tests hand a fake, and the dependency surface stays explicit
+ * instead of quietly reaching `store` / `conversations`. A real harness
+ * satisfies this structurally (`Harness` extends `AppServerClient`, which owns
+ * `agents` / `teams` / `skills`).
+ */
+interface ExportDeps {
+  agents: {
+    export(agentId: string): Promise<ExpertPack>;
+  };
+  teams: {
+    export(teamId: string, teamVersion?: string): Promise<ExpertPack>;
+  };
+  skills: {
+    files(skillId: string): Promise<{
+      files: {
+        path: string;
+      }[];
+    }>;
+    readFile(skillId: string, path: string): Promise<Uint8Array>;
+  };
+}
+interface ExportResult {
+  /** The pack is also returned in memory: a consumer that never touches the disk needs no second call. */
+  pack: ExpertPack;
+  dir: string;
+  /** Skill names actually written (deduplicated). */
+  writtenSkills: string[];
+  /**
+   * Skills the pack **declares** but this host cannot resolve (`skill/files`
+   * rejected them). Reported honestly, never skipped in silence: the pack
+   * states declarations, resolvability is a host fact the consumer has to
+   * judge (doc `32` §5 R8, live criterion EX-008).
+   */
+  danglingSkills: {
+    id: string;
+    error: string;
+  }[];
+}
+/**
+ * Write an in-hand pack to `dir` as a real directory (doc `35` §5 layout).
+ * "Materialize" here means exactly that: the in-memory pack object plus the
+ * skill 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
+ * ```
+ *
+ * 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` 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.
+ */
+export declare function materializePack(deps: ExportDeps, pack: ExpertPack, dir: string): Promise<ExportResult>;
+/**
+ * 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.
+ */
+export declare function exportAgent(deps: ExportDeps, agentId: string, dir: string): Promise<ExportResult>;
+/**
+ * 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`.
+ */
+export declare function exportTeam(deps: ExportDeps, teamId: string, dir: string, teamVersion?: string): Promise<ExportResult>;
+//#endregion
 //#region src/readiness.d.ts
 /**
  * Readiness protocol (docs/agent-store/12 P0-1).
@@ -114,4 +196,4 @@ export interface Harness extends AppServerClient {
  */
 export declare function launchHarness(options: HarnessOptions): Promise<Harness>;
 //#endregion
-export type { ReadinessInfo, SpawnExitInfo, SpawnOptions, SpawnedServer };
+export type { ExportDeps, ExportResult, ReadinessInfo, SpawnExitInfo, SpawnOptions, SpawnedServer };

package/dist/index.d.mts

@@ -1,8 +1,90 @@
 import { AppServerClient } from "@flowy-agent-store/client";
-import { ClientCapabilities, ClientInfo, InitializeResult } from "@flowy-agent-store/protocol";
+import { ClientCapabilities, ClientInfo, ExpertPack, InitializeResult } from "@flowy-agent-store/protocol";
 //#region src/bin.d.ts
 export declare function resolveAppServerBin(explicit?: string): string;
 //#endregion
+//#region src/export.d.ts
+/**
+ * The three wire faces this module needs, narrowed from {@link Harness} on
+ * purpose: unit tests hand a fake, and the dependency surface stays explicit
+ * instead of quietly reaching `store` / `conversations`. A real harness
+ * satisfies this structurally (`Harness` extends `AppServerClient`, which owns
+ * `agents` / `teams` / `skills`).
+ */
+interface ExportDeps {
+  agents: {
+    export(agentId: string): Promise<ExpertPack>;
+  };
+  teams: {
+    export(teamId: string, teamVersion?: string): Promise<ExpertPack>;
+  };
+  skills: {
+    files(skillId: string): Promise<{
+      files: {
+        path: string;
+      }[];
+    }>;
+    readFile(skillId: string, path: string): Promise<Uint8Array>;
+  };
+}
+interface ExportResult {
+  /** The pack is also returned in memory: a consumer that never touches the disk needs no second call. */
+  pack: ExpertPack;
+  dir: string;
+  /** Skill names actually written (deduplicated). */
+  writtenSkills: string[];
+  /**
+   * Skills the pack **declares** but this host cannot resolve (`skill/files`
+   * rejected them). Reported honestly, never skipped in silence: the pack
+   * states declarations, resolvability is a host fact the consumer has to
+   * judge (doc `32` §5 R8, live criterion EX-008).
+   */
+  danglingSkills: {
+    id: string;
+    error: string;
+  }[];
+}
+/**
+ * Write an in-hand pack to `dir` as a real directory (doc `35` §5 layout).
+ * "Materialize" here means exactly that: the in-memory pack object plus the
+ * skill 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
+ * ```
+ *
+ * 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` 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.
+ */
+export declare function materializePack(deps: ExportDeps, pack: ExpertPack, dir: string): Promise<ExportResult>;
+/**
+ * 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.
+ */
+export declare function exportAgent(deps: ExportDeps, agentId: string, dir: string): Promise<ExportResult>;
+/**
+ * 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`.
+ */
+export declare function exportTeam(deps: ExportDeps, teamId: string, dir: string, teamVersion?: string): Promise<ExportResult>;
+//#endregion
 //#region src/readiness.d.ts
 /**
  * Readiness protocol (docs/agent-store/12 P0-1).
@@ -114,4 +196,4 @@ export interface Harness extends AppServerClient {
  */
 export declare function launchHarness(options: HarnessOptions): Promise<Harness>;
 //#endregion
-export type { ReadinessInfo, SpawnExitInfo, SpawnOptions, SpawnedServer };
+export type { ExportDeps, ExportResult, ReadinessInfo, SpawnExitInfo, SpawnOptions, SpawnedServer };

package/dist/index.mjs

@@ -1,9 +1,9 @@
 import { createRequire } from "node:module";
 import { AppServerClient, WebSocketTransport, isLoopbackUrl } from "@flowy-agent-store/client";
 import { existsSync } from "node:fs";
-import { delimiter, join } from "node:path";
+import { delimiter, dirname, join } from "node:path";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
-import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { createInterface } from "node:readline";
 import { APP_SERVER_PROTOCOL_VERSION } from "@flowy-agent-store/protocol";
@@ -65,6 +65,109 @@ function findOnPath(name) {
 	}
 }
 //#endregion
+//#region src/export.ts
+/**
+* Export an expert (single agent) or an expert **team** together with its
+* skills, written out as a directory (doc `35`).
+*
+* The wire face (`agent/export` / `team/export`, docs/agent-store/32) carries
+* skills **by reference** — `{name, id}`, never bytes — so "export the team's
+* skills" means: walk the pack, fetch every referenced skill through
+* `skill/files` + `skill/file`, 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` promotes it into these three functions (and records why the
+* earlier decision against an SDK helper was reversed).
+*
+* 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.
+*/
+/**
+* Write an in-hand pack to `dir` as a real directory (doc `35` §5 layout).
+* "Materialize" here means exactly that: the in-memory pack object plus the
+* skill 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
+* ```
+*
+* 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` 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);
+	}
+	return {
+		pack,
+		dir,
+		writtenSkills,
+		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) {
@@ -309,4 +412,4 @@ async function launchHarness(options) {
 	}
 }
 //#endregion
-export { assertProtocolCompatible, launchHarness, parseReadinessLine, resolveAppServerBin, spawnAppServer };
+export { assertProtocolCompatible, exportAgent, exportTeam, launchHarness, materializePack, parseReadinessLine, resolveAppServerBin, spawnAppServer };

package/package.json

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