@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/fs-write-gate-policy.d.ts

@@ -1,11 +1,47 @@
 import type { ExecutionEnv } from "../internal/harness-types.js";
 import type { ToolPolicy } from "./tool-policy.js";
+/** Options for {@link createFsWriteGatePolicy}. */
 export interface FsWriteGatePolicyOptions {
+    /** The task's real execution env (the one the hands run against) — canonicalization must see the
+     *  actual filesystem (a remote/E2B task resolves in its container). */
     env: ExecutionEnv;
+    /** The FALLBACK base a relative path resolves against (omit = paths resolve as given). RB-108: the
+     *  call's TARGET prefers the live tracked cwd when the engine stamps one ({@link ToolCallRequest.cwd});
+     *  the `acceptDirs`/`exemptDirs` entries below always resolve against THIS value. */
     rootPath?: string;
+    /** Writes whose canonical target lands inside one of these dirs are ALLOWED (the accept-session
+     *  domain, e.g. the cwd subtree after "allow all edits during this session"). */
     acceptDirs?: readonly string[];
+    /** Writes whose canonical target lands inside one of these dirs are ALLOWED and never asked
+     *  (auto-approved working areas: the scratchpad dir, plan files). Checked before `acceptDirs`
+     *  (same verdict — the split is intent/observability, exemptions are structural not session-won). */
     exemptDirs?: readonly string[];
+    /** Verdict for a covered write OUTSIDE every domain: `"ask"` (the manual-mode default) routes it
+     *  to the ask-resolution chain (live onAsk / durable park / headless deny); `"allow"` is the
+     *  acceptEdits-mode shape (domain checks still run so a sensitive-path deny composes unchanged). */
     defaultWrite: "ask" | "allow";
+    /**
+     * Session-exemption lookup ("allow all for this session" grants recorded by the deployment's approval
+     * surface). Consulted ONCE per covered write, after the domain checks and immediately BEFORE the gate
+     * would produce its `ask`/default verdict — a `true` return short-circuits to `allow` (with a message
+     * naming the exemption source for the audit trail) so an already-granted write does not re-ask/park.
+     *
+     *  · `toolName` is the CANONICAL tool name (same normalization this gate matches on), so an exemption
+     *    recorded under either alias of a tool matches both — key your store with the same normalization.
+     *  · `canonicalPath` is the CANONICALIZED real target (the exact key the gate's own symlink-safe
+     *    containment judged) — a symlink alias of an exempted file therefore still hits the exemption,
+     *    and an exemption can never be minted for a raw alias that resolves elsewhere.
+     *  · FAIL-CLOSED: a throwing/rejecting lookup counts as "not exempt" (the write asks as before) —
+     *    an exemption-store outage must never widen the gate.
+     *  · Cannot override a DENY: this factory never denies; a sensitive-path deny composed alongside via
+     *    `combinePolicies` outranks this `allow` under the deny > ask > allow fold, and the two fail-closed
+     *    asks for an UNRESOLVABLE target fire before any canonical key exists, so they are never exempted.
+     */
     isExempt?: (toolName: string, canonicalPath: string) => boolean | Promise<boolean>;
 }
+/**
+ * Build the file-write approval gate policy. Mount via `combinePolicies` alongside the deployment's
+ * other layers (sensitive-path deny, session rules, caller policy) — see the module header for the
+ * layering contract. Idempotent + side-effect free per {@link combinePolicies}'s requirement.
+ */
 export declare function createFsWriteGatePolicy(opts: FsWriteGatePolicyOptions): ToolPolicy;

package/dist/core/git-worktree-env.d.ts

@@ -1,17 +1,48 @@
 import type { ExecutionEnv } from "../internal/harness-types.js";
+/** Private parent dir (under the repo root) that holds all managed worktrees, so {@link pruneWorktrees} and a
+ *  userland reaper can find orphans by a single known location. */
 export declare const WORKTREE_PARENT = ".sema-worktrees";
 export interface AddWorktreeOptions {
+    /** The base repository root — where `git worktree add` runs (the base env's cwd is typically this). */
     repoRoot: string;
+    /** Stable per-task identity, sanitized into the worktree dir name (for human-readable orphan diagnosis). */
     sessionId: string;
+    /**
+     * How to build a worktree-ROOTED {@link ExecutionEnv} for THIS env type — the only env-specific bit. Local:
+     * `(dir) => new NodeExecutionEnv({ cwd: dir })`. A single-E2B deployment: an E2B env whose cwd is `dir`. The
+     * returned env's fs/shell must operate relative to `dir`, so the agent's hands AND exec are confined there.
+     */
     rootEnvAt: (worktreeDir: string) => ExecutionEnv | Promise<ExecutionEnv>;
+    /** Base commit/ref for the worktree (default `HEAD` at creation time). */
     commit?: string;
 }
