@sema-agent/core 5.19.0 → 5.21.0

package/dist/core/lsp.d.ts

@@ -1,21 +1,68 @@
 import type { AgentTool, ExecutionEnv } from "../internal/harness-types.js";
+/**
+ * LSP code-intelligence tool (design/64 §13.1) — the app-dev命门 (go-to-def / find-refs / hover across
+ * Dart/Kotlin/TS). A single `lsp` tool with a 9-operation enum, built over a pluggable {@link LspServerManager}.
+ *
+ * **Seam note (core verifying the design against real code):** the design assumed core spawns a language
+ * server inside the ExecutionEnv via `execStream`, but `execStream` is OUTPUT-only — it has no stdin, so the
+ * base seam can't drive a persistent stdio language server generically. So core ships the **tool + manager
+ * seam + graceful degrade + git-ignore filter + formatters**; the *real* in-env manager (E2B LSP sidecar, or
+ * a future bidirectional-process seam) is deployment-provided via {@link RunnerDeps.lspManager}. When no
+ * server is available for a file's language the tool **degrades gracefully** ("fall back to Grep/Read")
+ * rather than erroring — the design's hard constraint for remote portability.
+ */
 export type LspOperation = "goToDefinition" | "findReferences" | "hover" | "documentSymbol" | "workspaceSymbol" | "goToImplementation" | "prepareCallHierarchy" | "incomingCalls" | "outgoingCalls";
 export declare const LSP_OPERATIONS: readonly LspOperation[];
+/**
+ * A source location (a definition/reference/implementation hit). `uri` is a file path or file:// URI.
+ *
+ * Base convention (the seam's factual contract, service[64] flag①): `line` is **1-based**, `character`
+ * is **0-based** — the tool-schema convention the model is taught. Core passes positions through
+ * VERBATIM in both directions; the `LspServerManager` implementation owns the conversion to/from the
+ * LSP wire protocol (which is 0-based for BOTH) — e.g. request line−1 on the way in, result line+1 on
+ * the way out, call-hierarchy items relayed as wire values it already converted.
+ */
 export interface LspLocation {
     uri: string;
+    /** 1-based (tool convention — manager converts to the 0-based LSP wire). */
     line: number;
+    /** 0-based (matches the LSP wire). */
     character: number;
+    /** Optional one-line preview of the matched line. */
     preview?: string;
 }
+/** A symbol (document/workspace symbol, call-hierarchy item). Same base convention as {@link LspLocation}. */
 export interface LspSymbolInfo {
     name: string;
     kind?: string;
     uri: string;
+    /** 1-based (tool convention — manager converts to the 0-based LSP wire). */
     line: number;
+    /** 0-based (matches the LSP wire). */
     character: number;
+    /**
+     * HRD-LSP-18: the server supplied NO range for this symbol — `line`/`character` are placeholders, not a
+     * location. LSP allows exactly this for an unresolved `WorkspaceSymbol` (`{ name, kind, location: { uri } }`,
+     * resolved later via `workspaceSymbol/resolve`), and the coercion below used to substitute `{0,0}` silently,
+     * which the tool then rendered as a precise-looking `uri:1:1` the server never said. Set ⇒ the renderer
+     * prints the file WITHOUT coordinates.
+     */
     positionUnknown?: boolean;
 }
