@agentproto/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy André and agentproto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @agentproto/runtime
+
+The long-running gateway that turns an agentproto workspace into a live runtime. Composes the MCP server (CRUD verbs), HTTP transport, HEARTBEAT.md autonomy loop, conversation persistence, and the **sessions registry** (agent CLIs, raw spawns, and real PTY-backed terminals).
+
+Used directly by [`@agentproto/cli`](../cli/README.md)'s `agentproto serve` verb. Also embeddable when you want to host the same surface inside another Node process (the playground gateway, app-specific deployments, etc.).
+
+```bash
+npm install @agentproto/runtime
+```
+
+## Quick start
+
+If you just want a daemon, use the CLI — `agentproto serve` wires this package end-to-end with adapter resolution, PTY support, and tunnel reconnect logic. The docs below cover the **embedding** path.
+
+```ts
+import { createGateway } from "@agentproto/runtime"
+import { loadNodePtyFactory } from "@agentproto/cli/util/pty-factory" // optional
+
+const gateway = await createGateway({
+  workspace: "/abs/path/to/workspace",
+  specs: [],                                  // AIP doctype specs (optional)
+  port: 18790,
+  // Optional: enable POST /sessions/terminal + WS /sessions/:id/pty
+  spawnPty: await loadNodePtyFactory() ?? undefined,
+  // Optional: enable POST /sessions/agent + start_agent_session MCP tool
+  resolveAgentAdapter: async slug => { /* return AgentAdapter or null */ },
+  listAgentAdapters: async () => [ /* AdapterInfo[] */ ],
+})
+console.log("gateway up at", gateway.url)
+// ... later
+await gateway.stop()
+```
+
+A per-boot bearer token is generated automatically and written into `<workspace>/.agentproto/runtime.json` (mode `0600`). Override with `createGateway({ token })` if you have your own.
+
+## What the gateway exposes
+
+| Surface           | URL                                      | Notes                                                  |
+|-------------------|------------------------------------------|--------------------------------------------------------|
+| Health            | `GET /health`                            | Workspace + uptime — always public                     |
+| Events (SSE)      | `GET /events`                            | RuntimeEvents stream                                   |
+| MCP               | `POST /mcp` (Streamable HTTP)            | Stateless mode; per-request transport                  |
+| Conversations     | `GET /conversations` / `GET /conversations/<id>` | Markdown bodies                                |
+| Adapter discovery | `GET /adapters`                          | When `listAgentAdapters` is wired                      |
+| Sessions list     | `GET /sessions` / `GET /sessions/:id`    | id-or-name in `:id`                                   |
+| Agent spawn       | `POST /sessions/agent`                   | Long-lived ACP agent (needs `resolveAgentAdapter`)    |
+| **PTY spawn**     | **`POST /sessions/terminal`**            | Needs `spawnPty` factory                              |
+| **PTY attach**    | **`WS /sessions/:id/pty`**               | JSON frames `{kind:data|input|resize|exit|ping|pong}`; multi-subscriber, min-size resize, ring-buffer replay |
+| SSE attach        | `GET /sessions/:id/stream`               | Line-by-line text events                              |
+| Kill / forget     | `POST /sessions/:id/kill`, `DELETE /sessions/:id` | SIGTERM, then drop from registry             |
+
+### Auth model
+
+- `Authorization: Bearer <token>` required on **mutating** `/sessions/*` routes (POST/DELETE) and the PTY WS upgrade.
+- **No loopback bypass** for those routes — the threat being defended against is a browser fetch from a localhost-loaded page, which IS loopback. A browser can't read `runtime.json` (mode 0600); a same-user process can.
+- Read routes (`GET /sessions`, SSE `/stream`) stay open for read-only telemetry compatibility.
+- The optional `auth?: AuthOptions` field on `createGateway` is for the *tunnel* bearer (Cloudflare-fronted public surface), independent of the per-boot token.
+
+## SessionsRegistry
+
+Exposed via `gateway.sessions`. Useful when you want to register externally-spawned children (e.g. tunnel-driven spawns) or programmatically attach without going through HTTP.
+
+```ts
+gateway.sessions.spawnPty({
+  argv: ["bash", "-l"],
+  cwd: gateway.workspace,
+  workspaceSlug: "default",
+  cols: 120,
+  rows: 40,
+  name: "ops-shell",
+})
+
+const handle = gateway.sessions.attachPty(
+  "ops-shell",
+  { cols: 120, rows: 40 },
+  (chunk) => process.stdout.write(chunk),
+  (evt) => console.log("exited", evt.exitCode),
+)
+handle?.write("uptime\n")
+handle?.resize(80, 24)
+handle?.detach()
+```
+
+Other methods: `spawn` (raw `child_process.spawn`), `spawnAgent` (ACP), `register` (adopt an external `ChildProcess`), `attach` (SSE-style line subscription), `kill`, `forget`, `findByIdOrName`, `writeTerminalInput`, `readTerminalOutput`, `shutdown`. See [`sessions.ts`](./src/sessions.ts) for the typed surface.
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).

