@sema-agent/core 5.41.0 → 5.43.0

package/dist/core/runner/prepare-hands-readface.js

@@ -0,0 +1,283 @@
+import { emitTrace } from "../trace.js";
+import { StubExecutionEnv } from "../stub-env.js";
+import { hasBackgroundShell } from "../background-shell.js";
+import { defaultTaskRegistry } from "../task-registry.js";
+import { bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, pdfModelCapabilitiesOf, resolveReadDenyBuiltins, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
+import { resolveKey } from "../../tools/fs/safety.js";
+import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
+import { deliverEngineNotice } from "../types.js";
+import { rebaseWorkspacePath } from "./prepare-workspace-restore.js";
+const readFaceClampAnnouncedSinks = new WeakSet();
+let readFaceClampConsoleAnnounced = false;
+export function __resetReadFaceClampAnnouncement() {
+    readFaceClampConsoleAnnounced = false;
+}
+export function resolveHandsLessReadFace(input) {
+    const { resume, fullShellReachable, spec, deps } = input;
+    let handsLessResolvedFace;
+    let readDenyAdditionsNormalized = [];
+    {
+        const liveFace = resolveReadFace({
+            specReadFace: spec.readFace,
+            depsReadFace: deps.readFace,
+            readOnlyMount: spec.handsReadOnly === true,
+            orgGoverned: deps.permissionRuleOrg !== undefined,
+            fullShellReachable,
+        });
+        const seed = resume?.seed.readFace;
+        handsLessResolvedFace = resume !== undefined && (seed === undefined || seed.face === "roots") ? "roots" : liveFace;
+        const denyAdditions = [...(deps.readDenyPatterns ?? []), ...(spec.readDenyPatterns ?? []), ...(seed?.denyEntries ?? [])];
+        resolveReadDenyBuiltins({
+            ...(deps.readDenyBuiltinTiers !== undefined ? { tiers: deps.readDenyBuiltinTiers } : {}),
+            ...(deps.readDenyBuiltinExclude !== undefined ? { exclude: deps.readDenyBuiltinExclude } : {}),
+        });
+        if (denyAdditions.length > 0) {
+            readDenyAdditionsNormalized = compileReadDeny(denyAdditions, "readDenyPatterns", { tiers: [] }).entries;
+        }
+    }
+    return {
+        readFileStateForCheckpoint: undefined,
+        seedContextFiles: undefined,
+        handsCwdRef: undefined,
+        workspaceStateSettle: undefined,
+        wsSnapshot: undefined,
+        rebaseWsPath: (p) => p,
+        backgroundTaskToolsActive: false,
+        resolvedReadFace: undefined,
+        readDenyAdditionsNormalized,
+        handsLessResolvedFace,
+        additionalRootsCanonical: [],
+        additionalReadRootsCanonical: [],
+        attachmentRootCanonical: undefined,
+        readDenyMatcher: undefined,
+        shellGatedBash: false,
+        shellGatedMonitor: false,
+    };
+}
+export async function prepareHandsMount(input) {
+    const { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, firstPartyOffload, tools, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes } = input;
+    let readFileStateForCheckpoint;
+    let seedContextFiles;
+    let handsCwdRef;
+    let workspaceStateSettle;
+    let wsSnapshot;
+    let rebaseWsPath = (p) => p;
+    let backgroundTaskToolsActive = false;
+    let resolvedReadFace;
+    let readDenyAdditionsNormalized = [];
+    let handsLessResolvedFace;
+    let shellGatedBash = false;
+    let shellGatedMonitor = false;
+    const additionalRootsCanonical = [];
+    const additionalReadRootsCanonical = [];
+    let attachmentRootCanonical;
+    let readDenyMatcher;
+    if (handsEnabled) {
+        const rootRaw = taskRootFinal;
+        const canon = await executionEnv.canonicalPath(rootRaw);
+        const rootCanonical = canon.ok ? canon.value : rootRaw;
+        attachmentRootCanonical = rootCanonical;
+        const canonicalizeExtraDirs = async (dirs, field, sink) => {
+            for (const dir of dirs ?? []) {
+                if (!dir || !dir.trim())
+                    continue;
+                const c = await executionEnv.canonicalPath(dir);
+                if (c.ok) {
+                    sink.push(c.value);
+                }
+                else {
+                    deps.onError?.(new Error(`${field} entry skipped (cannot canonicalize): ${dir}`), {
+                        phase: "config",
+                        sessionId,
+                    });
+                    emitTrace(deps.tracer, () => ({
+                        kind: "config.additional_directory_skipped",
+                        version: 1,
+                        taskId: hostTaskId,
+                        entry: dir,
+                        ...(field !== "additionalDirectories" ? { field } : {}),
+                        reason: `${c.error.code}: ${c.error.message}`,
+                        ts: Date.now(),
+                    }));
+                }
+            }
+        };
+        await canonicalizeExtraDirs(spec.additionalDirectories, "additionalDirectories", additionalRootsCanonical);
+        await canonicalizeExtraDirs(spec.additionalReadDirectories, "additionalReadDirectories", additionalReadRootsCanonical);
+        if (spec.envFacts?.scratchpadDir) {
+            let c = await executionEnv.canonicalPath(spec.envFacts.scratchpadDir);
+            if (!c.ok && c.error.code === "not_found") {
+                const marker = await executionEnv.joinPath([spec.envFacts.scratchpadDir, ".sema-scratchpad"]);
+                const exclusiveCreate = executionEnv.writeFileExclusive?.bind(executionEnv);
+                if (marker.ok && exclusiveCreate) {
+                    const w = await exclusiveCreate(marker.value, "");
+                    if (w.ok || w.error.code === "already_exists")
+                        c = await executionEnv.canonicalPath(spec.envFacts.scratchpadDir);
+                }
+            }
+            if (c.ok)
+                additionalRootsCanonical.push(c.value);
+        }
+        for (const a of [additionalRootsCanonical, additionalReadRootsCanonical])
+            a.splice(0, a.length, ...new Set(a));
+        const readFileState = new Map((resume?.seed.readFileState ?? []).map(([k, v]) => [rebaseRestoredPath(k), v]));
+        readFileStateForCheckpoint = readFileState;
+        seedContextFiles = async (files) => {
+            for (const f of files) {
+                const rk = await resolveKey(executionEnv, rootCanonical, f.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, resolvedReadFace);
+                if (rk.ok)
+                    seedReadFileStateFromContext(readFileState, rk.key, f.content);
+            }
+        };
+        const handsIncludeShell = !(executionEnv instanceof StubExecutionEnv);
+        const handsReadOnly = spec.handsReadOnly === true;
+        backgroundTaskToolsActive = handsIncludeShell && !handsReadOnly && hasBackgroundShell(executionEnv);
+        wsSnapshot = resume !== undefined || !(handsIncludeShell && !handsReadOnly) ? undefined : await session.getWorkspaceState().catch(() => undefined);
+        rebaseWsPath = (p) => (wsSnapshot === undefined || wsSnapshot.taskRoot === rootCanonical ? p : rebaseWorkspacePath(p, wsSnapshot.taskRoot, rootCanonical));
+        if (handsIncludeShell && !handsReadOnly) {
+            handsCwdRef = { current: rootCanonical };
+            if (resume?.seed.handsCwd !== undefined)
+                handsCwdRef.current = rebaseRestoredPath(resume.seed.handsCwd);
+            else if (wsSnapshot?.handsCwd !== undefined)
+                handsCwdRef.current = rebaseWsPath(wsSnapshot.handsCwd);
+            workspaceStateSettle = {
+                rootCanonical,
+                restoredHandsCwd: handsCwdRef.current !== rootCanonical ? handsCwdRef.current : undefined,
+                ...(resume !== undefined ? { baselineUnknown: true } : {}),
+            };
+        }
+        const seedReadFaceSection = resume?.seed.readFace;
+        const readDenyAdditions = [...(deps.readDenyPatterns ?? []), ...(spec.readDenyPatterns ?? []), ...(seedReadFaceSection?.denyEntries ?? [])];
+        const readDenyBuiltinCfg = {
+            ...(deps.readDenyBuiltinTiers !== undefined ? { tiers: [...deps.readDenyBuiltinTiers] } : {}),
+            ...(deps.readDenyBuiltinExclude !== undefined ? { exclude: [...deps.readDenyBuiltinExclude] } : {}),
+        };
+        readDenyMatcher = compileReadDeny(readDenyAdditions, "readDenyPatterns", readDenyBuiltinCfg);
+        readDenyAdditionsNormalized = compileReadDeny(readDenyAdditions, "readDenyPatterns", { tiers: [] }).entries;
+        let liveReadFace = resolveReadFace({
+            specReadFace: spec.readFace,
+            depsReadFace: deps.readFace,
+            readOnlyMount: handsReadOnly,
+            orgGoverned: deps.permissionRuleOrg !== undefined,
+            fullShellReachable,
+            onDeploymentClamp: () => {
+                const sink = deps.onNotice;
+                if (typeof sink === "function") {
+                    if (readFaceClampAnnouncedSinks.has(sink))
+                        return;
+                    readFaceClampAnnouncedSinks.add(sink);
+                }
+                else {
+                    if (readFaceClampConsoleAnnounced)
+                        return;
+                    readFaceClampConsoleAnnounced = true;
+                }
+                deliverEngineNotice(sink, deploymentReadFaceClampNotice());
+            },
+        });
+        if (resume !== undefined && (seedReadFaceSection === undefined || seedReadFaceSection.face === "roots"))
+            liveReadFace = "roots";
+        resolvedReadFace = liveReadFace;
+        if (resume === undefined && spec.sessionId !== undefined) {
+            const prior = await session.buildContext().catch(() => undefined);
+            for (const rec of wholeFileRecordsFromTranscript(prior?.messages ?? [])) {
+                const rk = await resolveKey(executionEnv, rootCanonical, rec.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, liveReadFace);
+                if (rk.ok)
+                    seedReadFileStateFromTranscript(readFileState, rk.key, rec.content, rec.at);
+            }
+        }
+        const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
+            ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
+            ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),
+            ...(readDenyAdditions.length > 0 ? { readDenyPatterns: readDenyAdditions } : {}),
+            ...(readDenyBuiltinCfg.tiers !== undefined ? { readDenyBuiltinTiers: readDenyBuiltinCfg.tiers } : {}),
+            ...(readDenyBuiltinCfg.exclude !== undefined ? { readDenyBuiltinExclude: readDenyBuiltinCfg.exclude } : {}),
+            readFace: liveReadFace,
+            includeShell: handsIncludeShell,
+            readOnly: handsReadOnly,
+            ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),
+            taskRegistry: defaultTaskRegistry,
+            taskOwner: hostTaskId,
+            taskScope,
+            oneShot: spec.oneShot,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+            ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
+            ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
+            ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
+            pdfModelCapabilities: pdfModelCapabilitiesOf(model),
+            ...(deps.hands?.bashReadonlyAllow !== undefined ? { bashReadonlyAllow: deps.hands.bashReadonlyAllow } : {}),
+            ...(deps.hands?.commitCoAuthor !== undefined ? { commitCoAuthor: deps.hands.commitCoAuthor } : {}),
+            ...(deps.hands?.readImageDownsampler !== undefined ? { readImageDownsampler: deps.hands.readImageDownsampler } : {}),
+            ...(deps.hands?.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: deps.hands.autoBackgroundOnTimeout } : {}),
+            ...(deps.hands?.readCyberReminder !== undefined ? { readCyberReminder: deps.hands.readCyberReminder } : {}),
+            beforeWrite: async (w) => {
+                const deploymentGate = deps.hands?.beforeWrite;
+                if (deploymentGate) {
+                    const verdict = await deploymentGate(w);
+                    if (verdict !== undefined && verdict.ok === false)
+                        return verdict;
+                }
+                return memoryWriteGateRef.current?.(w);
+            },
+            mountBackgroundTaskTools: false,
+            monitorToolActive: backgroundTaskToolsActive && !(toolFaceSnapshot.exclude?.includes("Monitor") ?? false),
+        });
+        {
+            const bandNames = new Set(band.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+            const shadowed = (spec.tools ?? []).filter((t) => [t.name, ...(t.aliases ?? [])].some((n) => bandNames.has(n)));
+            if (shadowed.length > 0) {
+                const names = shadowed.map((t) => `"${t.name}"`).join(", ");
+                deps.onError?.(new Error(`spec.tools ${shadowed.length > 1 ? "entries" : "entry"} ${names} collide${shadowed.length > 1 ? "" : "s"} with the built-in hands tool band — the built-in wins (registered later; the harness tool Map is last-write-wins) and the caller tool never dispatches this task. Rename the caller tool, or don't inject executionEnv if you intend to replace the band.`), { phase: "config", sessionId });
+            }
+        }
+        tools.push(...band.map((t) => firstPartyOffload(t)));
+        const shellGate = effectiveShellGate;
+        if (shellGate === "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
+            deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — no shell safety-axis ` +
+                `fold applies to this run (commands are adjudicated by the ordinary policy/hook chain only). ` +
+                `Set spec.shellGate to "classify" or "always" if this deployment expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
+        }
+        if (shellGate !== "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
+            const bashTierBefore = irreversibilityTier.get("Bash");
+            shellGatedBash = !egressTools.has("Bash") && bashTierBefore !== "always" && bashTierBefore !== "maybe";
+            const bashEffectiveTier = shellGate === "always" || bashTierBefore === "always" ? "always" : "maybe";
+            irreversibilityTier.set("Bash", bashEffectiveTier);
+            irreversibleTools.add("Bash");
+            const shellReadBoundary = () => ({
+                roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
+                ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
+                denyMatch: (p) => readDenyMatcher?.matchPath(p)?.pattern ?? null,
+                ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
+            });
+            if (shellGate === "classify" && shellGatedBash)
+                reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
+            if (backgroundTaskToolsActive) {
+                const monitorTierBefore = irreversibilityTier.get("Monitor");
+                shellGatedMonitor = !egressTools.has("Monitor") && monitorTierBefore !== "always" && monitorTierBefore !== "maybe";
+                const monitorEffectiveTier = shellGate === "always" || monitorTierBefore === "always" ? "always" : "maybe";
+                irreversibilityTier.set("Monitor", monitorEffectiveTier);
+                irreversibleTools.add("Monitor");
+                if (shellGate === "classify" && shellGatedMonitor)
+                    reversibilityProbes.set("Monitor", bashReversibilityProbe(undefined, shellReadBoundary));
+            }
+        }
+    }
+    return {
+        readFileStateForCheckpoint,
+        seedContextFiles,
+        handsCwdRef,
+        workspaceStateSettle,
+        wsSnapshot,
+        rebaseWsPath,
+        backgroundTaskToolsActive,
+        resolvedReadFace,
+        readDenyAdditionsNormalized,
+        handsLessResolvedFace,
+        additionalRootsCanonical,
+        additionalReadRootsCanonical,
+        attachmentRootCanonical,
+        readDenyMatcher,
+        shellGatedBash,
+        shellGatedMonitor,
+    };
+}

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

