@sema-agent/core 5.48.0 → 5.50.0

package/dist/orchestration/workflow-governance.d.ts

@@ -125,6 +125,33 @@ export interface ResourceClampNote {
     /** The effective value the child actually runs under (min of script/baseline/caps, or a forced ceiling). */
     applied: number;
 }
+/**
+ * The worktree-overlay merge — `{ ...base, ...worktreeBase }` with ONE amendment: an overlay key
+ * whose value is OWN NULLISH (`undefined` OR `null` — both plain-JS deployment shapes) never
+ * overrides `base`; it reads as the absent key its value spells ("an absent overlay field inherits
+ * from base", the documented semantics). The GENERIC successor of the per-key protections that grew
+ * one field at a time (three face arrays, then `onAsk` — the mount-side deletes, which remain for
+ * their base-slot readings) while every OTHER same-shaped key stayed destructive: a surviving own
+ * nullish overlay key erased the base value — `toolPolicy` / `shellGate` / `limits` / `hooks` /
+ * `restoreGatedTools` / `readFace` / … — for exactly the children an untrusted script can route to
+ * the overlay (`isolation: "worktree"`), own-`undefined` keys included (a spread copies them; the
+ * old `=== null` face drop missed that half). One rule at the one merge point: a new baseline key
+ * is safe with no list to extend. The single exception is {@link NULL_VALUED_BASELINE_KEYS}
+ * (`checkpointStore: null` — the deployment disarming durable suspend for isolated children is a
+ * capability removal it must be able to spell). Explicit non-nullish overlay values keep winning
+ * wholesale — the documented deployment override.
+ *
+ * ACCEPTED COST, stated (adversarial-review round 2): the rule is direction-blind — a CAPABILITY
+ * key's out-of-type overlay `null` used to WITHHOLD the base value by the same spread accident
+ * (e.g. `worktreeBase: { getApiKeyAndHeaders: null }` overwrote the base resolver AND defeated the
+ * parent-credential `=== undefined` fill in workflow.ts — silently blocking the documented
+ * inheritance, the same seam-defeat disease the onAsk r3 ruling deleted null for), and such a key
+ * now inherits per the documented contract. Deployments withhold capabilities from isolated
+ * children with IN-TYPE spellings (`tools: []`, a deny `toolPolicy`, `handsReadOnly: true`);
+ * `getApiKeyAndHeaders` currently has no in-type disable value — that expressiveness gap is a
+ * baseline-contract question, deliberately not solved by resurrecting undocumented null semantics.
+ */
+export declare function overlayWorktreeBaseline(base: WorkflowGovernanceBaseline["base"], worktreeBase: WorkflowGovernanceBaseline["base"]): WorkflowGovernanceBaseline["base"];
 /** Resolve an LLM-supplied model NAME to a deploy-configured `Model`, FAIL-CLOSED against the allowlist.
  *  Throws (never falls open to the whole catalog) when no allowlist is configured or the name is not on it. */
 export declare function resolveModelName(name: string, allowlist: string[] | undefined, models: Record<string, Model> | undefined): Model;

package/dist/orchestration/workflow-governance.js

@@ -57,6 +57,19 @@ function emitStrippedKeysNotice(survey, onNotice) {
     }
 }
 const VALID_THINKING = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+const NULL_VALUED_BASELINE_KEYS = new Set(["checkpointStore"]);