package/dist/config.d.ts

@@ -0,0 +1,144 @@
+/**
+ * `~/.agentproto/config.json` — single hand-editable JSON for the
+ * agentproto control plane's defaults. Sits alongside the existing
+ * surface files (workspaces.json, credentials.json, sessions.json):
+ *
+ *   workspaces.json     which directories are workspaces + which is active
+ *   credentials.json    tunnel host bearer tokens (mode 0600)
+ *   sessions.json       last-known snapshot of the registry (informational)
+ *   config.json         daemon defaults: port, bind, allowed origins,
+ *                       tunnel host, feature toggles
+ *
+ * Resolution order for every daemon knob is:
+ *   1. CLI flag (e.g. --port)
+ *   2. Env var (where one exists, e.g. AGENTPROTO_TOKEN)
+ *   3. config.json
+ *   4. Hardcoded default
+ *
+ * This means a user can call `agentproto config set daemon.port 18791`
+ * once and never re-pass `--port 18791` to `serve install` etc. CLI
+ * flags still win for one-off overrides.
+ *
+ * Schema is intentionally narrow + extensible — unknown keys are
+ * preserved on save (deep-merge), so a newer CLI writing a new
+ * field won't drop one an older CLI doesn't know about. No secrets
+ * here; credentials stay in credentials.json (mode 0600).
+ */
+declare const CONFIG_VERSION: 1;
+interface DaemonConfig {
+    /** Absolute path to the workspace the daemon binds to at boot. */
+    workspace?: string;
+    /** HTTP port. Default 18790. */
+    port?: number;
+    /** Bind addr. Default 127.0.0.1. */
+    bind?: string;
+    /** Trusted browser origins for mutating /sessions/* routes (in
+     *  addition to the hardcoded localhost defaults). */
+    allowedOrigins?: string[];
+    /** When true, the daemon does NOT auto-trust localhost-on-any-port.
+     *  Only origins explicitly listed in `allowedOrigins` are allowed.
+     *  Pair with a curated list (e.g. `["http://localhost:3000"]`) for
+     *  hardened setups. Default false. */
+    strictOrigins?: boolean;
+    /** Server label sent in tunnel hello frames. */
+    label?: string;
+}
+interface TunnelConfig {
+    /** Cloud WS URL. When set + autoconnect=true, `agentproto serve`
+     *  bootstraps with `--connect <host>`. */
+    host?: string;
+    /** apt_ daemon token to present at the tunnel upgrade. When set,
+     *  `agentproto serve` uses this BEFORE falling back to
+     *  credentials.json — handy in profiles where the token-per-host
+     *  mapping in credentials.json doesn't fit (e.g. host = tunnel URL
+     *  but credentials were minted against the api URL). */
+    token?: string;
+    /** Whether `agentproto daemon start` connects the tunnel by
+     *  default. v0 only — implementer can ignore until daemon needs it. */
+    autoconnect?: boolean;
+}
+interface FeaturesConfig {
+    /** Hint that PTY is desired — informational; the daemon still
+     *  detects node-pty's presence at runtime. */
+    pty?: boolean;
+}
+/**
+ * Per-environment connection bundle. A profile overrides specific
+ * fields of the top-level `daemon` / `tunnel` / `features` blocks
+ * when selected via `--profile <name>` (or the top-level
+ * `activeProfile` setting). Missing fields fall through to the
+ * top-level config, so a profile only needs to declare what's
+ * different — typically just `tunnel.host` + `tunnel.token`.
+ *
+ * Example:
+ *   {
+ *     "daemon": { "workspace": "/code", "port": 18790 },
+ *     "activeProfile": "local",
+ *     "profiles": {
+ *       "local": { "tunnel": { "host": "ws://localhost:3200/connect",
+ *                              "token": "apt_local", "autoconnect": true } },
+ *       "prod":  { "tunnel": { "host": "wss://tunnel.guilde.work/connect",
+ *                              "token": "apt_prod",  "autoconnect": true },
+ *                  "daemon": { "port": 18791 } }
+ *     }
+ *   }
+ *
+ * Sandbox daemons generate per-sandbox profile entries at provision
+ * time so the daemon inside the sandbox boots with
+ * `agentproto serve --profile sandbox-<id>` and no extra plumbing.
+ */
+interface ProfileConfig {
+    daemon?: DaemonConfig;
+    tunnel?: TunnelConfig;
+    features?: FeaturesConfig;
+}
+interface AgentprotoConfig {
+    version?: number;
+    daemon?: DaemonConfig;
+    tunnel?: TunnelConfig;
+    features?: FeaturesConfig;
+    /** Named connection profiles. See `ProfileConfig` for the merge
+     *  semantics — a profile's fields shallow-override the top-level
+     *  defaults for the selected run. */
+    profiles?: Record<string, ProfileConfig>;
+    /** Profile name to use when `--profile` isn't passed. When unset,
+     *  the top-level `daemon` / `tunnel` blocks are used directly. */
+    activeProfile?: string;
+    /** Unknown keys preserved across save round-trips. */
+    [unknown: string]: unknown;
+}
+declare const CONFIG_FILE_PATH: () => string;
+/**
+ * Load config.json. Returns an empty object (NOT null) when the file
+ * is missing, malformed, or unreadable — callers can `cfg.daemon?.port`
+ * safely without null-guards. Errors during a malformed-read are
+ * logged once so the user notices the file is broken without the
+ * daemon refusing to boot.
+ */
+declare function loadConfig(path?: string): Promise<AgentprotoConfig>;
+/**
+ * Write config.json atomically (tmp + rename) so a concurrent
+ * `agentproto config edit` can't half-truncate the file. Writes
+ * `next` AS-IS — callers are expected to pass the full desired
+ * state (loaded the existing config, mutated, passed it back).
+ *
+ * Earlier versions deep-merged with the on-disk file, but that made
+ * deletions impossible: `setConfigKey(cfg, "x", undefined)` would
+ * remove the key from memory, then the deep-merge would silently
+ * re-add it from disk. The current design trusts the caller's
+ * snapshot and uses atomic rename for crash safety.
+ */
+declare function saveConfig(next: AgentprotoConfig, path?: string): Promise<void>;
+/**
+ * Read a dot-notation key (`daemon.port`) out of a config. Returns
+ * `undefined` when any segment is missing.
+ */
+declare function getConfigKey(cfg: AgentprotoConfig, dotted: string): unknown;
+/**
+ * Set a dot-notation key in a config. Returns a new object — does
+ * NOT mutate. Creates intermediate objects as needed. Setting
+ * `value: undefined` is treated as a delete.
+ */
+declare function setConfigKey(cfg: AgentprotoConfig, dotted: string, value: unknown): AgentprotoConfig;
+
+export { type AgentprotoConfig, CONFIG_FILE_PATH, CONFIG_VERSION, type DaemonConfig, type FeaturesConfig, type ProfileConfig, type TunnelConfig, getConfigKey, loadConfig, saveConfig, setConfigKey };

