@agentproto/runtime 0.1.0

package/dist/mcp-imports.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Discover MCP servers already configured in the user's local agent
+ * tooling — claude-code, cursor, goose, etc. — so the daemon can
+ * surface them in the UI without making the user re-enter the same
+ * credentials and URLs they already painstakingly configured for
+ * one host.
+ *
+ * v1 is read-only discovery: we report what's there with source
+ * attribution. Future v1.1 ships an "import to daemon" verb that
+ * proxies the discovered server through the daemon's own /mcp
+ * endpoint so every operator (cloud Guilde, local agents) sees a
+ * unified set without per-host config drift.
+ *
+ * Sources scanned (in priority order):
+ *   - ~/.claude.json (claude-code) — `mcpServers` top-level + nested
+ *     under `projects[<path>].mcpServers`. Most users land here.
+ *   - ~/.cursor/mcp.json (cursor) — flat `mcpServers` map.
+ *   - ~/.config/goose/config.yaml (goose) — TOML/YAML hybrid; we
+ *     only handle the YAML form for now.
+ *   - any `.mcp.json` under the user's home that follows the
+ *     standard mcpServers shape.
+ *
+ * Each source contributes 0..N entries. Errors are caught + logged
+ * (broken JSON, missing files, permission denied) — partial
+ * discovery beats failing the whole listing on one bad file.
+ */
+interface DiscoveredMcp {
+    /** Stable id within (source, scope, name) — for de-dupe and
+     *  cross-call identity (UI treat as React key). */
+    id: string;
+    /** Where we found it. Lets the UI render a source badge. */
+    source: "claude-code" | "cursor" | "goose" | "workspace";
+    /** "global" when the entry sits at the top level of the host's
+     *  config; "project:<path>" when it's scoped to a single
+     *  workspace. claude-code in particular nests per-project. */
+    scope: string;
+    /** The host's name for the entry (key in the mcpServers map). */
+    name: string;
+    /** Wire transport — `stdio` (command + args) or `http` / `sse` (url). */
+    type: "stdio" | "http" | "sse" | "unknown";
+    /** stdio entries: argv to spawn. */
+    command?: string;
+    args?: string[];
+    /** stdio entries: env injected into the child. */
+    env?: Record<string, string>;
+    /** http/sse entries: target URL. */
+    url?: string;
+    /** http/sse entries: extra headers (Authorization, etc.). */
+    headers?: Record<string, string>;
+    /** Free-form tags from the source config — claude-code's project
+     *  scope is the most common. */
+    tags?: string[];
+    /** Reason field when `type === "unknown"` — surfaces why the
+     *  parser couldn't classify the entry (e.g. neither command nor
+     *  url present). */
+    parseNote?: string;
+}
+
+/**
+ * `~/.agentproto/imported-mcps.json` — the user's curated set of
+ * discovered MCPs they want the daemon to know about. v1 is just
+ * persistence + read-side; the actual MCP-proxy implementation
+ * (where the daemon's /mcp endpoint aggregates the imported
+ * servers' tools under namespace prefixes) is v2 work.
+ *
+ * Purpose: today, "I see you have chrome-devtools in claude" is
+ * read-only. Once a user imports it, the operator agent can refer
+ * to it ("the user said it's enabled — call it") and a future
+ * proxy layer can actually expose it. We persist the choice now so
+ * the data is in place when the proxy lands.
+ *
+ * File shape:
+ *   {
+ *     "version": 1,
+ *     "imports": [
+ *       {
+ *         "id":         "claude-code:project:/path:chrome-devtools",
+ *         "alias":      "chrome-devtools",
+ *         "addedAt":    "2026-05-10T...",
+ *         "snapshot":   { ...the DiscoveredMcp at import time }
+ *       }
+ *     ]
+ *   }
+ *
+ * Snapshotting at import time keeps the daemon resilient to the
+ * source config getting deleted (user runs `claude mcp remove ...`).
+ * The imported entry stays usable; only the next discovery pass
+ * stops listing it as "available to import."
+ */
+
+declare const IMPORTED_MCPS_PATH: () => string;
+declare const IMPORTED_MCPS_VERSION: 1;
+interface ImportedMcpEntry {
+    id: string;
+    alias: string;
+    addedAt: string;
+    snapshot: DiscoveredMcp;
+}
+interface ImportedMcpsConfig {
+    version: typeof IMPORTED_MCPS_VERSION;
+    imports: ImportedMcpEntry[];
+}
+declare function loadImportedMcps(path?: string): Promise<ImportedMcpsConfig>;
+declare function saveImportedMcps(config: ImportedMcpsConfig, path?: string): Promise<void>;
+/**
+ * Add (or replace) an import. Snapshots the discovered MCP at
+ * import time so the entry stays usable when the source config
+ * disappears.
+ */
+declare function addImport(config: ImportedMcpsConfig, input: {
+    snapshot: DiscoveredMcp;
+    alias?: string;
+}): ImportedMcpsConfig;
+declare function removeImport(config: ImportedMcpsConfig, id: string): ImportedMcpsConfig;
+declare function findImport(config: ImportedMcpsConfig, id: string): ImportedMcpEntry | undefined;
+
+export { IMPORTED_MCPS_PATH, IMPORTED_MCPS_VERSION, type ImportedMcpEntry, type ImportedMcpsConfig, addImport, findImport, loadImportedMcps, removeImport, saveImportedMcps };

package/dist/mcp-imports.mjs

