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

package/dist/index.d.cts

@@ -0,0 +1,248 @@
+import { AppServerClient } from "@flowy-agent-store/client";
+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 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` and the two flat asset methods).
+ */
+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>;
+  };
+  /**
+   * The plugin-level snapshot asset byte face (`import/asset`, doc 38). The
+   * pack names the `avatars/`, `bin/` and `scripts/` files by reference —
+   * that list is the single source of what to fetch — and this fetches one
+   * file's bytes. (The listing method `import/assets` exists on the client;
+   * materialization deliberately trusts only the pack, so the exported
+   * directory can never contain a file the pack does not name.)
+   */
+  readImportAsset(snapshotId: 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[];
+  /**
+   * Snapshot-relative asset paths actually written, in the pack's order. The
+   * materialized directory is therefore a complete **plugin root**: a team
+   * whose scripts resolve `PLUGIN_ROOT/bin/init_task.py` two levels above
+   * their skill finds it, and the `avatars/` references in its own skill
+   * documents resolve too (doc 38 §3.5).
+   */
+  writtenAssets: 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 (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.
+ */
+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).
+ *
+ * The runtime prints exactly one machine-readable line on stdout after the
+ * socket is bound. Tracing logs share stdout, so the host scans lines for a
+ * JSON object with `"agent_store": "listening"` and ignores everything else.
+ */
+interface ReadinessInfo {
+  host: string;
+  port: number;
+  url: string;
+  protocol_version: string;
+  version: string;
+  auth: string;
+}
+/** Parse one stdout line; `null` when it is not the readiness line. */
+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;
+  /** Data directory the child owns. Defaults to a fresh temp dir (removed on `close`). */
+  dataDir?: string;
+  /** Port to bind. Defaults to `0` (OS-assigned, reported by the readiness line). */
+  port?: number;
+  /** Extra CLI args appended after the managed ones. */
+  extraArgs?: string[];
+  /**
+   * What the spawned host does with its default marketplace sources at boot
+   * (doc `37` §3.1). Sent as `AGENT_STORE_MARKET_DOWNLOAD`.
+   *
+   * - `"lazy"` — register the declared sources and download nothing; the
+   *   archives wait for an explicit `market/refresh` / `refreshMarketplace()`;
+   * - `"none"` — register nothing at all, so `store/list` starts empty;
+   * - `"eager"` — fetch every declared source during boot.
+   *
+   * Omitted = the host's own policy (`download_on_start` per source, default
+   * `true`, so a declared source *is* downloaded unless it says otherwise).
+   * This is a process-scoped override: nothing is written to the user's config.
+   */
+  marketDownload?: "eager" | "lazy" | "none";
+  /**
+   * Config file for this child only (doc `37` §3.1). Sent as
+   * `AGENT_STORE_CONFIG`.
+   *
+   * Without it the host reads the per-user `~/.agent-store/config.toml` — which
+   * a spawned, SDK-owned host should not have to share. The data directory is
+   * independent of this (`dataDir`, always explicit).
+   */
+  configPath?: 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`.
+   *
+   * An entry here **wins over the typed options above** (`marketDownload`,
+   * `configPath`): the raw map is the caller's most specific statement, and
+   * nothing this factory derives should silently overwrite it.
+   */
+  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>;
+}
+export declare function spawnAppServer(options?: SpawnOptions): Promise<SpawnedServer>;
+//#endregion
+//#region src/index.d.ts
+export interface HarnessOptions extends SpawnOptions {
+  client: ClientInfo;
+  capabilities?: ClientCapabilities;
+  token?: string;
+  requestTimeoutMs?: number;
+}
+/**
+ * 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>;
+}
+/**
+ * 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.
+ */
+export declare function launchHarness(options: HarnessOptions): Promise<Harness>;
+//#endregion
+export type { ExportDeps, ExportResult, ReadinessInfo, SpawnExitInfo, SpawnOptions, SpawnedServer };