+/**
+ * design/97 CORE-6 — the env-agnostic git-WORKTREE isolation primitive. Creates a detached worktree under
+ * {@link WORKTREE_PARENT} in `repoRoot` (via the BASE env's shell) and returns a worktree-ROOTED ExecutionEnv
+ * (built by `rootEnvAt`) whose `destroy()` removes the worktree. A control-plane `executionEnvFactory` calls this
+ * when its `ctx.isolation === "worktree"` and returns the result (with `destroy`); for a non-isolated task it
+ * returns the SHARED base env (no `destroy`) so the Runner never tears the base down.
+ *
+ * ISOLATE-ONLY (clay): the runtime never merges — the orchestrator script reads each worktree's result and
+ * decides verify/merge in userland. Caveats (codex review): `git worktree` isolates the git WORKING COPY, not
+ * arbitrary shell access (bash can still reach the host — sandbox separately); UNCOMMITTED changes in the base
+ * repo are absent in the child (detached HEAD); a worktree orphaned by a process crash is reaped by
+ * {@link pruneWorktrees} (userland — there is no Runner hook for post-kill cleanup).
+ */
 export declare function addWorktree(baseEnv: ExecutionEnv, opts: AddWorktreeOptions): Promise<{
     env: ExecutionEnv & {
         destroy(): Promise<void>;
     };
     worktreeDir: string;
 }>;
+/** Reap orphaned worktrees (after a crash removed their dirs) — `git worktree prune` deregisters them. A userland
+ *  reaper calls this periodically against the base repo; core ships no post-kill Runner hook.
+ *
+ *  HRD-PTL-11: the exec Result used to be discarded, so every caller had to ASSUME the prune landed — and
+ *  ExitWorktree's "already gone externally" leg told the model "stale git worktree metadata was pruned"
+ *  on a claim it could not have checked. Same fail-loud treatment {@link removeWorktree} already got
+ *  (server [1796]②): report the outcome, let the caller decide what to say. Never throws (a throwing env
+ *  lands on the same `{ok:false}`), so a caller that ignores the value behaves exactly as before. */
 export declare function pruneWorktrees(baseEnv: ExecutionEnv, repoRoot: string): Promise<{
     ok: true;
 } | {

package/dist/core/governance-codes.d.ts

@@ -1,4 +1,10 @@
+/** Retry class of a governance code: `transient` = a later retry can self-heal (control-plane
+ *  absence/outage); `terminal` = policy adjudicated, re-issuing changes nothing. */
 export type GovernanceRetryClass = "transient" | "terminal";
+/**
+ * The closed governance-code registry. tsc forces every entry to a valid class; the gate test
+ * forces the naming convention and pack-family completeness. Adding a code = one deliberate row.
+ */
 export declare const GOVERNANCE_CODES: {
     readonly "usage.window_exhausted": "terminal";
     readonly "memory.admission_required": "transient";
@@ -8,5 +14,18 @@ export declare const GOVERNANCE_CODES: {
     readonly "config.locked_key": "terminal";
 };
 export type GovernanceCode = keyof typeof GOVERNANCE_CODES;
+/**
+ * `memory.*` error codes DELIBERATELY outside governance: write-gate and engine incident codes
+ * (secret detection, promotable-gate refusals, announce/partition incidents, tail truncation) —
+ * mechanical faults and content-safety refusals, not per-principal policy verdicts; they classify
+ * as `logic`. The gate test forces every `memory.*` literal minted in src/ to appear EITHER in
+ * {@link GOVERNANCE_CODES} or here — a new code gets NAMED and dispositioned, never silently
+ * classified.
+ */
 export declare const NON_GOVERNANCE_MEMORY_CODES: ReadonlySet<string>;
+/**
+ * Look up a code's governance retry class. Registered code ⇒ its table class; unregistered
+ * `usage.*` ⇒ `"terminal"` (the prefix family's shipped classification); anything else ⇒
+ * `undefined` (NOT governance — the caller falls through to its ordinary taxonomy).
+ */
 export declare function governanceRetryClass(code: string): GovernanceRetryClass | undefined;