@@ -0,0 +1,82 @@
+import { promises } from 'fs';
+import { homedir } from 'os';
+import { resolve, dirname } from 'path';
+
+/**
+ * @agentproto/runtime v0.1.0-alpha
+ * Long-running gateway: MCP server + HTTP transport + HEARTBEAT autonomy + conversation persistence over a workspace dir.
+ */
+
+var IMPORTED_MCPS_PATH = () => resolve(homedir(), ".agentproto", "imported-mcps.json");
+var IMPORTED_MCPS_VERSION = 1;
+var EMPTY = {
+  version: IMPORTED_MCPS_VERSION,
+  imports: []
+};
+async function loadImportedMcps(path = IMPORTED_MCPS_PATH()) {
+  let raw;
+  try {
+    raw = await promises.readFile(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return EMPTY;
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `agentproto: ${path} is not valid JSON (${err instanceof Error ? err.message : String(err)}). Delete or fix manually.`
+    );
+  }
+  return normalize(parsed);
+}
+async function saveImportedMcps(config, path = IMPORTED_MCPS_PATH()) {
+  await promises.mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  await promises.writeFile(tmp, JSON.stringify(config, null, 2) + "\n", "utf8");
+  await promises.rename(tmp, path);
+}
+function addImport(config, input) {
+  const alias = (input.alias ?? input.snapshot.name).trim();
+  if (!alias) {
+    throw new Error("addImport: alias resolves to empty string");
+  }
+  const addedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const next = {
+    id: input.snapshot.id,
+    alias,
+    addedAt,
+    snapshot: input.snapshot
+  };
+  const others = config.imports.filter((e) => e.id !== input.snapshot.id);
+  return { ...config, imports: [...others, next] };
+}
+function removeImport(config, id) {
+  return { ...config, imports: config.imports.filter((e) => e.id !== id) };
+}
+function findImport(config, id) {
+  return config.imports.find((e) => e.id === id);
+}
+function normalize(parsed) {
+  if (!parsed || typeof parsed !== "object") return EMPTY;
+  const obj = parsed;
+  const imports = [];
+  if (Array.isArray(obj.imports)) {
+    for (const entry of obj.imports) {
+      if (!entry || typeof entry !== "object") continue;
+      const e = entry;
+      const id = typeof e.id === "string" ? e.id : "";
+      const alias = typeof e.alias === "string" ? e.alias : id;
+      const addedAt = typeof e.addedAt === "string" ? e.addedAt : (/* @__PURE__ */ new Date()).toISOString();
+      const snapshot = e.snapshot;
+      if (!id || !snapshot) continue;
+      imports.push({ id, alias, addedAt, snapshot });
+    }
+  }
+  return { version: IMPORTED_MCPS_VERSION, imports };
+}
+
+export { IMPORTED_MCPS_PATH, IMPORTED_MCPS_VERSION, addImport, findImport, loadImportedMcps, removeImport, saveImportedMcps };
+//# sourceMappingURL=mcp-imports.mjs.map
+//# sourceMappingURL=mcp-imports.mjs.map