package/dist/config.mjs

@@ -0,0 +1,76 @@
+import { promises } from 'fs';
+import { homedir } from 'os';
+import { join, 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 CONFIG_VERSION = 1;
+var CONFIG_FILE_PATH = () => join(homedir(), ".agentproto", "config.json");
+async function loadConfig(path) {
+  const target = path ?? CONFIG_FILE_PATH();
+  try {
+    const raw = await promises.readFile(target, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    console.warn(
+      `[runtime/config] ${target}: top-level value is not an object \u2014 ignoring`
+    );
+    return {};
+  } catch (err) {
+    const code = err.code;
+    if (code && code !== "ENOENT") {
+      console.warn(
+        `[runtime/config] failed to read ${target}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    return {};
+  }
+}
+async function saveConfig(next, path) {
+  const target = path ?? CONFIG_FILE_PATH();
+  const payload = { ...next, version: CONFIG_VERSION };
+  const dir = dirname(target);
+  await promises.mkdir(dir, { recursive: true });
+  const tmp = `${target}.tmp`;
+  await promises.writeFile(tmp, JSON.stringify(payload, null, 2) + "\n", "utf8");
+  await promises.rename(tmp, target);
+}
+function getConfigKey(cfg, dotted) {
+  let cur = cfg;
+  for (const part of dotted.split(".")) {
+    if (cur == null || typeof cur !== "object") return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+function setConfigKey(cfg, dotted, value) {
+  const parts = dotted.split(".");
+  const out = { ...cfg };
+  let cur = out;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const k = parts[i];
+    const next = cur[k];
+    if (next && typeof next === "object" && !Array.isArray(next)) {
+      cur[k] = { ...next };
+    } else {
+      cur[k] = {};
+    }
+    cur = cur[k];
+  }
+  const leaf = parts[parts.length - 1];
+  if (value === void 0) {
+    delete cur[leaf];
+  } else {
+    cur[leaf] = value;
+  }
+  return out;
+}
+
+export { CONFIG_FILE_PATH, CONFIG_VERSION, getConfigKey, loadConfig, saveConfig, setConfigKey };
+//# sourceMappingURL=config.mjs.map
+//# sourceMappingURL=config.mjs.map

package/dist/config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"names":["fs"],"mappings":"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","file":"config.mjs","sourcesContent":["/**\n * `~/.agentproto/config.json` — single hand-editable JSON for the\n * agentproto control plane's defaults. Sits alongside the existing\n * surface files (workspaces.json, credentials.json, sessions.json):\n *\n *   workspaces.json     which directories are workspaces + which is active\n *   credentials.json    tunnel host bearer tokens (mode 0600)\n *   sessions.json       last-known snapshot of the registry (informational)\n *   config.json         daemon defaults: port, bind, allowed origins,\n *                       tunnel host, feature toggles\n *\n * Resolution order for every daemon knob is:\n *   1. CLI flag (e.g. --port)\n *   2. Env var (where one exists, e.g. AGENTPROTO_TOKEN)\n *   3. config.json\n *   4. Hardcoded default\n *\n * This means a user can call `agentproto config set daemon.port 18791`\n * once and never re-pass `--port 18791` to `serve install` etc. CLI\n * flags still win for one-off overrides.\n *\n * Schema is intentionally narrow + extensible — unknown keys are\n * preserved on save (deep-merge), so a newer CLI writing a new\n * field won't drop one an older CLI doesn't know about. No secrets\n * here; credentials stay in credentials.json (mode 0600).\n */\n\nimport { promises as fs } from \"node:fs\"\nimport { homedir } from \"node:os\"\nimport { dirname, join } from \"node:path\"\n\nexport const CONFIG_VERSION = 1 as const\n\nexport interface DaemonConfig {\n  /** Absolute path to the workspace the daemon binds to at boot. */\n  workspace?: string\n  /** HTTP port. Default 18790. */\n  port?: number\n  /** Bind addr. Default 127.0.0.1. */\n  bind?: string\n  /** Trusted browser origins for mutating /sessions/* routes (in\n   *  addition to the hardcoded localhost defaults). */\n  allowedOrigins?: string[]\n  /** When true, the daemon does NOT auto-trust localhost-on-any-port.\n   *  Only origins explicitly listed in `allowedOrigins` are allowed.\n   *  Pair with a curated list (e.g. `[\"http://localhost:3000\"]`) for\n   *  hardened setups. Default false. */\n  strictOrigins?: boolean\n  /** Server label sent in tunnel hello frames. */\n  label?: string\n}\n\nexport interface TunnelConfig {\n  /** Cloud WS URL. When set + autoconnect=true, `agentproto serve`\n   *  bootstraps with `--connect <host>`. */\n  host?: string\n  /** apt_ daemon token to present at the tunnel upgrade. When set,\n   *  `agentproto serve` uses this BEFORE falling back to\n   *  credentials.json — handy in profiles where the token-per-host\n   *  mapping in credentials.json doesn't fit (e.g. host = tunnel URL\n   *  but credentials were minted against the api URL). */\n  token?: string\n  /** Whether `agentproto daemon start` connects the tunnel by\n   *  default. v0 only — implementer can ignore until daemon needs it. */\n  autoconnect?: boolean\n}\n\nexport interface FeaturesConfig {\n  /** Hint that PTY is desired — informational; the daemon still\n   *  detects node-pty's presence at runtime. */\n  pty?: boolean\n}\n\n/**\n * Per-environment connection bundle. A profile overrides specific\n * fields of the top-level `daemon` / `tunnel` / `features` blocks\n * when selected via `--profile <name>` (or the top-level\n * `activeProfile` setting). Missing fields fall through to the\n * top-level config, so a profile only needs to declare what's\n * different — typically just `tunnel.host` + `tunnel.token`.\n *\n * Example:\n *   {\n *     \"daemon\": { \"workspace\": \"/code\", \"port\": 18790 },\n *     \"activeProfile\": \"local\",\n *     \"profiles\": {\n *       \"local\": { \"tunnel\": { \"host\": \"ws://localhost:3200/connect\",\n *                              \"token\": \"apt_local\", \"autoconnect\": true } },\n *       \"prod\":  { \"tunnel\": { \"host\": \"wss://tunnel.guilde.work/connect\",\n *                              \"token\": \"apt_prod\",  \"autoconnect\": true },\n *                  \"daemon\": { \"port\": 18791 } }\n *     }\n *   }\n *\n * Sandbox daemons generate per-sandbox profile entries at provision\n * time so the daemon inside the sandbox boots with\n * `agentproto serve --profile sandbox-<id>` and no extra plumbing.\n */\nexport interface ProfileConfig {\n  daemon?: DaemonConfig\n  tunnel?: TunnelConfig\n  features?: FeaturesConfig\n}\n\nexport interface AgentprotoConfig {\n  version?: number\n  daemon?: DaemonConfig\n  tunnel?: TunnelConfig\n  features?: FeaturesConfig\n  /** Named connection profiles. See `ProfileConfig` for the merge\n   *  semantics — a profile's fields shallow-override the top-level\n   *  defaults for the selected run. */\n  profiles?: Record<string, ProfileConfig>\n  /** Profile name to use when `--profile` isn't passed. When unset,\n   *  the top-level `daemon` / `tunnel` blocks are used directly. */\n  activeProfile?: string\n  /** Unknown keys preserved across save round-trips. */\n  [unknown: string]: unknown\n}\n\nexport const CONFIG_FILE_PATH = (): string =>\n  join(homedir(), \".agentproto\", \"config.json\")\n\n/**\n * Load config.json. Returns an empty object (NOT null) when the file\n * is missing, malformed, or unreadable — callers can `cfg.daemon?.port`\n * safely without null-guards. Errors during a malformed-read are\n * logged once so the user notices the file is broken without the\n * daemon refusing to boot.\n */\nexport async function loadConfig(path?: string): Promise<AgentprotoConfig> {\n  const target = path ?? CONFIG_FILE_PATH()\n  try {\n    const raw = await fs.readFile(target, \"utf8\")\n    const parsed = JSON.parse(raw) as unknown\n    if (parsed && typeof parsed === \"object\" && !Array.isArray(parsed)) {\n      return parsed as AgentprotoConfig\n    }\n    console.warn(\n      `[runtime/config] ${target}: top-level value is not an object — ignoring`,\n    )\n    return {}\n  } catch (err) {\n    // ENOENT is the common case; only warn on other shapes.\n    const code = (err as NodeJS.ErrnoException).code\n    if (code && code !== \"ENOENT\") {\n      console.warn(\n        `[runtime/config] failed to read ${target}: ${\n          err instanceof Error ? err.message : String(err)\n        }`,\n      )\n    }\n    return {}\n  }\n}\n\n/**\n * Write config.json atomically (tmp + rename) so a concurrent\n * `agentproto config edit` can't half-truncate the file. Writes\n * `next` AS-IS — callers are expected to pass the full desired\n * state (loaded the existing config, mutated, passed it back).\n *\n * Earlier versions deep-merged with the on-disk file, but that made\n * deletions impossible: `setConfigKey(cfg, \"x\", undefined)` would\n * remove the key from memory, then the deep-merge would silently\n * re-add it from disk. The current design trusts the caller's\n * snapshot and uses atomic rename for crash safety.\n */\nexport async function saveConfig(\n  next: AgentprotoConfig,\n  path?: string,\n): Promise<void> {\n  const target = path ?? CONFIG_FILE_PATH()\n  const payload = { ...next, version: CONFIG_VERSION }\n  const dir = dirname(target)\n  await fs.mkdir(dir, { recursive: true })\n  const tmp = `${target}.tmp`\n  await fs.writeFile(tmp, JSON.stringify(payload, null, 2) + \"\\n\", \"utf8\")\n  await fs.rename(tmp, target)\n}\n\n/**\n * Read a dot-notation key (`daemon.port`) out of a config. Returns\n * `undefined` when any segment is missing.\n */\nexport function getConfigKey(\n  cfg: AgentprotoConfig,\n  dotted: string,\n): unknown {\n  let cur: unknown = cfg\n  for (const part of dotted.split(\".\")) {\n    if (cur == null || typeof cur !== \"object\") return undefined\n    cur = (cur as Record<string, unknown>)[part]\n  }\n  return cur\n}\n\n/**\n * Set a dot-notation key in a config. Returns a new object — does\n * NOT mutate. Creates intermediate objects as needed. Setting\n * `value: undefined` is treated as a delete.\n */\nexport function setConfigKey(\n  cfg: AgentprotoConfig,\n  dotted: string,\n  value: unknown,\n): AgentprotoConfig {\n  const parts = dotted.split(\".\")\n  const out: AgentprotoConfig = { ...cfg }\n  let cur: Record<string, unknown> = out as Record<string, unknown>\n  for (let i = 0; i < parts.length - 1; i++) {\n    const k = parts[i]!\n    const next = cur[k]\n    if (next && typeof next === \"object\" && !Array.isArray(next)) {\n      cur[k] = { ...(next as Record<string, unknown>) }\n    } else {\n      cur[k] = {}\n    }\n    cur = cur[k] as Record<string, unknown>\n  }\n  const leaf = parts[parts.length - 1]!\n  if (value === undefined) {\n    delete cur[leaf]\n  } else {\n    cur[leaf] = value\n  }\n  return out\n}\n\n/**\n * Deep merge — objects are recursively combined, everything else\n * (arrays, primitives) is replaced wholesale by `b`. Mirrors what\n * `Object.assign({}, a, b)` does for shallow keys.\n */\nfunction deepMerge<A extends Record<string, unknown>, B extends Record<string, unknown>>(\n  a: A,\n  b: B,\n): A & B {\n  const out: Record<string, unknown> = { ...a }\n  for (const [k, v] of Object.entries(b)) {\n    const cur = out[k]\n    if (\n      v &&\n      typeof v === \"object\" &&\n      !Array.isArray(v) &&\n      cur &&\n      typeof cur === \"object\" &&\n      !Array.isArray(cur)\n    ) {\n      out[k] = deepMerge(\n        cur as Record<string, unknown>,\n        v as Record<string, unknown>,\n      )\n    } else {\n      out[k] = v\n    }\n  }\n  return out as A & B\n}\n"]}

package/dist/conversations.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Append-only conversation persistence as plain markdown.
+ *
+ * Each conversation is a file at `<workspace>/conversations/<id>.md`
+ * with a frontmatter header (`schema: conversation/v1`, `id`, `agent`,
+ * `started`, `status`) and a body composed of `## <role> — <iso>`
+ * blocks. Append-only: turns are concatenated to the body, never
+ * rewritten in place. Readers tolerant to clock skew use the timestamp
+ * in each block, not file mtime.
+ *
+ * The format is intentionally trivial — git-diffable, human-editable,
+ * survives `cat`. Designed to converge with the AIP runtime/v1 spec
+ * (TBD) once it lands.
+ */
+type ConvRole = "user" | "assistant" | "system";
+interface ConversationMeta {
+    id: string;
+    agent: string;
+    started: string;
+    status: "open" | "closed";
+}
+interface ConversationTurn {
+    role: ConvRole;
+    at: string;
+    /** Optional sub-attribution after the role (e.g. agent id). */
+    attribution?: string;
+    content: string;
+}
+interface ConversationStore {
+    /**
+     * Open a conversation. If the file doesn't exist, it's created with
+     * a frontmatter header. If it exists, no-op (idempotent).
+     */
+    open(id: string, meta: {
+        agent: string;
+    }): Promise<void>;
+    appendTurn(id: string, role: ConvRole, content: string, opts?: {
+        attribution?: string;
+        at?: string;
+    }): Promise<void>;
+    read(id: string): Promise<{
+        meta: ConversationMeta;
+        turns: ConversationTurn[];
+    }>;
+    list(): Promise<Array<{
+        id: string;
+        meta: ConversationMeta;
+    }>>;
+    /** Workspace-relative path to the conv file, for tooling. */
+    pathFor(id: string): string;
+}
+interface FileConversationStoreOptions {
+    /** Absolute workspace root. */
+    workspace: string;
+    /** Override `<workspace>/conversations`. */
+    dir?: string;
+}
+declare function fileConversationStore(opts: FileConversationStoreOptions): ConversationStore;
+
+export { type ConvRole, type ConversationMeta, type ConversationStore, type ConversationTurn, type FileConversationStoreOptions, fileConversationStore };

package/dist/conversations.mjs

@@ -0,0 +1,146 @@
+import { existsSync } from 'fs';
+import { readdir, readFile, writeFile, mkdir } from 'fs/promises';
+import { 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 FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/;
+function fileConversationStore(opts) {
+  const dir = opts.dir ?? join(opts.workspace, "conversations");
+  const filePath = (id) => join(dir, `${id}.md`);
+  return {
+    pathFor: filePath,
+    async open(id, meta) {
+      await mkdir(dir, { recursive: true });
+      const path = filePath(id);
+      if (existsSync(path)) return;
+      const header = renderHeader({
+        id,
+        agent: meta.agent,
+        started: (/* @__PURE__ */ new Date()).toISOString(),
+        status: "open"
+      });
+      await writeFile(path, header, "utf8");
+    },
+    async appendTurn(id, role, content, options) {
+      const path = filePath(id);
+      if (!existsSync(path)) {
+        await this.open(id, { agent: options?.attribution ?? "unknown" });
+      }
+      const block = renderTurn({
+        role,
+        at: options?.at ?? (/* @__PURE__ */ new Date()).toISOString(),
+        attribution: options?.attribution,
+        content
+      });
+      await writeFile(path, block, { encoding: "utf8", flag: "a" });
+    },
+    async read(id) {
+      const path = filePath(id);
+      const source = await readFile(path, "utf8");
+      return parseConversation(source, id);
+    },
+    async list() {
+      if (!existsSync(dir)) return [];
+      const entries = await readdir(dir, { withFileTypes: true });
+      const out = [];
+      for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+        const id = entry.name.slice(0, -3);
+        try {
+          const source = await readFile(join(dir, entry.name), "utf8");
+          const { meta } = parseConversation(source, id);
+          out.push({ id, meta });
+        } catch {
+        }
+      }
+      return out;
+    }
+  };
+}
+function renderHeader(meta) {
+  return [
+    "---",
+    `schema: conversation/v1`,
+    `id: ${meta.id}`,
+    `agent: ${meta.agent}`,
+    `started: ${meta.started}`,
+    `status: ${meta.status}`,
+    "---",
+    "",
+    ""
+  ].join("\n");
+}
+function renderTurn(turn) {
+  const heading = turn.attribution ? `## ${turn.role} \u2014 ${turn.at} (${turn.attribution})` : `## ${turn.role} \u2014 ${turn.at}`;
+  return `${heading}
+
+${turn.content.trimEnd()}
+
+`;
+}
+function parseConversation(source, fallbackId) {
+  const match = source.match(FRONTMATTER_RE);
+  let meta = {
+    id: fallbackId,
+    agent: "unknown",
+    started: "",
+    status: "open"
+  };
+  let body = source;
+  if (match) {
+    meta = parseFrontmatter(match[1] ?? "", fallbackId);
+    body = source.slice(match[0].length);
+  }
+  const turns = [];
+  const lines = body.split("\n");
+  let current = null;
+  let buffer = [];
+  const flush = () => {
+    if (!current) return;
+    current.content = buffer.join("\n").trim();
+    turns.push(current);
+    current = null;
+    buffer = [];
+  };
+  const headingRe = /^##\s+(user|assistant|system)\s+—\s+(\S+)(?:\s+\(([^)]+)\))?\s*$/;
+  for (const line of lines) {
+    const m = line.match(headingRe);
+    if (m) {
+      flush();
+      current = {
+        role: m[1],
+        at: m[2] ?? "",
+        attribution: m[3],
+        content: ""
+      };
+      continue;
+    }
+    if (current) buffer.push(line);
+  }
+  flush();
+  return { meta, turns };
+}
+function parseFrontmatter(raw, fallbackId) {
+  const out = {};
+  for (const line of raw.split("\n")) {
+    const colon = line.indexOf(":");
+    if (colon < 1) continue;
+    const key = line.slice(0, colon).trim();
+    const value = line.slice(colon + 1).trim();
+    out[key] = value;
+  }
+  return {
+    id: out.id ?? fallbackId,
+    agent: out.agent ?? "unknown",
+    started: out.started ?? "",
+    status: out.status === "closed" ? "closed" : "open"
+  };
+}
+
+export { fileConversationStore };
+//# sourceMappingURL=conversations.mjs.map
+//# sourceMappingURL=conversations.mjs.map

package/dist/conversations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/conversations.ts"],"names":[],"mappings":"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","file":"conversations.mjs","sourcesContent":["/**\n * Append-only conversation persistence as plain markdown.\n *\n * Each conversation is a file at `<workspace>/conversations/<id>.md`\n * with a frontmatter header (`schema: conversation/v1`, `id`, `agent`,\n * `started`, `status`) and a body composed of `## <role> — <iso>`\n * blocks. Append-only: turns are concatenated to the body, never\n * rewritten in place. Readers tolerant to clock skew use the timestamp\n * in each block, not file mtime.\n *\n * The format is intentionally trivial — git-diffable, human-editable,\n * survives `cat`. Designed to converge with the AIP runtime/v1 spec\n * (TBD) once it lands.\n */\n\nimport { existsSync } from \"node:fs\"\nimport { mkdir, readFile, readdir, writeFile } from \"node:fs/promises\"\nimport { join } from \"node:path\"\n\nconst FRONTMATTER_RE = /^---\\n([\\s\\S]*?)\\n---\\n/\n\nexport type ConvRole = \"user\" | \"assistant\" | \"system\"\n\nexport interface ConversationMeta {\n  id: string\n  agent: string\n  started: string\n  status: \"open\" | \"closed\"\n}\n\nexport interface ConversationTurn {\n  role: ConvRole\n  at: string\n  /** Optional sub-attribution after the role (e.g. agent id). */\n  attribution?: string\n  content: string\n}\n\nexport interface ConversationStore {\n  /**\n   * Open a conversation. If the file doesn't exist, it's created with\n   * a frontmatter header. If it exists, no-op (idempotent).\n   */\n  open(id: string, meta: { agent: string }): Promise<void>\n  appendTurn(\n    id: string,\n    role: ConvRole,\n    content: string,\n    opts?: { attribution?: string; at?: string },\n  ): Promise<void>\n  read(\n    id: string,\n  ): Promise<{ meta: ConversationMeta; turns: ConversationTurn[] }>\n  list(): Promise<Array<{ id: string; meta: ConversationMeta }>>\n  /** Workspace-relative path to the conv file, for tooling. */\n  pathFor(id: string): string\n}\n\nexport interface FileConversationStoreOptions {\n  /** Absolute workspace root. */\n  workspace: string\n  /** Override `<workspace>/conversations`. */\n  dir?: string\n}\n\nexport function fileConversationStore(\n  opts: FileConversationStoreOptions,\n): ConversationStore {\n  const dir = opts.dir ?? join(opts.workspace, \"conversations\")\n\n  const filePath = (id: string) => join(dir, `${id}.md`)\n\n  return {\n    pathFor: filePath,\n\n    async open(id, meta) {\n      await mkdir(dir, { recursive: true })\n      const path = filePath(id)\n      if (existsSync(path)) return\n      const header = renderHeader({\n        id,\n        agent: meta.agent,\n        started: new Date().toISOString(),\n        status: \"open\",\n      })\n      await writeFile(path, header, \"utf8\")\n    },\n\n    async appendTurn(id, role, content, options) {\n      const path = filePath(id)\n      // Lazy-open: if a caller appends without opening, create the\n      // file so the operation never silently drops a turn.\n      if (!existsSync(path)) {\n        await this.open(id, { agent: options?.attribution ?? \"unknown\" })\n      }\n      const block = renderTurn({\n        role,\n        at: options?.at ?? new Date().toISOString(),\n        attribution: options?.attribution,\n        content,\n      })\n      // Append a leading blank line so the new block is always\n      // separated from whatever's above (header or prev turn).\n      await writeFile(path, block, { encoding: \"utf8\", flag: \"a\" })\n    },\n\n    async read(id) {\n      const path = filePath(id)\n      const source = await readFile(path, \"utf8\")\n      return parseConversation(source, id)\n    },\n\n    async list() {\n      if (!existsSync(dir)) return []\n      const entries = await readdir(dir, { withFileTypes: true })\n      const out: Array<{ id: string; meta: ConversationMeta }> = []\n      for (const entry of entries) {\n        if (!entry.isFile() || !entry.name.endsWith(\".md\")) continue\n        const id = entry.name.slice(0, -3)\n        try {\n          const source = await readFile(join(dir, entry.name), \"utf8\")\n          const { meta } = parseConversation(source, id)\n          out.push({ id, meta })\n        } catch {\n          // Skip malformed conv files rather than crash list().\n        }\n      }\n      return out\n    },\n  }\n}\n\n// ── render ───────────────────────────────────────────────────────────\n\nfunction renderHeader(meta: ConversationMeta): string {\n  return [\n    \"---\",\n    `schema: conversation/v1`,\n    `id: ${meta.id}`,\n    `agent: ${meta.agent}`,\n    `started: ${meta.started}`,\n    `status: ${meta.status}`,\n    \"---\",\n    \"\",\n    \"\",\n  ].join(\"\\n\")\n}\n\nfunction renderTurn(turn: ConversationTurn): string {\n  const heading = turn.attribution\n    ? `## ${turn.role} — ${turn.at} (${turn.attribution})`\n    : `## ${turn.role} — ${turn.at}`\n  return `${heading}\\n\\n${turn.content.trimEnd()}\\n\\n`\n}\n\n// ── parse ────────────────────────────────────────────────────────────\n\ninterface ParsedConversation {\n  meta: ConversationMeta\n  turns: ConversationTurn[]\n}\n\nfunction parseConversation(source: string, fallbackId: string): ParsedConversation {\n  const match = source.match(FRONTMATTER_RE)\n  let meta: ConversationMeta = {\n    id: fallbackId,\n    agent: \"unknown\",\n    started: \"\",\n    status: \"open\",\n  }\n  let body = source\n  if (match) {\n    meta = parseFrontmatter(match[1] ?? \"\", fallbackId)\n    body = source.slice(match[0].length)\n  }\n\n  const turns: ConversationTurn[] = []\n  // Split on `## <role> — <iso>` headings. Conservative — anything\n  // that doesn't match is treated as continuation of the prior turn.\n  const lines = body.split(\"\\n\")\n  let current: ConversationTurn | null = null\n  let buffer: string[] = []\n\n  const flush = () => {\n    if (!current) return\n    current.content = buffer.join(\"\\n\").trim()\n    turns.push(current)\n    current = null\n    buffer = []\n  }\n\n  const headingRe =\n    /^##\\s+(user|assistant|system)\\s+—\\s+(\\S+)(?:\\s+\\(([^)]+)\\))?\\s*$/\n\n  for (const line of lines) {\n    const m = line.match(headingRe)\n    if (m) {\n      flush()\n      current = {\n        role: m[1] as ConvRole,\n        at: m[2] ?? \"\",\n        attribution: m[3],\n        content: \"\",\n      }\n      continue\n    }\n    if (current) buffer.push(line)\n  }\n  flush()\n\n  return { meta, turns }\n}\n\nfunction parseFrontmatter(\n  raw: string,\n  fallbackId: string,\n): ConversationMeta {\n  const out: Record<string, string> = {}\n  for (const line of raw.split(\"\\n\")) {\n    const colon = line.indexOf(\":\")\n    if (colon < 1) continue\n    const key = line.slice(0, colon).trim()\n    const value = line.slice(colon + 1).trim()\n    out[key] = value\n  }\n  return {\n    id: out.id ?? fallbackId,\n    agent: out.agent ?? \"unknown\",\n    started: out.started ?? \"\",\n    status: (out.status === \"closed\" ? \"closed\" : \"open\"),\n  }\n}\n"]}