-export type LspNoneReason = "unsupported_operation" | "server_error" | "timeout" | "cancelled" | "server_terminated" | "no_call_hierarchy_item" | "file_sync_failed";
+/**
+ * RB-232(黑板 [1937]): WHY a "none" result was "none". Absent `reason` = a GENUINE empty answer (the server
+ * answered null/[] — today's behavior byte-for-byte, and what an external manager returning bare
+ * `{kind:"none"}` keeps getting). The failure reasons exist because one literal "No results." used to cover
+ * both real emptiness and every transport-level fault — a findReferences that TIMED OUT read as "no
+ * references, safe to delete" (CC 2.1.220 keeps these apart: `Error performing ${operation}: ...` vs the
+ * plain empty-result strings, pretty220.js ~474840).
+ */
+export type LspNoneReason = "unsupported_operation" | "server_error" | "timeout" | "cancelled" | "server_terminated" | "no_call_hierarchy_item"
+/** HRD-LSP-7: the QUERIED file could not be read for the didOpen/didChange re-sync (deleted between the
+ *  tool's precheck and the op, EACCES, non-regular, over the size cap, a symlinked over-cap target). The
+ *  session used to swallow that and query the server anyway, so the resulting `null`/`[]` was
+ *  indistinguishable from a confirmed-empty answer — the exact confusion the reason set exists to end. */
+ | "file_sync_failed";
 export type LspResult = {
     kind: "locations";
     locations: LspLocation[];
@@ -30,48 +77,150 @@ export type LspResult = {
     reason?: LspNoneReason;
     detail?: string;
 };
+/** The property {@link brandLspFailure} sets — a STRING property, not a class: the brand must survive a
+ *  dual ESM/CJS build and duplicated module instances, where `instanceof` does not (same structural-
+ *  detection philosophy as {@link pathToUri}'s form detection — never key on identity you don't control). */
 export declare const LSP_FAILURE_BRAND = "lspFailureReason";
+/** Brand a transport-layer error with its {@link LspNoneReason} at the THROW site — the throw site is the
+ *  only place that still holds the discriminator (e.g. the JSON-RPC error CODE, which message-regex
+ *  classification cannot recover, and which differs textually across transports). */
 export declare function brandLspFailure<E extends Error>(e: E, reason: LspNoneReason, detail?: string): E;
+/** Duck-typed read of {@link brandLspFailure}'s brand (membership-checked — an arbitrary string-valued
+ *  property of the same name on a third-party error never becomes a reason we didn't define). */
 export declare function lspFailureOf(e: unknown): {
     reason: LspNoneReason;
     detail?: string;
 } | undefined;
+/**
+ * The abort signal for work shared by several callers: it fires only once EVERY registered caller has
+ * abandoned it, so one caller's cancellation can never cancel another caller's work. A joiner that
+ * passes no signal never abandons (the job then runs to completion regardless of the others).
+ *
+ * The scope is single-use: once it has aborted, the owner must NOT let a new caller join it (the job it
+ * guards is already dying) — check {@link signal}`.aborted` before reusing an in-flight entry.
+ */
 export declare class SharedAbortScope {
     private readonly controller;
     private joiners;
     private abandoned;
     get signal(): AbortSignal;
+    /** Register one caller (its `signal` may be absent = it never abandons). */
     join(signal?: AbortSignal): void;
     private abandon;
 }
+/**
+ * Give ONE caller its own settle on a shared job: the caller's `signal` resolves it with `onAbort()`
+ * without disturbing the job (which other callers may still need). The job's own settle is always
+ * observed, so a later rejection can never surface as an unhandled rejection.
+ */
 export declare function settleOnAbort<T>(job: Promise<T>, signal: AbortSignal | undefined, onAbort: () => T): Promise<T>;
+/**
+ * HRD-LSP-5: resolve a model-supplied `filePath` against the TASK's cwd, once, for every leg.
+ *
+ * The tool used to join a relative path to `env.cwd` for the existence/size PRECHECK only and hand the
+ * ORIGINAL string to `sessionFor` → `readText`/`pathToUri`, which resolve against the HOST process cwd.
+ * With a task cwd that is not the host cwd (worktree/sandbox/service worker — i.e. every non-trivial
+ * deployment) the two legs then addressed two different files: the precheck passed on the real file
+ * while the server was handed `file:///<host-cwd>/<rel>`, and the model got a confident "No results."
+ * for a file that was never analyzed.
+ *
+ * Absolute-form input (either family) passes the join; "no cwd known" keeps the caller's spelling.
+ *
+ * REF-C3 — the result is dot-folded, which is what makes this function THE key-minting seam: every URI
+ * for a file (didOpen, publishDiagnostics, the diagnostics registry's `fileEdited` clear, buildRequest)
+ * comes from here, and `pathToUri`'s POSIX branch is a hand-assembled per-segment encode that keeps a
+ * `.` segment verbatim. Without the fold, `./src/a.ts` and `src/a.ts` minted two keys for one file:
+ * delivered diagnostics never cleared, and the server held a duplicate document. The edit-nudge leg in
+ * prepare-task.ts had grown its own copy of the fold for exactly this reason; it now calls this instead,
+ * so "one file, one key" is a property of the code rather than of two spellings staying in step.
+ */
 export declare function resolveLspPath(filePath: string, cwd?: string): string;
+/** Request positions use the same base convention as {@link LspLocation}: line 1-based, character 0-based. */
 export interface LspRequestParams {
     filePath: string;
+    /** 1-based (tool convention) — the manager converts to the 0-based LSP wire (line−1). */
     line?: number;
+    /** 0-based (matches the LSP wire). */
     character?: number;
+    /** For workspaceSymbol: the symbol query string. */
     symbol?: string;
 }
+/** An active language-server session for one language, scoped to a workspace. */
 export interface LspSession {
     request(op: LspOperation, params: LspRequestParams, signal?: AbortSignal): Promise<LspResult>;
 }
+/**
+ * A JSON-RPC transport to ONE language server, POST-`initialize`. The DEPLOYMENT provides the concrete
+ * transport; the protocol logic ({@link buildRequest}/`parseResult`, `TransportLspSession`) drives the LSP
+ * over this single seam, so the two lanes can't drift:
+ *  - **TOC** = {@link StdioLspTransport} (spawn the server LOCALLY; Content-Length JSON-RPC over its stdio — a
+ *    faithful copy of CC's `services/lsp/LSPClient`);
+ *  - **TOB** = a WS bridge (the server runs INSIDE a remote sandbox, reached over a WebSocket — service's
+ *    `ws-transport`, because `execStream` is output-only so the base seam can't drive a stdio server remotely).
+ */
 export interface LspTransport {
+    /** A JSON-RPC request; resolves the `result` (or rejects on a JSON-RPC error / timeout / abort). */
     request(method: string, params: unknown, signal?: AbortSignal): Promise<unknown>;
+    /** A JSON-RPC notification (no response) — e.g. `textDocument/didOpen`. */
     notify(method: string, params: unknown): void;
+    /**
+     * design/121: subscribe to server→client NOTIFICATIONS (a message with a `method` and no `id` —
+     * `textDocument/publishDiagnostics`, `window/logMessage`, …). Returns an unsubscribe. Optional and
+     * ADDITIVE: a transport without it — or with no subscriber — behaves exactly as before (notifications
+     * dropped). The transport must swallow a throwing handler (a bad consumer must never kill the read loop).
+     */
     onNotification?(handler: (method: string, params: unknown) => void): () => void;
     close(): Promise<void>;
+    /** True once the underlying connection is gone (closed/errored) — the manager evicts + reopens. Optional so
+     *  a test mock stays minimal. */
     readonly closed?: boolean;
 }
+/** Reads a workspace file's CURRENT text for the session's didOpen/didChange re-sync. TOC = local fs; TOB =
+ *  the sandbox ExecutionEnv. */
 export type LspReadText = (filePath: string, signal?: AbortSignal) => Promise<string>;
+/** CC 2.1.220's LSP file cap (10MB — `File too large for LSP analysis`, pretty220.js ~474745). Single-sourced
+ *  in core: the TOOL-layer check in {@link createLspTool} (the model-visible enforcement, CC-parity) and the
+ *  defense-in-depth throw in the engine's `defaultLspReadText` must agree on one number. */
 export declare const MAX_LSP_FILE_BYTES: number;
+/**
+ * Resolves a language server session for a file. Returns `undefined` when no server is available for the
+ * file's language — the tool then degrades gracefully (design/64 §13.1 remote-portability constraint).
+ */
 export interface LspServerManager {
+    /**
+     * Resolve a session for `filePath`'s language, or `undefined` to degrade. `env` is the task's
+     * ExecutionEnv (the SAME sandbox the agent runs in) — core passes it because a real in-env language
+     * server must run inside that sandbox, and core already holds the per-task env at mount time. Supplying
+     * it here means a manager can be **stateless** (it doesn't need a sessionId→env registry). It is
+     * optional/last for back-compat: a manager that resolves the env another way (e.g. a sessionId registry
+     * keyed off `executionEnvFactory`) may ignore it.
+     */
     sessionFor(filePath: string, signal?: AbortSignal, env?: ExecutionEnv): Promise<LspSession | undefined>;
+    /**
+     * HRD-LSP-14 — OPTIONAL: why the last {@link sessionFor} for this file returned `undefined`, as a phrase
+     * for the model-facing degrade line ("no language server for its language in this environment" is used
+     * when absent). `undefined` ⇒ nothing more specific to say. ADDITIVE: a manager without it behaves
+     * exactly as before. Exists because `undefined` collapses "this language has no server configured",
+     * "the binary is not installed" and "the server is installed and fails to start" into one sentence that
+     * is only true for the first — and the operator can only act on the third if someone says it.
+     */
     unavailableReason?(filePath: string, env?: ExecutionEnv): string | undefined;
+    /** design/121: the manager's workspace diagnostics registry, when the deployment's manager supports
+     *  pushed diagnostics (NodeLspManager always does). The Runner drains it at turn boundaries to inject
+     *  `<new-diagnostics>` + emit the structured `diagnostics` frame. Absent ⇒ no diagnostics lane. */
     readonly diagnostics?: import("./lsp-diagnostics.js").LspDiagnosticsRegistry;
 }
 export interface LspToolOptions {
+    /** Drop results in files ignored by git (CC parity, design/64 §16/§17). Default: keep all. */
     isPathIgnored?: (uri: string) => boolean | Promise<boolean>;
+    /** The task's ExecutionEnv, passed through to {@link LspServerManager.sessionFor} (the agent's sandbox —
+     *  where an in-env language server must run). The Runner wires this from the per-task env. */
     env?: ExecutionEnv;
 }
+/** Build the `lsp` tool over a {@link LspServerManager}. Mounted only when a manager is wired (opt-in). */
 export declare function createLspTool(manager: LspServerManager, opts?: LspToolOptions): AgentTool;
+/**
+ * A git-check-ignore-based path filter for {@link LspToolOptions.isPathIgnored} (CC parity). Best-effort:
+ * if git isn't available or the check fails, nothing is treated as ignored (keep all). Caches per path.
+ */
 export declare function gitCheckIgnoreFilter(env: ExecutionEnv, root: string): (uri: string) => Promise<boolean>;

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

@@ -1,32 +1,89 @@
+/** One parked message. `seq` is minted by the store, monotonic per (scope, handle), stable across
+ *  lease/expiry cycles (a re-leased message keeps its number — dedup/ordering key). */
 export interface MailboxMessage {
     seq: number;
+    /** Sender display name, when the sender had one (SendMessage `senderName` — display only). */
     from?: string;
     content: string;
     sentAt: number;
+    /** design/176 — the peer-message forwarding chain (engine-minted hop tokens; typed side channel,
+     *  never model-facing text). Presence — even an empty array — marks the record as written through
+     *  the sema send gate; an absent field means a pre-176 or FOREIGN-engine record (a shared CC inbox
+     *  has other writers): such records deliver with an empty chain and are never retro-admitted —
+     *  cross-engine records sit outside the guard's promise domain by ruling. */
     hopChain?: string[];
 }
+/** A leased batch: the messages a claim winner owns for delivery, plus the ack cursor. */
 export interface MailboxLease {
     messages: MailboxMessage[];
+    /** Ack everything ≤ this seq once the revived cycle has durably received the batch. */
     maxSeq: number;
 }
+/** REF-D18: one appended mailbox message — the SINGLE shape the interface method and both the
+ *  In-Memory and File implementations reference. */
 export interface MailboxAppendMessage {
     from?: string;
     content: string;
     sentAt: number;
+    /** design/176 — see {@link MailboxMessage.hopChain}. */
     hopChain?: string[];
 }
+/**
+ * The pluggable mailbox seam (design/151 §7.1). Contract notes for implementations (file/pg):
+ * - `append` is durable-first (a returned seq means the message survives a crash); seq is monotonic
+ *   per (scope, handle) and never reused WITHIN a box's lifetime (across lease/ack cycles the
+ *   high-water mark persists). `drop` ENDS the lifetime — a later rebuild restarts at 1 (server[1523]
+ *   定谳: the row died with the box, dedup keys carry the handle, and a* handles are 64-bit-random).
+ *   RB-90 (2026-07-25, red probe) SPLITS `reap` back out of that sentence: the two were grouped, but
+ *   only `drop` is preceded by the row's death. `reap` is an age-based sweep that runs while the
+ *   recipient is alive and may hold a lease, so restarting seq there let a stale ack (up to the
+ *   pre-sweep high-water) delete a brand-new message no consumer had ever been shown — the "a parked
+ *   message is never lost" promise at the top of this file, broken silently. `reap` therefore CLEARS a
+ *   box and KEEPS its high-water mark; both bundled impls do so.
+ * - `claimLease` atomically marks every currently-visible (unleased or lease-expired) message as
+ *   leased by `owner` until `now + ttlMs`, returning them in seq order. Empty mailbox → null.
+ *   A second claim by a DIFFERENT owner while a live lease exists returns null (single consumer
+ *   per window — the row claim-CAS already guarantees one revival winner; this is the belt); the
+ *   SAME owner re-claiming RENEWS the lease and picks up any newer messages (the crash-retry form
+ *   — server[1523] 定谳: both bundled impls behave so, the contract follows the implementations).
+ * - `ack` deletes every message with seq ≤ upToSeq (the winner calls it at ATTACH success, never
+ *   before — §7.1: ack-late is what makes a crashed revival lossless).
+ * - `releaseLease` (best-effort) returns a lease early (spawn preflight failed before delivery).
+ * - `reap` ages out whole mailboxes by newest-message age (explicit policy). It is the BACKSTOP, not
+ *   the only reclaim path: the winning-delete arm of `reapDurableAgents` calls {@link MailboxStore.drop}
+ *   for the row it deletes, in the same sweep (F-13 — the row's mailbox dies with the row). That call
+ *   is ADVISORY: a drop fault never blocks the reap, and a box orphaned that way still ages out here.
+ *   `drop` therefore has a real caller — an implementation that stubs it strands mailboxes until the
+ *   age policy catches them.
+ */
 export interface MailboxStore {
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
+    /** Observation face (the "N pending" receipt figure) — count of currently-visible messages. */
     peekCount(scope: string, handle: string): Promise<number>;
+    /** Drop the WHOLE mailbox for (scope, handle) — the row-deletion companion (F-13). */
     drop(scope: string, handle: string): Promise<void>;
+    /** Age out mailboxes whose newest message BY `sentAt` (not by array/insertion order — RB-250②)
+     *  is older than maxAgeMs. Returns mailboxes dropped. */
     reap(scope: string, now: number, opts?: {
         maxAgeMs?: number;
     }): Promise<number>;
 }
+/** RB-250② (2026-07-28, 黑板 [1937]) class fix — the box age for `reap` is the MAX `sentAt`, not the
+ *  last array element: `sentAt` is caller-supplied, so append order need not be time order, and taking
+ *  the tail let a box whose freshest message was mid-array be swept — both bundled backends discarded
+ *  a brand-new message while the CC adapter (stores/cc/mailbox-store.ts, the in-package reference)
+ *  already reduces over MAX. Non-finite `sentAt` ⇒ undefined ("unknown age ⇒ never reaped", the CC
+ *  adapter's documented posture — treating it as very old would let a malformed row delete a live
+ *  box). Module-level export only; NOT re-exported from src/index.ts. */
 export declare function newestSentAt(messages: readonly MailboxMessage[]): number | undefined;
+/**
+ * In-process reference implementation (single-instance / tests). Same posture as
+ * {@link import("./background-agent-store.js").InMemoryBackgroundAgentStore}: not default-mounted,
+ * detached copies at both boundaries, single-event-loop atomicity.
+ */
 export declare class InMemoryMailboxStore implements MailboxStore {
     private boxes;
     private key;

package/dist/core/mailbox-store.js

@@ -1,3 +1,4 @@
+import { assertRetentionPolicy } from "./retention-policy.js";
 export function newestSentAt(messages) {
     let newest;
     for (const m of messages) {
@@ -65,6 +66,7 @@ export class InMemoryMailboxStore {
         this.boxes.delete(this.key(scope, handle));
     }
     async reap(scope, now, opts) {
+        assertRetentionPolicy("MailboxStore.reap", opts);
         if (opts?.maxAgeMs === undefined)
             return 0;
         let dropped = 0;