package/dist/mcp-imports.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mcp-imports.ts"],"names":["resolvePath","fs"],"mappings":"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","file":"mcp-imports.mjs","sourcesContent":["/**\n * `~/.agentproto/imported-mcps.json` — the user's curated set of\n * discovered MCPs they want the daemon to know about. v1 is just\n * persistence + read-side; the actual MCP-proxy implementation\n * (where the daemon's /mcp endpoint aggregates the imported\n * servers' tools under namespace prefixes) is v2 work.\n *\n * Purpose: today, \"I see you have chrome-devtools in claude\" is\n * read-only. Once a user imports it, the operator agent can refer\n * to it (\"the user said it's enabled — call it\") and a future\n * proxy layer can actually expose it. We persist the choice now so\n * the data is in place when the proxy lands.\n *\n * File shape:\n *   {\n *     \"version\": 1,\n *     \"imports\": [\n *       {\n *         \"id\":         \"claude-code:project:/path:chrome-devtools\",\n *         \"alias\":      \"chrome-devtools\",\n *         \"addedAt\":    \"2026-05-10T...\",\n *         \"snapshot\":   { ...the DiscoveredMcp at import time }\n *       }\n *     ]\n *   }\n *\n * Snapshotting at import time keeps the daemon resilient to the\n * source config getting deleted (user runs `claude mcp remove ...`).\n * The imported entry stays usable; only the next discovery pass\n * stops listing it as \"available to import.\"\n */\n\nimport { promises as fs } from \"node:fs\"\nimport { homedir } from \"node:os\"\nimport { dirname, resolve as resolvePath } from \"node:path\"\nimport type { DiscoveredMcp } from \"./mcp-discovery.js\"\n\nexport const IMPORTED_MCPS_PATH = (): string =>\n  resolvePath(homedir(), \".agentproto\", \"imported-mcps.json\")\n\nexport const IMPORTED_MCPS_VERSION = 1 as const\n\nexport interface ImportedMcpEntry {\n  id: string\n  alias: string\n  addedAt: string\n  snapshot: DiscoveredMcp\n}\n\nexport interface ImportedMcpsConfig {\n  version: typeof IMPORTED_MCPS_VERSION\n  imports: ImportedMcpEntry[]\n}\n\nconst EMPTY: ImportedMcpsConfig = {\n  version: IMPORTED_MCPS_VERSION,\n  imports: [],\n}\n\nexport async function loadImportedMcps(\n  path: string = IMPORTED_MCPS_PATH()\n): Promise<ImportedMcpsConfig> {\n  let raw: string\n  try {\n    raw = await fs.readFile(path, \"utf8\")\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"ENOENT\") return EMPTY\n    throw err\n  }\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(raw)\n  } catch (err) {\n    throw new Error(\n      `agentproto: ${path} is not valid JSON (${\n        err instanceof Error ? err.message : String(err)\n      }). Delete or fix manually.`\n    )\n  }\n  return normalize(parsed)\n}\n\nexport async function saveImportedMcps(\n  config: ImportedMcpsConfig,\n  path: string = IMPORTED_MCPS_PATH()\n): Promise<void> {\n  await fs.mkdir(dirname(path), { recursive: true })\n  const tmp = `${path}.tmp.${process.pid}`\n  await fs.writeFile(tmp, JSON.stringify(config, null, 2) + \"\\n\", \"utf8\")\n  await fs.rename(tmp, path)\n}\n\n/**\n * Add (or replace) an import. Snapshots the discovered MCP at\n * import time so the entry stays usable when the source config\n * disappears.\n */\nexport function addImport(\n  config: ImportedMcpsConfig,\n  input: { snapshot: DiscoveredMcp; alias?: string }\n): ImportedMcpsConfig {\n  const alias = (input.alias ?? input.snapshot.name).trim()\n  if (!alias) {\n    throw new Error(\"addImport: alias resolves to empty string\")\n  }\n  const addedAt = new Date().toISOString()\n  const next: ImportedMcpEntry = {\n    id: input.snapshot.id,\n    alias,\n    addedAt,\n    snapshot: input.snapshot,\n  }\n  const others = config.imports.filter(e => e.id !== input.snapshot.id)\n  return { ...config, imports: [...others, next] }\n}\n\nexport function removeImport(\n  config: ImportedMcpsConfig,\n  id: string\n): ImportedMcpsConfig {\n  return { ...config, imports: config.imports.filter(e => e.id !== id) }\n}\n\nexport function findImport(\n  config: ImportedMcpsConfig,\n  id: string\n): ImportedMcpEntry | undefined {\n  return config.imports.find(e => e.id === id)\n}\n\nfunction normalize(parsed: unknown): ImportedMcpsConfig {\n  if (!parsed || typeof parsed !== \"object\") return EMPTY\n  const obj = parsed as Record<string, unknown>\n  const imports: ImportedMcpEntry[] = []\n  if (Array.isArray(obj.imports)) {\n    for (const entry of obj.imports) {\n      if (!entry || typeof entry !== \"object\") continue\n      const e = entry as Record<string, unknown>\n      const id = typeof e.id === \"string\" ? e.id : \"\"\n      const alias = typeof e.alias === \"string\" ? e.alias : id\n      const addedAt =\n        typeof e.addedAt === \"string\" ? e.addedAt : new Date().toISOString()\n      const snapshot = e.snapshot as DiscoveredMcp | undefined\n      if (!id || !snapshot) continue\n      imports.push({ id, alias, addedAt, snapshot })\n    }\n  }\n  return { version: IMPORTED_MCPS_VERSION, imports }\n}\n"]}

package/dist/resume-strategies.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Per-adapter resume strategies — the daemon's view of "how do I
+ * continue a previous session for THIS adapter?".
+ *
+ * The driver already has an `AgentCliContinuation` declaration in
+ * the adapter manifest (AIP-45). That covers strategy NAMES
+ * (`native-resume`, `pinned-session`, `transcript`, `none`) but is
+ * silent on the mechanics that live OUTSIDE the runtime — like
+ * "where on disk does this adapter store its conversations?" or
+ * "what argv do I pass to resume into PTY mode?".
+ *
+ * This table is that practical bridge. Each entry declares three
+ * optional hooks:
+ *
+ *   outputHint   regex matched against each output line; group 1 is
+ *                the resume id. Stored as `desc.resumeMetadata[storeAs]`.
+ *   fsProbe      async function that probes a per-adapter directory
+ *                for a stored session id, scoped to a workspace cwd.
+ *                Used when `outputHint` never matched.
+ *   spawnArgs    given a captured id, returns the argv to spawn a
+ *                PTY that resumes the session. agentproto then
+ *                bypasses ACP/agent-cli and runs the provider
+ *                directly — the most reliable resume path because
+ *                it leans on the provider's native UX.
+ *
+ * Adapters that don't declare anything here fall back to:
+ *   1. ACP-level resume via `resumeSessionId` on POST /sessions/agent
+ *   2. Fresh spawn (same shape, no continuity)
+ *
+ * Eventually each adapter should ship its own strategy on
+ * `AgentCliHandle.resumeStrategy` (driver-side). This central table
+ * is the bootstrap: it lets a new adapter become resume-capable
+ * without bumping its npm package; once that lands, entries
+ * graduate into the adapter packages.
+ */
+/** Where on disk the resume id ends up on the session descriptor. */
+type ResumeMetadataKey = "claudeResumeId" | "hermesResumeId" | "codexResumeId" | "openClawResumeId" | "openCodeResumeId";
+interface ResumeStrategy {
+    /** When set, run on every output line for this adapter. Group 1
+     *  captures the resume id. The match is saved on the descriptor
+     *  as `resumeMetadata[storeAs]`. */
+    outputHint?: RegExp;
+    /** Where the matched id is recorded on the descriptor. */
+    storeAs: ResumeMetadataKey;
+    /** Probe the adapter's on-disk session store for the most-recently
+     *  modified session in the given workspace. Returns the resume id
+     *  or null when nothing eligible. Files older than `prevStartedAt`
+     *  are ignored (avoids resuming an unrelated prior conversation).
+     *
+     *  Skip when the adapter doesn't persist sessions externally. */
+    fsProbe?(cwd: string, prevStartedAt: string): Promise<string | null>;
+    /** Return the argv to spawn a PTY that resumes into the given id.
+     *  When omitted, the daemon falls back to ACP-level resume via
+     *  the agent-cli protocol instead of the provider's native CLI. */
+    spawnArgs?(id: string): string[];
+}
+declare const RESUME_STRATEGIES: Record<string, ResumeStrategy>;
+/**
+ * Helper: which adapters declare any resume capability? Used by
+ * `agentproto sessions restart` to print a helpful "this adapter
+ * doesn't support resume; falling back to fresh spawn" hint when
+ * applicable.
+ */
+declare function hasResumeStrategy(adapterSlug: string | undefined): boolean;
+
+export { RESUME_STRATEGIES, type ResumeMetadataKey, type ResumeStrategy, hasResumeStrategy };

