@sema-agent/core 7.5.1 → 7.5.2

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

@@ -0,0 +1,233 @@
+import { classifyToolContentOrigin, contentOriginPollutes, delegationCallIsExternal } from "../memory-engine/content-origin.js";
+import { narrowContentSafety, readCardAttestation } from "../memory-engine/delegation-provenance.js";
+import { recordSyncUnattestable, sessionSettlements } from "../memory-engine/delegation-settlement.js";
+import { protocolOf } from "../protocol-table.js";
+import { deliverEngineNotice } from "../types.js";
+import { inlineUntrusted } from "../untrusted-text.js";
+import { fileArgPath } from "../../tools/fs/safety.js";
+export function prepareMemoryEngineSession(input) {
+    const { memoryEngineSession, internals, memoryDelegationEvidence, externalContentTargetActive, lockedPreflight, mcp, sessionId, runId, deps, provenanceForChildrenRef, delegationSettlementRef, spec, envHandToolNames, tools, contentOriginWrapRef } = input;
+    const delegationProvenanceChannel = internals?.delegationProvenance;
+    if (memoryEngineSession !== undefined || delegationProvenanceChannel !== undefined) {
+        const pollution = memoryEngineSession?.pollution;
+        const delegationEvidenceAttestedOnly = memoryDelegationEvidence === "attested-only";
+        let staticMarkWaiverAnnounced = false;
+        const effectiveSafety = narrowContentSafety(delegationProvenanceChannel?.contentSafety, memoryEngineSession?.contentSafety);
+        const trustedTools = effectiveSafety.trustedTools;
+        const execIsExternalContent = effectiveSafety.execIsExternalContent || externalContentTargetActive;
+        provenanceForChildrenRef.current = { trustedTools: [...trustedTools], execIsExternalContent };
+        announceDeclaredMcpContentClasses({
+            entries: lockedPreflight.mcp,
+            statuses: mcp.statuses,
+            execIsExternalContent,
+            sessionId,
+            runId,
+            onNotice: deps.onNotice,
+        });
+        if (memoryEngineSession?.settlement !== undefined) {
+            delegationSettlementRef.current = { controlDir: memoryEngineSession.settlement.controlDir, sessionId: memoryEngineSession.settlement.sessionId };
+        }
+        const recordExternal = () => {
+            if (delegationProvenanceChannel !== undefined)
+                delegationProvenanceChannel.ref.current.sawExternal = true;
+        };
+        const recordIncomplete = () => {
+            if (delegationProvenanceChannel !== undefined)
+                delegationProvenanceChannel.ref.current.incomplete = true;
+        };
+        const callerToolNames = new Set((spec.tools ?? []).map((t) => t.name));
+        const contentOriginWrapped = new WeakSet();
+        const classOf = (t) => externalContentTargetActive && envHandToolNames.has(t.name)
+            ? "external"
+            : classifyToolContentOrigin({
+                declared: t.contentOrigin,
+                isProtocolTool: protocolOf(t.name) !== undefined,
+                isCallerTool: callerToolNames.has(t.name),
+                trusted: trustedTools.has(t.name),
+            });
+        const delegationByName = new Map();
+        for (const t of spec.tools ?? []) {
+            const withFaces = t;
+            if (withFaces.agentToolFaces === undefined && t.agentListing === undefined)
+                continue;
+            delegationByName.set(t.name, { faces: withFaces.agentToolFaces, pool: withFaces.agentToolPool });
+        }
+        const poolToolPollutes = (t) => contentOriginPollutes(classifyToolContentOrigin({
+            declared: t.contentOrigin,
+            isProtocolTool: protocolOf(t.name) !== undefined,
+            isCallerTool: true,
+            trusted: trustedTools.has(t.name),
+        }), execIsExternalContent);
+        const recallTaintJudge = memoryEngineSession?.recallTaint?.judgeDeliveredPath;
+        contentOriginWrapRef.current = () => {
+            for (let i = 0; i < tools.length; i++) {
+                const t = tools[i];
+                if (contentOriginWrapped.has(t))
+                    continue;
+                const origin = classOf(t);
+                const delegation = delegationByName.get(t.name);
+                const isDelegation = delegation !== undefined;
+                const pollutes = contentOriginPollutes(origin, execIsExternalContent);
+                const readsMemoryPlane = recallTaintJudge !== undefined && t.name === "Read";
+                if (!pollutes && !isDelegation && !readsMemoryPlane) {
+                    contentOriginWrapped.add(t);
+                    continue;
+                }
+                const inner = t.execute.bind(t);
+                const mark = (reason, cause) => {
+                    try {
+                        pollution?.markPolluted(reason, cause);
+                    }
+                    catch {
+                    }
+                };
+                const wrapped = {
+                    ...t,
+                    execute: async (toolCallId, params, signal, onUpdate) => {
+                        if (pollutes) {
+                            mark(`tool "${t.name}" (${origin} content class) was invoked in this session`, "observed");
+                            recordExternal();
+                        }
+                        if (!isDelegation) {
+                            if (!readsMemoryPlane)
+                                return inner(toolCallId, params, signal, onUpdate);
+                            const result = await inner(toolCallId, params, signal, onUpdate);
+                            const raw = result;
+                            const contentField = typeof raw === "object" && raw !== null ? raw.content : undefined;
+                            const headText = typeof raw === "string"
+                                ? raw
+                                : typeof contentField === "string"
+                                    ? contentField
+                                    : Array.isArray(contentField) && typeof contentField[0]?.text === "string"
+                                        ? contentField[0].text
+                                        : "";
+                            const delivered = result?.isError !== true &&
+                                result?.details?.type !== "file_unchanged" &&
+                                !headText.startsWith("<system-reminder");
+                            const fp = fileArgPath(params);
+                            if (delivered && fp !== undefined && recallTaintJudge(fp)) {
+                                mark(`the "${t.name}" tool delivered the content of an external-origin memory entry file`, "derived");
+                            }
+                            return result;
+                        }
+                        let preCallLaunchRows;
+                        if (delegationEvidenceAttestedOnly && memoryEngineSession?.settlement !== undefined) {
+                            try {
+                                preCallLaunchRows = new Set(sessionSettlements(memoryEngineSession.settlement.controlDir, memoryEngineSession.settlement.sessionId)
+                                    .filter((r) => r.row.lane === "background" && r.row.toolUseId === toolCallId)
+                                    .map((r) => r.row.settleId));
+                            }
+                            catch {
+                                preCallLaunchRows = undefined;
+                            }
+                        }
+                        const requested = params?.subagent_type;
+                        const external = delegationCallIsExternal({
+                            requestedType: typeof requested === "string" ? requested : undefined,
+                            faces: delegation.faces,
+                            pool: delegation.pool,
+                            isPolluting: poolToolPollutes,
+                        });
+                        const result = await inner(toolCallId, params, signal, onUpdate);
+                        const att = readCardAttestation(result?.details);
+                        if (att === "external") {
+                            mark(`tool "${t.name}" returned the output of a delegated agent that invoked an external-content-class tool at runtime` +
+                                (typeof requested === "string" ? ` (subagent_type "${requested}")` : ""), "observed");
+                            recordExternal();
+                        }
+                        else if (att !== "clean") {
+                            if (external) {
+                                const staticFaceReason = `tool "${t.name}" returned the output of a delegated agent whose tool face can reach external content` +
+                                    (typeof requested === "string" ? ` (subagent_type "${requested}")` : " (no subagent_type named — classified fail-closed)");
+                                if (!delegationEvidenceAttestedOnly) {
+                                    mark(staticFaceReason, "static");
+                                }
+                                else {
+                                    const receiptDetails = result?.details;
+                                    const claimsLaunchReceipt = receiptDetails !== undefined && receiptDetails !== null && receiptDetails.status === "async_launched";
+                                    const claimedSettleId = claimsLaunchReceipt && typeof receiptDetails.settle_id === "string" ? receiptDetails.settle_id : undefined;
+                                    const settlementSeat = memoryEngineSession?.settlement;
+                                    let isLaunchReceipt = false;
+                                    if (claimsLaunchReceipt && settlementSeat !== undefined) {
+                                        try {
+                                            isLaunchReceipt =
+                                                preCallLaunchRows !== undefined &&
+                                                    claimedSettleId !== undefined &&
+                                                    !preCallLaunchRows.has(claimedSettleId) &&
+                                                    sessionSettlements(settlementSeat.controlDir, settlementSeat.sessionId).some((r) => r.row.lane === "background" && r.row.settleId === claimedSettleId && r.row.toolUseId === toolCallId);
+                                        }
+                                        catch {
+                                            isLaunchReceipt = false;
+                                        }
+                                    }
+                                    if (!isLaunchReceipt && settlementSeat !== undefined) {
+                                        try {
+                                            recordSyncUnattestable(settlementSeat.controlDir, { sessionId: settlementSeat.sessionId, toolCallId, now: Date.now });
+                                        }
+                                        catch (err) {
+                                            const e = new Error(`delegated output withheld (fail-closed): the delegation delivered without a provable attestation and the settlement account could not record the fact (${err instanceof Error ? err.message : String(err)}) — repair the memory control plane or retry`);
+                                            e.code = "memory.settlement_record_failed";
+                                            throw e;
+                                        }
+                                    }
+                                }
+                                if (delegationEvidenceAttestedOnly && pollution !== undefined && !staticMarkWaiverAnnounced) {
+                                    staticMarkWaiverAnnounced = true;
+                                    const waivedReason = inlineUntrusted(staticFaceReason, 200);
+                                    deliverEngineNotice(deps.onNotice, {
+                                        code: "memory.delegation_static_mark_waived",
+                                        message: `Delegation static-face pollution mark waived: ${waivedReason}. The deployment configured ` +
+                                            `memoryDelegationEvidence="attested-only", so a static tool-face verdict alone does not mark this ` +
+                                            `session's memory polluted; a delivered "external" attestation and a direct polluting-class ` +
+                                            `invocation still mark, and on a provenance-armed chain this delegation still records as ` +
+                                            `incomplete. At most one notice per prepared task leg.`,
+                                        detail: {
+                                            reason: waivedReason,
+                                            ...(typeof requested === "string" ? { subagentType: inlineUntrusted(requested, 120) } : {}),
+                                            sessionId,
+                                            runId,
+                                        },
+                                    });
+                                }
+                            }
+                            recordIncomplete();
+                        }
+                        return result;
+                    },
+                };
+                contentOriginWrapped.add(wrapped);
+                tools[i] = wrapped;
+            }
+        };
+        contentOriginWrapRef.current();
+    }
+    return { armed: memoryEngineSession !== undefined || delegationProvenanceChannel !== undefined };
+}
+function announceDeclaredMcpContentClasses(args) {
+    for (const entry of args.entries ?? []) {
+        const declaredClass = entry.contentOrigin;
+        if (declaredClass === undefined)
+            continue;
+        const server = inlineUntrusted(String(entry.name), 160);
+        const toolCount = args.statuses?.find((s) => s.name === entry.name)?.toolNames?.length ?? 0;
+        const resourceFaceCaveat = " (Not covered: the cross-server resource faces — ListMcpResourcesTool/ReadMcpResourceTool/ReadMcpResourceDirTool — stay externally classified and still mark.)";
+        const posture = declaredClass === "local"
+            ? `this server's mounted tools' invocations will not mark this session's memory as externally exposed.${resourceFaceCaveat}`
+            : declaredClass === "execution"
+                ? `this server's mounted tools' invocations will not mark this session's memory unless the execIsExternalContent strict upgrade is armed (currently: ${args.execIsExternalContent ? "armed" : "off"}).${resourceFaceCaveat}`
+                : "its tools stay externally classified and this declaration PINS that — the trustedTools allowlist no longer exempts them, and invocations mark this session's memory.";
+        deliverEngineNotice(args.onNotice, {
+            code: "memory.content_class_declared",
+            message: `MCP server "${server}" (${toolCount} tool(s) mounted) is declared ` +
+                `contentOrigin "${declaredClass}" by this deployment's configuration — ${posture}`,
+            detail: {
+                server,
+                contentOrigin: declaredClass,
+                toolCount,
+                ...(declaredClass === "execution" ? { execIsExternalContent: args.execIsExternalContent } : {}),
+                sessionId: args.sessionId,
+                runId: args.runId,
+            },
+        });
+    }
+}

