@sema-agent/core 5.11.0 → 5.13.0

package/dist/core/retention.d.ts

@@ -0,0 +1,36 @@
+export type RetentionDeclaration = "managed" | "none";
+export interface RetentionDeclaring {
+    readonly retention?: RetentionDeclaration;
+}
+export interface RetentionPolicy {
+    maxAgeDays: number;
+}
+export interface ManagedRetentionCapability {
+    listRetentionDomains(): Promise<readonly string[]>;
+    expireCheckpoints(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<RetentionReceipt>;
+    deleteExpiredSessions(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<RetentionReceipt>;
+    deleteOrphanToolResults(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<RetentionReceipt>;
+}
+export interface RetentionReceipt {
+    domain: string;
+    deleted: number;
+    skipped: number;
+    tombstones: number;
+}
+export declare function assertRetentionCapability(input: {
+    policy: RetentionPolicy | undefined;
+    locked: boolean;
+    stores: ReadonlyArray<{
+        name: string;
+        store: object | undefined;
+    }>;
+}): void;

package/dist/core/retention.js

@@ -0,0 +1,31 @@
+function codedError(code, message) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+export function assertRetentionCapability(input) {
+    const { policy, locked, stores } = input;
+    if (policy !== undefined && (!Number.isFinite(policy.maxAgeDays) || policy.maxAgeDays < 0)) {
+        throw codedError("config.retention_policy", `retentionPolicy.maxAgeDays must be a finite non-negative number of days (got ${String(policy.maxAgeDays)}).`);
+    }
+    const declaredRetention = (name, store) => {
+        const r = store.retention;
+        if (r === undefined || r === "none")
+            return "none";
+        if (r === "managed")
+            return "managed";
+        throw codedError("config.retention_capability", `store "${name}" declares an unparseable retention value ${JSON.stringify(r)} — expected "managed" or "none".`);
+    };
+    const declarations = stores
+        .filter((s) => s.store !== undefined)
+        .map(({ name, store }) => ({ name, retention: declaredRetention(name, store) }));
+    if (!locked || policy === undefined)
+        return;
+    const incapable = declarations.filter(({ retention }) => retention !== "managed");
+    if (incapable.length > 0) {
+        throw codedError("config.retention_capability", `retention policy is LOCKED but ${incapable.map((s) => s.name).join(", ")} ` +
+            `declare${incapable.length === 1 ? "s" : ""} retention "none" (or no declaration — read fail-closed as "none"): ` +
+            `a locked retention policy over stores that cannot delete would be "policy locked, data immortal". ` +
+            `Wire managed-retention stores, or unlock/remove the retention policy.`);
+    }
+}

package/dist/core/runner/assemble-result.js

@@ -154,7 +154,7 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     if (errorCode !== undefined && SALVAGE_ELIGIBLE_TERMINALS.has(errorCode)) {
         salvagedOutput = text.trim() || undefined;
     }
-    const retryAfterMs = errorCode === "usage.window_exhausted" ? flags.retryAfterMs : undefined;
+    const retryAfterMs = errorCode === "usage.window_exhausted" || errorCode === "memory.admission_required" ? flags.retryAfterMs : undefined;
     const { compactionMicroUsd: _internalCompaction, ...publicStats } = stats;
     void _internalCompaction;
     if (flags.unpricedSpend)

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

@@ -1,7 +1,19 @@
 import { type TracerHook } from "../trace.js";
 import type { MaybeCompactOptions } from "../auto-compaction.js";
-import type { TaskSpec } from "../types.js";
+import type { StaleToolResultOffloadOptions, TaskSpec } from "../types.js";
+import type { Context } from "../../internal/llm.js";
+import { type ToolResultStore } from "../tool-result-store.js";
 import type { Prepared } from "./prepare-task.js";
 export declare function buildWorkingFileAttachments(spec: TaskSpec, prepared: Prepared): MaybeCompactOptions["workingFileAttachments"];
+export declare function forkContextOption(prepared: Prepared, disable: boolean): Pick<MaybeCompactOptions, "forkContext">;
 export declare function centerAdoptionOption(prepared: Prepared): Partial<Pick<MaybeCompactOptions, "centerAdoption">>;
+export declare const STALE_OFFLOAD_DEFAULT_KEEP_RECENT_PER_TOOL = 3;
+export declare const STALE_OFFLOAD_DEFAULT_MIN_SAVINGS_CHARS = 2000;
+export interface ResolvedStaleToolResultOffload {
+    keepRecentPerTool: number;
+    minSavingsChars: number;
+}
+export declare function resolveStaleToolResultOffload(knob: StaleToolResultOffloadOptions | undefined): ResolvedStaleToolResultOffload | undefined;
+export declare function buildStaleOffloadPointer(toolName: string, ref: string, chars: number): string;
+export declare function projectStaleToolResults(context: Context, cfg: ResolvedStaleToolResultOffload, store: ToolResultStore, sessionId: string, writtenRefs: Set<string>): Promise<Context>;
 export declare function emitInputTruncated(tracer: TracerHook | undefined, taskId: string): NonNullable<MaybeCompactOptions["onInputTruncated"]>;

package/dist/core/runner/compaction-call-options.js

@@ -1,4 +1,6 @@
+import { createHash } from "node:crypto";
 import { emitTrace } from "../trace.js";
+import { buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX } from "../tool-result-store.js";
 export function buildWorkingFileAttachments(spec, prepared) {
     if (spec.compaction?.attachWorkingFiles === false || !prepared.readTaskFile)
         return undefined;
@@ -13,10 +15,93 @@ export function buildWorkingFileAttachments(spec, prepared) {
         ...(typeof spec.compaction?.attachWorkingFiles === "object" ? spec.compaction.attachWorkingFiles : undefined),
     };
 }
+export function forkContextOption(prepared, disable) {
+    return disable ? {} : { forkContext: prepared.lastBrainContext };
+}
 export function centerAdoptionOption(prepared) {
     const ca = prepared.centerCompactionCandidate?.();
     return ca !== undefined ? { centerAdoption: ca } : {};
 }
+export const STALE_OFFLOAD_DEFAULT_KEEP_RECENT_PER_TOOL = 3;
+export const STALE_OFFLOAD_DEFAULT_MIN_SAVINGS_CHARS = 2000;
+export function resolveStaleToolResultOffload(knob) {
+    if (knob === undefined)
+        return undefined;
+    const check = (name, v, fallback) => {
+        if (v === undefined)
+            return fallback;
+        if (!Number.isInteger(v) || v < 0) {
+            const e = new Error(`compaction.staleToolResultOffload.${name} must be a non-negative integer, got ${String(v)}`);
+            e.code = "config.stale_tool_result_offload_invalid";
+            throw e;
+        }
+        return v;
+    };
+    return {
+        keepRecentPerTool: check("keepRecentPerTool", knob.keepRecentPerTool, STALE_OFFLOAD_DEFAULT_KEEP_RECENT_PER_TOOL),
+        minSavingsChars: check("minSavingsChars", knob.minSavingsChars, STALE_OFFLOAD_DEFAULT_MIN_SAVINGS_CHARS),
+    };
+}
+export function buildStaleOffloadPointer(toolName, ref, chars) {
+    return (`[Stale tool result offloaded to save context: ${chars} chars from an earlier "${toolName}" call ` +
+        `saved to persisted output ref "${ref}". Newer results of this tool are still shown in full below; ` +
+        `use the ${OFFLOAD_TOOL_NAME} tool with this ref if you need the offloaded content again.]`);
+}
+function toolResultText(m) {
+    return m.content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("\n");
+}
+export async function projectStaleToolResults(context, cfg, store, sessionId, writtenRefs) {
+    const byTool = new Map();
+    context.messages.forEach((m, i) => {
+        if (m.role !== "toolResult" || m.isError)
+            return;
+        const list = byTool.get(m.toolName);
+        const row = { idx: i, msg: m };
+        if (list === undefined)
+            byTool.set(m.toolName, [row]);
+        else
+            list.push(row);
+    });
+    const replacements = new Map();
+    for (const [toolName, rows] of byTool) {
+        const staleCount = rows.length - cfg.keepRecentPerTool;
+        for (let k = 0; k < staleCount; k++) {
+            const { idx, msg } = rows[k];
+            const text = toolResultText(msg);
+            if (text.startsWith(PERSISTED_OUTPUT_PREFIX))
+                continue;
+            const ref = buildToolResultRef(sessionId, `${msg.toolCallId}_s${createHash("sha256").update(text, "utf8").digest("hex").slice(0, 32)}`);
+            const pointer = buildStaleOffloadPointer(toolName, ref, text.length);
+            if (text.length - pointer.length < cfg.minSavingsChars)
+                continue;
+            if (!writtenRefs.has(ref)) {
+                try {
+                    await store.put(ref, text);
+                    writtenRefs.add(ref);
+                }
+                catch {
+                    continue;
+                }
+            }
+            replacements.set(idx, { msg, pointer });
+        }
+    }
+    if (replacements.size === 0)
+        return context;
+    return {
+        ...context,
+        messages: context.messages.map((m, i) => {
+            const hit = replacements.get(i);
+            if (hit === undefined)
+                return m;
+            const rest = hit.msg.content.filter((b) => b.type !== "text");
+            return { ...hit.msg, content: [{ type: "text", text: hit.pointer }, ...rest] };
+        }),
+    };
+}
 export function emitInputTruncated(tracer, taskId) {
     return (info) => emitTrace(tracer, () => ({
         kind: "compaction.input_truncated",

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

@@ -8,6 +8,13 @@ export interface PrepareMemoryInput {
     memoryWriteGateRef: {
         current?: BeforeWriteHook;
     };
+    admissionCtx: {
+        orgMemoryDenied: boolean;
+        complianceDegraded: boolean;
+        parentAdmittedOrgScopes: readonly string[] | undefined;
+        priorOwnVerdict: import("../memory-admission.js").OwnOrgAdmissionVerdict | undefined;
+        governedProvenance: boolean;
+    };
 }
 export interface PrepareMemoryResult {
     memoryEngineSession: Prepared["memoryEngineSession"];
@@ -16,5 +23,7 @@ export interface PrepareMemoryResult {
         path: string;
         content: string;
     }>;
+    admittedOrgScopes: readonly string[];
+    ownOrgVerdict: import("../memory-admission.js").OwnOrgAdmissionVerdict | undefined;
 }
 export declare function prepareMemory(input: PrepareMemoryInput): Promise<PrepareMemoryResult>;

package/dist/core/runner/prepare-memory.js

@@ -1,3 +1,4 @@
+import { admitMemoryScopes } from "../memory-admission.js";
 import { adoptLegacyRepoDirs, deriveRepoControlPlaneDir, deriveProjectControlDir, deriveProjectMemoryDir, deriveRepoMemoryDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, lookupProjectIdHint, recordProjectIdHint, resolveMemoryEngineRoot } from "../memory-engine/layout.js";
 import { classifyScopePlanes, derivePersonalControlDir, derivePersonalMemoryDir, mergeHarvestReports, mergeInjections, needsDualRoots, parsedProjectPlane } from "../memory-engine/dual-root.js";
 import { normalizeMemorySpec } from "../memory.js";
@@ -5,8 +6,33 @@ import { MemoryEngine } from "../memory-engine/engine.js";
 import { assertScopeContractPlacement, parseScopeKey, resolveProjectId } from "../memory-engine/scope-contract.js";
 import { FileMemoryEngineBackend } from "../memory-engine/file-backend.js";
 export async function prepareMemory(input) {
-    const { spec, deps, sessionId, taskRootPath, memoryWriteGateRef } = input;
+    const { spec, deps, sessionId, taskRootPath, memoryWriteGateRef, admissionCtx } = input;
     const memorySpec = normalizeMemorySpec(spec.memory);
+    let admittedOrgScopes = [];
+    let ownOrgVerdict;
+    if (memorySpec && memorySpec.enabled && deps.memoryBackend) {
+        const outcome = await admitMemoryScopes({
+            memorySpec,
+            principal: spec.principal,
+            admission: deps.memoryScopeAdmission,
+            deploymentScopes: new Set(deps.deploymentMemoryScopes ?? []),
+            orgMemoryDenied: admissionCtx.orgMemoryDenied,
+            complianceDegraded: admissionCtx.complianceDegraded,
+            parentAdmittedOrgScopes: admissionCtx.parentAdmittedOrgScopes,
+            priorOwnVerdict: admissionCtx.priorOwnVerdict,
+            governedProvenance: admissionCtx.governedProvenance,
+        });
+        admittedOrgScopes = outcome.admittedOrgScopes;
+        ownOrgVerdict = outcome.ownVerdict;
+        for (const droppedScope of outcome.droppedDeploymentScopes) {
+            deps.onError?.(new Error(`org memory scope "${droppedScope}" (deployment-declared) was narrowed away (admission resolver or the session's frozen verdict) — the layer is not mounted this session.`), { phase: "memory", sessionId });
+        }
+        if (outcome.writeScopeNarrowed) {
+            deps.onError?.(new Error(`org memory writeScope "${String(memorySpec.writeScope)}" was not explicitly granted by admission — the session's memory write face is read-only (org layers default read-only).`), { phase: "memory", sessionId });
+        }
+        memorySpec.scopes = outcome.scopes;
+        memorySpec.writeScope = outcome.writeScope;
+    }
     const useMemoryEngine = Boolean(memorySpec && memorySpec.enabled && deps.memoryBackend);
     let memoryEngineSession;
     if (useMemoryEngine && memorySpec) {
@@ -193,5 +219,5 @@ export async function prepareMemory(input) {
         if (memoryBlock !== undefined && injection.indexSeed !== undefined)
             seedFiles = [injection.indexSeed];
     }
-    return { memoryEngineSession, memoryBlock, ...(seedFiles !== undefined ? { seedFiles } : {}) };
+    return { memoryEngineSession, memoryBlock, admittedOrgScopes, ownOrgVerdict, ...(seedFiles !== undefined ? { seedFiles } : {}) };
 }

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

@@ -1,5 +1,6 @@
 import { AgentHarness, type ThinkingLevel } from "../../internal/harness.js";
 import type { Model } from "../../internal/llm.js";
+import { type CompactionForkContext } from "../auto-compaction.js";
 import { type MaterializedMcp } from "../mcp.js";
 import { type MaterializedA2a } from "../a2a.js";
 import type { HarvestReport, MemorySessionHandle } from "../memory-engine/types.js";
@@ -199,6 +200,7 @@ export interface Prepared {
     toolEffects: Map<string, ToolEffect>;
     wakeRecovered: RecoveredOrphan[];
     promptOverheadTokens: number;
+    lastBrainContext: () => CompactionForkContext | undefined;
     readTaskFile?: (path: string) => Promise<string | null>;
     recentlyReadFiles?: () => string[];
     normalizeAttachmentPath?: (raw: string) => Promise<string>;
@@ -302,6 +304,8 @@ export interface InheritedGate {
         rules: SessionPermissionRules;
     }>;
     shellGate?: "off" | "always" | "classify";
+    admittedOrgScopes?: readonly string[];
+    orgAdmissionGoverned?: true;
     parentConstraints?: ReadonlyArray<{
         policy: ToolPolicy;
         onAsk?: OnAsk;