@sema-agent/core 7.56.0 → 7.57.0

package/dist/core/read-only-shell.js

@@ -1,10 +1,12 @@
 import { posix } from "node:path";
 import { lexedWordOf, readShellCommand } from "./shell-run-candidates.js";
+import { unlistedReaderSentence } from "../tools/fs/bash-readonly-classifier.js";
 import { descriptorsOfPlan, newLineDescriptors, standardDeviceUnrebound } from "../tools/fs/shell-read-device.js";
 import { planShellReads } from "../tools/fs/shell-read-plan.js";
 import { writesOnlyStandardDevices } from "../tools/fs/shell-read-write-targets.js";
 import { FIND_ACTION_PRIMARIES, FIND_NEWER_PRIMARY, FIND_VALUE_PRIMARIES, FLAG_VALUE_ACCEPTS, READ_ONLY_BARE_ONLY, READ_ONLY_BARE_PROGRAMS, READ_ONLY_COMMAND_TABLE, READ_ONLY_ENV_NAMES, READ_ONLY_EXACT_FORMS, READ_ONLY_GLOB_PROGRAMS, XARGS_READ_ONLY_TARGETS, dockerRetargetDanger, } from "./read-only-shell-table.js";
 const NOT = (reason) => ({ readOnly: false, reason });