package/dist/core/runner/prepare-park-ask.d.ts

@@ -0,0 +1,164 @@
+/**
+ * design/390 §1.2 M19 (park ask) — prepareTask's PARK CLOSURE and CONTENT-ASK ROUTING closure, verbatim from the driver's
+ * gate-machinery block: `resolveContentAsk` (the question face's delivery race, the binding table's cap and redemption
+ * identity, the stranded-answer disclosure) and `suspendAsk` (the sync-first decline and the park-priority mandates, the
+ * args capture / fidelity projection / re-adjudication steps, the pause-then-cut fence, the gate-kind choice, the row
+ * mint, the commit through the saga and the post-commit publication). The one module-scope helper only this segment
+ * threw (`ParkRefusal`) moved with it. The interface is the dependency list the segment had implicitly (design/238
+ * R-1) — the two closures used to capture every seat here off the driver's scope, which is the capture surface this
+ * decomposition exists to make explicit.
+ *
+ * The thirteen-argument park closure is unchanged: twelve positional seats then the structural {@link AskCarry}, the
+ * shape the gate's one invocation site (`parkWith`) holds. The ask's origin word and the denial-limit fallback ride the
+ * carry onto the row exactly as before — this phase mints no origin, changes no word, adds no arm to the closed set.
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (both closures run per tool call), so the
+ * phase adds no yield between the boundary parks before it and the gate station after it (design/390 §1.5).
+ * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * Both closures exist exactly when the ask lane and the saga do (the same predicate) — an absent lane answers two absent
+ * closures, so the orchestrator grows no branch.
+ */
+import type { AgentHarness, AgentMessage, AgentTool, ExecutionEnv } from "../../internal/harness.js";
+import { type OnQuestion } from "../ask-question.js";
+import { type CheckpointStore } from "../checkpoint-store.js";
+import type { SessionStore } from "../session.js";
+import { type OnAsk, type ToolCallRequest, type ToolPolicy } from "../tool-policy.js";
+import { type ToolResultStore } from "../tool-result-store.js";
+import type { RunnerDeps, RuntimeCaps, TaskSpec } from "../types.js";
+import type { CwdRef } from "../../tools/fs/fs-shared.js";
+import { type ContentAskBinding } from "./content-ask-bindings.js";
+import type { AskLane, ParkAsk, Prepared, SuspendSaga } from "./contracts.js";
+import type { createRuleOffersOf } from "./permission-rule-lanes.js";
+export interface PrepareParkAskInput {
+    /** borrowed-readonly — the in-stream ask lane, or undefined when the gate machinery is inactive (then both closures are
+     *  absent). Read: `composedCallSignal` (the fence and the delivery race), `approvalPreviewOf` (the row's preview). */
+    askLane: AskLane | undefined;
+    /** borrowed-readonly — the durable settlement saga, or undefined (same law). Read: `suspendableEnv` / `parkOnlyRemoteEnv` /
+     *  `parkOnlyHandle` (the pause target), `suspendLoopCapHit`, `serializeCheckpointState`, `inFlightSpendMicroUsd`,
+     *  `compensatePausedVM` (the pause-then-cut arm), `commitSuspendSaga` (the point of no return). */
+    saga: SuspendSaga | undefined;
+    /** borrowed-readonly — the REBOUND spec. Read: `principal` (the question's source identity, the unattended re-scope, the
+     *  row's identity record), `retainBackgroundProcesses` (the park-only sweep gate). Never mutated. */
+    spec: Pick<TaskSpec, "principal" | "retainBackgroundProcesses">;
+    /** borrowed-readonly — the deployment's error face, as a Pick over the SAME `deps` object (receiver preserved for
+     *  `deps.onError?.()`): the park refusals' disclosure, the pin failure. */
+    deps: Pick<RunnerDeps, "onError">;
+    /** borrowed-readonly — the acquired session id (the question's `sourceTaskId`, the row's session and source, every tag). */
+    sessionId: string;
+    /** borrowed-readonly — the leg's checkpoint store, or undefined (then `suspendAsk` is absent — the park predicate's store
+     *  term). Read: the declared fidelity; the saga writes to it. */
+    checkpointStore: CheckpointStore | undefined;
+    /** borrowed-readonly — the wiring-manifest phase's park predicate (`parkLane.effective`): arms `suspendAsk`. */
+    parkLaneArmed: boolean;
+    /** borrowed-readonly — the question-face phase's routability predicate (the mounted question tool is the engine's own,
+     *  resolved against the LIVE roster per call). */
+    contentAskRoutable: (toolCallId: string) => boolean;
+    /** borrowed-readonly — the live question face, or undefined (then a content ask answers `unavailable`). */
+    liveQuestionFace: OnQuestion | undefined;
+    /** borrowed-readonly — the mounted AskUserQuestion tool, or undefined; only its `parameters` schema is read (the pre-delivery
+     *  validation). */
+    mountedQuestionTool: AgentTool | undefined;
+    /** borrowed-mutable — the content-ask binding table (the question-face phase mints it). Writer here: `bindOutcome`
+     *  (`set`, cap-checked before every insertion); the mounted tool and the leg-end settle consume. */
+    contentAskBindings: Map<string, ContentAskBinding>;
+    /** borrowed-mutable — the stranded late answers (the question-face phase mints it). Writer here: the delivery race's
+     *  aborted arm (`push`) when an answer lands after the race. */
+    lateStrandedAnswers: Array<{
+        deliveryId: string;
+        toolCallId: string;
+    }>;
+    /** borrowed-readonly — the question-face phase's stranded-answer disclosure (called on the same late arm). */
+    discloseStrandedAnswers: (records: ReadonlyArray<{
+        deliveryId: string;
+        toolCallId: string;
+    }>, why: string) => void;
+    /** borrowed-readonly — the run's own approver seat, or undefined (the sync-first decline's live-approver test). */
+    onAsk: OnAsk | undefined;
+    /** borrowed-readonly — the resolved per-principal entitlements, or undefined (`forceDurableGate` keeps park priority). */
+    runtimeCaps: RuntimeCaps | undefined;
+    /** borrowed-readonly — the inherited-unavailable marker set; read only here (`has`: park priority and the row's
+     *  `inheritedUnresolved`). The ask lane consumes, the gate station sweeps. */
+    inheritedUnavailableAsks: ReadonlySet<string>;
+    /** borrowed-readonly — the policy the projection re-adjudication consults when the codec moved the value, or undefined
+     *  (then a moved projection refuses the park). Called at park time. */
+    basePolicyForResumeEdit: ToolPolicy | undefined;
+    /** borrowed-readonly — the per-leg-immutable budget snapshot the re-adjudication carries (same object as the main gate). */
+    budgetSnapshot: NonNullable<ToolCallRequest["budget"]>;
+    /** borrowed-readonly — the hand's live tracked cwd, or undefined; `current` is read at park time for the re-adjudication.
+     *  Not written here. */
+    handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the run's offload store, or undefined (a volatile store holding results refuses the park). */
+    offloadStore: ToolResultStore | undefined;
+    /** borrowed-readonly — the per-task owned env, or undefined (a non-remote per-task env refuses the park). Never destroyed. */
+    ownedEnv: ExecutionEnv | undefined;
+    /** borrowed-readonly — the restore-incomplete adapter's missing members, or undefined (names the actual gap in the refusal). */
+    incompleteSuspendAdapter: readonly ("resumeVM" | "postResumeInit")[] | undefined;
+    /** borrowed-readonly — the acquired session; `getLeafId` (the resume point) and `buildContext` (the batch position) are read. */
+    session: Pick<Prepared["session"], "getLeafId" | "buildContext">;
+    /** borrowed-readonly — the session store; only the optional `pin` is called (best-effort, after commit). */
+    sessions: Pick<SessionStore, "pin">;
+    /** borrowed-readonly — the restart-loop chain base (the row's `suspendCount`, the cap's count). */
+    suspendChainBase: () => number;
+    /** borrowed-readonly — the restart-loop cap. */
+    maxSuspends: number;
+    /** borrowed-mutable — the run-scoped remote-lifecycle failure log. Writer here: a refused `suspendVM` (`push`). */
+    remoteEnvFailures: Prepared["remoteEnvFailures"];
+    /** borrowed-readonly — whether Bash is coarsely shell-gated (the risk descriptor's `shellGated`). */
+    shellGatedBash: boolean;
+    /** borrowed-readonly — whether Monitor is coarsely shell-gated (same). */
+    shellGatedMonitor: boolean;
+    /** borrowed-readonly — the effective shell-gate doctrine persisted on the descriptor. */
+    effectiveShellGate: "off" | "classify" | "always";
+    /** borrowed-readonly — the EFFECTIVE durable-approval opt-in (the caller's, or the synthesized mandate scope): picks the
+     *  gate kind, the scope and the ttl. */
+    durableApproval: TaskSpec["durableApproval"];
+    /** borrowed-readonly — the cross-slice ledger carried on the resumed checkpoint, or undefined. */
+    priorLedger: Prepared["resourceLedger"];
+    /** borrowed-readonly — the loop's live spend seat; `.get` is read at mint time. */
+    liveSpendRef: Prepared["liveSpendRef"];
+    /** borrowed-readonly — the human total the first slice seeds the ledger from, or undefined. */
+    resourceTotal: {
+        totalBudgetMicroUsd?: number;
+        totalTokens?: number;
+    } | undefined;
+    /** borrowed-readonly — the inherited-gate phase's three version-stamp predicates (face / F-012 / org admission). */
+    faceCheckpointState: () => boolean;
+    /** borrowed-readonly — see `faceCheckpointState`. */
+    f012CheckpointState: () => boolean;
+    /** borrowed-readonly — see `faceCheckpointState`. */
+    orgAdmissionCheckpointState: () => boolean;
+    /** borrowed-readonly — the policy-chain phase's rule-offer factory (the row's suggestion members). */
+    ruleOffersOf: ReturnType<typeof createRuleOffersOf>;
+    /** borrowed-readonly — the injectable wall clock (the row's `suspendedAt`). */
+    now: () => number;
+    /** borrowed-readonly — the per-task human-review accumulator; snapshotted onto the row (never written here). */
+    humanReviewRef: Prepared["humanReviewRef"];
+    /** borrowed-mutable — prepare's abort seat. Writers here: `abort()` after a committed park and on a failed pause
+     *  compensation; `.signal` is composed into the fence. */
+    abortController: {
+        readonly signal: AbortSignal;
+        abort(): void;
+    };
+    /** borrowed-mutable — the built harness. Writer here: `abort()` (release the gate, then stop the loop). */
+    harness: Pick<AgentHarness, "abort">;
+    /** borrowed-mutable — the durable-suspend holder (`Prepared.suspendRef`). Writer here: the commit-side publication. */
+    suspendRef: Prepared["suspendRef"];
+    /** borrowed-readonly — the review holder; handed to the commit-side discriminant, which never writes it for these kinds. */
+    reviewRef: Prepared["reviewRef"];
+}
+export interface PrepareParkAskResult {
+    /** owned — the two closures as ONE value, or undefined exactly when the ask lane (and so the saga) is absent. */
+    parkAsk: ParkAsk | undefined;
+}
+/** The M19 park-ask phase body — prepareTask's park closure and content-ask routing stretch, verbatim (see the module header). */
+export declare function prepareParkAsk(input: PrepareParkAskInput): PrepareParkAskResult;
+/**
+ * From the resumed/active transcript, the batch position of `currentId` (design/45 §4.ter): the tool-call
+ * ids of the assistant message that issued it (the batch), and the subset already resolved (executed
+ * before the suspend — #1..k-1). ID-based, not positional (council Question #1): immune to reordering.
+ */
+export declare function batchContextAt(messages: AgentMessage[], currentId: string): {
+    batchToolCallIds: string[];
+    completedCallIds: string[];
+};