@sema-agent/core 5.65.0 → 6.0.0

package/dist/core/runner/prepare-task.d.ts

@@ -2,6 +2,7 @@ import { AgentHarness, type ThinkingLevel } from "../../internal/harness.js";
 import type { Model } from "../../internal/llm.js";
 import { type CompactionForkContext } from "../auto-compaction.js";
 import { type AutoModeDecider } from "../auto-mode.js";
+import { type AutoModeArmingRecipe } from "../auto-mode-arming.js";
 import { type MaterializedMcp } from "../mcp.js";
 import { type MaterializedA2a } from "../a2a.js";
 import type { HarvestReport, MemorySessionHandle } from "../memory-engine/types.js";
@@ -17,6 +18,7 @@ import { CacheBreakDetector, type ToolFingerprintInput } from "../cache-break-de
 import { type BrainCallGuardrailRef } from "../../brain/timeout.js";
 import { type OutputRef, type BlockedRef, type SkillListingEntry } from "./synthetic-tools.js";
 import type { MemoryEngine } from "../memory-engine/engine.js";
+import { type SessionReadFileStates } from "./prepare-hands-readface.js";
 import { type GitStatusLaneRef } from "./git-status-frame.js";
 import { type ToolManifestRow } from "../../prompt-assembly/tool-catalog.js";
 import type { ToolDisclosureManifest } from "../trace.js";