+export function overlayWorktreeBaseline(base, worktreeBase) {
+    let overlay = worktreeBase;
+    for (const key of Object.keys(worktreeBase)) {
+        const v = worktreeBase[key];
+        if (v !== undefined && (v !== null || NULL_VALUED_BASELINE_KEYS.has(key)))
+            continue;
+        if (overlay === worktreeBase)
+            overlay = { ...worktreeBase };
+        delete overlay[key];
+    }
+    return { ...base, ...overlay };
+}
 export function resolveModelName(name, allowlist, models) {
     if (!allowlist || allowlist.length === 0) {
         throw new WorkflowModelNotAllowedError(name, "no workflowModelAllowlist is configured (fail-closed: an LLM-authored script cannot pick a model)");

package/dist/orchestration/workflow-primitives.d.ts

@@ -44,4 +44,11 @@ parentCheckpointStoreDisabled?: boolean,
 parentReadFace?: () => TaskSpec["readFace"], 
 /** Twin of the above for the deny-set additions (built-ins always apply; these are the extra
  *  entries the host's own deployment/task layers stacked on). */
-parentReadDenyPatterns?: () => TaskSpec["readDenyPatterns"]): WorkflowPrimitives;
+parentReadDenyPatterns?: () => TaskSpec["readDenyPatterns"], 
+/** #345 ③ — the HOST task's write-hands clamp is ON (`spec.handsReadOnly === true`). Injected
+ *  tighten-only into every spawned child, like the read-face clamp above; see the injection
+ *  below for why it outranks even a `worktreeBase: { handsReadOnly: false }` overlay. */
+parentHandsReadOnly?: boolean, 
+/** #345 ③ — the HOST task's hard-headless clamp is ON (`spec.interactiveTools === false`).
+ *  Same tighten-only injection; only the disabling value ever arrives here as `true`. */
+parentInteractiveToolsOff?: boolean): WorkflowPrimitives;

package/dist/orchestration/workflow-primitives.js

@@ -1,5 +1,5 @@
 import { assertSupportedAgentIsolation } from "./workflow.js";
-import { buildGovernedChildSpec } from "./workflow-governance.js";
+import { buildGovernedChildSpec, overlayWorktreeBaseline } from "./workflow-governance.js";
 function safeAgentOptions(opts) {
     if (typeof opts !== "object" || opts === null)
         return {};
@@ -22,12 +22,12 @@ function formatResourceClampNote(notes) {
     const parts = notes.map((n) => `${n.field}: requested ${n.requested === undefined ? "unset" : n.requested} → applied ${n.applied}`);
     return `workflow governance tightened this agent's resource limits (${parts.join("; ")})`;
 }
-export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThinking, parentPrincipal, parentCheckpointStoreDisabled, parentReadFace, parentReadDenyPatterns) {
+export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThinking, parentPrincipal, parentCheckpointStoreDisabled, parentReadFace, parentReadDenyPatterns, parentHandsReadOnly, parentInteractiveToolsOff) {
     const agent = (spec, opts) => {
         if (typeof spec === "string")
             spec = { objective: spec };
         const agentOpts = safeAgentOptions(opts);
-        const effectiveBaseline = (b) => agentOpts.isolation === "worktree" && b.worktreeBase !== undefined ? { ...b, base: { ...b.base, ...b.worktreeBase } } : b;
+        const effectiveBaseline = (b) => agentOpts.isolation === "worktree" && b.worktreeBase != null ? { ...b, base: overlayWorktreeBaseline(b.base, b.worktreeBase) } : b;
         const childSpec = governance
             ? buildGovernedChildSpec(spec, effectiveBaseline(governance.baseline), governance.models, governance.caps, (notes) => ctx.log(formatResourceClampNote(notes)), governance.onNotice)
             : { ...spec };
@@ -53,6 +53,14 @@ export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThi
                 childSpec.readDenyPatterns = childSpec.readDenyPatterns !== undefined ? [...childSpec.readDenyPatterns, ...pd] : [...pd];
             }
         }