package/dist/resume-strategies.mjs

@@ -0,0 +1,64 @@
+import { promises } from 'fs';
+import { homedir } from 'os';
+import { resolve, join } from 'path';
+
+/**
+ * @agentproto/runtime v0.1.0-alpha
+ * Long-running gateway: MCP server + HTTP transport + HEARTBEAT autonomy + conversation persistence over a workspace dir.
+ */
+
+var RESUME_STRATEGIES = {
+  "claude-code": {
+    // Printed by claude on graceful exit when session persistence
+    // is on (default). Example: `claude --resume 0e483f81-1a44-4bec-9667-b37158450296`
+    outputHint: /claude\s+--resume\s+([0-9a-f-]{8,})/i,
+    storeAs: "claudeResumeId",
+    fsProbe: probeMtimeLatestJsonl(".claude/projects"),
+    spawnArgs: (id) => ["claude", "--resume", id]
+  }
+  // Stubs for other shipped adapters — fill in as we learn each
+  // provider's resume mechanism. Today they fall back to ACP-level
+  // resume (whatever the agent-cli runtime supports) or fresh spawn.
+  //
+  //   hermes: { storeAs: "hermesResumeId", ... }
+  //   codex: { storeAs: "codexResumeId", ... }
+  //   openclaw: { storeAs: "openClawResumeId", ... }
+  //   opencode: { storeAs: "openCodeResumeId", ... }
+};
+function probeMtimeLatestJsonl(storeRel) {
+  return async (cwd, prevStartedAt) => {
+    const encoded = cwd.replace(/\//g, "-");
+    const dir = resolve(homedir(), storeRel, encoded);
+    let entries;
+    try {
+      entries = await promises.readdir(dir);
+    } catch {
+      return null;
+    }
+    const jsonl = entries.filter((e) => e.endsWith(".jsonl"));
+    if (jsonl.length === 0) return null;
+    const startedAtMs = Date.parse(prevStartedAt);
+    const candidates = [];
+    for (const f of jsonl) {
+      try {
+        const st = await promises.stat(join(dir, f));
+        if (!Number.isFinite(startedAtMs) || st.mtimeMs >= startedAtMs - 1e3) {
+          candidates.push({ name: f, mtime: st.mtimeMs });
+        }
+      } catch {
+      }
+    }
+    if (candidates.length === 0) return null;
+    candidates.sort((a, b) => b.mtime - a.mtime);
+    return candidates[0].name.replace(/\.jsonl$/, "");
+  };
+}
+function hasResumeStrategy(adapterSlug) {
+  if (!adapterSlug) return false;
+  const s = RESUME_STRATEGIES[adapterSlug];
+  return !!(s && (s.outputHint || s.fsProbe || s.spawnArgs));
+}
+
+export { RESUME_STRATEGIES, hasResumeStrategy };
+//# sourceMappingURL=resume-strategies.mjs.map
+//# sourceMappingURL=resume-strategies.mjs.map

package/dist/resume-strategies.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resume-strategies.ts"],"names":["fs"],"mappings":";;;;;;;;;AAoEO,IAAM,iBAAA,GAAoD;AAAA,EAC/D,aAAA,EAAe;AAAA;AAAA;AAAA,IAGb,UAAA,EAAY,sCAAA;AAAA,IACZ,OAAA,EAAS,gBAAA;AAAA,IACT,OAAA,EAAS,sBAAsB,kBAAkB,CAAA;AAAA,IACjD,SAAA,EAAW,CAAA,EAAA,KAAM,CAAC,QAAA,EAAU,YAAY,EAAE;AAAA;AAC5C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUF;AASA,SAAS,sBACP,QAAA,EACgE;AAChE,EAAA,OAAO,OAAO,KAAK,aAAA,KAAkB;AACnC,IAAA,MAAM,OAAA,GAAU,GAAA,CAAI,OAAA,CAAQ,KAAA,EAAO,GAAG,CAAA;AACtC,IAAA,MAAM,GAAA,GAAM,OAAA,CAAQ,OAAA,EAAQ,EAAG,UAAU,OAAO,CAAA;AAChD,IAAA,IAAI,OAAA;AACJ,IAAA,IAAI;AACF,MAAA,OAAA,GAAU,MAAMA,QAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAAA,IAChC,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,IAAA;AAAA,IACT;AACA,IAAA,MAAM,QAAQ,OAAA,CAAQ,MAAA,CAAO,OAAK,CAAA,CAAE,QAAA,CAAS,QAAQ,CAAC,CAAA;AACtD,IAAA,IAAI,KAAA,CAAM,MAAA,KAAW,CAAA,EAAG,OAAO,IAAA;AAC/B,IAAA,MAAM,WAAA,GAAc,IAAA,CAAK,KAAA,CAAM,aAAa,CAAA;AAC5C,IAAA,MAAM,aAAgD,EAAC;AACvD,IAAA,KAAA,MAAW,KAAK,KAAA,EAAO;AACrB,MAAA,IAAI;AACF,QAAA,MAAM,KAAK,MAAMA,QAAA,CAAG,KAAK,IAAA,CAAK,GAAA,EAAK,CAAC,CAAC,CAAA;AACrC,QAAA,IAAI,CAAC,OAAO,QAAA,CAAS,WAAW,KAAK,EAAA,CAAG,OAAA,IAAW,cAAc,GAAA,EAAM;AACrE,UAAA,UAAA,CAAW,KAAK,EAAE,IAAA,EAAM,GAAG,KAAA,EAAO,EAAA,CAAG,SAAS,CAAA;AAAA,QAChD;AAAA,MACF,CAAA,CAAA,MAAQ;AAAA,MAER;AAAA,IACF;AACA,IAAA,IAAI,UAAA,CAAW,MAAA,KAAW,CAAA,EAAG,OAAO,IAAA;AACpC,IAAA,UAAA,CAAW,KAAK,CAAC,CAAA,EAAG,MAAM,CAAA,CAAE,KAAA,GAAQ,EAAE,KAAK,CAAA;AAC3C,IAAA,OAAO,WAAW,CAAC,CAAA,CAAG,IAAA,CAAK,OAAA,CAAQ,YAAY,EAAE,CAAA;AAAA,EACnD,CAAA;AACF;AAQO,SAAS,kBAAkB,WAAA,EAA0C;AAC1E,EAAA,IAAI,CAAC,aAAa,OAAO,KAAA;AACzB,EAAA,MAAM,CAAA,GAAI,kBAAkB,WAAW,CAAA;AACvC,EAAA,OAAO,CAAC,EAAE,CAAA,KAAM,EAAE,UAAA,IAAc,CAAA,CAAE,WAAW,CAAA,CAAE,SAAA,CAAA,CAAA;AACjD","file":"resume-strategies.mjs","sourcesContent":["/**\n * Per-adapter resume strategies — the daemon's view of \"how do I\n * continue a previous session for THIS adapter?\".\n *\n * The driver already has an `AgentCliContinuation` declaration in\n * the adapter manifest (AIP-45). That covers strategy NAMES\n * (`native-resume`, `pinned-session`, `transcript`, `none`) but is\n * silent on the mechanics that live OUTSIDE the runtime — like\n * \"where on disk does this adapter store its conversations?\" or\n * \"what argv do I pass to resume into PTY mode?\".\n *\n * This table is that practical bridge. Each entry declares three\n * optional hooks:\n *\n *   outputHint   regex matched against each output line; group 1 is\n *                the resume id. Stored as `desc.resumeMetadata[storeAs]`.\n *   fsProbe      async function that probes a per-adapter directory\n *                for a stored session id, scoped to a workspace cwd.\n *                Used when `outputHint` never matched.\n *   spawnArgs    given a captured id, returns the argv to spawn a\n *                PTY that resumes the session. agentproto then\n *                bypasses ACP/agent-cli and runs the provider\n *                directly — the most reliable resume path because\n *                it leans on the provider's native UX.\n *\n * Adapters that don't declare anything here fall back to:\n *   1. ACP-level resume via `resumeSessionId` on POST /sessions/agent\n *   2. Fresh spawn (same shape, no continuity)\n *\n * Eventually each adapter should ship its own strategy on\n * `AgentCliHandle.resumeStrategy` (driver-side). This central table\n * is the bootstrap: it lets a new adapter become resume-capable\n * without bumping its npm package; once that lands, entries\n * graduate into the adapter packages.\n */\n\nimport { promises as fs } from \"node:fs\"\nimport { homedir } from \"node:os\"\nimport { join, resolve } from \"node:path\"\n\n/** Where on disk the resume id ends up on the session descriptor. */\nexport type ResumeMetadataKey =\n  | \"claudeResumeId\"\n  | \"hermesResumeId\"\n  | \"codexResumeId\"\n  | \"openClawResumeId\"\n  | \"openCodeResumeId\"\n\nexport interface ResumeStrategy {\n  /** When set, run on every output line for this adapter. Group 1\n   *  captures the resume id. The match is saved on the descriptor\n   *  as `resumeMetadata[storeAs]`. */\n  outputHint?: RegExp\n  /** Where the matched id is recorded on the descriptor. */\n  storeAs: ResumeMetadataKey\n  /** Probe the adapter's on-disk session store for the most-recently\n   *  modified session in the given workspace. Returns the resume id\n   *  or null when nothing eligible. Files older than `prevStartedAt`\n   *  are ignored (avoids resuming an unrelated prior conversation).\n   *\n   *  Skip when the adapter doesn't persist sessions externally. */\n  fsProbe?(cwd: string, prevStartedAt: string): Promise<string | null>\n  /** Return the argv to spawn a PTY that resumes into the given id.\n   *  When omitted, the daemon falls back to ACP-level resume via\n   *  the agent-cli protocol instead of the provider's native CLI. */\n  spawnArgs?(id: string): string[]\n}\n\nexport const RESUME_STRATEGIES: Record<string, ResumeStrategy> = {\n  \"claude-code\": {\n    // Printed by claude on graceful exit when session persistence\n    // is on (default). Example: `claude --resume 0e483f81-1a44-4bec-9667-b37158450296`\n    outputHint: /claude\\s+--resume\\s+([0-9a-f-]{8,})/i,\n    storeAs: \"claudeResumeId\",\n    fsProbe: probeMtimeLatestJsonl(\".claude/projects\"),\n    spawnArgs: id => [\"claude\", \"--resume\", id],\n  },\n\n  // Stubs for other shipped adapters — fill in as we learn each\n  // provider's resume mechanism. Today they fall back to ACP-level\n  // resume (whatever the agent-cli runtime supports) or fresh spawn.\n  //\n  //   hermes: { storeAs: \"hermesResumeId\", ... }\n  //   codex: { storeAs: \"codexResumeId\", ... }\n  //   openclaw: { storeAs: \"openClawResumeId\", ... }\n  //   opencode: { storeAs: \"openCodeResumeId\", ... }\n}\n\n/**\n * Build an `fsProbe` for adapters that store one `.jsonl` per session\n * inside `~/<storeRel>/<cwd-encoded>/`. The encoded cwd is the\n * absolute path with `/` → `-` (claude's convention; others tend to\n * use the same scheme). Returns the UUID of the most-recently\n * modified `.jsonl`, filtered to files at-or-after `prevStartedAt`.\n */\nfunction probeMtimeLatestJsonl(\n  storeRel: string,\n): (cwd: string, prevStartedAt: string) => Promise<string | null> {\n  return async (cwd, prevStartedAt) => {\n    const encoded = cwd.replace(/\\//g, \"-\")\n    const dir = resolve(homedir(), storeRel, encoded)\n    let entries: string[]\n    try {\n      entries = await fs.readdir(dir)\n    } catch {\n      return null\n    }\n    const jsonl = entries.filter(e => e.endsWith(\".jsonl\"))\n    if (jsonl.length === 0) return null\n    const startedAtMs = Date.parse(prevStartedAt)\n    const candidates: { name: string; mtime: number }[] = []\n    for (const f of jsonl) {\n      try {\n        const st = await fs.stat(join(dir, f))\n        if (!Number.isFinite(startedAtMs) || st.mtimeMs >= startedAtMs - 1000) {\n          candidates.push({ name: f, mtime: st.mtimeMs })\n        }\n      } catch {\n        // ignore unreadable entry\n      }\n    }\n    if (candidates.length === 0) return null\n    candidates.sort((a, b) => b.mtime - a.mtime)\n    return candidates[0]!.name.replace(/\\.jsonl$/, \"\")\n  }\n}\n\n/**\n * Helper: which adapters declare any resume capability? Used by\n * `agentproto sessions restart` to print a helpful \"this adapter\n * doesn't support resume; falling back to fresh spawn\" hint when\n * applicable.\n */\nexport function hasResumeStrategy(adapterSlug: string | undefined): boolean {\n  if (!adapterSlug) return false\n  const s = RESUME_STRATEGIES[adapterSlug]\n  return !!(s && (s.outputHint || s.fsProbe || s.spawnArgs))\n}\n"]}

