@sema-ai/core 1.275.1

package/dist/core/session-policy-store.js

@@ -0,0 +1,177 @@
+/**
+ * design/99 §E6 — per-session permission rules: a durable, session-scoped policy narrowing folded into the
+ * task-time {@link import("./tool-policy.js").ToolPolicy} (see {@link import("./runner/session-rule-policy.js").createSessionRulePolicy}).
+ *
+ * Why core-owned (not a parallel service store): the rules must be ENFORCED by the same policy fold that runs
+ * every tool call, so storage and enforcement can't drift (the [210] capability-token invariant). core defines
+ * the seam + an InMemory default; a deployment supplies a DURABLE cross-replica backend (its CAS-rev semantics
+ * must match this InMemory one byte-for-byte — a cross-backend equivalence test is the contract).
+ *
+ * Safety model:
+ * - **tighten-only by default**: a NORMAL write may only ADD denies / NARROW allowlists / NARROW allowDirs. A
+ *   write that LOOSENS (removes a deny, widens an allowlist/allowDirs) is REFUSED unless it is an OPERATOR
+ *   write. core has NO role system — `operator` is a boolean the caller FREEZES from a verified principal
+ *   (mirrors `steer.trusted`); core never adjudicates operator-ness, it only honors the flag.
+ * - **CAS rev** (optimistic concurrency): a `putRules` with a stale `expectedRev` is rejected, so two replicas
+ *   can't lose an update (mirrors the checkpoint store's `resolve` OCC).
+ * - **structured fields only**: core interprets `toolAllow/Deny`, `allowDirs`, `commandAllow/Deny` (argv[0]
+ *   names). A richer rule DSL is the service's/profile's job — core grows no rule interpreter.
+ * - **NOT A SANDBOX**: command rules inherit the coarse argv[0] matching (wrappers like `sh -c`/`sudo` bypass);
+ *   the real isolation boundary is the executionEnv, never these rules.
+ */
+import { posix } from "node:path";
+/** Typed error from {@link SessionPolicyStore.putRules}. `conflict` = stale `expectedRev`; `loosen_forbidden`
+ *  = a non-operator write tried to relax the rules. */
+export class SessionPolicyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SessionPolicyError";
+    }
+}
+/**
+ * LEXICAL path containment for the tighten gate. **Must agree with the runtime's view of what a dir IS** (the
+ * runtime resolves `..`/`.`/`//` via `canonicalizeTarget`): both args are `posix.normalize`d FIRST so a
+ * non-operator can't smuggle a write-confinement OUTSIDE the prior dir by writing `<prior>/../etc` — which is
+ * lexically "within `<prior>`" by a naive `startsWith` but canonicalizes to `/etc` at run time (the tighten
+ * gate must never UNDER-report a loosening).
+ *
+ * RESIDUAL (documented, bounded): the gate is LEXICAL and cannot follow symlinks at write time, while the
+ * runtime IS symlink-aware. A stored allowDir whose LAST component is a pre-existing symlink to outside the
+ * prior set would be seen as "within" by this gate yet resolve elsewhere at run time. This is bounded: while an
+ * `allowDirs` confinement is active the runtime DENIES `bash` (non-path-confinable), so a confined non-operator
+ * cannot CREATE such a symlink — it must pre-exist on the deployment's filesystem. Operators / the durable
+ * backend should keep `allowDirs` to real directories; a future symlink-aware write-time canonicalize closes it.
+ */
+function lexWithin(root, p) {
+    // [K-PLATFORM-SWEEP] MINOR#6: fold to "/" form (+ drive-letter case) BEFORE posix.normalize — win-form
+    // allowDirs were one opaque segment to posix semantics, so every win-family tighten was rejected as a
+    // widening (fail-closed but unusable). Form-detected, not process.platform.
+    const fold = (x) => {
+        let n = x.replace(/\\/g, "/");
+        if (/^[A-Za-z]:(\/|$)/.test(n))
+            n = n[0].toLowerCase() + n.slice(1);
+        return n;
+    };
+    const nr = posix.normalize(fold(root)).replace(/\/+$/, "") || "/";
+    const np = posix.normalize(fold(p)).replace(/\/+$/, "") || "/";
+    // Root "/" contains every absolute path. Without this special-case the `np.startsWith(nr + "/")` test becomes
+    // `startsWith("//")` (false for all real paths), so a valid NARROWING from allowDirs:["/"] to a subdir would
+    // be wrongly flagged as a widening and the tightening rejected (R5 bug-hunt; fail-closed, never a loosen leak).
+    if (nr === "/")
+        return true;
+    return np === nr || np.startsWith(nr + "/");
+}
+/** Normalize a rules object's `allowDirs` (lexical `posix.normalize`) so stored rules are `..`-free and the
+ *  tighten diff compares the same canonical-ish form the runtime resolves. */
+export function normalizeRules(rules) {
+    // Build the CANONICAL form: only the known fields, DROPPING any explicit-`undefined` key so a structuredClone
+    // (InMemory) and a JSON round-trip (File) produce byte-identical stored rules (cross-backend equivalence,
+    // review M3). allowDirs is lexically `posix.normalize`d so the tighten diff matches the runtime's resolved view.
+    const out = {};
+    // COPY the list arrays (not alias) so the stored + returned rules are detached from the caller's input
+    // arrays — matches InMemory's structuredClone return and keeps both backends' returns byte-equivalent AND
+    // safe against a caller that mutates the array it passed in (review: File putRules returned aliased arrays).
+    if (rules.toolAllow !== undefined)
+        out.toolAllow = [...rules.toolAllow];
+    if (rules.toolDeny !== undefined)
+        out.toolDeny = [...rules.toolDeny];
+    if (rules.commandAllow !== undefined)
+        out.commandAllow = [...rules.commandAllow];
+    if (rules.commandDeny !== undefined)
+        out.commandDeny = [...rules.commandDeny];
+    if (rules.allowDirs !== undefined)
+        out.allowDirs = rules.allowDirs.map((d) => posix.normalize(d).replace(/\/+$/, "") || "/");
+    return out;
+}
+/**
+ * Pure tighten-only diff: the reasons `next` LOOSENS `prior` (empty ⇒ `next` is a pure tightening or no-op).
+ * Direction per field — deny-lists: removing an entry loosens. allowlists: removing the list (→ everything
+ * allowed) or adding an entry outside the prior set loosens; prior-undefined → any defined next only narrows.
+ * allowDirs: removing confinement, or adding a dir not within some prior dir, loosens (coarse raw containment).
+ */
+export function loosenReasons(prior, next) {
+    const reasons = [];
+    for (const field of ["toolDeny", "commandDeny"]) {
+        const n = new Set(next[field] ?? []);
+        for (const x of prior[field] ?? [])
+            if (!n.has(x))
+                reasons.push(`removed ${field} "${x}"`);
+    }
+    for (const field of ["toolAllow", "commandAllow"]) {
+        const p = prior[field];
+        if (p === undefined)
+            continue; // no prior allowlist ⇒ a defined next only narrows
+        const n = next[field];
+        if (n === undefined) {
+            reasons.push(`removed ${field} allowlist (all allowed)`);
+            continue;
+        }
+        const ps = new Set(p);
+        for (const x of n)
+            if (!ps.has(x))
+                reasons.push(`widened ${field} with "${x}"`);
+    }
+    const pd = prior.allowDirs;
+    if (pd !== undefined && pd.length > 0) {
+        const nd = next.allowDirs;
+        if (nd === undefined || nd.length === 0)
+            reasons.push("removed allowDirs confinement");
+        else
+            for (const dir of nd)
+                if (!pd.some((d) => lexWithin(d, dir)))
+                    reasons.push(`widened allowDirs with "${dir}"`);
+    }
+    return reasons;
+}
+/** strip any caller-passed `rev` from a rules object so the store is the sole authority on it. */
+export function stripRev(rules) {
+    const { ...rest } = rules;
+    delete rest.rev;
+    return rest;
+}
+/**
+ * In-process default {@link SessionPolicyStore} (single-replica). A deployment that needs cross-replica
+ * durability supplies its own backend with the SAME CAS-rev + tighten-only semantics. Single-threaded JS makes
+ * the read-check-write trivially atomic here; a durable backend folds it into a CAS WHERE clause.
+ */
+export class InMemorySessionPolicyStore {
+    map = new Map();
+    key(sessionId, principal) {
+        return JSON.stringify([sessionId, principal ?? null]); // delimiter-injection-safe composite key
+    }
+    async getRules(sessionId, principal) {
+        const r = this.map.get(this.key(sessionId, principal));
+        return r ? structuredClone(r) : null;
+    }
+    async putRules(sessionId, principal, rules, opts) {
+        const key = this.key(sessionId, principal);
+        const prior = this.map.get(key);
+        if (opts?.expectedRev !== undefined && (prior?.rev ?? 0) !== opts.expectedRev) {
+            throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${prior?.rev ?? 0})`);
+        }
+        const clean = normalizeRules(stripRev(rules)); // §E6 fix: normalize allowDirs so the tighten diff + stored form match the runtime
+        if (prior && opts?.operator !== true) {
+            const loosens = loosenReasons(prior, clean);
+            if (loosens.length > 0) {
+                throw new SessionPolicyError("loosen_forbidden", `a non-operator session-rule write may only tighten; refused: ${loosens.join("; ")}`);
+            }
+        }
+        const next = { ...structuredClone(clean), rev: (prior?.rev ?? 0) + 1 };
+        this.map.set(key, next);
+        return structuredClone(next);
+    }
+    async listBySession(sessionId) {
+        // [271]: the composite key encodes [sessionId, principal] — decode it to recover the principal each rules
+        // record belongs to (getRules is per-principal; export needs them all).
+        const out = [];
+        for (const [k, rules] of this.map) {
+            const [sid, principal] = JSON.parse(k);
+            if (sid === sessionId)
+                out.push({ principal: principal ?? undefined, rules: structuredClone(rules) });
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=session-policy-store.js.map

package/dist/core/session-policy-store.js.map

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

package/dist/core/session-reconcile.d.ts

@@ -0,0 +1,63 @@
+import type { AgentMessage } from "../internal/harness.js";
+import type { Session } from "./session.js";
+import type { ToolEffect } from "./types.js";
+/**
+ * Wake/resume side-effect reconciliation.
+ *
+ * Problem (design/07 · C3): a task can be interrupted (crash, kill, timeout, lost instance) in the
+ * window between an assistant message with tool calls being persisted and that turn's tool results
+ * being flushed. The session event log then ends with one or more **orphan tool calls** — a tool
+ * call with no matching `toolResult`. On wake this is two bugs at once:
+ *   1. Most chat APIs reject a request whose assistant tool_call is not followed by a tool result.
+ *   2. The tool's `execute` may already have run (the side effect happened) — or may not have. The
+ *      outcome is genuinely unknown.
+ *
+ * Contract enforced here:
+ *   - **Never auto-replay a tool.** Reconstruction (`buildSessionContext`) already does not re-run
+ *     tools; this guarantees we also never synthesize a "success" that hides an unknown outcome.
+ *   - For each orphan, append a synthetic `toolResult` (isError) that tells the model the call was
+ *     interrupted and its outcome is unknown — making the transcript API-valid AND handing the
+ *     decision to the model under its verification discipline.
+ *   - Use the tool's {@link ToolEffect} to tune the message: `read`/`idempotent` are safe to repeat;
+ *     `write` (and unknown tools, conservatively) must be verified/confirmed before repeating.
+ *
+ * This runs on `acquire` of a resumed session, before the next turn starts. New/empty sessions and
+ * cleanly-finished sessions have no orphans and are left untouched.
+ */
+/** An assistant tool call with no matching `toolResult` in the active branch. */
+export interface OrphanToolCall {
+    toolCallId: string;
+    toolName: string;
+}
+/** Outcome of reconciling a resumed session. */
+export interface ReconcileReport {
+    /** Orphan calls that were closed with a synthetic interrupted result (empty when nothing to do). `entryId` =
+     *  the persisted toolResult entry id — message-identity Phase 1: the caller emits a `message_committed` for each
+     *  so a consumer's `entryId → message` map stays complete for these reconcile-appended results (they render a
+     *  `tool_end`). They are never a compaction floor (`toolResult` is excluded from cut points), so this is map
+     *  completeness, not `preserved_segment` correctness. */
+    recovered: Array<OrphanToolCall & {
+        entryId: string;
+    }>;
+}
+/**
+ * Find assistant tool calls in `messages` that have no matching `toolResult`.
+ * Order follows first appearance in the transcript (orphans are normally only at the tail).
+ *
+ * `suspendedBatch` (design/45 §15.2 net-add #7): the set of tool-call ids belonging to a **deliberately
+ * suspended** batch (the pending + not-yet-started calls of a durable-checkpoint suspension). These are
+ * NOT orphans — they are waiting to be resumed via `runner.resume()`, not crash-interrupted. Wake-path
+ * reconcile must skip them, or it would append `[INTERRUPTED]` results and **destroy the suspended
+ * batch** (the bug this guard fixes: the wake/resume naming overload became real data destruction).
+ * `runner.resume()` uses a checkpoint-aware entry that bypasses this reconcile entirely for those calls.
+ */
+export declare function findOrphanToolCalls(messages: AgentMessage[], suspendedBatch?: ReadonlySet<string>): OrphanToolCall[];
+/**
+ * Reconcile a resumed session's active branch: close any orphan tool calls with a synthetic
+ * interrupted `toolResult` (never re-running the tool). Returns what was recovered.
+ *
+ * @param toolEffects optional name→effect map (from the task's tools). Unknown names are treated as
+ *   `write` — the conservative default, so an unrecognized interrupted call is never said to be safe.
+ */
+export declare function reconcileInterruptedSession(session: Session, toolEffects?: Map<string, ToolEffect>, suspendedBatch?: ReadonlySet<string>): Promise<ReconcileReport>;
+//# sourceMappingURL=session-reconcile.d.ts.map

package/dist/core/session-reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-reconcile.d.ts","sourceRoot":"","sources":["../../src/core/session-reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B;;;;6DAIyD;IACzD,SAAS,EAAE,KAAK,CAAC,cAAc,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD;AAaD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,EAAE,EACxB,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACnC,cAAc,EAAE,CAmBlB;AAED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,OAAO,EAChB,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACrC,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACnC,OAAO,CAAC,eAAe,CAAC,CAuB1B"}

package/dist/core/session-reconcile.js

@@ -0,0 +1,71 @@
+import { canonicalToolName } from "./tool-name-aliases.js";
+const INTERRUPTED_UNKNOWN = "[INTERRUPTED] The previous run ended before this tool call's result was recorded. Its outcome " +
+    "is UNKNOWN — the action may have completed, partially completed, or never run. Do not assume " +
+    "success or failure. Before relying on it: if it is safe to read, query the current state to " +
+    "check; if this was a write or irreversible action, confirm with the user before repeating it.";
+const INTERRUPTED_SAFE = "[INTERRUPTED] The previous run ended before this tool call's result was recorded. This tool is " +
+    "read-only/idempotent, so its outcome carries no risk: simply call it again if you still need " +
+    "the result.";
+/**
+ * Find assistant tool calls in `messages` that have no matching `toolResult`.
+ * Order follows first appearance in the transcript (orphans are normally only at the tail).
+ *
+ * `suspendedBatch` (design/45 §15.2 net-add #7): the set of tool-call ids belonging to a **deliberately
+ * suspended** batch (the pending + not-yet-started calls of a durable-checkpoint suspension). These are
+ * NOT orphans — they are waiting to be resumed via `runner.resume()`, not crash-interrupted. Wake-path
+ * reconcile must skip them, or it would append `[INTERRUPTED]` results and **destroy the suspended
+ * batch** (the bug this guard fixes: the wake/resume naming overload became real data destruction).
+ * `runner.resume()` uses a checkpoint-aware entry that bypasses this reconcile entirely for those calls.
+ */
+export function findOrphanToolCalls(messages, suspendedBatch) {
+    const resolved = new Set();
+    for (const m of messages) {
+        if (m.role === "toolResult") {
+            resolved.add(m.toolCallId);
+        }
+    }
+    const orphans = [];
+    for (const m of messages) {
+        if (m.role !== "assistant") {
+            continue;
+        }
+        for (const part of m.content) {
+            if (part.type === "toolCall" && !resolved.has(part.id) && !suspendedBatch?.has(part.id)) {
+                orphans.push({ toolCallId: part.id, toolName: part.name });
+            }
+        }
+    }
+    return orphans;
+}
+/**
+ * Reconcile a resumed session's active branch: close any orphan tool calls with a synthetic
+ * interrupted `toolResult` (never re-running the tool). Returns what was recovered.
+ *
+ * @param toolEffects optional name→effect map (from the task's tools). Unknown names are treated as
+ *   `write` — the conservative default, so an unrecognized interrupted call is never said to be safe.
+ */
+export async function reconcileInterruptedSession(session, toolEffects, suspendedBatch) {
+    const { messages } = await session.buildContext();
+    const orphans = findOrphanToolCalls(messages, suspendedBatch);
+    const recovered = [];
+    for (const orphan of orphans) {
+        // Q6 (design/102 §3.6, release-gate): a PRE-rename persisted session's orphan holds an OLD tool name (e.g.
+        // "read_file"); `toolEffects` is keyed by the NEW names, so canonicalize before the lookup — else a read/
+        // idempotent orphan from an old session falls to the "write" default and is over-conservatively reported
+        // INTERRUPTED_UNKNOWN instead of INTERRUPTED_SAFE.
+        const effect = toolEffects?.get(canonicalToolName(orphan.toolName)) ?? "write";
+        const safe = effect === "read" || effect === "idempotent";
+        // Capture the returned entry id (message-identity Phase 1) — the caller emits a `message_committed` for it.
+        const entryId = await session.appendMessage({
+            role: "toolResult",
+            toolCallId: orphan.toolCallId,
+            toolName: orphan.toolName,
+            content: [{ type: "text", text: safe ? INTERRUPTED_SAFE : INTERRUPTED_UNKNOWN }],
+            isError: true,
+            timestamp: Date.now(),
+        });
+        recovered.push({ ...orphan, entryId });
+    }
+    return { recovered };
+}
+//# sourceMappingURL=session-reconcile.js.map

package/dist/core/session-reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-reconcile.js","sourceRoot":"","sources":["../../src/core/session-reconcile.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA0C3D,MAAM,mBAAmB,GACvB,gGAAgG;IAChG,+FAA+F;IAC/F,8FAA8F;IAC9F,+FAA+F,CAAC;AAElG,MAAM,gBAAgB,GACpB,iGAAiG;IACjG,+FAA+F;IAC/F,aAAa,CAAC;AAEhB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAwB,EACxB,cAAoC;IAEpC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAC5B,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YAC7B,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,cAAc,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;gBACxF,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,OAAgB,EAChB,WAAqC,EACrC,cAAoC;IAEpC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC;IAClD,MAAM,OAAO,GAAG,mBAAmB,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAgD,EAAE,CAAC;IAClE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,2GAA2G;QAC3G,0GAA0G;QAC1G,yGAAyG;QACzG,mDAAmD;QACnD,MAAM,MAAM,GAAG,WAAW,EAAE,GAAG,CAAC,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,OAAO,CAAC;QAC/E,MAAM,IAAI,GAAG,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,YAAY,CAAC;QAC1D,4GAA4G;QAC5G,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC;YAC1C,IAAI,EAAE,YAAY;YAClB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC;YAChF,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;QACH,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}

package/dist/core/session-store.d.ts

@@ -0,0 +1,99 @@
+import { type SessionRepo } from "../internal/harness.js";
+import { type AcquiredSession, type SessionStore, type SessionSummary } from "./session.js";
+/** What idle-eviction and `release` do to the underlying repo. */
+export type EvictPolicy = "delete" | "forget";
+export interface TtlSessionStoreOptions {
+    /** Idle TTL before a cached session is evicted. Default 7 days. */
+    defaultTtlDays?: number;
+    /** Optional background sweep interval (ms). Off by default (sweeps opportunistically on acquire). */
+    sweepIntervalMs?: number;
+    /**
+     * Backing session repo. Default `InMemorySessionRepo` (process-only, lost on restart). Supply a
+     * **durable** repo (e.g. a TiDB-backed `SessionRepo`, or the vendored file repo) to persist
+     * sessions: `acquire` then **resumes** an existing session via `repo.open`, so any stateless
+     * runner instance — even after a restart or on another replica — continues the same conversation.
+     */
+    repo?: SessionRepo;
+    /**
+     * What idle-eviction and `release` do to the repo:
+     * - `"delete"` — remove the session from the repo too (correct for the throwaway in-memory repo).
+     * - `"forget"` — only drop the in-memory cache; the **durable** backend keeps the history so it can
+     *   be resumed later (the backend runs its own retention/GC).
+     *
+     * Defaults to `"delete"` for the built-in in-memory repo and `"forget"` when a custom `repo` is
+     * supplied — so a durable store never silently deletes history on an idle timer.
+     */
+    evict?: EvictPolicy;
+}
+/**
+ * TTL-cached {@link SessionStore} over a pluggable {@link SessionRepo}.
+ *
+ * Sessions are cached in process memory and evicted after `defaultTtlDays` of inactivity. With the
+ * default in-memory repo they live only in this process (lost on restart). Supply a **durable** repo
+ * and the same caching/concurrency logic becomes a "session center": on `acquire`, a session not in
+ * the live cache is **resumed from the repo** (`repo.open`) rather than recreated — so a stateless
+ * runner resumes a conversation after a restart or across replicas. The optimistic-lock seam
+ * (`SessionWriteOptions.expectedLeafId` → `SessionError("conflict")`) keeps two replicas writing the
+ * same session safe; the Runner reconciles a lost CAS and retries.
+ *
+ * See `design/10-会话持久化与会话中心.md` for the durable-backend (TiDB) contract.
+ */
+export declare class TtlSessionStore implements SessionStore {
+    private repo;
+    private entries;
+    /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) share one session. */
+    private pending;
+    /** Sessions pinned by a design/45 checkpoint — skipped by idle sweep until unpinned (B6/§5). */
+    private pinned;
+    private defaultTtlMs;
+    private evictPolicy;
+    private sweepTimer?;
+    constructor(opts?: TtlSessionStoreOptions);
+    /** Get an existing session by id (resuming from the repo if needed), or create one. */
+    acquire(sessionId?: string, opts?: {
+        requireExisting?: boolean;
+    }): Promise<AcquiredSession>;
+    /** Resume an existing session from the repo, or create it if the backend has no such id (unless
+     *  `requireExisting`, in which case a genuinely-missing id fails loud instead — design/114 Phase3). */
+    private openOrCreate;
+    private createAndStore;
+    /** Refresh the idle timer for a session. */
+    touch(sessionId: string): void;
+    /** Record the most recent task run on a cached session (the `/resume` `lastRunId`); also bumps the idle
+     *  timer. Best-effort — a no-op if the session isn't cached here (the run will still be re-attachable via
+     *  its checkpoint). */
+    noteTaskRun(sessionId: string, taskId: string): void;
+    /** List the live cache as {@link SessionSummary} projections, newest-first by `lastActiveAt` (so a shell's
+     *  `/resume` shows recent sessions + their last run first). The in-memory store lists only its live cache,
+     *  not evicted/durable history — a durable backend overrides this to list persisted sessions. */
+    list(): Promise<SessionSummary[]>;
+    /**
+     * design/110 (F3) — FORK a session: copy `sourceId`'s committed history into a NEW session and return its id
+     * (or `null` when the source doesn't exist). Delegates to the backing repo's `fork`, so a durable repo persists the
+     * branch; the in-memory repo holds it in-process. Registering the result in this cache makes `acquire(forkedId)`
+     * hit immediately — the synchronous child run that `Agent(subagent_type:"fork")` launches resumes the fork without a repo round-trip.
+     *
+     * Adding this method is what makes {@link hasSessionFork} true for a `TtlSessionStore` wrapping ANY repo, so the
+     * fork capability mounts (it was INERT before — the durable repo had `fork` but the store never exposed it).
+     */
+    fork(sourceId: string, owner?: string | null): Promise<string | null>;
+    /** Drop a session from the live set. With a durable repo (`evict: "forget"`) the history is kept. */
+    release(sessionId: string): Promise<void>;
+    /** Drop only the cached view — the repo keeps the session regardless of `evictPolicy`, so a re-acquire
+     *  re-opens the SAME history (B-17: the reconcile retry / prepare-throw paths must never delete). Cost
+     *  on the default in-memory repo: ONE retained session object **per forgotten id** until process end
+     *  (invisible to `size`/`sweep`, which track the cache) — accumulation across many distinct forgotten
+     *  ids is the accepted trade-off vs silent history loss; deployments with churn use a durable repo,
+     *  where retention is the backend's normal job. A pinned id stays pinned (a forget must never expose a
+     *  suspended task's session to sweep eviction). */
+    forget(sessionId: string): void;
+    /** Pin a session so idle sweep can't evict it while a design/45 checkpoint awaits resume (§5). */
+    pin(sessionId: string): void;
+    /** Release a design/45 pin (on resume or checkpoint expiry); the session resumes normal idle eviction. */
+    unpin(sessionId: string): void;
+    /** Evict idle-expired sessions from the cache. Deletes durable history only when `evict: "delete"`. */
+    sweep(now?: number): void;
+    get size(): number;
+    dispose(): void;
+}
+//# sourceMappingURL=session-store.d.ts.map

package/dist/core/session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../../src/core/session-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,WAAW,EAEjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAqB,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAe/G,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qGAAqG;IACrG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,YAAW,YAAY;IAClD,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,OAAO,CAA4B;IAC3C,2FAA2F;IAC3F,OAAO,CAAC,OAAO,CAA0C;IACzD,gGAAgG;IAChG,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,UAAU,CAAC,CAAiC;gBAExC,IAAI,GAAE,sBAA2B;IAW7C,uFAAuF;IACjF,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAkCjG;2GACuG;YACzF,YAAY;YAuBZ,cAAc;IAS5B,4CAA4C;IAC5C,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAO9B;;2BAEuB;IACvB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAQpD;;qGAEiG;IAC3F,IAAI,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAYvC;;;;;;;;OAQG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA4C3E,qGAAqG;IAC/F,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB/C;;;;;;uDAMmD;IACnD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI/B,kGAAkG;IAClG,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI5B,0GAA0G;IAC1G,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9B,uGAAuG;IACvG,KAAK,CAAC,GAAG,SAAa,GAAG,IAAI;IAe7B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,IAAI,IAAI;CAKhB"}