@@ -37,11 +37,7 @@ export declare function __resetMaterializeEnvAnnouncements(): void;
  *  seam below (console latch only): tests here legitimately reuse ONE sink across prepares to pin
  *  the per-sink dedup itself, so the seam must be able to re-arm a still-referenced sink. */
 export declare function __resetToolModelGateAnnouncements(): void;
-/** Test seam (mirrors `__resetMalformedNoticeSeatAnnouncement`): never called by production code.
- *  Deliberately asymmetric — it resets only the console latch: the WeakSet arm needs no seam
- *  because a test resets it by minting a fresh sink function (identity IS the ledger key), while
- *  the console arm's key is the process itself, which only this seam can refresh. */
-export declare function __resetReadFaceClampAnnouncement(): void;
+export { __resetReadFaceClampAnnouncement } from "./prepare-hands-readface.js";
 /**
  * design/164 件四 — how long before an execution environment's declared `lifetimeMs` expires the engine
  * stops the run and checkpoints it. The margin has to cover ONE suspend: pausing/snapshotting the
@@ -437,6 +433,7 @@ export interface Prepared {
      *  fired this run. */
     suspendRef: {
         token?: CheckpointToken;
+        checkpointId?: string;
         gate?: CheckpointGate;
         scope?: string;
         restoreMode?: "snapshot" | "park_only";
@@ -457,6 +454,7 @@ export interface Prepared {
      *  `status:"needs_review"`. Empty unless a review pause fired this run. */
     reviewRef: {
         token?: CheckpointToken;
+        checkpointId?: string;
         gate?: CheckpointGate;
         scope?: string;
         restoreMode?: "snapshot" | "park_only";