package/dist/index.d.mts

@@ -0,0 +1,248 @@
+import { AppServerClient } from "@flowy-agent-store/client";
+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 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` and the two flat asset methods).
+ */
+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>;
+  };
+  /**
+   * The plugin-level snapshot asset byte face (`import/asset`, doc 38). The
+   * pack names the `avatars/`, `bin/` and `scripts/` files by reference —
+   * that list is the single source of what to fetch — and this fetches one
+   * file's bytes. (The listing method `import/assets` exists on the client;
+   * materialization deliberately trusts only the pack, so the exported
+   * directory can never contain a file the pack does not name.)
+   */
+  readImportAsset(snapshotId: 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[];
+  /**
+   * Snapshot-relative asset paths actually written, in the pack's order. The
+   * materialized directory is therefore a complete **plugin root**: a team
+   * whose scripts resolve `PLUGIN_ROOT/bin/init_task.py` two levels above
+   * their skill finds it, and the `avatars/` references in its own skill
+   * documents resolve too (doc 38 §3.5).
+   */
+  writtenAssets: 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 (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.
+ */
+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).
+ *
+ * The runtime prints exactly one machine-readable line on stdout after the
+ * socket is bound. Tracing logs share stdout, so the host scans lines for a
+ * JSON object with `"agent_store": "listening"` and ignores everything else.
+ */
+interface ReadinessInfo {
+  host: string;
+  port: number;
+  url: string;
+  protocol_version: string;
+  version: string;
+  auth: string;
+}
+/** Parse one stdout line; `null` when it is not the readiness line. */
+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;
+  /** Data directory the child owns. Defaults to a fresh temp dir (removed on `close`). */
+  dataDir?: string;
+  /** Port to bind. Defaults to `0` (OS-assigned, reported by the readiness line). */
+  port?: number;
+  /** Extra CLI args appended after the managed ones. */
+  extraArgs?: string[];
+  /**
+   * What the spawned host does with its default marketplace sources at boot
+   * (doc `37` §3.1). Sent as `AGENT_STORE_MARKET_DOWNLOAD`.
+   *
+   * - `"lazy"` — register the declared sources and download nothing; the
+   *   archives wait for an explicit `market/refresh` / `refreshMarketplace()`;
+   * - `"none"` — register nothing at all, so `store/list` starts empty;
+   * - `"eager"` — fetch every declared source during boot.
+   *
+   * Omitted = the host's own policy (`download_on_start` per source, default
+   * `true`, so a declared source *is* downloaded unless it says otherwise).
+   * This is a process-scoped override: nothing is written to the user's config.
+   */
+  marketDownload?: "eager" | "lazy" | "none";
+  /**
+   * Config file for this child only (doc `37` §3.1). Sent as
+   * `AGENT_STORE_CONFIG`.
+   *
+   * Without it the host reads the per-user `~/.agent-store/config.toml` — which
+   * a spawned, SDK-owned host should not have to share. The data directory is
+   * independent of this (`dataDir`, always explicit).
+   */
+  configPath?: 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`.
+   *
+   * An entry here **wins over the typed options above** (`marketDownload`,
+   * `configPath`): the raw map is the caller's most specific statement, and
+   * nothing this factory derives should silently overwrite it.
+   */
+  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>;
+}
+export declare function spawnAppServer(options?: SpawnOptions): Promise<SpawnedServer>;
+//#endregion
+//#region src/index.d.ts
+export interface HarnessOptions extends SpawnOptions {
+  client: ClientInfo;
+  capabilities?: ClientCapabilities;
+  token?: string;
+  requestTimeoutMs?: number;
+}
+/**
+ * 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>;
+}
+/**
+ * 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.
+ */
+export declare function launchHarness(options: HarnessOptions): Promise<Harness>;
+//#endregion
+export type { ExportDeps, ExportResult, ReadinessInfo, SpawnExitInfo, SpawnOptions, SpawnedServer };