+const READ_ONLY = { readOnly: true };
 export const CD_GIT_COMPOUND_SENTENCE = "This command changes directory before running a version-control command, which can pick up untrusted hooks or repository configuration from the target directory. Approve only if you trust it.";
 export function changesDirectoryBeforeGit(shape, cwd) {
     const programs = shape.segments.map((s) => peelBuiltinPrefix(s.argv.slice(leadingAssignmentCount(s.argv)).map((w) => w.text))[0] ?? "");
@@ -20,7 +22,6 @@ export function changesDirectoryBeforeGit(shape, cwd) {
     const trim = (p) => p.replace(/\/+$/, "") || "/";
     return trim(posix.resolve(cwd, target.text)) !== trim(cwd);
 }
-const READ_ONLY = { readOnly: true };
 const BARE_PROGRAMS = new Set(READ_ONLY_BARE_PROGRAMS.filter((p) => !p.includes(" ")));
 const BARE_MULTIWORD = READ_ONLY_BARE_PROGRAMS.filter((p) => p.includes(" ")).map((p) => p.split(" "));
 const GLOB_PROGRAMS = new Set(READ_ONLY_GLOB_PROGRAMS);
@@ -41,7 +42,11 @@ const PRINTF_ESCAPE = new RegExp(`%[^%a-zA-Z]*${PRINTF_LENGTH}\\\\[0-7xX]`);
 const PRINTF_NUMERIC = new RegExp(`%[-+ 0#']*[0-9.*]*${PRINTF_LENGTH}[diouxXeEfFgGaAn]`);
 const JQ_DANGER_FLAG = /^['"]?-[a-zA-Z]*[fL]/;
 const JQ_DANGER_TEXT = /--from-file|--rawfile|--slurpfile|--run-tests|--library-path|\benv\b|\$ENV\b|\binclude\b|\bimport\b/;
-export function readOnlyShellVerdict(command, shape = readShellCommand(command), cwd, bound) {
+export function readOnlyShellVerdict(command, opts = {}) {
+    const { cwd, bound, readers } = opts;
+    if (readers !== undefined && typeof readers.has !== "function")
+        throw new TypeError("readOnlyShellVerdict: `readers` must be a Set of program names");
+    const shape = opts.shape ?? readShellCommand(command);
     const line = lineStructureObjection(shape);
     if (line !== undefined)
         return NOT(line);
@@ -66,12 +71,15 @@ export function readOnlyShellVerdict(command, shape = readShellCommand(command),
     let boundOfText;
     const bindings = () => (boundOfText ??= (typeof bound === "function" ? bound() : bound) ?? lineDescriptorsOfText(command));
     for (const seg of shape.segments) {
-        const verdict = segmentVerdict(seg, descriptors, bindings);
+        const verdict = segmentVerdict(seg, descriptors, bindings, readers);
         if (!verdict.readOnly)
             return verdict;
     }
     return READ_ONLY;
 }
+function unlistedObjection(program, readers) {
+    return readers !== undefined && !readers.has(program) ? NOT(unlistedReaderSentence(program)) : undefined;
+}
 const CD_GIT_REASON = "a compound that changes directory and runs git";
 function lineStructureObjection(shape) {
     if (shape.grouped)
@@ -144,16 +152,11 @@ function peelBuiltinPrefix(words) {
                 return t;
             t = t.slice(r);
         }
-        else if (t[0] === "noglob") {
-            if (t.length <= 1)
-                return t;
-            t = t.slice(1);
-        }
         else
             return t;
     }
 }
-function segmentVerdict(seg, line, bindings) {
+function segmentVerdict(seg, line, bindings, readers) {
     for (const r of seg.redirections) {
         const target = r.target.text;
         if (!READING_REDIRECTS.has(r.op) && !standardDeviceUnrebound(target, line, []) && !(r.op === ">&" && /^\d+$/.test(target)))
@@ -174,6 +177,9 @@ function segmentVerdict(seg, line, bindings) {
         return NOT("a bare assignment runs no program");
     const words = peelBuiltinPrefix(run.map((w) => w.text));
     const program = words[0];
+    const unlisted = unlistedObjection(program, readers);
+    if (unlisted !== undefined)
+        return unlisted;
     if (run.some((w) => expansionKind(w) === "glob"))
         return GLOB_PROGRAMS.has(program) ? READ_ONLY : NOT(`\`${program}\` with a glob argument — the glob may name anything`);
     if (DEVICE_WRITERS.has(program) && writesOnlyStandardDevices(program, words.slice(1), bindings()))
@@ -181,7 +187,7 @@ function segmentVerdict(seg, line, bindings) {
     const structural = structuralReading(words);
     if (structural !== null)
         return structural ? READ_ONLY : NOT(`\`${program}\` with these arguments is not a read-only form`);
-    return tableReading(words, run);
+    return tableReading(words, run, readers);
 }
 export function lineDescriptorsOfText(command) {
     return descriptorsOfPlan(planShellReads(command, { readers: new Set(), cwd: "/", roots: [] }));
@@ -248,7 +254,7 @@ function printfReading(words) {
     }
     return true;
 }
-function tableReading(words, run) {
+function tableReading(words, run, readers) {
     const program = words[0];
     const hit = TABLE_ROWS.find((r) => words.length >= r.words.length && r.words.every((w, i) => words[i] === w));
     if (hit !== undefined) {
@@ -259,7 +265,8 @@ function tableReading(words, run) {
             if (a.includes("{") && (a.includes(",") || a.includes("..")))
                 return NOT(`\`${program}\`: a brace pattern argument`);
         }
-        if (!flagWalk(args, hit.row, program))
+        const named = [];
+        if (!flagWalk(args, hit.row, program, named))
             return NOT(`\`${program}\`: an option outside its read-only set (or a malformed option value)`);
         if (hit.row.wordsShape !== undefined ? !hit.row.wordsShape(args) : run.some((w) => w.raw.includes("`")))
             return NOT(`\`${program}\`: arguments outside its read-only form`);
@@ -267,6 +274,11 @@ function tableReading(words, run) {
             return NOT(`\`${program}\`: a line break inside an argument`);
         if (hit.row.dangerous?.(args) === true)
             return NOT(`\`${program}\`: an argument form upstream marks as writing, executing or resolving`);
+        for (const target of named) {
+            const unlisted = unlistedObjection(target, readers);
+            if (unlisted !== undefined)
+                return unlisted;
+        }
         return READ_ONLY;
     }
     if (program === "uniq" && words.slice(1).every((w, i, all) => /^-[a-zA-Z]+$/.test(w) || /^--[a-zA-Z-]+(=\S+)?$/.test(w) || (i > 0 && /^-[fsw]$/.test(all[i - 1]) && /^\d+$/.test(w))))
@@ -296,7 +308,7 @@ function jqReading(args) {
     }
     return true;
 }
-function flagWalk(args, row, program) {
+function flagWalk(args, row, program, named) {
     let i = 0;
     while (i < args.length) {
         let word = args[i];
@@ -309,7 +321,10 @@ function flagWalk(args, row, program) {
                 i++;
                 word = args[i];
             }
-            return XARGS_TARGETS.includes(word);
+            if (!XARGS_TARGETS.includes(word))
+                return false;
+            named.push(word);
+            return true;
         }
         if (word === "--") {
             if (row.respectsDoubleDash !== false)

package/dist/core/remote-env.d.ts

@@ -323,7 +323,7 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
      * `{isolation:true, suspendable:true}` adapter); **partial-capability** adapters (SSH/ADB: `{false, false}`
      * — a real machine/device, not snapshotable and not isolated) declare it here. **Required + explicit** so
      * the orchestrator never has to guess: there is no safe default (assuming isolation when there is none is a
-     * security hole; assuming suspendable crashes on `suspendVM`). Use {@link isSuspendable}/{@link isIsolated}
+     * security hole; assuming suspendable crashes on `suspendVM`). Use {@link isSuspendable}/{@link isIsolated}/{@link processTableOf}
      * rather than the structural {@link isRemoteExecutionEnv} (method presence ≠ semantics — a stub `suspendVM`
      * that returns `"unsupported"` still satisfies the structural check). Extensible: add fields as new
      * partial-capability classes appear.
@@ -355,6 +355,29 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
          *  Read STRICTLY through {@link canonicalPathIsAuthoritative}, like every other capability whose
          *  `true` changes what a containment leg does; a wrong-SHAPE value reads absent and is announced. */
         canonicalPathAuthoritative?: boolean;
+        /** True iff the commands this env runs are processes on a table that holds THIS process — the table the
+         *  engine itself and the processes above it are on, so a kill the model writes there can reach them.
+         *  `true` for an adapter that spawns the commands as this process's own descendants (a host lane), and
+         *  for one whose commands run in a PID namespace that contains this process's (the host of the container
+         *  the engine runs in); `false` only for one whose commands run where this process is not: another
+         *  machine (SSH host, device, cloud sandbox) or a PID namespace this process is not in (a sandbox
+         *  container, a pod). Not {@link isolation}: a non-isolated SSH host is a real machine and still another
+         *  table. The self-preservation guard of the Bash tool asks its question exactly when this is `true`
+         *  (and for every env that is not remote at all), and does not ask where it is `false`.
+         *
+         *  What a `true` buys is the guard's question exactly as a NodeExecutionEnv gets it, limits included: on this
+         *  process's own table, of the platform's `pgrep`, with the kill's words as written, from this process's own
+         *  working directory. It is put as for this process's descendants, so for commands on the same table that
+         *  are not (SSH to `localhost`) BSD's `pgrep` leaves its OWN caller's ancestors out where the real kill would
+         *  not, and from an enclosing namespace the question sees only this process's namespace, not the ancestors
+         *  above it.
+         *
+         *  REQUIRED, with no default: either reading of an absent value is wrong somewhere (assuming `true`
+         *  refuses an ordinary `pkill` in a sandbox because a word matched this engine here; assuming `false`
+         *  lets a host lane's `pkill` end the session that issued it). So an absent or non-boolean value is
+         *  announced once per run at the env's admission point and the guard refuses every pattern kill that needs the question on
+         *  that env (`pkill -P $$` runs), naming this declaration, until the adapter states it. Read through {@link processTableOf}. */
+        sharesProcessTable: boolean;
     };
     /** Identity of the connected workspace (design/48 §5 gap 1). Synchronous: it is data the env already holds. */
     workspaceHandle(): WorkspaceHandle;
@@ -634,3 +657,16 @@ export declare function boundaryIsTheSandbox(env: ExecutionEnv): boolean;
  * has no case to fire on.
  */
 export declare function canonicalPathIsAuthoritative(env: ExecutionEnv): boolean;
+/**
+ * Which process table this env's commands run on, as its adapter declares it
+ * ({@link RemoteExecutionEnv.capabilities}.sharesProcessTable):
+ *  · `"this"` — a table that holds this process: a remote env that declares `true`, and every env that is not
+ *    remote. The second is the base contract's in-process env (its commands are this process's children); an
+ *    adapter that runs commands elsewhere without the remote seam has no block to declare in and is read the
+ *    same way, which errs toward asking (a refusal of a kill that could not have reached this process);
+ *  · `"other"` — a remote env that declares `false`;
+ *  · `"undeclared"` — a remote env whose declaration is absent, not a boolean, or cannot be read (a throwing
+ *    getter or Proxy trap). There is no default to fold it to, so the caller refuses what it cannot answer.
+ * Total: it never throws. It does not announce — the admission census does, once per run.
+ */
+export declare function processTableOf(env: ExecutionEnv): "this" | "other" | "undeclared";

package/dist/core/remote-env.js

@@ -67,3 +67,14 @@ export function boundaryIsTheSandbox(env) {
 export function canonicalPathIsAuthoritative(env) {
     return isRemoteExecutionEnv(env) ? env.capabilities.canonicalPathAuthoritative === true : false;
 }
+export function processTableOf(env) {
+    try {
+        if (!isRemoteExecutionEnv(env))
+            return "this";
+        const declared = env.capabilities.sharesProcessTable;
+        return declared === true ? "this" : declared === false ? "other" : "undeclared";
+    }
+    catch {
+        return "undeclared";
+    }
+}

package/dist/core/resume-startup-cause.d.ts

@@ -84,6 +84,28 @@ export type ReopenReasonTableCoversEveryCause = AssertAllKeysHandled<Exclude<Res
  * decision is untouched, and the retry replays it.
  */
 export declare function reopenReasonOf(cause: ResumeStartupCause | undefined): ReopenReason;
-/** What the result of a returned resume leg says after its checkpoint was reopened, per reason. */
-export declare function reopenedUnstartedSentence(reason: ReopenReason): string;
+/**
+ * What happened to a claimed row whose approved action never started — the one closed outcome every exit of such a leg reports
+ * (the thrown-prepare backstop, the returned-leg settle, the post-claim abort): `reopened` under a reason (the row is pending again),
+ * `declined` (the store's `reopen` answered `false`: the row is no longer the resolved row this leg claimed — missing, expired, its
+ * decided action already disposed, or pending again — which the boolean does not say), `unknown` (the reopen threw: the write may have
+ * committed and only its acknowledgement been lost, so the row's state cannot be proven from here).
+ */
+export type UnstartedRow = {
+    readonly kind: "reopened";
+    readonly reason: ReopenReason;
+} | {
+    readonly kind: "declined";
+} | {
+    readonly kind: "unknown";
+    readonly thrown: unknown;
+};
+/**
+ * THE compensation of a claimed leg whose approved action never started: the claim's reversal (`reopen`, bound to the row) asked once,
+ * under `reason`, and read into {@link UnstartedRow} — its answer, never a code sniffed off whatever it threw (a store's own error may
+ * carry any code, and a throw after a committed write is not a refusal). Every exit calls it; none re-reads the outcome another way.
+ */
+export declare function compensateUnstarted(reopen: (reason: ReopenReason) => Promise<"reopened" | "declined">, reason: ReopenReason): Promise<UnstartedRow>;
+/** The sentence for {@link UnstartedRow} — one per outcome, the same on every exit; the exit puts its own lead before it. */
+export declare function unstartedRowSentence(row: UnstartedRow): string;
 export {};

package/dist/core/resume-startup-cause.js

@@ -1,3 +1,4 @@
+import { egressThrownText } from "./untrusted-egress.js";
 export const REOPEN_REASONS = Object.freeze(["env_failed", "tool_unavailable", "constraint_rejected", "config_refused"]);
 export const RESUME_STARTUP_CAUSES = Object.freeze(["environment", "session_gone", "transcript_corrupt", "tool_unavailable", "configuration", "decision_rejected"]);
 const CAUSE_OF_CODE = new Map([
@@ -44,7 +45,25 @@ const REOPEN_REASON_OF_CAUSE = {
 export function reopenReasonOf(cause) {
     return cause === undefined ? "env_failed" : REOPEN_REASON_OF_CAUSE[cause];
 }
-export function reopenedUnstartedSentence(reason) {
+export async function compensateUnstarted(reopen, reason) {
+    try {
+        return (await reopen(reason)) === "reopened" ? { kind: "reopened", reason } : { kind: "declined" };
+    }
+    catch (thrown) {
+        return { kind: "unknown", thrown };
+    }
+}
+export function unstartedRowSentence(row) {
+    switch (row.kind) {
+        case "reopened":
+            return reopenedUnstartedSentence(row.reason);
+        case "declined":
+            return "the approved action never started, and the store DECLINED to reopen the checkpoint — it is no longer the resolved row this leg claimed (missing, expired, its decided action already disposed, or pending again): read the row before deciding; if it is resolved or gone, a retry needs a fresh approval";
+        case "unknown":
+            return `the approved action never started, and reopening the checkpoint FAILED IN FLIGHT (${egressThrownText("same-principal", row.thrown)}) — its state UNKNOWN, unprovable from here: re-read it before deciding; do NOT issue a fresh approval on the assumption the old one is dead`;
+    }
+}
+function reopenedUnstartedSentence(reason) {
     switch (reason) {
         case "env_failed":
             return "the approved action never started, so the checkpoint was REOPENED (pending): the same approval can be resumed again, do not ask for a fresh one";

package/dist/core/roles.js

@@ -1,6 +1,7 @@
 import { selectModel } from "./select-model.js";
 import { namesRoleBase } from "../prompt-assembly/role-base.js";
 import { readPromptRole } from "../prompt-assembly/select.js";
+import { readMember } from "./thrown-value.js";
 import { MODEL_ROLES } from "./types.js";
 export { MODEL_ROLES } from "./types.js";
 function catalogModel(ref, models) {
@@ -13,13 +14,36 @@ function modelBindingRefusal(field, reason, message) {
     e.detail = { field, reason };
     return e;
 }
+const ROLE_RECORD_KEYS = new Set(["model", "select", "thinking", "promptRole", "systemPrompt"]);
+function isModelShaped(s) {
+    try {
+        if (typeof s === "function" || isList(s)) {
+            Reflect.ownKeys(s);
+            return false;
+        }
+        if (Reflect.ownKeys(s).some((k) => typeof k !== "string" || !ROLE_RECORD_KEYS.has(k)))
+            return true;
+        return readMember(s, "id") !== undefined || readMember(s, "api") !== undefined;
+    }
+    catch {
+        return true;
+    }
+}
 function isBindingObject(value) {
     return (typeof value === "object" && value !== null) || typeof value === "function";
 }
 function bindingShown(value) {
     if (typeof value === "string")
         return JSON.stringify(value.length > 80 ? `${value.slice(0, 80)}…` : value);
-    return value === null ? "null" : Array.isArray(value) ? "a list" : `a ${typeof value}`;
+    return value === null ? "null" : isList(value) ? "a list" : `a ${typeof value}`;
+}
+function isList(value) {
+    try {
+        return Array.isArray(value);
+    }
+    catch {
+        return false;
+    }
 }
 function unknownModelRefRefusal(ref, seat) {
     return modelBindingRefusal(seat, "unknown_model_ref", `Unknown model ref ${bindingShown(ref)} in ${seat}. Provide it in RunnerDeps.models or pass a Model object.`);
@@ -30,6 +54,7 @@ function modelOfBinding(value, models, seat, binds) {
         const held = catalogModel(value, models);
         if (held === undefined)
             throw unknownModelRefRefusal(value, seat);
+        assertModelObject(held, seat, `${bindingShown(value)} (a catalog entry)`);
         return held;
     }
     return value;
@@ -37,9 +62,19 @@ function modelOfBinding(value, models, seat, binds) {
 function assertModelBindingShape(value, seat, binds) {
     if (typeof value === "string")
         return;
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    if (typeof value !== "object" || value === null || isList(value)) {
         throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(value)}, not a model reference — ${binds}.`);
     }
+    assertModelObject(value, seat, "a Model object", binds === ROLE_BINDS ? " At a role seat an object with a key beyond model / select / thinking / promptRole / systemPrompt is read as a Model, not as a role record." : "");
+}
+function assertModelObject(value, seat, what, note = "") {
+    const id = readMember(value, "id");
+    const api = readMember(value, "api");
+    const [member, got] = typeof id !== "string" || id === "" ? ["id", id] : typeof api !== "string" ? ["api", api] : [undefined, undefined];
+    if (member === undefined)
+        return;
+    const shown = got === undefined ? "absent" : bindingShown(got);
+    throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${what} whose \`${member}\` is ${shown} — a Model carries a non-empty string \`id\` and a string \`api\`.${note}`);
 }
 const ROLE_BINDS = "a role binds a catalog model name or a Model object";
 const roleModelSeat = (named, seat) => (typeof named === "string" ? seat : `${seat}.model`);
@@ -158,7 +193,10 @@ function roleTierModel(role, models) {
     if (!models || !models[TIERS_ACTIVE])
         return undefined;
     const tier = ROLE_TIER_DEFAULTS[role];
-    return tier !== undefined ? models[tier] : undefined;
+    const m = tier !== undefined ? models[tier] : undefined;
+    if (m)
+        assertModelObject(m, `tiers.${String(tier)}`, "the catalog entry the tier word names");
+    return m;
 }
 const FALLBACK = {
     default: [],
@@ -178,7 +216,7 @@ function specParts(s, seat = "a role seat") {
     if (!isBindingObject(s)) {
         throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(s)}, not a model reference — a role binds a catalog model name, a Model object or a { model, select, thinking, systemPrompt } record.`);
     }
-    if ("id" in s && "api" in s) {
+    if (isModelShaped(s)) {
         return { model: s };
     }
     const cfg = s;
@@ -192,7 +230,7 @@ function toConfig(s) {
     if (s === undefined) {
         return undefined;
     }
-    if (typeof s === "string" || ("id" in s && "api" in s)) {
+    if (typeof s === "string" || isModelShaped(s)) {
         return { model: s };
     }
     return s;
@@ -248,8 +286,13 @@ function partsModel(parts, models, seat = "a role seat") {
         if (needs != null && !Array.isArray(needs)) {
             throw modelBindingRefusal(`${seat}.select`, "not_a_model_ref", `${seat}.select.needs is ${bindingShown(needs)}, not a list of capabilities (vision / reasoning).`);
         }
-        const held = models != null && typeof models === "object" ? Object.values(models).filter(Boolean) : [];
-        return selectModel(held, parts.select);
+        const held = models != null && typeof models === "object" ? Object.entries(models).filter(([, m]) => Boolean(m)) : [];
+        for (const [key, m] of held)
+            assertModelObject(m, `${seat}.select`, `the catalog entry ${bindingShown(key)} the criteria read`);
+        const picked = selectModel(held.map(([, m]) => m), parts.select);
+        if (picked !== undefined)
+            assertModelObject(picked, `${seat}.select`, "the catalog entry the criteria pick");
+        return picked;
     }
     return undefined;
 }

package/dist/core/runner/compact-session.d.ts

@@ -0,0 +1,10 @@
+import { type CompactSessionRequest, type CompactSessionResult } from "../auto-compaction.js";
+import { type SessionStore } from "../session.js";
+import type { RunnerDeps } from "../types.js";
+import { type SessionLockSeats } from "./session-verb-doors.js";
+/** What the Runner lends the compaction: its current deps, its session store, and its lock. */
+export interface CompactSessionSeats extends SessionLockSeats {
+    deps: RunnerDeps;
+    sessions: SessionStore;
+}
+export declare function compactIdleSession(seats: CompactSessionSeats, request: CompactSessionRequest): Promise<CompactSessionResult>;

package/dist/core/runner/compact-session.js

@@ -0,0 +1,202 @@
+import { convertToLlm, uuidv7 } from "../../internal/harness.js";
+import { compactionFailureReason, compactionPassReport, DEFAULT_COMPACTION_INSTRUCTIONS, isCompactionManualCancel, manualCompactOutcomeOf, maybeCompact, mintCompactedEvent } from "../auto-compaction.js";
+import { contextOverlayFor } from "../context-settings.js";
+import { admitLegMods, legFacadeSeats } from "../mods/stations.js";
+import { malformedPricingField } from "../pricing.js";
+import { resolveTaskModel } from "../roles.js";
+import { StoredSession } from "../session.js";
+import { emitTrace } from "../trace.js";
+import { egressThrownText } from "../untrusted-egress.js";
+import { emitInputTruncated, legCompactionSettings } from "./compaction-call-options.js";
+import { compactionHookOptions, summaryProviderOptions } from "./compaction-seams.js";
+import { compactionSummaryFallback, compactionSummaryIsDerived } from "./derived-route-fallback.js";
+import { resolveCompactionModel } from "./prepare-config-doors.js";
+import { compactionActivationSnapshot } from "./prepare-tool-disclosure-mount.js";
+import { derivedLegBrain, sideCallBookOf } from "./side-call-account.js";
+import { acquireExistingSession, claimIdleSession, readPlainRequest, shownValue } from "./session-verb-doors.js";
+const VERB = "Runner.compactSession";
+const REQUEST_KEYS = new Set(["sessionId", "model", "instructions", "compaction", "compactionModel", "getApiKeyAndHeaders", "signal"]);
+const SETTINGS_KEYS = new Set(["enabled", "reserveTokens", "keepRecentTokens", "instructions", "clampTolerance"]);
+export async function compactIdleSession(seats, request) {
+    const req = screenCompactSessionRequest(request);
+    const { deps } = seats;
+    const resolved = resolveTaskModel({ model: req.model }, deps);
+    const named = resolveCompactionModel(req.compactionModel !== undefined ? { compactionModel: req.compactionModel } : {}, deps, "compactSession.compactionModel");
+    if (req.signal?.aborted === true)
+        return { outcome: "mooted", events: [] };
+    const release = await claimIdleSession(seats, req.sessionId, () => sessionBusyRefusal(req.sessionId));
+    try {
+        const acquired = await acquireExistingSession(seats.sessions, req.sessionId, VERB, "nothing was compacted");
+        const legMods = await admitLegMods({ spec: {}, deps, sessionId: req.sessionId });
+        return await compactOnSession(req, deps, new StoredSession(acquired.session.getStorage()), resolved, named, legMods);
+    }
+    finally {
+        release();
+    }
+}
+async function compactOnSession(req, deps, session, resolved, named, legMods) {
+    const { sessionId } = req;
+    const events = [];
+    const ident = () => ({ eventId: uuidv7() });
+    const passReport = compactionPassReport({ push: (e) => events.push(e) }, ident);
+    const stats = { turns: 0, tokens: 0, toolCalls: 0, promptTokens: 0, totalInputTokens: 0, cachedTokens: 0, cacheWriteTokens: 0, cacheWriteTokensLong: 0, outputTokens: 0, costMicroUsd: 0 };
+    const telemetry = { unpricedSpend: false, tracer: deps.tracer, taskId: sessionId };
+    const accountBook = sideCallBookOf(stats, { telemetry, pricing: () => deps.pricing, noteUnevaluablePriceTable: (p) => void (malformedPricingField(p) !== undefined && (telemetry.unpricedSpend = true)), catalog: deps.models });
+    let calls = 0;
+    const book = (lane, model, reply) => {
+        calls += 1;
+        accountBook(lane, model, reply);
+    };
+    const answer = (outcome) => ({
+        outcome,
+        events,
+        ...(calls > 0
+            ? {
+                usage: {
+                    tokens: stats.tokens,
+                    totalInputTokens: stats.totalInputTokens,
+                    promptTokens: stats.promptTokens,
+                    cachedTokens: stats.cachedTokens,
+                    cacheWriteTokens: stats.cacheWriteTokens,
+                    outputTokens: stats.outputTokens,
+                    costMicroUsd: stats.costMicroUsd,
+                    ...(stats.usageMissing === true ? { usageMissing: true } : {}),
+                    ...(telemetry.unpricedSpend ? { unpriced: true } : {}),
+                },
+            }
+            : {}),
+    });
+    const trace = deps.tracer;
+    try {
+        const compactionModel = compactionSummaryIsDerived(req.compactionModel !== undefined, named) ? await compactionSummaryFallback({ derived: named, primary: resolved.model, brain: deps.brain, getApiKeyAndHeaders: req.getApiKeyAndHeaders, onNotice: deps.onNotice, sessionId }) : named;
+        const branch = await session.getBranch();
+        const contextMessages = convertToLlm((await session.buildContext()).messages);
+        bindSessionFacade(legMods, { deps, req, model: resolved.model, messages: contextMessages, book });
+        const overlay = contextOverlayFor(deps.contextSettings, resolved.modelRef, deps);
+        const activeTools = compactionActivationSnapshot(branch);
+        const thinking = resolved.thinking ?? resolved.model.defaultThinking;
+        const comp = await maybeCompact({
+            session,
+            model: resolved.model,
+            ...(overlay !== undefined ? { contextOverlay: overlay } : {}),
+            ...(compactionModel !== undefined ? { compactionModel } : {}),
+            brain: derivedLegBrain(() => deps.brain, "compaction", book),
+            ...(req.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: req.getApiKeyAndHeaders } : {}),
+            ...(thinking !== undefined ? { thinking } : {}),
+            settings: legCompactionSettings(req.compaction !== undefined ? { compaction: req.compaction } : {}, overlay),
+            customInstructions: req.instructions ?? req.compaction?.instructions ?? DEFAULT_COMPACTION_INSTRUCTIONS,
+            ...(req.signal !== undefined ? { signal: req.signal, manualCancelSignal: req.signal } : {}),
+            minTokens: 0,
+            force: true,
+            onInputTruncated: emitInputTruncated(trace, sessionId),
+            ...(activeTools.length > 0 ? { activeTools } : {}),
+            ...summaryProviderOptions({ deps }, 0),
+            ...compactionHookOptions({ deps }, { modBus: legMods.bus, hookIdentity: undefined, sessionId }, "manual", req.signal),
+            onStarted: passReport.onStarted,
+        });
+        const outcome = manualCompactOutcomeOf(comp);
+        if (comp.compacted) {
+            events.push(mintCompactedEvent(comp, "manual", ident()));
+            return answer(outcome);
+        }
+        if (comp.blocked)
+            emitTrace(trace, () => ({ kind: "compaction.blocked", version: 1, taskId: sessionId, trigger: "manual", ts: Date.now() }));
+        else if (comp.disabled)
+            emitTrace(trace, () => ({ kind: "compaction.disabled", version: 1, taskId: sessionId, ts: Date.now() }));
+        else
+            emitTrace(trace, () => ({ kind: "compaction.noop", version: 1, taskId: sessionId, ts: Date.now() }));
+        events.push({ type: "compaction_outcome", outcome: outcome, trigger: "manual", ...ident() });
+        return answer(outcome);
+    }
+    catch (err) {
+        if (isCompactionManualCancel(err)) {
+            emitTrace(trace, () => ({ kind: "compaction.mooted", version: 1, taskId: sessionId, reason: "cancelled", ts: Date.now() }));
+            events.push({ type: "compaction_outcome", outcome: "mooted", trigger: "manual", reason: "cancelled", ...passReport.end, ...ident() });
+            return answer("mooted");
+        }
+        deps.onError?.(asError(err), { phase: "compaction", sessionId });
+        const reason = compactionFailureReason(err);
+        emitTrace(trace, () => ({ kind: "compaction.failed", version: 1, taskId: sessionId, trigger: "manual", reason, ts: Date.now() }));
+        events.push({ type: "compaction_outcome", outcome: "failed", trigger: "manual", reason, ...passReport.end, ...ident() });
+        return answer("failed");
+    }
+}
+function bindSessionFacade(legMods, input) {
+    const unavailable = (method) => {
+        throw new Error(`${method}: not available on a session-level compaction (${VERB}) — there is no run, so no execution environment, working directory, tool roster or agent listing`);
+    };
+    const seats = legFacadeSeats({
+        deps: input.deps,
+        spec: input.req.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: input.req.getApiKeyAndHeaders } : {},
+        sessionId: input.req.sessionId,
+        model: input.model,
+        executionEnv: { exec: () => unavailable("process.run") },
+        taskRoot: "",
+        cwdRef: undefined,
+        lastBrainContext: () => ({ messages: input.messages }),
+        activeTools: new Set(),
+        agentListing: undefined,
+        book: (answeredBy, reply) => input.book("mod", answeredBy, reply),
+        toolCall: () => unavailable("tool.call"),
+    });
+    legMods.bindFacade({
+        ...seats,
+        cwd: () => unavailable("session.cwd"),
+        root: () => unavailable("session.root"),
+        tools: () => unavailable("tool.list"),
+        agents: () => unavailable("agent.list"),
+    });
+}
+function asError(err) {
+    return err instanceof Error ? err : new Error(egressThrownText("same-principal", err));
+}
+function screenCompactSessionRequest(request) {
+    const bad = (what) => {
+        const e = new Error(`${VERB}: ${what} — nothing was compacted. The request is { sessionId, model, instructions?, compaction?, compactionModel?, getApiKeyAndHeaders?, signal? }.`);
+        e.code = "compact.invalid_request";
+        throw e;
+    };
+    const { sessionId, model, instructions, compaction, compactionModel, getApiKeyAndHeaders, signal } = readPlainRequest(request, REQUEST_KEYS, bad);
+    if (typeof sessionId !== "string" || sessionId === "")
+        return bad(`sessionId must be a non-empty string, got ${shownValue(sessionId)}`);
+    if (model === undefined)
+        return bad("model is required — the model the session's next turn runs on, whose window bounds the pass");
+    if (instructions !== undefined && typeof instructions !== "string")
+        return bad(`instructions must be a string when given, got ${shownValue(instructions)}`);
+    if (getApiKeyAndHeaders !== undefined && typeof getApiKeyAndHeaders !== "function")
+        return bad(`getApiKeyAndHeaders must be a function when given, got ${shownValue(getApiKeyAndHeaders)}`);
+    if (signal !== undefined && !(signal instanceof AbortSignal))
+        return bad(`signal must be an AbortSignal when given, got ${shownValue(signal)}`);
+    return {
+        sessionId,
+        model: model,
+        instructions,
+        compaction: compaction === undefined ? undefined : screenSettings(compaction, bad),
+        compactionModel: compactionModel,
+        getApiKeyAndHeaders: getApiKeyAndHeaders,
+        signal,
+    };
+}
+function screenSettings(raw, bad) {
+    const { enabled, reserveTokens, keepRecentTokens, instructions, clampTolerance } = readPlainRequest(raw, SETTINGS_KEYS, (what) => bad(`compaction: ${what}`));
+    if (enabled !== undefined && typeof enabled !== "boolean")
+        return bad(`compaction.enabled must be a boolean when given, got ${shownValue(enabled)}`);
+    for (const [name, v] of [["reserveTokens", reserveTokens], ["keepRecentTokens", keepRecentTokens], ["clampTolerance", clampTolerance]]) {
+        if (v !== undefined && typeof v !== "number")
+            return bad(`compaction.${name} must be a number when given, got ${shownValue(v)}`);
+    }
+    if (instructions !== undefined && typeof instructions !== "string")
+        return bad(`compaction.instructions must be a string when given, got ${shownValue(instructions)}`);
+    return {
+        ...(enabled !== undefined ? { enabled: enabled } : {}),
+        ...(reserveTokens !== undefined ? { reserveTokens: reserveTokens } : {}),
+        ...(keepRecentTokens !== undefined ? { keepRecentTokens: keepRecentTokens } : {}),
+        ...(instructions !== undefined ? { instructions: instructions } : {}),
+        ...(clampTolerance !== undefined ? { clampTolerance: clampTolerance } : {}),
+    };
+}
+function sessionBusyRefusal(sessionId) {
+    const e = new Error(`${VERB}: a task is running or queued on session "${sessionId}" in this Runner, or a write one of its tasks issued has not settled — compacting it now would rewrite the transcript under that work, so nothing was compacted; a running task takes the request through its own stream (TaskStream.compact), otherwise retry once it has ended and its writes have settled`);
+    e.code = "compact.session_busy";
+    return e;
+}

package/dist/core/runner/compaction-call-options.d.ts

@@ -156,7 +156,7 @@ export declare function emitInputTruncated(tracer: TracerHook | undefined, taskI
  */
 export declare function legContextOverlayOption(prepared: Prepared, runner: RunnerDepsSeat): Pick<MaybeCompactOptions, "contextOverlay">;
 /**
- * The compaction SETTINGS a pass runs under — the assembly all three lanes share.
+ * The compaction SETTINGS a pass runs under — the assembly all three lanes and the out-of-run `Runner.compactSession` share.
  *
  * `{ ...DEFAULT_COMPACTION_SETTINGS, ...spec.compaction }` was hand-copied at each lane, and it is where the
  * deployment's live `enabled` declaration belongs: `maybeCompact` has exactly one enablement gate (it reads
@@ -165,4 +165,4 @@ export declare function legContextOverlayOption(prepared: Prepared, runner: Runn
  * compaction runs" a single expression ({@link compactionEnabled}: the request authored it > the deployment
  * declared it > on).
  */
-export declare function legCompactionSettings(spec: TaskSpec, overlay: ContextWindowOverlay | undefined): CompactionSettings;
+export declare function legCompactionSettings(spec: Pick<TaskSpec, "compaction">, overlay: ContextWindowOverlay | undefined): CompactionSettings;