@@ -190,6 +192,20 @@ export type GuardChainOutcome = {
  * verbatim (arm-B adoption / the r8 dead-turn stand-down).
  */
 export declare function runGuardChain(args: GuardChainArgs): Promise<GuardChainOutcome>;
+/**
+ * design/381 — the run's turn-start file-history BOUNDARY seat. `begin(entryId)` starts the capture
+ * for the turn's own initial entry (first-wins: exactly one boundary per turn incarnation, DV-4);
+ * `settle()` awaits the in-flight capture's settle and is the caller's LEASE CLOSE (awaited before
+ * the first tool executes) as well as the finish-tail durability await. The capture is bounded by a
+ * 30s timeout whose abort FENCES the attempt (the store's `boundaryPublishVerdict` guarantees a
+ * timed-out capture never publishes); failure is disclosed via onError(phase:"rewind") and NEVER
+ * blocks the turn — a turn whose capture failed simply has no boundary (the reference behaves the
+ * same), and there is no mid-turn re-capture (the store's spent lease refuses it with zero reads).
+ */
+export interface FileHistoryBoundarySeat {
+    begin(entryId: string): void;
+    settle(): Promise<void>;
+}
 export interface Prepared {
     harness: AgentHarness;
     /** The CONCRETE built-in session (engine-internal: prepare constructs/acquires `StoredSession` itself,
@@ -197,6 +213,26 @@ export interface Prepared {
      *  the `Session` contract instead. */
     session: StoredSession;
     sessionId: string;
+    /**
+     * #499 — THIS INVOCATION's own identity, minted once at the top of {@link prepareTask} and never
+     * rewritten. The third id of the trio, and the only one the engine owns outright:
+     *  - `spec.taskId` — the HOST's task identity (absent whenever the host names nothing);
+     *  - `sessionId`   — the CONVERSATION's identity (shared by every run that continues it);
+     *  - `runId`       — THIS call of the engine.
+     *
+     * The gap it closes: the repo-wide `spec.taskId ?? sessionId` spelling answers the same value for
+     * two runs of one session whenever the host supplies no task id, so every per-run account keyed on
+     * it FOLDED two runs into one row (two runs each losing one steer read as one run losing one).
+     * A per-run account must key on this; a per-TASK fact (trace `taskId`, the host's own correlation
+     * handle) must keep the task spelling — the two are different questions and the station sweep
+     * judged each one.
+     *
+     * Minted here (never at the Runner's stream entry) so that a standalone `prepareTask` exercise gets
+     * a real id too, and so the mint has exactly one site. A leg whose prepare THROWS never returns a
+     * `Prepared` at all — but the id still reaches its caller through the `runIdSink` carrier, because
+     * prepare emits run-scoped disclosures of its own and each must have a terminal that names it.
+     */
+    runId: string;
     /** design/319 (A ticket) — the session's reminder provenance mark this run mints under (adopted
      *  through the prepare adoption ladder: checkpoint seed → trusted fork channel → session entry →
      *  fresh mint). Every engine-authored `<system-reminder>` open tag in the run carries it, and the
@@ -276,6 +312,10 @@ export interface Prepared {
     /** RB-430-a: prepare-time rewind disclosures (conversation-only branch / no snapshot backend / no file
      *  env), echoed verbatim onto `TaskResult.rewindNotes`. Present only when there is something to say. */
     rewindNotes?: NonNullable<TaskResult["rewindNotes"]>;
+    /** design/381 — the run's turn-start boundary seat (present iff a fileHistoryStore is wired and
+     *  the run mounts a real fs env). runtask calls begin() at the first committed user entry and
+     *  awaits settle() at the lease close + the finish tail. */
+    fileHistoryBoundary?: FileHistoryBoundarySeat;
     /** #240 (design/199 v1.1) + #242 — the run's RESOLVED read face for the result observation seat
      *  (`TaskResult.effectiveReadFace`): `carrierReadFace()`'s value at prepare completion — the hands
      *  block's single resolution, or the hands-less legs' resolver run (live spec-time facts, with the
@@ -308,6 +348,12 @@ export interface Prepared {
         restoredWorktreeDir?: string;
         baselineUnknown?: boolean;
     };
+    /** #483 codex r2+r3 — the settle-time session-seat SEAL (see prepare-hands-readface): re-anchors
+     *  the per-session read-state seat to the entry id THIS run last committed (its own
+     *  message_committed tail — provenance, never a shared-leaf re-read). The driver calls it once at
+     *  the run's settle, every terminal (suspend included), under the session lock; undefined argument
+     *  (no commits) is a no-op. Synchronous, never throws. Absent ⇔ hands-less / no seat channel. */
+    sealReadStateSeat?: (ownCommittedTailEntryId: string | undefined) => void;
     /** design/99 §E6 — the DENY-NARROWING layers (session rules + skill scope, deny-only). Re-checked on RESUME
      *  before an approved pending tool executes, so a rule tightened during the suspend still applies. */
     denyNarrowingPolicy?: ToolPolicy;
@@ -491,6 +537,25 @@ export interface Prepared {
         /** Merged injection across all planes (single-root sessions: identical to engine.inject(handle)). */
         inject: () => import("../memory-engine/engine.js").MemoryInjection;
         harvest: (phase?: "checkpoint" | "terminal") => Promise<HarvestReport | undefined>;
+        /**
+         * design/383 §2.1 — the session's capture opt-out face (the `TaskStream.optOutMemoryCapture`
+         * verb's target; host-API only — no tool face reads it, §2.6). `flip` re-adjudicates the
+         * entitlement at call time (fresh caps resolve), mints the one-way record, runs the §2.3
+         * boundary sweep, and delivers the effectiveness notice; its typed refusals are the
+         * `memory.capture_optout_*` family. `optedOut` is the live state read (declared / standing /
+         * flipped) — a GENUINE-record read: a store fault answers false here and TRUE on
+         * `indeterminate` instead (rescan post-6.0.0-RC — the fault must reach the delegation floor
+         * as its own third state, never as either boolean; an irreversible record is never minted off
+         * an unreadable state, and an outage must not spawn un-floored children). Present whenever
+         * the memory session mounted.
+         */
+        captureOptOut?: {
+            optedOut: () => boolean;
+            indeterminate: () => boolean;
+            flip: (reason?: string) => Promise<{
+                outcome: "created" | "existed";
+            }>;
+        };
         /**
          * design/178 §3 — the session's ONE-WAY pollution face. `markPolluted` fires when an
          * external-content-class tool is invoked (the prepare-time tool wrap below is the caller);
@@ -803,6 +868,22 @@ export interface Prepared {
         path: string;
         contentHash: string | null;
     }>;
+    /** #500 — the RAW instruction-file text this leg's `loadProjectMemory` returned
+     *  (`ProjectMemoryLoad.content`), for the compaction lanes' `contextInstructionFiles` seat.
+     *
+     *  Which bytes, exactly: the string prepare-task hands `composeMemoryBlock(projectMem, "project")`
+     *  — pre-compose, unfenced, straight from the host seam. The two neighbours are deliberately NOT
+     *  candidates: the assembled `memoryBlock` carries the memory ENGINE's layers (bytes the model
+     *  itself authored in-band this session through the memory tools) and the seat's contract is
+     *  host/systemPrompt tier; the COMPOSED project block would arrive at a mint that neutralizes the
+     *  whole authority family, `user_memory`/`scope` included, so the engine would rewrite the tags of
+     *  its own composition. Raw text in, one fence at the mint.
+     *
+     *  Present only when the deployment wired the loader AND it answered non-blank — the same
+     *  predicate that composes the project layer, so the summarizer's copy and the main prompt's copy
+     *  can never disagree about whether this deployment HAS instruction files. Absent ⇒ every
+     *  compaction lane omits the key entirely. */
+    projectInstructionContent?: string;
     /** The `workflow_size_guideline_change` lane's seam, the {@link dateChange} shape one lane over:
      *  `legGuideline` = the RESOLVED guideline this leg's Workflow tool card was built with (the card is
      *  a per-mount snapshot, so it never re-renders mid-leg — the model learns a retune from the tail
@@ -1165,6 +1246,16 @@ export interface InheritedGate {
          */
         autoMode?: {
             decider: AutoModeDecider;
+            /**
+             * #503 — the SERIALIZABLE criteria half of this classifier (assembly inputs + knobs + the
+             * deployment's settings epoch), present when the arming deployment opted in
+             * (`RunnerDeps.autoMode.persistArming`). A durable park records it on the chain entry so a
+             * CROSS-PROCESS redemption can rebuild an equivalent decider over its own model leg instead of
+             * answering `unavailable` forever; the constraint-chain digest binds it, so a resume re-supplies
+             * exactly what the row carries. It never affects THIS process's decisions — the live `decider` is
+             * the one every gate consults, here and on every descendant.
+             */
+            arming?: AutoModeArmingRecipe;
         };
         /**
          * Set ONLY on an entry whose `policy` is the folded form of an ancestor's PreToolUse screening face
@@ -1469,6 +1560,41 @@ export interface RunInternals {
     /** design/147 S2a — the spawning run's sessionId (paired with parentTaskId; see
      *  ToolExecuteContext.parentSessionId). */
     parentSessionId?: string;
+    /**
+     * design/383 §2.5 — the memory-capture opt-out FLOOR: TRUE ⇔ the spawning session was under an
+     * opt-out when this child spawned. The child then runs opted-out itself (its prepare mints its
+     * own one-way record, reason naming the floor) — NOT re-adjudicated against the child's
+     * entitlement (the floor is the parent's already-granted opt-out tightening the tree; a
+     * re-adjudication that could answer "no" would be a loosening door). Trusted internals channel
+     * on purpose (the parentInteractionPosture law): never a child-spec field, so no chosen
+     * AgentDefinition and no spec surgery can shed it; rides `internalsSnapshot`, so retained
+     * revivals keep it. Grandchildren inherit through each generation's own live seat (an opted-out
+     * child forwards TRUE to its children in turn — monotone by construction).
+     */
+    memoryCaptureFloor?: true;
+    /**
+     * design/383 §2.5 (rescan post-6.0.0-RC) — the floor's THIRD state: the spawning session's
+     * capture state was INDETERMINATE at spawn (its record store faulted at the getter read).
+     * Neither boolean is honest there — no floor runs a possibly-recorded lineage captured, a coined
+     * floor mints an IRREVERSIBLE record off an unreadable state — so the lane carries the fault
+     * itself and the child's prepare resolves it against the live record query (found ⇒ floor;
+     * still faulting ⇒ the child runs indeterminate — mechanical restrictions, no mint; readable
+     * and clean ⇒ clean). Same trusted-channel law as {@link memoryCaptureFloor}; mutually
+     * exclusive with it at the spawn site (the floor wins when the state IS known).
+     */
+    memoryCaptureFloorIndeterminate?: true;
+    /** design/383 §2.5 — the spawning session's write-plane control dir (the coordinate its capture
+     *  opt-out record is keyed under), so a child on a DIFFERENT memory plane can still run the
+     *  record-query leg against the parent's own carrier. Trusted chain, rides internalsSnapshot. */
+    memoryCaptureQueryDir?: string;
+    /** design/383 §2.5 (codex round 3) — the ancestor chain's capture coordinates (root first, one
+     *  row per generation, appended by each spawner's ctx seat). The child's harvest closures walk
+     *  every row, so a mid-run flip ANYWHERE up the tree suppresses every in-flight descendant.
+     *  Trusted chain; rides internalsSnapshot. */
+    memoryCaptureAncestors?: ReadonlyArray<{
+        sessionId: string;
+        controlDir?: string;
+    }>;
     /**
      * The FLEET-task kind of this run, declared by the lane that spawned it and stamped onto every
      * `task_progress` tick the run mints (`TaskEvent`'s `taskType`). A consumer merging progress ticks
@@ -1582,6 +1708,14 @@ export interface RunInternals {
     /** design/116 detach: the run-local per-tool-call detach hub. runtask creates it and exposes
      *  `TaskStream.detach(toolCallId)`; the hands Bash tool threads `signalFor(toolCallId)` into env.exec. */
     detachHub?: import("../tool-detach.js").ToolDetachHub;
+    /**
+     * #483 rung-1 — the Runner's per-session read-file-state seats (CC parity: readFileState is
+     * session-scoped). Always set by the Runner's own prepare call (overriding any caller value, like
+     * the peer refs beside it); absent on a standalone prepareTask, where the transcript-replay rung
+     * covers alone. A CACHE, never an authority — see {@link SessionReadFileStates}. Trusted internals
+     * channel, same posture as every other field here.
+     */
+    sessionReadStates?: SessionReadFileStates;
     onTaskNotification?: (notification: TaskNotificationPayload, 
     /** Injection tier (design/373 — the ladder is LIVE): "next" = the running turn's next boundary
      *  (arrival order, consecutive frames batch); "later" = the run's would-otherwise-stop seat
@@ -1783,4 +1917,10 @@ export declare function prepareTask(spec: TaskSpec, deps: RunnerDeps, sessions:
 /** design/98 §3.1 (S8c): a TRUSTED self-reference to the Runner, passed by the Runner itself (never a
  *  TaskSpec field) so the `run_workflow` tool can execute child tasks via `runner.runTask`. Undefined when
  *  prepareTask is exercised standalone (then run_workflow is simply not mounted). */
-runnerSelf?: Runner): Promise<Prepared>;
+runnerSelf?: Runner, 
+/** #499 — carrier for the id minted below, so a prepare that THROWS still lets its caller name the
+ *  run (prepare emits run-scoped notices of its own; each needs a terminal that names it). Same seat
+ *  shape the Runner uses for the generated taskId/sessionId. */
+runIdSink?: {
+    runId?: string;
+}): Promise<Prepared>;