opensquid 0.5.395

package/dist/runtime/agent_bridge/session_manager.js

@@ -0,0 +1,226 @@
+/**
+ * agent_bridge — warm-pool session manager (WAB.3, 0.5.95).
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.3.
+ * Architecture: `docs/tasks/WAB.1-architecture.md` decisions (b) + (c) +
+ * Section 2 module layout (≤350 LOC budget for this file).
+ *
+ * Responsibility:
+ *   1. Maintain an LRU of `SessionState` objects keyed by canonical session
+ *      slug — Hermes-derived caps (`max=128`, `ttl=3_600_000ms`, verified
+ *      against `gateway/run.py:55-65`).
+ *   2. Lazy-construct a `SessionState` on first `getOrCreate`, hydrating
+ *      `history` from persisted JSONL (WAB.3 `SessionPersistence`).
+ *   3. On eviction (LRU cap hit, idle TTL expire, or shutdown), notify the
+ *      caller via the optional `onEvict` callback so any unfinished work
+ *      (e.g. a final flush) can be performed before the entry vanishes.
+ *      The state's `history` is already on disk — eviction is a memory
+ *      release, not a data loss.
+ *   4. `appendTurn` is the only mutation API — it APPEND-WRITES the new
+ *      entries to disk FIRST, then mutates the in-memory `history`, so a
+ *      persistence failure leaves the in-memory state cleanly unchanged
+ *      (the caller's catch can decide to retry or escalate).
+ *
+ * Non-responsibility (per WAB.1 (c)):
+ *   - Does NOT store an Anthropic SDK client per session. One daemon-wide
+ *     client is shared.
+ *   - Does NOT compute cache-control breakpoints. Those are derived from
+ *     `history` positions at request-time by the agent loop (WAB.4).
+ *   - Does NOT serialize concurrent appends to the same session. This is
+ *     intentional: the manager is the unsynchronized data plane; the
+ *     control plane (`ChatDispatcher` in `dispatcher.ts`) owns the
+ *     per-session mutex+queue policy and is the sole production caller of
+ *     `appendTurn` (regression-locked by `appendturn_sole_caller.test.ts`).
+ *     See the `Concurrency contract:` paragraph on `appendTurn` below for
+ *     the policy details.
+ *
+ * Imports from: lru-cache, ./session_persistence.js, ./types.js.
+ * Imported by: (future) dispatcher.ts, daemon.ts.
+ */
+import { LRUCache } from 'lru-cache';
+import {} from './session_persistence.js';
+import { sessionKeyString, } from './types.js';
+// ---------------------------------------------------------------------------
+// Constants — Hermes-derived (gateway/run.py:55-65).
+// ---------------------------------------------------------------------------
+/** Max warm sessions in memory. Hermes `_AGENT_CACHE_MAX_SIZE`. */
+export const AGENT_CACHE_MAX_SIZE = 128;
+/** Idle TTL after which an untouched session is evicted. Hermes
+ *  `_AGENT_CACHE_IDLE_TTL_SECS = 3600.0` → 3_600_000 ms. */
+export const AGENT_CACHE_IDLE_TTL_MS = 3_600_000;
+// ---------------------------------------------------------------------------
+// SessionManager
+// ---------------------------------------------------------------------------
+export class SessionManager {
+    cache;
+    persistence;
+    defaultPackId;
+    defaultModelAlias;
+    nowMs;
+    onEvict;
+    shutdownInProgress = false;
+    constructor(opts) {
+        this.persistence = opts.persistence;
+        this.defaultPackId = opts.defaultPackId;
+        this.defaultModelAlias = opts.defaultModelAlias;
+        this.nowMs = opts.nowMs ?? Date.now;
+        this.onEvict = opts.onEvict;
+        this.cache = new LRUCache({
+            max: opts.maxSessions ?? AGENT_CACHE_MAX_SIZE,
+            ttl: opts.idleTtlMs ?? AGENT_CACHE_IDLE_TTL_MS,
+            // updateAgeOnGet: every cache hit (in `getOrCreate`) resets the TTL
+            // countdown. Matches Hermes's "idle ≥ 1h → evict" semantics.
+            updateAgeOnGet: true,
+            // ttlAutopurge: actively evict expired entries on the timer wheel
+            // rather than only on next access. Without this, an idle session
+            // would sit in memory until the next `getOrCreate` for that key
+            // (which might never come) — defeats the eviction policy.
+            ttlAutopurge: true,
+            dispose: (value, _key, reason) => {
+                // Skip the explicit-shutdown drain path here; we already invoke
+                // onEvict('shutdown') from `shutdown()` before clearing.
+                if (this.shutdownInProgress)
+                    return;
+                const mapped = mapDisposeReason(reason);
+                if (mapped === null)
+                    return;
+                try {
+                    this.onEvict?.(value, mapped);
+                }
+                catch {
+                    // dispose is a sync hook; throwing here corrupts lru-cache's
+                    // internal state per its docs. Swallow + rely on the consumer
+                    // to instrument its own onEvict body with try/catch.
+                }
+            },
+        });
+    }
+    /**
+     * Look up an existing warm session, or create one (hydrating its
+     * `history` from persisted JSONL). Cache-hit path is a single LRU
+     * lookup + sync return inside an awaited promise — no extra I/O.
+     *
+     * `projectUuid` is required (sessions are project-scoped); pack id +
+     * model alias use the manager-level defaults at creation time. WAB.6
+     * will add per-call overrides.
+     */
+    async getOrCreate(key, projectUuid) {
+        const slug = sessionKeyString(key);
+        const existing = this.cache.get(slug);
+        if (existing !== undefined) {
+            // updateAgeOnGet handled the TTL; refresh lastActivityMs too so
+            // telemetry stays consistent with cache age.
+            existing.lastActivityMs = this.nowMs();
+            return existing;
+        }
+        const history = await this.persistence.loadHistory(slug);
+        const state = {
+            key,
+            history,
+            lastActivityMs: this.nowMs(),
+            projectUuid,
+            packId: this.defaultPackId,
+            modelAlias: this.defaultModelAlias,
+            turnInFlight: false,
+        };
+        this.cache.set(slug, state);
+        return state;
+    }
+    /**
+     * Append entries from a completed turn. Persistence happens BEFORE
+     * in-memory mutation so a write failure leaves the state untouched
+     * (the caller can catch and decide).
+     *
+     * If the session was evicted between turn-start and turn-completion
+     * (race against LRU cap or idle TTL), the method is a no-op — there is
+     * no warm state to update, and re-creating it just to attach orphan
+     * entries would corrupt the order on disk (the evicted state's flush
+     * already covers it).
+     *
+     * Concurrency contract: this method ASSUMES the caller has serialized
+     * concurrent calls for the same session. The control plane —
+     * `ChatDispatcher.handleFlush` + `runTurnChain` in `dispatcher.ts` —
+     * enforces this via a per-session `inFlight` map (depth 1) plus a
+     * `pendingQueue` map (depth 1, coalesce up to MAX_QUEUE_COALESCE_ATTEMPTS,
+     * then DROP + warn). Adding a SECOND production caller would violate
+     * the contract; the `appendturn_sole_caller.test.ts` regression net
+     * catches that drift.
+     */
+    async appendTurn(key, entries) {
+        const slug = sessionKeyString(key);
+        const state = this.cache.get(slug);
+        if (state === undefined)
+            return;
+        // Persist first → if this throws, state is untouched + caller catches.
+        await this.persistence.appendEntries(slug, entries);
+        state.history.push(...entries);
+        state.lastActivityMs = this.nowMs();
+        state.turnInFlight = false;
+    }
+    /**
+     * Mark a session's turn as in-flight. Pure in-memory; intended for the
+     * batch coordinator (WAB.5) to set BEFORE issuing the agent turn so
+     * other inbound batches buffer.
+     */
+    beginTurn(key) {
+        const state = this.cache.get(sessionKeyString(key));
+        if (state !== undefined)
+            state.turnInFlight = true;
+    }
+    /** Test/admin: returns the live entry without resetting age. */
+    peek(key) {
+        return this.cache.peek(sessionKeyString(key));
+    }
+    /** Live entry count — for telemetry + tests. */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Drain the cache: emit `onEvict(state, 'shutdown')` for each live
+     * session, then clear. Idempotent. After shutdown, the manager is
+     * single-use — re-using it would silently start a fresh cache; we
+     * surface that as a recoverable no-op rather than throw (matches
+     * `InboxTransportBridge.shutdown` semantics).
+     */
+    shutdown() {
+        if (this.shutdownInProgress)
+            return;
+        this.shutdownInProgress = true;
+        // Snapshot entries to a local array — `cache.entries()` is a live
+        // iterator and `cache.clear()` invalidates it mid-loop.
+        const snapshot = [];
+        for (const [, state] of this.cache.entries())
+            snapshot.push(state);
+        for (const state of snapshot) {
+            try {
+                this.onEvict?.(state, 'shutdown');
+            }
+            catch {
+                /* see dispose-hook rationale above */
+            }
+        }
+        this.cache.clear();
+    }
+}
+// ---------------------------------------------------------------------------
+// Reason mapping
+// ---------------------------------------------------------------------------
+function mapDisposeReason(reason) {
+    switch (reason) {
+        case 'evict':
+            return 'lru';
+        case 'expire':
+            return 'idle';
+        case 'delete':
+            // `cache.delete` is only called from shutdown drain (handled
+            // separately) — but if a future caller invokes it directly, label
+            // as 'shutdown' (the closest semantic match: the entry is gone
+            // because someone explicitly removed it).
+            return 'shutdown';
+        case 'set':
+        case 'fetch':
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=session_manager.js.map

package/dist/runtime/agent_bridge/session_manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_manager.js","sourceRoot":"","sources":["../../../src/runtime/agent_bridge/session_manager.ts"],"names":[],"mappings":"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"}

package/dist/runtime/agent_bridge/session_persistence.d.ts

@@ -0,0 +1,95 @@
+/**
+ * agent_bridge — append-only JSONL persistence for warm-pool session
+ * history (WAB.3, 0.5.95).
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.3.
+ * Architecture: `docs/tasks/WAB.1-architecture.md` decision (c) + Section 2
+ * module layout (≤200 LOC budget for this file).
+ *
+ * On-disk contract:
+ *   - One JSONL file per session at
+ *     `~/.opensquid/agent-bridge/sessions/<slug>.jsonl`.
+ *   - Each row is exactly one serialized `ChatHistoryEntry`.
+ *   - Writes are APPEND-ONLY (`fs.appendFile`); files are never truncated
+ *     or rewritten. Restart-resume reads the full file front-to-back into
+ *     memory at session creation, so history order = byte order.
+ *
+ * Why JSONL (not SQLite):
+ *   - Append-only matches the access pattern (1 turn = N entries appended;
+ *     never a partial update).
+ *   - `O_APPEND` writes ≤ `PIPE_BUF` (4KB on macOS / 4KB on Linux) are
+ *     atomic per POSIX. Most history entries (text content) are well under
+ *     this. Long entries split JSONL `\n` cleanly so the reader's
+ *     line-by-line tolerance handles interleaved partial writes too.
+ *   - Same shape as the chat-daemon inbox and the drift catalog
+ *     (`src/runtime/drift_catalog.ts`) — consistent file format makes ops
+ *     + grepability easier.
+ *
+ * Slug encoding (filesystem safety):
+ *   - SessionKey slug form is `<platform>:<chatId>[:<threadId>]` — colons
+ *     are not safe on Windows + interact poorly with shell tooling.
+ *   - We replace `:` with `__` (rare in identifiers so we can recover the
+ *     original by inverse on debug), then replace any character that is
+ *     NOT alphanumeric / `-` / `_` with `_`. This avoids path-traversal
+ *     vectors (no `/`, no `..`, no nulls) while keeping the filename
+ *     readable for the common case (Telegram + Discord ids are
+ *     alphanumeric with optional `-` prefix for TG supergroups).
+ *
+ * Tolerance:
+ *   - Malformed JSON line on load: skipped + reported via `onWarn`; valid
+ *     rows still load. Never throws on a corrupt line.
+ *   - Schema-mismatched line on load: same — warn + skip.
+ *   - Missing file on load: returns `[]` (fresh session). The directory
+ *     is created lazily on first `appendEntries`, so reads never need
+ *     to mkdir.
+ *
+ * Imports from: node:fs/promises, node:os, node:path, ./types.js.
+ * Imported by: session_manager.ts.
+ */
+import { type ChatHistoryEntry } from './types.js';
+/**
+ * Filesystem-safe encoding of a session slug. Pure function (no I/O) so it
+ * can be reused by the session manager + tests for deterministic asserts.
+ */
+export declare function encodeSessionSlug(slug: string): string;
+export interface SessionPersistenceOptions {
+    /** Override the sessions root (default: `~/.opensquid/agent-bridge/sessions`). */
+    root?: string;
+    /** Structured warn sink for malformed rows. */
+    onWarn?: (message: string) => void;
+}
+export declare class SessionPersistence {
+    private readonly root;
+    private readonly warn;
+    /** Tracks which session dirs we have already ensured exist (avoids
+     *  redundant mkdir syscalls on the hot append path). */
+    private readonly dirsEnsured;
+    constructor(opts?: SessionPersistenceOptions);
+    /**
+     * Resolve the absolute file path for a session. Exposed for tests +
+     * the session manager's eviction-flush callback diagnostics.
+     */
+    pathFor(slug: string): string;
+    /**
+     * Read all history entries for a session, in append order. Missing file
+     * → empty array (fresh session). Malformed / schema-mismatched rows are
+     * skipped + warned; valid rows are still returned. Non-streaming: history
+     * is bounded by LRU cap × N turns and the agent loop needs the full array.
+     */
+    loadHistory(slug: string): Promise<ChatHistoryEntry[]>;
+    /**
+     * Append history entries to the session's JSONL. Uses `fs.appendFile`
+     * (which opens with `O_APPEND`) so concurrent writers serialize at the
+     * kernel level for sub-PIPE_BUF rows. Per-line `\n` framing tolerates
+     * the (extremely rare) case of an interleaved >4KB row.
+     *
+     * Atomic-or-throw contract: either the whole batch of entries is
+     * appended, or this method throws and the caller's state should not
+     * advance. We build one string + one syscall to keep the atomicity
+     * boundary at "all or nothing" for the typical small batch.
+     */
+    appendEntries(slug: string, entries: ChatHistoryEntry[]): Promise<void>;
+    /** Lazy mkdir guarded by an in-memory set — keeps repeat appends cheap. */
+    private ensureDir;
+}
+//# sourceMappingURL=session_persistence.d.ts.map

package/dist/runtime/agent_bridge/session_persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_persistence.d.ts","sourceRoot":"","sources":["../../../src/runtime/agent_bridge/session_persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAMH,OAAO,EAAE,KAAK,gBAAgB,EAA0B,MAAM,YAAY,CAAC;AAgB3E;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtD;AAMD,MAAM,WAAW,yBAAyB;IACxC,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAMD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD;4DACwD;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,IAAI,GAAE,yBAA8B;IAKhD;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI7B;;;;;OAKG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAyC5D;;;;;;;;;;OAUG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7E,2EAA2E;YAC7D,SAAS;CAKxB"}

package/dist/runtime/agent_bridge/session_persistence.js

@@ -0,0 +1,178 @@
+/**
+ * agent_bridge — append-only JSONL persistence for warm-pool session
+ * history (WAB.3, 0.5.95).
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.3.
+ * Architecture: `docs/tasks/WAB.1-architecture.md` decision (c) + Section 2
+ * module layout (≤200 LOC budget for this file).
+ *
+ * On-disk contract:
+ *   - One JSONL file per session at
+ *     `~/.opensquid/agent-bridge/sessions/<slug>.jsonl`.
+ *   - Each row is exactly one serialized `ChatHistoryEntry`.
+ *   - Writes are APPEND-ONLY (`fs.appendFile`); files are never truncated
+ *     or rewritten. Restart-resume reads the full file front-to-back into
+ *     memory at session creation, so history order = byte order.
+ *
+ * Why JSONL (not SQLite):
+ *   - Append-only matches the access pattern (1 turn = N entries appended;
+ *     never a partial update).
+ *   - `O_APPEND` writes ≤ `PIPE_BUF` (4KB on macOS / 4KB on Linux) are
+ *     atomic per POSIX. Most history entries (text content) are well under
+ *     this. Long entries split JSONL `\n` cleanly so the reader's
+ *     line-by-line tolerance handles interleaved partial writes too.
+ *   - Same shape as the chat-daemon inbox and the drift catalog
+ *     (`src/runtime/drift_catalog.ts`) — consistent file format makes ops
+ *     + grepability easier.
+ *
+ * Slug encoding (filesystem safety):
+ *   - SessionKey slug form is `<platform>:<chatId>[:<threadId>]` — colons
+ *     are not safe on Windows + interact poorly with shell tooling.
+ *   - We replace `:` with `__` (rare in identifiers so we can recover the
+ *     original by inverse on debug), then replace any character that is
+ *     NOT alphanumeric / `-` / `_` with `_`. This avoids path-traversal
+ *     vectors (no `/`, no `..`, no nulls) while keeping the filename
+ *     readable for the common case (Telegram + Discord ids are
+ *     alphanumeric with optional `-` prefix for TG supergroups).
+ *
+ * Tolerance:
+ *   - Malformed JSON line on load: skipped + reported via `onWarn`; valid
+ *     rows still load. Never throws on a corrupt line.
+ *   - Schema-mismatched line on load: same — warn + skip.
+ *   - Missing file on load: returns `[]` (fresh session). The directory
+ *     is created lazily on first `appendEntries`, so reads never need
+ *     to mkdir.
+ *
+ * Imports from: node:fs/promises, node:os, node:path, ./types.js.
+ * Imported by: session_manager.ts.
+ */
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { chatHistoryEntrySchema } from './types.js';
+// ---------------------------------------------------------------------------
+// Constants (top-of-file for ops visibility)
+// ---------------------------------------------------------------------------
+const SESSIONS_SUBDIR = 'agent-bridge/sessions';
+const noopWarn = () => {
+    /* default sink */
+};
+// ---------------------------------------------------------------------------
+// Slug encoding
+// ---------------------------------------------------------------------------
+/**
+ * Filesystem-safe encoding of a session slug. Pure function (no I/O) so it
+ * can be reused by the session manager + tests for deterministic asserts.
+ */
+export function encodeSessionSlug(slug) {
+    // First, encode `:` → `__` so the canonical separator survives identifiably.
+    const colonReplaced = slug.split(':').join('__');
+    // Then, scrub anything else outside [A-Za-z0-9_-].
+    return colonReplaced.replace(/[^A-Za-z0-9_-]/g, '_');
+}
+// ---------------------------------------------------------------------------
+// SessionPersistence
+// ---------------------------------------------------------------------------
+export class SessionPersistence {
+    root;
+    warn;
+    /** Tracks which session dirs we have already ensured exist (avoids
+     *  redundant mkdir syscalls on the hot append path). */
+    dirsEnsured = new Set();
+    constructor(opts = {}) {
+        this.root = opts.root ?? join(homedir(), '.opensquid', SESSIONS_SUBDIR);
+        this.warn = opts.onWarn ?? noopWarn;
+    }
+    /**
+     * Resolve the absolute file path for a session. Exposed for tests +
+     * the session manager's eviction-flush callback diagnostics.
+     */
+    pathFor(slug) {
+        return join(this.root, `${encodeSessionSlug(slug)}.jsonl`);
+    }
+    /**
+     * Read all history entries for a session, in append order. Missing file
+     * → empty array (fresh session). Malformed / schema-mismatched rows are
+     * skipped + warned; valid rows are still returned. Non-streaming: history
+     * is bounded by LRU cap × N turns and the agent loop needs the full array.
+     */
+    async loadHistory(slug) {
+        const path = this.pathFor(slug);
+        let raw;
+        try {
+            raw = await fs.readFile(path, 'utf8');
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ENOENT')
+                return [];
+            this.warn(`[agent_bridge.persistence] read failed ${path}: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+        const entries = [];
+        const lines = raw.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const rawLine = lines[i];
+            if (rawLine === undefined)
+                continue;
+            const line = rawLine.trim();
+            if (line === '')
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch (err) {
+                this.warn(`[agent_bridge.persistence] malformed JSON at ${path}:${i + 1}: ${err instanceof Error ? err.message : String(err)}`);
+                continue;
+            }
+            const result = chatHistoryEntrySchema.safeParse(parsed);
+            if (!result.success) {
+                this.warn(`[agent_bridge.persistence] schema mismatch at ${path}:${i + 1}: ${result.error.message}`);
+                continue;
+            }
+            entries.push(result.data);
+        }
+        return entries;
+    }
+    /**
+     * Append history entries to the session's JSONL. Uses `fs.appendFile`
+     * (which opens with `O_APPEND`) so concurrent writers serialize at the
+     * kernel level for sub-PIPE_BUF rows. Per-line `\n` framing tolerates
+     * the (extremely rare) case of an interleaved >4KB row.
+     *
+     * Atomic-or-throw contract: either the whole batch of entries is
+     * appended, or this method throws and the caller's state should not
+     * advance. We build one string + one syscall to keep the atomicity
+     * boundary at "all or nothing" for the typical small batch.
+     */
+    async appendEntries(slug, entries) {
+        if (entries.length === 0)
+            return;
+        await this.ensureDir();
+        const path = this.pathFor(slug);
+        // Strip the in-memory-only `cacheMark` hint before serializing — it is
+        // recomputed per-turn by the agent loop from history positions and
+        // would otherwise pollute the on-disk shape.
+        const lines = entries.map((entry) => JSON.stringify(stripCacheMark(entry)));
+        const payload = `${lines.join('\n')}\n`;
+        await fs.appendFile(path, payload, 'utf8');
+    }
+    /** Lazy mkdir guarded by an in-memory set — keeps repeat appends cheap. */
+    async ensureDir() {
+        if (this.dirsEnsured.has(this.root))
+            return;
+        await fs.mkdir(this.root, { recursive: true });
+        this.dirsEnsured.add(this.root);
+    }
+}
+/** Drop the in-memory-only `cacheMark` field. Returns a new object. */
+function stripCacheMark(entry) {
+    const rest = {
+        role: entry.role,
+        content: entry.content,
+        timestamp: entry.timestamp,
+    };
+    return rest;
+}
+//# sourceMappingURL=session_persistence.js.map

package/dist/runtime/agent_bridge/session_persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_persistence.js","sourceRoot":"","sources":["../../../src/runtime/agent_bridge/session_persistence.ts"],"names":[],"mappings":"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"}

package/dist/runtime/agent_bridge/tool_dispatcher.d.ts

@@ -0,0 +1,60 @@
+/**
+ * agent_bridge — tool dispatcher (WAB.4, 0.5.97).
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.4.
+ * Architecture: `docs/tasks/WAB.1-architecture.md` decisions (e) + (f).
+ *
+ * Responsibility:
+ *   1. Hold a name-indexed registry of `ToolSpec` + `ToolHandler` pairs.
+ *   2. On `call(name, input, ctx)`: look up the spec, run the spec's
+ *      optional `validate(input)` guard (throws on bad input), forward
+ *      the validated value to the handler, return the handler's string
+ *      output (which the agent loop feeds back as a `tool_result` block).
+ *   3. On `list()`: return the snapshot of registered specs in the order
+ *      they were registered. The agent loop passes this to
+ *      `Anthropic.messages.create({ tools })`.
+ *
+ * Non-responsibility:
+ *   - Does NOT call the model. The agent loop (`agent_loop.ts`) owns the
+ *     SDK round-trip; the dispatcher only resolves `tool_use` blocks.
+ *   - Does NOT manage tool lifecycle (registration happens once per
+ *     session at construction; no add/remove at runtime in WAB.4).
+ *   - Does NOT auto-convert zod → JSON Schema. Tool authors supply both
+ *     `input_schema` (JSON Schema, for the model) and `validate`
+ *     (runtime guard, for the dispatcher) — see types.ts comment.
+ *
+ * Error contract:
+ *   - Unknown name → `Error` with prefix `tool_dispatcher: unknown tool`.
+ *     The agent loop catches and surfaces as a fatal turn error (the
+ *     model invoked something not in the declared list — likely a
+ *     schema/spec mismatch).
+ *   - Validation failure → re-throws the validator's error (zod's
+ *     `ZodError` carries structured detail; ajv's `ValidationError`
+ *     similarly). Caller can inspect the error class.
+ *   - Handler rejection → surfaces unmodified.
+ *
+ * Imports from: ./types.js.
+ * Imported by: agent_loop.ts (caller), pack_binding.ts (WAB.6
+ *   builder), daemon.ts (WAB.7 wiring).
+ */
+import type { ToolContext, ToolDispatcher, ToolHandler, ToolSpec } from './types.js';
+export interface ToolRegistration {
+    spec: ToolSpec;
+    handler: ToolHandler;
+}
+export declare class SimpleToolDispatcher implements ToolDispatcher {
+    private readonly tools;
+    constructor(initial?: ToolRegistration[]);
+    /**
+     * Add a tool to the registry. Throws on duplicate name — silent
+     * shadowing would let one pack hijack another pack's tool surface.
+     */
+    register(t: ToolRegistration): void;
+    /** Live tool count (telemetry / tests). */
+    get size(): number;
+    /** Whether a tool with this name is registered. */
+    has(name: string): boolean;
+    list(): ToolSpec[];
+    call(name: string, input: unknown, ctx: ToolContext): Promise<string>;
+}
+//# sourceMappingURL=tool_dispatcher.d.ts.map

package/dist/runtime/agent_bridge/tool_dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool_dispatcher.d.ts","sourceRoot":"","sources":["../../../src/runtime/agent_bridge/tool_dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAmBrF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,WAAW,CAAC;CACtB;AAeD,qBAAa,oBAAqB,YAAW,cAAc;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;gBAE/C,OAAO,GAAE,gBAAgB,EAAO;IAI5C;;;OAGG;IACH,QAAQ,CAAC,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAOnC,2CAA2C;IAC3C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mDAAmD;IACnD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAQ1B,IAAI,IAAI,QAAQ,EAAE;IAQZ,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;CAiB5E"}