package/dist/workspace-fs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `WorkspaceFs` — minimal `readFile` / `writeFile` adapter over a
+ * workspace directory. Mirrors the `McpWorkspace.filesystem` shape
+ * used by `@guilde/mcp` so the daemon can be plugged in as the
+ * workspace backend for a Guilde MCP server (via its
+ * `loadGuildWorkspace` injection point) without re-shimming.
+ *
+ * All paths are workspace-relative. Absolute paths are rejected to
+ * keep the surface predictable when the daemon binds to a public
+ * port.
+ */
+interface WorkspaceFs {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    exists(path: string): Promise<boolean>;
+}
+interface CreateWorkspaceFsOptions {
+    /** Absolute path to the workspace root. */
+    workspace: string;
+}
+declare class WorkspacePathError extends Error {
+    constructor(message: string);
+}
+declare function createWorkspaceFs(opts: CreateWorkspaceFsOptions): WorkspaceFs;
+
+export { type CreateWorkspaceFsOptions, type WorkspaceFs, WorkspacePathError, createWorkspaceFs };

package/dist/workspace-fs.mjs

@@ -0,0 +1,60 @@
+import { existsSync } from 'fs';
+import { mkdir, writeFile, readFile } from 'fs/promises';
+import { resolve, dirname, isAbsolute, normalize, join, relative } from 'path';
+
+/**
+ * @agentproto/runtime v0.1.0-alpha
+ * Long-running gateway: MCP server + HTTP transport + HEARTBEAT autonomy + conversation persistence over a workspace dir.
+ */
+
+var WorkspacePathError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WorkspacePathError";
+  }
+};
+function createWorkspaceFs(opts) {
+  const root = resolve(opts.workspace);
+  function resolvePath(path) {
+    if (typeof path !== "string" || path.length === 0) {
+      throw new WorkspacePathError("path must be a non-empty string");
+    }
+    if (isAbsolute(path)) {
+      throw new WorkspacePathError(
+        "absolute paths are not allowed; use a workspace-relative path"
+      );
+    }
+    const joined = normalize(join(root, path));
+    const rel = relative(root, joined);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+      throw new WorkspacePathError(
+        `path escapes the workspace: '${path}'`
+      );
+    }
+    return joined;
+  }
+  return {
+    async readFile(path) {
+      const abs = resolvePath(path);
+      const buf = await readFile(abs);
+      return buf.toString("utf8");
+    },
+    async writeFile(path, content) {
+      const abs = resolvePath(path);
+      await mkdir(dirname(abs), { recursive: true });
+      await writeFile(abs, content);
+    },
+    async exists(path) {
+      try {
+        const abs = resolvePath(path);
+        return existsSync(abs);
+      } catch {
+        return false;
+      }
+    }
+  };
+}
+
+export { WorkspacePathError, createWorkspaceFs };
+//# sourceMappingURL=workspace-fs.mjs.map
+//# sourceMappingURL=workspace-fs.mjs.map

