@agentproto/runtime 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,546 @@
+import { DoctypeSpec } from '@agentproto/manifest';
+import { B as BuildHeartbeatAgent } from './heartbeat-COGpMrJS.js';
+export { H as HeartbeatAgent, a as HeartbeatRunner, R as RuntimeEvent, b as RuntimeEvents, p as parseDuration } from './heartbeat-COGpMrJS.js';
+import { ChildProcess } from 'node:child_process';
+import { WorkspaceFs } from './workspace-fs.js';
+export { createWorkspaceFs } from './workspace-fs.js';
+export { ConversationMeta, ConversationStore, ConversationTurn, fileConversationStore } from './conversations.js';
+
+/**
+ * Sessions registry — tracks long-lived child processes spawned by
+ * the agentproto daemon (terminals, agent CLIs, custom commands).
+ *
+ * The registry lives in-memory for the daemon's lifetime; a recent
+ * snapshot also persists to `~/.agentproto/sessions.json` so a fresh
+ * daemon restart can show "you had these running before" instead of
+ * losing all visibility on a crash.
+ *
+ * Each session owns:
+ *   - identity: id, kind, workspace slug, command + args, started time
+ *   - lifecycle: status (starting/running/exited/killed/error)
+ *   - output:    last N lines (ring buffer) for instant attach + a
+ *                Node EventEmitter for live streaming consumers
+ *
+ * Consumers:
+ *   - HTTP routes (GET /sessions, /sessions/:id, /sessions/:id/stream,
+ *     POST /sessions/:id/kill)
+ *   - CLI `agentproto sessions` (TUI navigation + attach)
+ *   - guilde-web Active tab (session cards + terminal viewer)
+ */
+
+/**
+ * Minimal shape we need from a driver-agent-cli session — kept as a
+ * structural type so the runtime package doesn't take a hard
+ * dependency on @agentproto/driver-agent-cli (the http-server route
+ * imports it and passes the constructed session in).
+ */
+interface AgentSessionLike {
+    sessionId: string;
+    send(message: unknown): AsyncIterable<AgentStreamEvent>;
+    cancel(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Minimal PTY surface — structurally compatible with
+ * @agentproto/acp/tunnel's PtyProcess (node-pty's IPty wrapper). The
+ * runtime declares its own so this package stays native-free; the
+ * cli's pty-factory util constructs values that satisfy both.
+ */
+interface PtyProcess {
+    readonly pid: number;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+    onData(handler: (data: string) => void): void;
+    onExit(handler: (event: {
+        exitCode: number;
+        signal?: number;
+    }) => void): void;
+}
+interface PtyFactoryOptions {
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    cols: number;
+    rows: number;
+}
+type PtyFactory = (opts: PtyFactoryOptions) => PtyProcess;
+interface AgentStreamEvent {
+    kind: string;
+    text?: string;
+    toolName?: string;
+    isError?: boolean;
+    reason?: string;
+    error?: {
+        message: string;
+        code?: number;
+        data?: unknown;
+    };
+}
+type SessionKind = "terminal" | "agent-cli" | "command";
+type SessionStatus = "starting" | "running" | "exited" | "killed" | "error";
+interface SessionDescriptor {
+    id: string;
+    kind: SessionKind;
+    workspaceSlug: string;
+    /** What was actually run — quoted joined for display purposes
+     *  (`bash -lc "claude --resume xyz"`). */
+    command: string;
+    pid: number | null;
+    status: SessionStatus;
+    startedAt: string;
+    endedAt?: string;
+    exitCode?: number;
+    /** Last time anything was written to stdout/stderr. Lets the UI
+     *  spot stuck sessions ("running for 2h, last output 12min ago"). */
+    lastOutputAt?: string;
+    /** Free-text label the spawner can attach (e.g. conversation id,
+     *  operator name) so the UI can group/filter. */
+    label?: string;
+    /** True when the session was spawned under a real PTY (node-pty)
+     *  instead of `child_process.spawn`. PTY sessions carry raw ANSI
+     *  bytes (alt-screen, key bindings, colors); attach goes through
+     *  WS /sessions/:id/pty rather than SSE /sessions/:id/stream. */
+    pty?: boolean;
+    /** User-friendly slug supplied at spawn time. Optional; when set,
+     *  attach/stop/kill commands accept it as an alias for the id. */
+    name?: string;
+    /** Argv that was spawned. Persisted so `agentproto sessions restart`
+     *  can clone the original shape without re-tokenizing the display
+     *  `command` string. Empty for agent-cli sessions (we record
+     *  `adapterSlug` separately). */
+    argv?: readonly string[];
+    /** Working directory the session was spawned in. Cloned by restart. */
+    cwd?: string;
+    /** Adapter slug for agent-cli sessions — restart uses this with
+     *  `/sessions/agent` to spin up a fresh ACP runtime. Undefined for
+     *  pty/command kinds. */
+    adapterSlug?: string;
+    /** ACP-level session id (the adapter's own handle — claude-code's
+     *  conversation id, hermes' chat id, …). Set at spawnAgent time
+     *  from `agentSession.sessionId`. Survives across daemon restarts
+     *  via sessions.json so `restart` can pass it as `resumeSessionId`
+     *  and reattach to the prior conversation history. */
+    adapterSessionId?: string;
+    /** Provider-specific resume hints sniffed from the session's
+     *  output. claude-code prints `claude --resume <uuid>` on exit;
+     *  we capture that uuid as `claudeResumeId`. On `restart`, when a
+     *  hint is present, agentproto prefers a PTY spawn with the
+     *  provider's native resume command (`claude --resume <id>`) over
+     *  the ACP-level resume — works wherever the provider persisted
+     *  the session, not just when the ACP wrapper did.
+     *
+     *  Keys are adapter-specific so future adapters can add their own
+     *  ("hermesResumeId", etc.) without changing this type. */
+    resumeMetadata?: Record<string, string>;
+}
+interface SessionsRegistry {
+    spawn(input: SpawnSessionInput): SessionDescriptor;
+    /** Adopt a ChildProcess that was spawned outside the registry —
+     *  e.g. by the tunnel server when the host dispatches a spawn
+     *  frame. The registry attaches its stdout/stderr listeners and
+     *  tracks the descriptor so the child shows up in /sessions and
+     *  the LocalDaemonSessionsCard. The caller keeps lifecycle
+     *  ownership (kill / wait); this is purely for observability.
+     *  Returns the descriptor for the registered session. */
+    register(input: RegisterSessionInput): SessionDescriptor;
+    /** Register an already-built agent session (caller resolves the
+     *  adapter + builds the runtime). Sets kind="agent-cli", consumes
+     *  the optional initial prompt synchronously, returns the
+     *  descriptor. The agent stays alive — call `sendPrompt(id, ...)`
+     *  for follow-up turns until `kill(id)` closes it. */
+    spawnAgent(input: SpawnAgentInput): SessionDescriptor;
+    /** Spawn a process under a real PTY (node-pty). Bytes flow through
+     *  the registry's byte ring buffer + emitter; attach with
+     *  `attachPty(id, ...)`. Throws when the registry was constructed
+     *  without a `spawnPty` factory (node-pty optional dep missing). */
+    spawnPty(input: SpawnPtyInput): SessionDescriptor;
+    /** Send a follow-up turn to a live agent session. Throws when the
+     *  session is missing, not an agent-cli kind, or busy. The events
+     *  stream into the existing ring buffer + line emitter so /stream
+     *  consumers see them as they arrive. */
+    sendPrompt(id: string, message: unknown): Promise<void>;
+    /** Fire-and-forget variant of `sendPrompt`. Validates the same
+     *  preconditions synchronously — throws on missing session / wrong
+     *  kind / busy — but returns immediately after the turn is started,
+     *  letting the caller stream output via the SSE endpoint instead of
+     *  blocking on the full turn. Async errors during the turn are
+     *  pushed into the ring buffer as `[error]` lines so `/stream`
+     *  subscribers see them. Used by the web UI's chat input where a
+     *  long turn would otherwise freeze the textbox. */
+    enqueuePrompt(id: string, message: unknown): void;
+    list(): SessionDescriptor[];
+    get(id: string): SessionDescriptor | undefined;
+    /** Subscribe to a session's output. Returns an unsubscribe fn.
+     *  Initial backfill: synchronously invokes `onLine` once for each
+     *  line currently in the ring buffer so attaches show context. */
+    attach(id: string, onLine: (line: string, stream: "stdout" | "stderr") => void): (() => void) | null;
+    /** Subscribe to a PTY session's byte stream. Returns a control
+     *  handle (write/resize/detach) and null when the session is
+     *  missing or not a PTY kind. Replays the ring buffer
+     *  synchronously before live frames start. Initial `cols`/`rows`
+     *  are required so the registry can compute min-size across
+     *  subscribers; recompute on every `resize` call. */
+    attachPty(id: string, initial: {
+        cols: number;
+        rows: number;
+    }, onData: (chunk: Buffer) => void, onExit: (event: {
+        exitCode: number;
+        signal?: number;
+    }) => void): {
+        write(data: string): void;
+        resize(cols: number, rows: number): void;
+        detach(): void;
+    } | null;
+    /** Find a session by exact id OR exact name match. Returns the
+     *  descriptor or undefined. Used by HTTP/MCP routes so callers
+     *  can refer to "claude-main" instead of "sess_a3f8c1b2". */
+    findByIdOrName(query: string): SessionDescriptor | undefined;
+    /** Write a chunk of text to a PTY session's stdin. Returns true
+     *  on success, false when the session is missing or not a PTY.
+     *  Single-shot variant of attachPty().write — useful for MCP
+     *  tools that drive a session through tool calls. */
+    writeTerminalInput(id: string, data: string): boolean;
+    /** Snapshot the recent PTY byte buffer as one Buffer. Newest
+     *  bytes at the end; `lastBytes` caps the returned size from the
+     *  tail. Returns null when the session is missing or not a PTY. */
+    readTerminalOutput(id: string, lastBytes?: number): Buffer | null;
+    kill(id: string, signal?: NodeJS.Signals): boolean;
+    /** Stop tracking a session (after it exited and the user clicked
+     *  "clear"). Doesn't kill — use `kill` first. */
+    forget(id: string): boolean;
+    /** Stop persisting + close all sessions. Killed children are not
+     *  awaited — the daemon shutdown loop handles process tree teardown. */
+    shutdown(): void;
+}
+interface RegisterSessionInput {
+    /** Pre-existing child process to adopt (e.g. from a tunnel spawn). */
+    child: ChildProcess;
+    /** Stable id — typically the tunnel's execId so callers cross-ref. */
+    id: string;
+    workspaceSlug: string;
+    /** Display label for the descriptor's `command` field. */
+    command: string;
+    kind?: SessionKind;
+    label?: string;
+}
+interface SpawnAgentInput {
+    workspaceSlug: string;
+    cwd: string;
+    /** Driver-built session ready to receive turns. Caller resolves
+     *  the adapter, calls createAgentCliRuntime(handle).start({cwd}),
+     *  and hands the result here. */
+    agentSession: AgentSessionLike;
+    /** Adapter slug for the descriptor (display only). */
+    adapterSlug: string;
+    /** Optional initial prompt to dispatch immediately. The promise
+     *  the registry returns resolves AFTER the spawn — the prompt
+     *  runs in the background, projecting events into the ring
+     *  buffer. Skip to spawn idle. */
+    initialPrompt?: string;
+    label?: string;
+    /** Pretty command for the descriptor (display only). */
+    commandPreview?: string;
+}
+interface SpawnSessionInput {
+    kind: SessionKind;
+    workspaceSlug: string;
+    /** Path of the workspace root (for the child's cwd). The registry
+     *  doesn't validate it against the workspaces config — caller has
+     *  already resolved this. */
+    cwd: string;
+    /** Argv. First element is the binary; rest are passed verbatim. */
+    argv: string[];
+    /** Extra env on top of the daemon's process.env. */
+    env?: Record<string, string>;
+    /** Optional pre-set id (lets the spawner reference the session
+     *  before the spawn returns — useful for telemetry). */
+    id?: string;
+    label?: string;
+    /** Keep the child's stdin open (default: closed). Most spawned
+     *  agents are non-interactive and emit a warning when stdin is a
+     *  pipe with no writer (claude-code prints "no stdin data
+     *  received in 3s, proceeding without it"). Closing stdin lets
+     *  them skip the wait. PTY/terminal kinds that genuinely need
+     *  bidirectional IO should opt in via `keepStdin: true` and the
+     *  caller is then responsible for writing to `child.stdin`. */
+    keepStdin?: boolean;
+}
+interface SpawnPtyInput {
+    workspaceSlug: string;
+    cwd: string;
+    argv: string[];
+    /** Initial PTY dimensions. The registry uses min(cols, rows) across
+     *  active subscribers thereafter — these are the seed values used
+     *  before anyone attaches. */
+    cols: number;
+    rows: number;
+    /** Extra env on top of process.env. TERM/LANG/PATH are forced by
+     *  the factory layer (node-pty.spawn options); don't try to clear
+     *  them here. */
+    env?: Record<string, string>;
+    /** User-friendly slug. Used by `findByIdOrName(query)`. Must not
+     *  collide with an existing session's name. */
+    name?: string;
+    label?: string;
+}
+
+/**
+ * Tiny node:http server that fronts the runtime gateway.
+ *
+ * Routes:
+ *   GET  /health              — { status, workspace, registered, uptime }
+ *   GET  /events              — SSE stream of RuntimeEvent
+ *   POST /mcp                 — MCP Streamable HTTP transport (POST)
+ *   GET  /mcp                 — MCP SSE response stream (GET)
+ *   DELETE /mcp               — close MCP session
+ *   GET  /conversations       — JSON list of conversation summaries
+ *   GET  /conversations/<id>  — markdown body of one conversation
+ *   POST /heartbeat/tick      — force-fire one heartbeat tick
+ *
+ * No auth in `mode: "none"` (loopback default). `mode: "bearer"`
+ * checks `Authorization: Bearer <token>` against the configured
+ * token. Health is always public so external monitors can probe.
+ *
+ * MCP transport: stateless mode for v1 — each request is independent.
+ * Stateful session pinning can come later when long-running streaming
+ * tool calls become a real use case.
+ */
+
+/**
+ * Pluggable adapter resolver — keeps the runtime package free of any
+ * @agentproto/cli dep. The host (cli `serve`, playground, embedding
+ * apps) builds the resolver and hands it in. Returning null means
+ * "adapter not found" → 404.
+ */
+type AgentAdapterResolver = (slug: string) => Promise<{
+    /** Build a fresh AgentSessionLike for the given cwd. The driver
+     *  spawns the adapter binary, opens the protocol, and the
+     *  registry holds the result.
+     *
+     *  When `resumeSessionId` is set, the driver reattaches to that
+     *  pre-existing adapter session (claude-code's conversation id,
+     *  hermes' chat handle, …) rather than starting blank. Same
+     *  mechanism as `agentproto run --resume <id>` — exposed over
+     *  HTTP so `agentproto sessions restart` works on agent-cli
+     *  sessions, not just PTY ones. */
+    startSession(opts: {
+        cwd: string;
+        resumeSessionId?: string;
+        /** Model identifier forwarded from `start_agent_session`. Adapters
+         *  that support model selection (e.g. via a `--model` CLI flag) may
+         *  honour this; others silently ignore it. */
+        model?: string;
+    }): Promise<AgentSessionLike>;
+    /** Display label for the descriptor's `command` field. */
+    commandPreview?: string;
+} | null>;
+/**
+ * Compact adapter metadata for the discovery endpoints. Independent
+ * of the resolver function above — hosts that can list installed
+ * adapters wire this; hosts that can only resolve by-slug skip it
+ * (the routes 501).
+ */
+interface AdapterListEntry {
+    slug: string;
+    name: string;
+    version: string;
+    description: string;
+    protocol: string;
+    streaming: boolean;
+    packageName: string;
+}
+type AgentAdapterLister = () => Promise<AdapterListEntry[]>;
+interface AuthOptions {
+    mode: "none" | "bearer";
+    token?: string;
+}
+
+/**
+ * `.agentproto/` config dir — runtime-managed state at the root of
+ * every workspace. Mirrors the `.git/` model: user-content stays at
+ * the workspace root (HEARTBEAT.md, conversations/, .agents/) while
+ * everything the runtime owns lives in `<workspace>/.agentproto/`.
+ *
+ * What goes here today:
+ *   - `runtime.json` — boot-time snapshot of the live config (PID,
+ *     port, resolved workspace, MCP server name, startedAt). Useful
+ *     for `cat .agentproto/runtime.json` diagnostics + future tooling
+ *     that wants to discover a running gateway from disk.
+ *
+ * What does NOT go here:
+ *   - HEARTBEAT.md — user-edited content
+ *   - conversations/ — user-readable chat history
+ *   - .agents/ — user-authored manifests
+ *
+ * The `.agentproto/` dir is safe to gitignore. The `runtime.json`
+ * file contains a per-boot bearer token used to gate mutating HTTP
+ * routes (POST /sessions/*, WS /sessions/:id/pty). The token lives
+ * in RAM + on disk only — never logged. File mode 0600 below; only
+ * processes running as the workspace user (and the daemon itself)
+ * can read it. A browser-loaded localhost page CAN'T read this file,
+ * which is what defends against the localhost-DNS-rebinding drive-by
+ * spawn vector.
+ */
+interface RuntimeMeta {
+    /** Absolute path to the workspace root the gateway is bound to. */
+    workspace: string;
+    /** HTTP listener port. */
+    port: number;
+    /** HTTP bind address (loopback or `0.0.0.0`). */
+    bind: string;
+    /** Process id of the running gateway. */
+    pid: number;
+    /** Wall-clock ISO timestamp at boot. */
+    startedAt: string;
+    /** MCP server name advertised in the initialize handshake. */
+    name: string;
+    /** AIP doctype names + extensions registered as MCP CRUD tools. */
+    registered: readonly string[];
+    /**
+     * Per-boot bearer token. Required on mutating routes (POST
+     * /sessions/*, POST /sessions/:id/kill, DELETE /sessions/:id, and
+     * WS upgrade to /sessions/:id/pty). Random uuid generated at boot
+     * by createGateway; regenerated each restart.
+     */
+    token: string;
+}
+/**
+ * Delete `<workspace>/.agentproto/runtime.json`. Best-effort — called
+ * from the daemon's graceful shutdown path so a CLI looking for the
+ * live daemon doesn't pick up a stale token after this process exits.
+ * Missing file is a no-op (the daemon may never have written one).
+ */
+declare function unlinkRuntimeMeta(workspace: string): Promise<void>;
+/**
+ * Read a runtime.json from `<workspace>/.agentproto/`. Returns the
+ * parsed object (no validation) plus the on-disk mtime, or null when
+ * the file is missing / unreadable / malformed.
+ */
+declare function readRuntimeMeta(workspace: string): Promise<{
+    meta: Partial<RuntimeMeta> & Record<string, unknown>;
+    mtime: Date;
+} | null>;
+/**
+ * For each `workspace` path, check whether its runtime.json points
+ * at a now-dead PID; if so, delete it. Returns the list of paths
+ * that were cleaned. Called by `agentproto serve` at boot to keep
+ * the discovery layer's view of "live daemons" honest — a stale
+ * file with the same port as the new daemon is the classic source
+ * of `sessions_unauthorized` 401s.
+ *
+ * Skips the running daemon's own workspace (passed in as
+ * `currentWorkspace`) since that file is OURS to write.
+ */
+declare function sweepStaleRuntimeMetas(workspaces: readonly string[], currentWorkspace: string): Promise<string[]>;
+
+/**
+ * @agentproto/runtime — long-running gateway around an agentproto
+ * workspace dir.
+ *
+ * Composes:
+ *   - `@agentproto/mcp-server` (CRUD verbs over registered specs)
+ *   - HTTP transport (Streamable HTTP) on a configurable port
+ *   - HEARTBEAT.md autonomy loop
+ *   - Append-only conversation persistence (`conversations/<id>.md`)
+ *   - Workspace filesystem adapter (compatible with the
+ *     `McpWorkspace.filesystem` shape used by `@guilde/mcp`)
+ *
+ * Single entry point: `createGateway(opts)`. Returns a handle with
+ * `url` and `stop()` — the rest of the surface lives on the HTTP
+ * server.
+ */
+
+type AnySpec = DoctypeSpec<any, any>;
+interface CreateGatewayOptions {
+    /** Absolute path to the workspace dir. */
+    workspace: string;
+    /** AIP doctype specs to expose as MCP CRUD verbs. */
+    specs: readonly AnySpec[];
+    /** Port to bind. Default 18790. */
+    port?: number;
+    /** Bind host. Default `127.0.0.1` (loopback). Set `0.0.0.0` for LAN. */
+    bind?: string;
+    /** Auth mode. Default `none` (safe only on loopback). */
+    auth?: AuthOptions;
+    /**
+     * Resolves a heartbeat-runnable agent from its workspace id.
+     * Required for HEARTBEAT.md to do anything; without it ticks emit
+     * `heartbeat-error` events instead of generating.
+     */
+    buildAgent?: BuildHeartbeatAgent;
+    /** Server name advertised over MCP. */
+    name?: string;
+    /** Server version advertised over MCP. */
+    version?: string;
+    /**
+     * Run BOOT.md once at startup. Pass `false` to disable. Defaults to
+     * `true`. The boot file is plain markdown — frontmatter-free; the
+     * agent named in `defaultBootAgent` (or skipped if unset) gets the
+     * body as a single prompt and the reply is appended to a `boot-<iso>`
+     * conversation.
+     */
+    boot?: boolean;
+    /** Agent id used for BOOT.md if no per-file frontmatter. */
+    defaultBootAgent?: string;
+    /** Optional adapter resolver — when provided, enables
+     *  `POST /sessions/agent` (long-running agent CLIs like
+     *  claude-code / hermes via the @agentproto/cli adapter system).
+     *  Without this, /sessions still works for raw `argv` spawns. */
+    resolveAgentAdapter?: AgentAdapterResolver;
+    /** Optional adapter lister — when provided, enables
+     *  `GET /adapters` HTTP route + `list_adapters` MCP tool so UIs
+     *  can discover what's installed on the host. */
+    listAgentAdapters?: AgentAdapterLister;
+    /** Optional PTY factory (node-pty wrapper, typically from the cli
+     *  layer's `loadNodePtyFactory()`). When provided, enables
+     *  `POST /sessions/terminal`, the `start_terminal_session` MCP
+     *  tool family, and the `/sessions/:id/pty` WebSocket. Without it,
+     *  those routes return 501 / the MCP tools aren't registered. */
+    spawnPty?: PtyFactory;
+    /** Override the per-boot bearer token. Default: `randomUUID()`.
+     *  Tests can pin a known value; production should always let
+     *  the gateway generate fresh. The token is written into
+     *  `<workspace>/.agentproto/runtime.json` (mode 0600) and required
+     *  on mutating `/sessions/*` routes + the PTY WS upgrade. */
+    token?: string;
+    /** Trusted browser origins allowed to drive mutating routes
+     *  without a bearer token. See `RuntimeHttpServerOptions.allowedOrigins`
+     *  for match semantics. Default: localhost on any port. */
+    allowedOrigins?: readonly string[];
+    /** When true, drop the localhost-wildcard defaults — only the
+     *  explicit `allowedOrigins` list is honoured. */
+    strictOrigins?: boolean;
+}
+interface GatewayHandle {
+    url: string;
+    workspace: string;
+    workspaceFs: WorkspaceFs;
+    registered: readonly string[];
+    /** Sessions registry — exposed so MCP tools / external spawners
+     *  inside the same process can register their child processes for
+     *  visibility through /sessions and the CLI TUI. */
+    sessions: SessionsRegistry;
+    /** Per-boot bearer token required on mutating /sessions/* routes
+     *  + WS PTY upgrades. Exposed so an embedding host (e.g. the CLI
+     *  shell that hosts the gateway in-process) can pass it to child
+     *  tools without re-reading the runtime.json file. */
+    token: string;
+    stop(): Promise<void>;
+}
+/**
+ * Spin up the gateway. Order:
+ *   1. Build MCP server + load AIP-40 extensions
+ *   2. Build conversation store + workspace fs adapter
+ *   3. (optional) Run BOOT.md once
+ *   4. Start HTTP server
+ *   5. Start heartbeat ticker
+ *
+ * `stop()` reverses 4–5 (heartbeat first, then HTTP). The MCP server
+ * is owned by the HTTP server's per-session transports and is closed
+ * implicitly when those close.
+ */
+declare function createGateway(opts: CreateGatewayOptions): Promise<GatewayHandle>;
+
+export { type AdapterListEntry, type AgentAdapterLister, type AgentAdapterResolver, type AgentSessionLike, type AgentStreamEvent, BuildHeartbeatAgent, type CreateGatewayOptions, type GatewayHandle, type RuntimeMeta, type SessionDescriptor, type SessionKind, type SessionStatus, type SessionsRegistry, type SpawnAgentInput, type SpawnSessionInput, WorkspaceFs, createGateway, readRuntimeMeta, sweepStaleRuntimeMetas, unlinkRuntimeMeta };