+        if (parentHandsReadOnly === true) {
+            childSpec.handsReadOnly = true;
+        }
+        if (parentInteractiveToolsOff === true) {
+            childSpec.interactiveTools = false;
+            if (childSpec.interactionPosture === "interactive")
+                delete childSpec.interactionPosture;
+        }
         if (onAgentSpawn) {
             return ctx.agentStream(childSpec, agentOpts).then((handle) => {
                 onAgentSpawn(handle);

package/dist/stores/file/file-snapshot-store.js

@@ -5,6 +5,12 @@ import { applyManifest, captureManifest, DEFAULT_SNAPSHOT_BOUNDS, } from "../../
 import { canonicalStoreKey, ensureDir, sanitizePathComponent, sanitizeScope, writeThenLink } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 const sharedInFlight = new Map();
+function containSinkThenable(r) {
+    if (typeof r?.then === "function") {
+        r.then(undefined, () => {
+        });
+    }
+}
 export class FileFileSnapshotStore {
     base;
     blobsDir;
@@ -37,7 +43,7 @@ export class FileFileSnapshotStore {
     }
     disclose(path, reason) {
         try {
-            this.onCorruptRead?.({ path, reason });
+            containSinkThenable(this.onCorruptRead?.({ path, reason }));
         }
         catch {
         }

package/dist/stores/file/index.d.ts

@@ -4,6 +4,7 @@ import type { ToolResultStore } from "../../core/tool-result-store.js";
 import { type EvictPolicy } from "../../core/session-store.js";
 import type { SessionStore } from "../../core/session.js";
 import { type FileCheckpointStoreOptions } from "./checkpoint-store.js";
+import type { StrategyStore } from "../../core/strategy-store.js";
 import type { BackgroundAgentStore } from "../../core/background-agent-store.js";
 import type { MailboxStore } from "../../core/mailbox-store.js";
 import type { RosterStore } from "../../agents/roster-store.js";
@@ -19,6 +20,7 @@ export { FileSessionPolicyStore, type FileSessionPolicyStoreOptions, type Sessio
 export { FileFileSnapshotStore, type FileFileSnapshotStoreOptions } from "./file-snapshot-store.js";
 export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
 export { FileUsageWindowStore } from "./usage-window-store.js";
+export { FileStrategyStore, type FileStrategyStoreOptions } from "./strategy-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionSource, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./adoption/marker.js";
@@ -136,6 +138,12 @@ export declare class FileStorageBackend {
     /** design/151 §7 S3c — the durable SendMessage mailbox (tier-3 parking lane), same data root.
      *  Wire into `RunnerDeps.mailboxStore` (single-instance pairing, same as above). */
     readonly mailboxStore: MailboxStore;
+    /** File-backed teacher-mode strategy repository (`root/strategies`) — pass as
+     *  `TeacherConfig.strategyStore` (with a `scope`) so escalation strategies survive a restart;
+     *  the in-memory default forgets everything each process, which zeroes the cross-session reuse
+     *  the repository exists for. Aggregated here so the TOC full-persistence assembly stays one
+     *  constructor (the same half-wiring hazard as the delegation trio). */
+    readonly strategyStore: StrategyStore;
     /** design/147 S1c — the durable name→agent roster (layer 0.5 resolution), `root/roster.json`.
      *  Wire into `RunnerDeps.rosterStore` so name-addressing survives a restart alongside the rows. */
     readonly rosterStore: RosterStore;

package/dist/stores/file/index.js

@@ -14,6 +14,7 @@ import { FileUsageWindowStore } from "./usage-window-store.js";
 import { FileBackgroundAgentStore } from "./background-agent-store.js";
 import { FileMailboxStore } from "./mailbox-store.js";
 import { FileRosterStore } from "../../agents/roster-store.js";
+import { FileStrategyStore } from "./strategy-store.js";
 export { FileCheckpointStore } from "./checkpoint-store.js";
 export { FileMemoryStore } from "./memory-store.js";
 export { FileSessionRepo } from "./session-store.js";
@@ -22,6 +23,7 @@ export { FileSessionPolicyStore } from "./session-policy-store.js";
 export { FileFileSnapshotStore } from "./file-snapshot-store.js";
 export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
 export { FileUsageWindowStore } from "./usage-window-store.js";
+export { FileStrategyStore } from "./strategy-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, } from "./adoption/marker.js";
@@ -38,6 +40,7 @@ export class FileStorageBackend {
     usageWindowStore;
     backgroundAgentStore;
     mailboxStore;
+    strategyStore;
     rosterStore;
     consolidationLock;
     lock;
@@ -74,6 +77,15 @@ export class FileStorageBackend {
             this.fileMailbox = new FileMailboxStore(this.root, corruptRead ?? {});
             this.mailboxStore = this.fileMailbox;
             this.rosterStore = new FileRosterStore(join(this.root, "roster.json"), corruptRead ?? {});
+            const strategiesRoot = join(this.root, "strategies");
+            this.strategyStore = new FileStrategyStore({
+                root: strategiesRoot,
+                ...(opts.onCorruptRead !== undefined
+                    ? {
+                        onIncident: (i) => opts.onCorruptRead?.({ path: i.path ?? strategiesRoot, reason: `strategy ${i.op}: ${i.error}` }),
+                    }
+                    : {}),
+            });
             this.consolidationLock = createFileConsolidationLock(join(this.root, "consolidation-locks"));
         }
         catch (err) {

package/dist/stores/file/session-policy-store.d.ts

@@ -1,17 +1,4 @@
 import { type PutRulesOptions, type SessionPermissionRules, type SessionPolicyStore, type SessionRulesRecord, type StoredSessionRules } from "../../core/session-policy-store.js";
-/**
- * design/99 §E6 — file-backed {@link SessionPolicyStore} for the local (TOC) backend: ONE JSON file per
- * `(sessionId, principal)`, semantics **byte-for-byte identical to `InMemorySessionPolicyStore`** (the
- * cross-backend equivalence contract). CAS-rev OCC + tighten-only reuse the SAME pure helpers
- * (`loosenReasons`/`normalizeRules`/`stripRev`) as core — no re-implemented rule logic that could drift.
- *
- * Atomicity: the file backend is single-process (the `FileStorageBackend` boot lock guarantees ONE writer per
- * data dir), and `getRules`/`putRules` read-check-write SYNCHRONOUSLY (no await between the rev read and the
- * atomic write), so the read-modify-write is atomic in the one event loop — exactly the InMemory store's premise.
- * Cross-process CORRECT concurrency is the Pg/TiDB backend's job (a CAS WHERE clause), by design.
- */
-/** Coordinates of one corrupt-treated-as-absent policy read (the {@link FileSessionPolicyStoreOptions.onCorruptRead}
- *  payload). Named rather than inline so the backend option that forwards it names the SAME shape. */
 export interface SessionPolicyCorruptReadInfo {
     /** The session whose read observed the corrupt row. On the enumeration face this is the session being
      *  ENUMERATED — a corrupt row's own `__sid` is by definition unreadable, so it cannot be attributed. */

package/dist/stores/file/session-policy-store.js

@@ -3,6 +3,12 @@ import { join } from "node:path";
 import { loosenReasons, normalizeRules, stripRev, SessionPolicyError, } from "../../core/session-policy-store.js";
 import { atomicWriteFile, ensureDir, sanitizeScope } from "./fs-atomic.js";
 import { assertAdoptionBootGate, readRootAdoptionFile } from "./adoption/marker.js";
+function containSinkThenable(r) {
+    if (typeof r?.then === "function") {
+        r.then(undefined, () => {
+        });
+    }
+}
 export class FileSessionPolicyStore {
     dir;
     onCorruptRead;
@@ -18,7 +24,7 @@ export class FileSessionPolicyStore {
     }
     disclose(info) {
         try {
-            this.onCorruptRead?.(info);
+            containSinkThenable(this.onCorruptRead?.(info));
         }
         catch {
         }

package/dist/stores/file/session-store.d.ts

@@ -29,7 +29,10 @@ export declare class FileSessionRepo implements SessionRepo {
     private readonly joined;
     constructor(root: string, opts?: FileSessionRepoOptions);
     /** The one delivery point for {@link FileSessionRepoOptions.onCorruptRead}; swallow-guarded here so
-     *  no call site has to remember. */
+     *  no call site has to remember. The sink seat is void-typed but a host may hand it an async
+     *  function — an async sink's rejection is observed off its returned thenable (same containment
+     *  as the strategy store's incident sink), so neither a sync throw nor an async rejection can
+     *  re-introduce the failure mode the fail-open avoids. */
     private disclose;
     private pathFor;
     /** Read + torn-tail-recover a session file into (meta, entries); a missing file → not_found. */

package/dist/stores/file/session-store.js

@@ -3,6 +3,12 @@ import { join } from "node:path";
 import { BaseSessionStorage, StoredSession, SessionError, getEntriesToFork, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
 import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
+function containSinkThenable(r) {
+    if (typeof r?.then === "function") {
+        r.then(undefined, () => {
+        });
+    }
+}
 const SUFFIX = ".jsonl";
 const sharedSessionStorages = new Map();
 const sessionStorageFinalizer = new FinalizationRegistry(({ canonical, log }) => {
@@ -67,7 +73,7 @@ export class FileSessionRepo {
     }
     disclose(path, reason) {
         try {
-            this.onCorruptRead?.({ path, reason });
+            containSinkThenable(this.onCorruptRead?.({ path, reason }));
         }
         catch {
         }

package/dist/stores/file/strategy-store.d.ts

@@ -0,0 +1,97 @@
+import { type StoredStrategy, type StrategyStore, type StrategyStoreIncident } from "../../core/strategy-store.js";
+/**
+ * File-backed {@link StrategyStore} — the persistence twin of `InMemoryStrategyStore`, so the teacher
+ * mode's cross-session reuse premise actually holds on a local (TOC) deployment where every session is
+ * a fresh process (an in-memory strategy repository there re-learns everything, every time).
+ *
+ * DESIGN STANCE — this is a **cache, not an authority store**: every entry is regenerable (worst case:
+ * ask the teacher again), so losing one never loses correctness. It therefore deliberately skips the
+ * journal/shadow armor of the memory file backend and does NOT fsync-harden beyond the shared
+ * atomic-write primitive, does NOT take a cross-process lock, and accepts a narrow multi-process race
+ * on save-side dedup (two processes can each write one copy of the same normalized entry — the read
+ * side dedups, and a lost max-confidence merge is cache-grade). What it does NOT relax: scope
+ * isolation and loud-refusal discipline, which are held to the same standard as the durable stores.
+ *
+ * Layout: `<root>/<scopeDir>/<id>.json`, one strategy per file, whole-file atomic replace on write.
+ * `scopeDir = slug(scope) + "-" + sha256(scope).slice(0,24)` — the slug is a strict `[a-z0-9-]`
+ * whitelist purely for readability; IDENTITY lives in the 96-bit hash, so no scope value, however
+ * hostile, can traverse out of the root or collide another scope's directory. Ids are gated to
+ * `[A-Za-z0-9_-]{1,64}` at save (the escalation loop mints UUIDs; the interface is public, so a
+ * hand-rolled id must not be able to name a path).
+ *
+ * `scope` is a NAMESPACE, not an authorization boundary — the store cannot authenticate its caller;
+ * whoever holds the instance can address any scope (same posture as the memory store). Authorization
+ * is the host's obligation.
+ */
+export interface FileStrategyStoreOptions {
+    /** Directory to keep strategies under (created `0o700` if absent; a non-directory or unwritable
+     *  path is refused loudly at construction — a store that cannot persist must not pretend to). */
+    root: string;
+    /** Per-scope capacity cap (entries), evicting the lowest-scoring on overflow. Default 100. */
+    maxPerScope?: number;
+    /**
+     * Disclosure sink for contained store incidents (a corrupt entry quarantined, an eviction that
+     * failed after a successful save, a degraded read). Absent ⇒ `console.warn`, once per op kind —
+     * a contained fault must be loud somewhere, but must never flood.
+     */
+    onIncident?: (i: StrategyStoreIncident) => void;
+}
+export declare class FileStrategyStore implements StrategyStore {
+    private readonly root;
+    private readonly maxPerScope;
+    private readonly onIncident?;
+    /** Ops that already warned on the absent-sink fallback (bounded disclosure — never flood). */
+    private readonly warnedOps;
+    /** Isolation scope for the host incident sink (sync throw AND async rejection contained). */
+    private readonly sinkNotifier;
+    /** Scope dirs whose stale temps this instance already swept (once per scope per instance). */
+    private readonly sweptTemps;
+    constructor(opts: FileStrategyStoreOptions);
+    /** `slug(scope)-sha256(scope)[0..24]` — slug is readability only; the hash is the injective key. */
+    private scopeDirName;
+    private scopeDirPath;
+    /** The scope dir must be a REAL directory — a symlink here means the store's namespace was tampered
+     *  with (a link could point retrieval at another scope's data, or writes out of the root). The
+     *  check-then-use window against a same-uid local attacker is out of the threat model: such an
+     *  attacker already holds the same rights as the store itself. */
+    private assertScopeDirSafe;
+    private incident;
+    /** Sweep crashed writers' stale temps (once per scope per instance). Fresh temps are left alone —
+     *  they may belong to a live concurrent writer. */
+    private sweepStaleTemps;
+    /** Load every VALID entry of a scope dir. Corrupt files are quarantined (`.bad` rename) with one
+     *  disclosure; entries that violate the read-side invariants (foreign scope / id≠filename) are
+     *  skipped with disclosure but NOT quarantined (a copied-in file may be someone's valid data);
+     *  normalized duplicates collapse to the best-scoring copy. */
+    private loadScope;
+    /** Rename a corrupt file to `<name>.bad` — one disclosure now, zero parse cost on every later read
+     *  (the suffix no longer matches the entry-file grammar). Never faults the calling operation. */
+    private quarantine;
+    /** Serialize + write one entry, refusing a record whose SERIALIZED form exceeds the read bound.
+     *  The field caps bound RAW string bytes, but JSON escaping expands control characters up to 6x —
+     *  without this door a save could succeed and then self-quarantine on the very next read (the
+     *  worst possible shape: an accepted write the store itself later refuses to serve). */
+    private writeEntry;
+    save(s: StoredStrategy): void;
+    private evict;
+    find(scope: string, query: string, limit: number): StoredStrategy[];
+    /** Bounded candidate view for the RETRIEVAL-adjacent paths (find/hasStrategy/save): an externally
+     *  inflated directory must not make a hot operation unbounded. MAINTENANCE passes Infinity — see
+     *  {@link prune}. */
+    private retrievalReadCap;
+    /**
+     * Trims to `maxSize` over an UNCAPPED enumeration: prune is the reconciliation verb, so it must see
+     * every entry file — under the bounded retrieval view, a capacity SHRINK across restarts (or
+     * `maxPerScope: 0`) left files beyond the window untouched, reporting success while the "removed"
+     * strategies sat on disk ready to resurrect under a later, larger capacity. Host-invoked
+     * maintenance accepts the O(all files) cost the retrieval path refuses.
+     */
+    prune(scope: string, maxSize: number): void;
+    /** Uncapped for the same reason as {@link prune}: this face feeds the seed capacity door, and an
+     *  under-count there turns "refuse what cannot fit" into silent eviction of fresh seeds. */
+    scopeUsage(scope: string): {
+        used: number;
+        capacity: number;
+    };
+    hasStrategy(scope: string, entry: Pick<StoredStrategy, "problem" | "strategy">): boolean;
+}