package/dist/workspace-fs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workspace-fs.ts"],"names":["fsReadFile","fsWriteFile"],"mappings":";;;;;;;;;AA2BO,IAAM,kBAAA,GAAN,cAAiC,KAAA,CAAM;AAAA,EAC5C,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AAAA,EACd;AACF;AAEO,SAAS,kBAAkB,IAAA,EAA6C;AAC7E,EAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,IAAA,CAAK,SAAS,CAAA;AAEnC,EAAA,SAAS,YAAY,IAAA,EAAsB;AACzC,IAAA,IAAI,OAAO,IAAA,KAAS,QAAA,IAAY,IAAA,CAAK,WAAW,CAAA,EAAG;AACjD,MAAA,MAAM,IAAI,mBAAmB,iCAAiC,CAAA;AAAA,IAChE;AACA,IAAA,IAAI,UAAA,CAAW,IAAI,CAAA,EAAG;AACpB,MAAA,MAAM,IAAI,kBAAA;AAAA,QACR;AAAA,OACF;AAAA,IACF;AACA,IAAA,MAAM,MAAA,GAAS,SAAA,CAAU,IAAA,CAAK,IAAA,EAAM,IAAI,CAAC,CAAA;AACzC,IAAA,MAAM,GAAA,GAAM,QAAA,CAAS,IAAA,EAAM,MAAM,CAAA;AACjC,IAAA,IAAI,IAAI,UAAA,CAAW,IAAI,CAAA,IAAK,UAAA,CAAW,GAAG,CAAA,EAAG;AAC3C,MAAA,MAAM,IAAI,kBAAA;AAAA,QACR,gCAAgC,IAAI,CAAA,CAAA;AAAA,OACtC;AAAA,IACF;AACA,IAAA,OAAO,MAAA;AAAA,EACT;AAEA,EAAA,OAAO;AAAA,IACL,MAAM,SAAS,IAAA,EAAM;AACnB,MAAA,MAAM,GAAA,GAAM,YAAY,IAAI,CAAA;AAC5B,MAAA,MAAM,GAAA,GAAM,MAAMA,QAAA,CAAW,GAAG,CAAA;AAChC,MAAA,OAAO,GAAA,CAAI,SAAS,MAAM,CAAA;AAAA,IAC5B,CAAA;AAAA,IACA,MAAM,SAAA,CAAU,IAAA,EAAM,OAAA,EAAS;AAC7B,MAAA,MAAM,GAAA,GAAM,YAAY,IAAI,CAAA;AAC5B,MAAA,MAAM,MAAM,OAAA,CAAQ,GAAG,GAAG,EAAE,SAAA,EAAW,MAAM,CAAA;AAC7C,MAAA,MAAMC,SAAA,CAAY,KAAK,OAAO,CAAA;AAAA,IAChC,CAAA;AAAA,IACA,MAAM,OAAO,IAAA,EAAM;AACjB,MAAA,IAAI;AACF,QAAA,MAAM,GAAA,GAAM,YAAY,IAAI,CAAA;AAC5B,QAAA,OAAO,WAAW,GAAG,CAAA;AAAA,MACvB,CAAA,CAAA,MAAQ;AACN,QAAA,OAAO,KAAA;AAAA,MACT;AAAA,IACF;AAAA,GACF;AACF","file":"workspace-fs.mjs","sourcesContent":["/**\n * `WorkspaceFs` — minimal `readFile` / `writeFile` adapter over a\n * workspace directory. Mirrors the `McpWorkspace.filesystem` shape\n * used by `@guilde/mcp` so the daemon can be plugged in as the\n * workspace backend for a Guilde MCP server (via its\n * `loadGuildWorkspace` injection point) without re-shimming.\n *\n * All paths are workspace-relative. Absolute paths are rejected to\n * keep the surface predictable when the daemon binds to a public\n * port.\n */\n\nimport { existsSync } from \"node:fs\"\nimport { mkdir, readFile as fsReadFile, writeFile as fsWriteFile } from \"node:fs/promises\"\nimport { dirname, isAbsolute, join, normalize, relative, resolve } from \"node:path\"\n\nexport interface WorkspaceFs {\n  readFile(path: string): Promise<string>\n  writeFile(path: string, content: string | Uint8Array): Promise<void>\n  exists(path: string): Promise<boolean>\n}\n\nexport interface CreateWorkspaceFsOptions {\n  /** Absolute path to the workspace root. */\n  workspace: string\n}\n\nexport class WorkspacePathError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = \"WorkspacePathError\"\n  }\n}\n\nexport function createWorkspaceFs(opts: CreateWorkspaceFsOptions): WorkspaceFs {\n  const root = resolve(opts.workspace)\n\n  function resolvePath(path: string): string {\n    if (typeof path !== \"string\" || path.length === 0) {\n      throw new WorkspacePathError(\"path must be a non-empty string\")\n    }\n    if (isAbsolute(path)) {\n      throw new WorkspacePathError(\n        \"absolute paths are not allowed; use a workspace-relative path\",\n      )\n    }\n    const joined = normalize(join(root, path))\n    const rel = relative(root, joined)\n    if (rel.startsWith(\"..\") || isAbsolute(rel)) {\n      throw new WorkspacePathError(\n        `path escapes the workspace: '${path}'`,\n      )\n    }\n    return joined\n  }\n\n  return {\n    async readFile(path) {\n      const abs = resolvePath(path)\n      const buf = await fsReadFile(abs)\n      return buf.toString(\"utf8\")\n    },\n    async writeFile(path, content) {\n      const abs = resolvePath(path)\n      await mkdir(dirname(abs), { recursive: true })\n      await fsWriteFile(abs, content)\n    },\n    async exists(path) {\n      try {\n        const abs = resolvePath(path)\n        return existsSync(abs)\n      } catch {\n        return false\n      }\n    },\n  }\n}\n"]}

