@sema-agent/core 5.19.0 → 5.21.0

package/dist/core/memory-admission.d.ts

@@ -1,9 +1,17 @@
 import type { NormalizedMemorySpec } from "./memory.js";
+/** Where a requested org scope came from — the trust axis of the dual-origin model above. */
 export type MemoryScopeOrigin = "deployment" | "request";
+/** One org scope submitted for admission, with its origin. */
 export interface MemoryScopeRequest {
     scope: string;
     origin: MemoryScopeOrigin;
 }
+/**
+ * The resolver's verdict — exactly two states. `ok: true` carries the FROZEN admitted projection:
+ * `scopes` must be a subset of the requested org scopes (an unrequested grant is a resolver fault ⇒
+ * refused), and `writeScope` is the explicit org write grant (`null` = org write face stays
+ * read-only). `ok: false` refuses the whole prepare.
+ */
 export type MemoryAdmissionVerdict = {
     ok: true;
     scopes: readonly string[];
@@ -12,40 +20,103 @@ export type MemoryAdmissionVerdict = {
     ok: false;
     reason: string;
 };
+/**
+ * The trusted deployment resolver ({@link import("./types.js").RunnerDeps.memoryScopeAdmission}).
+ * Receives ONLY the org-parsed scopes (non-org scopes are not its business), each tagged with its
+ * origin, plus the run's principal. Both async and sync forms are accepted.
+ */
 export type MemoryScopeAdmission = (input: {
     principal: string | undefined;
     requested: ReadonlyArray<MemoryScopeRequest>;
     requestedWriteScope: MemoryScopeRequest | null;
 }) => MemoryAdmissionVerdict | Promise<MemoryAdmissionVerdict>;
+/** Inputs to {@link admitMemoryScopes} — assembled by the prepare path (prepare-memory.ts). */
 export interface MemoryAdmissionInput {
     memorySpec: NormalizedMemorySpec;
     principal: string | undefined;
     admission: MemoryScopeAdmission | undefined;
+    /** The deployment's self-certified org scopes (`RunnerDeps.deploymentMemoryScopes`). */
     deploymentScopes: ReadonlySet<string>;
+    /** Compliance capability `org_memory_mount` denied for this principal (the veto covers the
+     *  REQUEST-origin plane — deployment-origin scopes are the operator's own declaration). */
     orgMemoryDenied: boolean;
+    /** True when the denial above came from a compliance-resolver fault (transient code family). */
     complianceDegraded: boolean;
+    /** The parent chain's frozen admitted org set; `undefined` on a top-level task. A delegated child
+     *  with an absent/older-shape chain gets the fail-closed empty set from the caller. */
     parentAdmittedOrgScopes: readonly string[] | undefined;
+    /** The SESSION freeze (resume legs): this session's own verdict at suspend. `undefined` = no
+     *  prior adjudication. Constrains the FINAL admitted projection regardless of origin — a
+     *  request-origin scope outside it refuses the prepare; a deployment-origin scope outside it is
+     *  dropped and disclosed; a write grant absent from it collapses to read-only. */
     priorOwnVerdict: OwnOrgAdmissionVerdict | undefined;
+    /** The monotonic governance-provenance bit (adversarial round 5): true when this leg's TREE is
+     *  org-governed — the deployment surface is configured here, or ANY ancestor/prior leg recorded
+     *  the bit (`InheritedGate.orgAdmissionGoverned`, persisted on checkpoints). Counts as governance
+     *  evidence even when every admitted set en route is EMPTY: a governed parent's org-less child,
+     *  resumed on a surface-less worker, must still refuse org-shaped non-v2 scopes. Trees that never
+     *  had a governance surface never mint the bit and keep the opaque posture. */
     governedProvenance: boolean;
 }
+/** The admission outcome the prepare path applies to the memory spec before materialization. */
 export interface MemoryAdmissionOutcome {
+    /** The spec's read layering with any resolver-dropped DEPLOYMENT-origin org scopes removed. */
     scopes: string[];
+    /** The effective write face (org write not explicitly granted ⇒ narrowed to `null`). */
     writeScope: string | null;
+    /** The frozen verdict for the child chain: every org scope this task actually mounts. */
     admittedOrgScopes: string[];
+    /** Deployment-origin org scopes narrowed away (by a present resolver, or by the session freeze) —
+     *  disclosed, never silent. */
     droppedDeploymentScopes: string[];
+    /** True when an org writeScope was narrowed to read-only (disclosed by the caller). */
     writeScopeNarrowed: boolean;
+    /** The session's own frozen verdict to PERSIST at suspend — present iff this leg ADJUDICATED an
+     *  org plane (the spec requested org scopes), including the adjudicated-empty case. `undefined`
+     *  for an org-less task (nothing to freeze). */
     ownVerdict: OwnOrgAdmissionVerdict | undefined;
 }
+/**
+ * Fold the delegation-chain FREEZE a prepare leg runs under (adversarial-review adoption,
+ * 2026-08-05). For a DELEGATED leg an undefined chain verdict reads fail-closed as the EMPTY set
+ * (an older-shape chain must never read as "unconstrained"); a top-level leg simply has no chain
+ * constraint. The SESSION freeze (the leg's own suspend-time verdict) is a separate input to
+ * {@link admitMemoryScopes} (`priorOwnVerdict`) — it must constrain the FINAL admitted projection
+ * regardless of origin (deployment-origin scopes bypass the chain freeze, not the session freeze),
+ * so it cannot ride this chain-side fold.
+ */
 export declare function foldAdmissionFreeze(input: {
     delegated: boolean;
     inherited: readonly string[] | undefined;
 }): readonly string[] | undefined;
+/**
+ * The session's OWN frozen org verdict: what THIS session actually mounted (and what write grant it
+ * held) at its last suspend. Persisted on the checkpoint (ownAdmittedOrgScopes /
+ * ownAdmittedOrgWriteScope) — including an ADJUDICATED-EMPTY `scopes: []` (a session whose whole org
+ * request was narrowed away must not read as "org-less" on resume). `writeScope: null` = the org
+ * write face was read-only.
+ */
 export interface OwnOrgAdmissionVerdict {
     scopes: readonly string[];
     writeScope: string | null;
 }
+/**
+ * #22 — read a durable background-agent row's recorded org verdict (module header, cross-process
+ * arm). TOTAL by construction: it answers a verdict for every row, so no caller ever has an
+ * "unknown" to fold. An absent field is the ZERO verdict (`{scopes: [], writeScope: null}`), never
+ * `undefined` — `undefined` is this module's spelling of "no prior adjudication constrains this
+ * leg", and handing that to a leg whose original verdict cannot be proven is precisely the
+ * widening the record exists to prevent. Structural parameter (not the record type) so the record
+ * schema keeps its single owner and this module stays free of a store import.
+ */
 export declare function readDurableOrgAdmission(row: {
     admittedOrgScopes?: readonly string[];
     admittedOrgWriteScope?: string | null;
 }): OwnOrgAdmissionVerdict;
+/**
+ * Adjudicate the org scopes of a task's normalized memory spec. Returns the outcome to apply, or
+ * throws a coded refusal (`memory.admission_required` — transient control-plane absence/fault;
+ * `memory.admission_denied` — terminal policy refusal; `config.compliance_denied`/`_required` — the
+ * compliance veto). A spec with no org scopes passes through untouched (zero cost, zero change).
+ */
 export declare function admitMemoryScopes(input: MemoryAdmissionInput): Promise<MemoryAdmissionOutcome>;

package/dist/core/memory-engine/content-origin.d.ts

@@ -1,27 +1,91 @@
+/**
+ * design/178 §3 — the tool content-origin classification (three tiers by CAPABILITY, fail-closed).
+ *
+ * The question this face answers per mounted tool: can invoking it bring content from OUTSIDE the
+ * deployment's trust boundary into the session — and therefore, via the automatic harvest path,
+ * into long-term memory? Three tiers:
+ *
+ *  - "external"  — network-retrieval families and external protocol channels. Invocation marks the
+ *                  session's memory POLLUTED (one-way, durable; the polluted harvest quarantines).
+ *  - "execution" — general execution (shell/exec). A NAMED residual channel: it can reach external
+ *                  content indirectly, but the two industry anchors this tier is calibrated against
+ *                  gate on network/protocol families only, and excluding every shell session would
+ *                  disable memory for the main coding scenario. Not polluting by default; the
+ *                  `execIsExternalContent` strict knob upgrades it to external.
+ *  - "local"     — purely local reads/computation.
+ *
+ * WHO CLASSIFIES (single-source rule): core built-ins declare `contentOrigin` on their own ToolSpec
+ * (the classification lives with the tool definition); protocol tools (MCP/A2A) are structurally
+ * external (the channel itself crosses the boundary); a HOST tool declares its own — and when it
+ * does not, the default is EXTERNAL (fail-closed: unknown = external), overridable only through the
+ * explicit `TaskSpec.memory.trustedTools` allowlist. A core-mounted built-in without a declaration
+ * defaults local: core owns those definitions, and the fail-closed default exists for tools core
+ * CANNOT vouch for, not for its own.
+ *
+ * There is deliberately no "gate inactive" state: every mounted tool gets a class.
+ */
 import type { ToolContentOrigin } from "../types.js";
 export interface ClassifyToolContentOriginInput {
+    /** The tool's own `contentOrigin` declaration (ToolSpec/AgentTool carry) — wins when present. */
     declared?: ToolContentOrigin;
+    /** True ⇔ the name belongs to a protocol namespace (mcp__/a2a__ …) — an external channel. */
     isProtocolTool: boolean;
+    /** True ⇔ the tool came from the caller/host surface (`TaskSpec.tools`), not a core mount. */
     isCallerTool: boolean;
+    /** True ⇔ `TaskSpec.memory.trustedTools` names this tool (explicit host exemption). */
     trusted: boolean;
 }
 export declare function classifyToolContentOrigin(input: ClassifyToolContentOriginInput): ToolContentOrigin;
+/**
+ * Declare `origin` on a tool object built OUTSIDE `defineTool` — a raw AgentTool literal, which is
+ * how core's protocol-facing tools are constructed. The axis rides the tool object untyped, exactly
+ * as `defineTool` spreads it, and this function is the ONE place that cast lives; the classifier
+ * reads the same property either way, so the "classification lives with the tool definition" rule
+ * holds for both construction styles.
+ */
 export declare function withContentOrigin<T extends object>(tool: T, origin: ToolContentOrigin): T;
+/** One offered agent type's tool narrowing, as the delegation tool declares it. */
 export interface AgentToolFace {
     name: string;
     allowTools?: readonly string[];
     denyTools?: readonly string[];
+    /** True ⇔ a child of this type is itself handed a delegation tool (the depth budget permits another
+     *  level and this face does not exclude the delegation tool). Such a child can reach any SIBLING
+     *  face, so its own narrowing is not the boundary — see {@link delegationCallIsExternal}. */
     canRedelegate?: boolean;
 }
+/** One tool in the pool a delegated child draws from — enough to classify it, nothing more. */
 export interface AgentPoolTool {
     name: string;
     aliases?: readonly string[];
     contentOrigin?: ToolContentOrigin;
 }
+/**
+ * design/178 §3 (ruled 2026-08-08) — classify ONE delegation call by the child's tool face.
+ *
+ * A child that can reach a network or protocol tool returns content from outside the trust boundary
+ * just as surely as calling that tool in this session would, and the parent's transcript is where it
+ * lands. The judgment is STATIC — the child's face is known from its definition before the call — so
+ * nothing here tracks what the child actually did (runtime provenance is the v2 ticket). That makes
+ * it conservative in the safe direction: a child that COULD reach external content counts as having
+ * done so.
+ *
+ * `pool` is the CHILD'S pool, not the parent's roster: a delegation tool carries its own tool set, and
+ * the two are explicitly allowed to differ — a parent mounting nothing but the delegation tool can
+ * hand its children a network tool. Comparing against the parent's roster would call that local.
+ *
+ * FAIL-CLOSED on ignorance: an unnamed type, a type the delegation tool does not offer, a tool that
+ * declares no faces, or a pool that cannot be enumerated statically (a spawn-time tool factory) is
+ * EXTERNAL. "We could not tell" and "it is safe" are different answers.
+ */
 export declare function delegationCallIsExternal(input: {
     requestedType: string | undefined;
     faces: ReadonlyArray<AgentToolFace> | undefined;
+    /** Undefined ⇔ the child's pool is not statically knowable ⇒ fail closed. */
     pool: ReadonlyArray<AgentPoolTool> | undefined;
+    /** Whether one pool tool carries a polluting class — the caller owns the deployment's config. */
     isPolluting: (tool: AgentPoolTool) => boolean;
 }): boolean;
+/** Whether a tool of `origin` pollutes the session's memory when invoked (strict = the
+ *  `execIsExternalContent` upgrade). */
 export declare function contentOriginPollutes(origin: ToolContentOrigin, strict: boolean): boolean;

package/dist/core/memory-engine/data-plane.d.ts

@@ -1,14 +1,23 @@
 import type { HarvestRejection, MemoryBackend, MemoryEntry, NotePatch, PatchReport, ScanFinding } from "./types.js";
+/** Default per-file byte cap — SAME value as the host engine's MAX_MEMORY_BYTES (独立轨 F3: a 60KB
+ *  entry legal on the host must not be re-rejected every remote round; one cap, one truth). */
 export declare const REMOTE_HARVEST_PER_FILE_BYTES: number;
+/** Missing-file ratio above which the harvest refuses wholesale (engine MASS_DELETION_FUSE_RATIO). */
 export declare const REMOTE_MASS_DELETION_FUSE_RATIO = 0.5;
+/** File-count cap per harvest (host DEFAULT_MAX_MEMORY_FILES parity — codex H10). */
 export declare const REMOTE_HARVEST_MAX_FILES = 500;
+/** Max DIRECTORY nesting depth below the memory root (host DEFAULT_MAX_ENTRY_DEPTH parity — the
+ *  host's `scanEntryFiles` walks a subdir only while `depth + 1 <= maxDepth`, so it counts directory
+ *  levels, NOT path segments: `a/b/c/note.md` (3 dirs) is accepted, `a/b/c/d/note.md` refused). */
 export declare const REMOTE_HARVEST_MAX_DEPTH = 3;
 export interface RemoteMemoryFile {
+    /** Path RELATIVE to the sandbox memory root, `/`-separated (e.g. `pref-editor.md`, `org-acme/x.md`). */
     relPath: string;
     content: string;
 }
 export interface RemoteMemoryBaseline {
     writeScope: string | null;
+    /** Every file materialized into the sandbox, with its commit-time identity (the CAS base). */
     files: Array<{
         relPath: string;
         id: string;
@@ -16,29 +25,53 @@ export interface RemoteMemoryBaseline {
         scope: string;
         readonly: boolean;
     }>;
+    /** Directory names of ALL read-only layers — including ZERO-entry ones (复审 D2): the harvest's
+     *  containment prefixes are otherwise inferred from `files`, so an empty inherited layer would be
+     *  invisible and a planted `<dir>/new.md` would slip in as a writeScope add. Optional (additive):
+     *  a baseline serialized before this field keeps the files-inferred prefixes only. */
     readonlyDirs?: string[];
 }
 export interface RemoteMaterialization {
+    /** Ship these into the sandbox memory root (the deployment owns the transport + any chmod). */
     files: Array<RemoteMemoryFile & {
         readonly: boolean;
     }>;
+    /** Keep this (serializable) and pass it to {@link harvestFilesToPatches} at harvest time. */
     baseline: RemoteMemoryBaseline;
 }
+/**
+ * Project backend entries into a shippable file list. Layout mirrors the host engine: the
+ * writeScope's entries sit at the memory root, every other scope under `<scopeDirName>/`
+ * (read-only inherited layers). Excluded: budget stubs (a remote v1 materializes full bodies only)
+ * and the derived MEMORY.md index (the deployment may render its own).
+ */
 export declare function materializeEntriesToFiles(backend: MemoryBackend, scopes: readonly string[], writeScope: string | null): Promise<RemoteMaterialization>;
 export interface RemoteHarvestResult {
+    /** Feed to `backend.applyPatches` (the deployment owns the call + the resulting PatchReport). */
     patches: NotePatch[];
     rejections: HarvestRejection[];
+    /** Baseline files absent from the read-back set (info; NEVER a delete — tombstones only). */
     missing: string[];
+    /** Set instead of patches when the mass-deletion fuse trips (deployment surfaces it, human call). */
     incident?: {
         kind: "mass_deletion";
         detail: string;
     };
+    /** Canonical projections (minted ids / completed frontmatter) the deployment SHOULD write back into
+     *  the sandbox after the backend commit succeeds, keyed by relPath — same promotion discipline as
+     *  the host engine (project only what applied; see {@link projectionsToWriteBack}). */
     projections: Array<{
         relPath: string;
         entry: MemoryEntry;
         content: string;
     }>;
 }
+/**
+ * The pure gate+diff core over files read back from a remote sandbox. Same judgment order as the
+ * host engine's harvest: readonly-layer tamper → rejection (restore is the deployment's I/O);
+ * missing + fuse; per-file size cap → scan rule set (secret/injection/filename) → parse →
+ * id-immutability (baseline id wins) → tombstone-only delete → CAS update / rename / add.
+ */
 export declare function harvestFilesToPatches(baseline: RemoteMemoryBaseline, files: readonly RemoteMemoryFile[], opts?: {
     perFileBytes?: number;
     massDeletionFuseRatio?: number;
@@ -46,6 +79,8 @@ export declare function harvestFilesToPatches(baseline: RemoteMemoryBaseline, fi
     maxDepth?: number;
     now?: () => number;
 }): RemoteHarvestResult;
+/** After `backend.applyPatches(result.patches)`, the projections worth writing back into the sandbox:
+ *  only those whose (id, non-delete op) actually APPLIED — the host engine's promotion discipline. */
 export declare function projectionsToWriteBack(result: RemoteHarvestResult, report: PatchReport): Array<{
     relPath: string;
     content: string;
@@ -54,6 +89,14 @@ export interface InboundEntryFinding {
     id: string;
     findings: ScanFinding[];
 }
+/**
+ * design/142 §3③ — the central-side inbound gate as a PURE function. A sync channel is a write path
+ * that bypasses the harvest gate by construction (same class as git pull, §2.7): before entries from
+ * another plane touch an authority disk, screen body + slug + size with the SAME rule set the
+ * harvest gate runs. Gate logic single-sourced in core; the execution seat rides the data plane
+ * (service calls this in its write face). Returns findings per OFFENDING entry only — empty array =
+ * the batch is clean.
+ */
 export declare function screenInboundEntries(entries: readonly MemoryEntry[], opts?: {
     perFileBytes?: number;
 }): InboundEntryFinding[];

package/dist/core/memory-engine/dual-root.d.ts

@@ -1,15 +1,39 @@
 import type { ParsedScopeKey } from "./scope-contract.js";
 import type { HarvestReport } from "./types.js";
 import type { MemoryInjection } from "./engine.js";
+/** The personal plane's shared mount under the config root (ALL projects, one home — the plane is
+ *  keyed by scope, not by repo: `user:alice` is the same disk from every checkout). */
 export declare function derivePersonalMemoryDir(configRoot: string): string;
 export declare function derivePersonalControlDir(configRoot: string): string;
 export interface ScopePlanes {
+    /** proj:/legacy scopes — the repo/path-keyed plane (order preserved). */
     project: string[];
+    /** user:/userproj:/org: scopes — the home-mount plane (order preserved). codex 复审 B1: `org` is
+     *  CENTRAL-authority (§2 表), so it routes with the personal keys — under a pinned in-repo File
+     *  backend an org layer projected into the repo would leak tenant-shared memory into commit
+     *  history. The mount is still the "personal" directory (one home plane; the plane is about
+     *  WHERE-NOT-to-project, not about ownership — org's authority disk is the central DB anyway). */
     personal: string[];
+    /** Which plane owns the write face (null = read-only layering everywhere). */
     writePlane: "project" | "personal" | null;
 }
+/** Classify a v2 session's scopes into planes. writeScope routes by its OWN key kind (it need not
+ *  be listed in scopes — normalizeMemorySpec contract). */
 export declare function classifyScopePlanes(scopes: readonly string[], writeScope: string | null): ScopePlanes;
+/** True when the classified session needs the dual-root assembly at all. */
 export declare function needsDualRoots(planes: ScopePlanes): boolean;
+/** Convenience for the placement gate: the parsed keys that stay on the PROJECT plane. */
 export declare function parsedProjectPlane(planes: ScopePlanes, writeScope: string | null): ParsedScopeKey[];
+/**
+ * Merge the two planes' injections into ONE block. Plane order is fixed: PROJECT first (the stable
+ * prefix — repo knowledge changes less often than personal notes), PERSONAL second; the instruction
+ * (trusted half, "where to write") comes from whichever plane owns the write face and leads the
+ * block, exactly like the single-root layout. v1 deliberately merges at BLOCK granularity — scope
+ * interleaving across planes is not reproduced (documented; the within-plane order is untouched).
+ */
 export declare function mergeInjections(project: MemoryInjection | undefined, personal: MemoryInjection | undefined): MemoryInjection;
+/** Merge the two planes' harvest reports into the single report the runner surfaces. Counters add,
+ *  lists concatenate, `ok` ANDs, the first incident wins the seat (both are still visible via the
+ *  merged lists). 独立轨 F7: pass the WRITE plane's report as `a` — first-argument fields (incident
+ *  seat, degraded seat) prefer `a`, and the write plane's degradation is the one that matters. */
 export declare function mergeHarvestReports(a: HarvestReport, b: HarvestReport): HarvestReport;