package/dist/workspaces-config.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `~/.agentproto/workspaces.json` — single source of truth for the
+ * local agentproto control plane. Tracks which directories the user
+ * has opted into as agentproto workspaces, plus which one is "active"
+ * (the daemon's default working set when no workspace is named in
+ * a tool call).
+ *
+ * Why a config file instead of recreating an MCP entry per workspace:
+ *   - One daemon = one MCP entry in the user's IDE (clean to read in
+ *     `claude mcp list`, no `dapper_willow` / `noble_lantern` spam).
+ *   - The daemon walks `workspaces[]` at boot and exposes them all;
+ *     tools that need a target take an optional `workspace` arg and
+ *     fall back to `active` when omitted.
+ *   - The CLI (`agentproto workspace add/list/remove/use`), the daemon,
+ *     and the guilde-web onboarding dialog all read+write the same
+ *     file, so changes from one surface are immediately visible to
+ *     the others.
+ *
+ * File layout is intentionally boring (small, hand-editable JSON) —
+ * future fields go on top, never break v1 readers.
+ */
+declare const WORKSPACES_CONFIG_VERSION: 1;
+interface WorkspaceEntry {
+    /** Stable handle — what tools accept as `workspace`. Lowercase
+     *  ASCII, hyphen-only. The CLI sanitises arbitrary names down to
+     *  this shape so paste-from-finder Just Works. */
+    slug: string;
+    /** Absolute filesystem path. Required absolute so the daemon can
+     *  serve the workspace regardless of its own cwd. */
+    path: string;
+    /** ISO-8601 — first time the entry was added. Pure metadata, no
+     *  behavioural impact. */
+    addedAt: string;
+    /** Last time the entry was touched (renamed, path edited, used as
+     *  active). Lets the CLI sort by recency without an N+1 stat. */
+    updatedAt: string;
+    /** Free-text label the user can attach so workspaces with similar
+     *  slugs stay distinguishable in `agentproto workspace list`. */
+    label?: string;
+}
+interface WorkspacesConfig {
+    version: typeof WORKSPACES_CONFIG_VERSION;
+    /** Active workspace slug — daemon defaults to this when no
+     *  `workspace` arg is passed. May be undefined when no workspaces
+     *  are registered yet. */
+    active?: string;
+    workspaces: WorkspaceEntry[];
+}
+declare const DEFAULT_CONFIG_DIR: () => string;
+declare const DEFAULT_CONFIG_PATH: () => string;
+/** Reduce arbitrary user input to a safe slug. Aligns with what most
+ *  tooling validates against (`/^[a-z0-9][a-z0-9-]{0,63}$/`) so the
+ *  daemon never has to encode it for URLs or filesystem paths. */
+declare function sanitizeSlug(input: string): string;
+/** Read the config from disk. Returns an empty config (no workspaces,
+ *  no active) when the file is missing — this is the legitimate
+ *  first-boot state, not an error. */
+declare function loadWorkspacesConfig(path?: string): Promise<WorkspacesConfig>;
+/** Write the config back. Creates the parent directory if missing.
+ *  Atomic-ish: writes to a temp file first, then renames over the
+ *  target — avoids the partial-write window where a concurrent reader
+ *  sees half a JSON object. */
+declare function saveWorkspacesConfig(config: WorkspacesConfig, path?: string): Promise<void>;
+/**
+ * Pure helpers — caller manages persistence. Returns a NEW config
+ * (never mutates) so callers can compose multiple updates before
+ * a single save.
+ */
+declare function addWorkspace(config: WorkspacesConfig, input: {
+    slug: string;
+    path: string;
+    label?: string;
+}): WorkspacesConfig;
+declare function removeWorkspace(config: WorkspacesConfig, slug: string): WorkspacesConfig;
+declare function setActiveWorkspace(config: WorkspacesConfig, slug: string): WorkspacesConfig;
+declare function findWorkspace(config: WorkspacesConfig, slug: string): WorkspaceEntry | undefined;
+/** The active workspace, or undefined when none is registered. Pure
+ *  convenience to avoid re-implementing the lookup at every caller. */
+declare function getActiveWorkspace(config: WorkspacesConfig): WorkspaceEntry | undefined;
+
+export { DEFAULT_CONFIG_DIR, DEFAULT_CONFIG_PATH, WORKSPACES_CONFIG_VERSION, type WorkspaceEntry, type WorkspacesConfig, addWorkspace, findWorkspace, getActiveWorkspace, loadWorkspacesConfig, removeWorkspace, sanitizeSlug, saveWorkspacesConfig, setActiveWorkspace };