@sema-agent/core 1.451.0 → 2.0.0

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

@@ -0,0 +1,191 @@
+import { deriveControlPlaneDir, 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";
+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 memorySpec = normalizeMemorySpec(spec.memory);
+    const useMemoryEngine = Boolean(memorySpec && memorySpec.enabled && deps.memoryBackend);
+    let memoryEngineSession;
+    if (useMemoryEngine && memorySpec) {
+        try {
+            const backend = deps.memoryBackend;
+            const pinned = backend.directoryRoot;
+            const engineRoot = resolveMemoryEngineRoot(deps.memoryEngineDir);
+            const repoRoot = deps.rootPath ?? taskRootPath;
+            let identityKey;
+            if (memorySpec.scopeContract === "v2" && repoRoot) {
+                const consumesProjectIdentity = [...memorySpec.scopes, ...(memorySpec.writeScope !== null ? [memorySpec.writeScope] : [])]
+                    .map(parseScopeKey)
+                    .some((k) => k.kind === "proj" || k.kind === "userproj");
+                let marker = null;
+                try {
+                    marker = resolveProjectId(repoRoot);
+                }
+                catch (err) {
+                    if (consumesProjectIdentity)
+                        throw err;
+                    deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
+                }
+                if (marker) {
+                    identityKey = marker.projectId;
+                    const firstSwitch = lookupProjectIdHint(engineRoot, repoRoot) !== marker.projectId;
+                    recordProjectIdHint(engineRoot, repoRoot, marker.projectId);
+                    if (firstSwitch) {
+                        try {
+                            const oldCtl = deriveControlPlaneDir(engineRoot, repoRoot);
+                            const newCtl = deriveProjectControlDir(engineRoot, marker.projectId);
+                            const drained = drainMemoryAnnouncements(oldCtl);
+                            for (const ann of drained.queue)
+                                enqueueMemoryAnnouncement(newCtl, ann);
+                        }
+                        catch {
+                        }
+                    }
+                    if (memorySpec.writeScope !== null) {
+                        const w = parseScopeKey(memorySpec.writeScope);
+                        if ((w.kind === "proj" || w.kind === "userproj") && w.projectId !== marker.projectId) {
+                            const e = new Error(`memory scope contract v2: writeScope ${memorySpec.writeScope} targets projectId ${w.projectId}, ` +
+                                `but this checkout's marker (.sema/project) declares ${marker.projectId} — refusing a mis-addressed write.`);
+                            e.code = "config.memory_project_identity";
+                            throw e;
+                        }
+                    }
+                }
+                else {
+                    const hint = lookupProjectIdHint(engineRoot, repoRoot);
+                    if (hint !== undefined) {
+                        deps.onError?.(new Error(`memory project marker missing but recoverable: ${repoRoot} previously carried projectId ${hint} ` +
+                            `(.sema/project deleted?). Restore the marker to keep the identity-keyed memory mount; this session ` +
+                            `falls back to the path-derived key.`), { phase: "config", sessionId });
+                    }
+                }
+            }
+            const memoryDir = typeof pinned === "string" && pinned
+                ? pinned
+                : identityKey !== undefined
+                    ? deriveProjectMemoryDir(engineRoot, identityKey)
+                    : deriveRepoMemoryDir(engineRoot, repoRoot);
+            const planes = memorySpec.scopeContract === "v2" ? classifyScopePlanes(memorySpec.scopes, memorySpec.writeScope) : undefined;
+            const dual = planes !== undefined && needsDualRoots(planes);
+            const personalOnly = planes !== undefined && !dual && planes.project.length === 0 && planes.writePlane !== "project" && (planes.personal.length > 0 || planes.writePlane === "personal");
+            if (memorySpec.scopeContract === "v2" && !personalOnly) {
+                assertScopeContractPlacement({
+                    parsedScopes: dual
+                        ? parsedProjectPlane(planes, memorySpec.writeScope)
+                        : [...memorySpec.scopes, ...(memorySpec.writeScope !== null ? [memorySpec.writeScope] : [])].map(parseScopeKey),
+                    memoryDir,
+                    repoRoot,
+                });
+            }
+            const personalMemoryDir = derivePersonalMemoryDir(engineRoot);
+            const personalControlDir = derivePersonalControlDir(engineRoot);
+            const createPersonalEngine = () => new MemoryEngine({
+                backend: typeof pinned === "string" && pinned
+                    ? new FileMemoryEngineBackend(personalMemoryDir, { controlDir: personalControlDir })
+                    : backend,
+                memoryDir: personalMemoryDir,
+                controlDir: personalControlDir,
+            });
+            let writeEngine;
+            let writeHandle;
+            let injectFn;
+            let harvestBoth;
+            if (dual) {
+                const projectEngine = new MemoryEngine({
+                    backend,
+                    memoryDir,
+                    controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveControlPlaneDir(engineRoot, repoRoot),
+                });
+                const personalEngine = createPersonalEngine();
+                const p = planes;
+                const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null);
+                const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null);
+                const writeIsPersonal = p.writePlane === "personal";
+                writeEngine = writeIsPersonal ? personalEngine : projectEngine;
+                writeHandle = writeIsPersonal ? personalHandle : projectHandle;
+                injectFn = () => mergeInjections(projectEngine.inject(projectHandle), personalEngine.inject(personalHandle));
+                harvestBoth = async () => {
+                    const writeFirst = writeIsPersonal ? [personalEngine, personalHandle] : [projectEngine, projectHandle];
+                    const readOther = writeIsPersonal ? [projectEngine, projectHandle] : [personalEngine, personalHandle];
+                    const writeReport = await writeFirst[0].harvest(writeFirst[1]);
+                    let readReport;
+                    let readFailure;
+                    try {
+                        readReport = await readOther[0].harvest(readOther[1]);
+                    }
+                    catch (err) {
+                        readFailure = err instanceof Error ? err.message : String(err);
+                    }
+                    const merged = readReport !== undefined ? mergeHarvestReports(writeReport, readReport) : writeReport;
+                    if (readFailure !== undefined)
+                        merged.warnings.push(`read-plane harvest failed (write-plane yield committed): ${readFailure}`);
+                    return merged;
+                };
+            }
+            else if (personalOnly) {
+                const personalEngine = createPersonalEngine();
+                const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope);
+                writeEngine = personalEngine;
+                writeHandle = handle;
+                injectFn = () => personalEngine.inject(handle);
+                harvestBoth = () => personalEngine.harvest(handle);
+            }
+            else {
+                const engine = new MemoryEngine({
+                    backend,
+                    memoryDir,
+                    controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveControlPlaneDir(engineRoot, repoRoot),
+                });
+                const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope);
+                writeEngine = engine;
+                writeHandle = handle;
+                injectFn = () => engine.inject(handle);
+                harvestBoth = () => engine.harvest(handle);
+            }
+            memoryWriteGateRef.current = (w) => writeEngine.gateWrite(writeHandle, w.key, w.content);
+            const harvestSafe = async (phase = "terminal") => {
+                try {
+                    const report = await harvestBoth();
+                    if (!report.ok && report.incident) {
+                        deps.onError?.(new Error(`memory harvest refused (${report.incident.kind}): ${report.incident.detail}`), { phase: "memory", sessionId });
+                    }
+                    try {
+                        deps.onMemoryHarvestReport?.(report, { sessionId, phase });
+                    }
+                    catch {
+                    }
+                    return report;
+                }
+                catch (err) {
+                    try {
+                        deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "memory", sessionId });
+                    }
+                    catch {
+                    }
+                    return undefined;
+                }
+            };
+            memoryEngineSession = { engine: writeEngine, handle: writeHandle, inject: injectFn, harvest: harvestSafe };
+        }
+        catch (err) {
+            if (typeof err.code === "string" && (err.code.startsWith("config.memory_scope") || err.code.startsWith("config.memory_project"))) {
+                throw err;
+            }
+            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "memory", sessionId });
+        }
+    }
+    let memoryBlock;
+    if (memorySpec && memorySpec.enabled && !useMemoryEngine) {
+        const detail = "TaskSpec.memory is enabled but RunnerDeps.memoryBackend is not configured; memory is inactive for this task (the legacy memoryStore fallback was retired in design/138 S4 and the dep was removed in design/157 B19).";
+        deps.onError?.(new Error(detail), { phase: "config", sessionId });
+    }
+    if (memoryEngineSession) {
+        const injection = memoryEngineSession.inject();
+        if (injection.block.trim())
+            memoryBlock = injection.block;
+    }
+    return { memoryEngineSession, memoryBlock };
+}

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

@@ -1,7 +1,6 @@
 import { AgentHarness, type ThinkingLevel } from "../../internal/harness.js";
 import type { Model } from "../../internal/llm.js";
 import { type MaterializedMcp } from "../mcp.js";
-import { MemoryEngine } from "../memory-engine/engine.js";
 import type { HarvestReport, MemorySessionHandle } from "../memory-engine/types.js";
 import { StoredSession } from "../session.js";
 import type { SessionStore } from "../session.js";
@@ -12,28 +11,14 @@ import { type CutKillRegistry } from "./cut-kill.js";
 import type { SessionPermissionRules } from "../session-policy-store.js";
 import { CacheBreakDetector, type ToolFingerprintInput } from "../cache-break-detector.js";
 import { type OutputRef, type BlockedRef, type SkillListingEntry } from "./synthetic-tools.js";
-import { type ConsolidationNote } from "./memory-consolidation.js";
+import type { MemoryEngine } from "../memory-engine/engine.js";
 import type { TaskNotificationPayload } from "../task-notification.js";
 import { type CwdRef } from "../../tools/fs/index.js";
 import type { Runner } from "./runtask.js";
 import { type CheckpointGate, type CheckpointState, type CheckpointToken, type ResourceLedger, type ResourceLimitReason } from "../checkpoint-store.js";
 import type { AgentMessage, AgentTool, ExecutionEnv } from "../../internal/harness.js";
-import type { ModelRole, RunnerDeps, TaskEvent, TaskSpec, ToolActivity, ToolEffect } from "../types.js";
+import type { RunnerDeps, TaskEvent, TaskSpec, ToolActivity, ToolEffect } from "../types.js";
 import type { RepairBundle } from "../../agents/repair-loop.js";
-export interface PreparedConsolidation {
-    scope: string;
-    notes: ConsolidationNote[];
-    settings: {
-        role: ModelRole;
-        band: {
-            lo: number;
-            hi: number;
-        };
-        searchLimit: number;
-        maxNotes: number;
-        timeoutSec: number;
-    };
-}
 export declare const DEFAULT_IRREVERSIBLE_SCOPE = "irreversible";
 export declare function checkpointScopeOf(spec: {
     durableApproval?: {
@@ -61,7 +46,6 @@ export interface Prepared {
         tokens: number;
         turns: number;
         tasks: number;
-        costUsd: number;
         costMicroUsd: number;
     };
     cwdRef?: CwdRef;
@@ -88,7 +72,7 @@ export interface Prepared {
         tools: ToolFingerprintInput[];
     };
     promptManifest: {
-        constitution: "core" | "replaced" | "provider-assembled" | "legacy";
+        constitution: "core" | "replaced" | "provider-assembled";
         blocks: Array<{
             id: string;
             chars: number;
@@ -130,7 +114,6 @@ export interface Prepared {
         apply: (committedArtifactDigest?: string) => void;
     } | undefined;
     activeTools: Set<string>;
-    consolidation?: PreparedConsolidation;
     memoryEngineSession?: {
         engine: MemoryEngine;
         handle: MemorySessionHandle;
@@ -255,13 +238,6 @@ export interface Prepared {
     trimPressureRef: {
         droppedMessages: boolean;
     };
-    dynamicRecall?: {
-        selector: import("../memory-recall.js").MemorySelector;
-        scopes: string[];
-        recentTools: string[];
-        surfacedIds: Set<string>;
-        surfacedKeys: Set<string>;
-    };
 }
 export interface PrepareResume {
     leafId: string;
@@ -350,4 +326,4 @@ export declare function batchContextAt(messages: AgentMessage[], currentId: stri
     completedCallIds: string[];
 };
 export declare function rebaseWorkspacePath(p: string, fromRaw: string, toRaw: string): string;
-export declare function prepareTask(spec: TaskSpec, deps: RunnerDeps, sessions: SessionStore, resume?: PrepareResume, _memorySelector?: import("../memory-recall.js").MemorySelector, internals?: RunInternals, runnerSelf?: Runner): Promise<Prepared>;
+export declare function prepareTask(spec: TaskSpec, deps: RunnerDeps, sessions: SessionStore, resume?: PrepareResume, internals?: RunInternals, runnerSelf?: Runner): Promise<Prepared>;

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

@@ -11,11 +11,6 @@ import { primaryActivityArg } from "../arg-summary.js";
 import { materializeMcpTools } from "../mcp.js";
 import { Type } from "typebox";
 import { brainToRuntime } from "../runtime.js";
-import { MemoryEngine } from "../memory-engine/engine.js";
-import { deriveControlPlaneDir, deriveProjectControlDir, deriveProjectMemoryDir, deriveRepoMemoryDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, lookupProjectIdHint, recordProjectIdHint, resolveMemoryEngineRoot } from "../memory-engine/layout.js";
-import { assertScopeContractPlacement, parseScopeKey, resolveProjectId } from "../memory-engine/scope-contract.js";
-import { classifyScopePlanes, derivePersonalControlDir, derivePersonalMemoryDir, mergeHarvestReports, mergeInjections, needsDualRoots, parsedProjectPlane } from "../memory-engine/dual-root.js";
-import { FileMemoryEngineBackend } from "../memory-engine/file-backend.js";
 import { StoredSession, isSessionConflict, hasSessionFork } from "../session.js";
 import { createAgentTranscriptTool, createSendMessageTool, createSubagentWorktreeHelper, forkGovernanceDenial, AGENT_TRANSCRIPT_TOOL_NAME, SEND_MESSAGE_TOOL_NAME, SubagentRetainLedger } from "../../agents/subagent.js";
 import { combinePolicies, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, resolveAsk, toolPolicyNameSets } from "../tool-policy.js";
@@ -32,12 +27,12 @@ import { reservedCollisions, reservedFor } from "../../brain/request-params.js";
 import { defineTool } from "../tools.js";
 import { canonicalToolName } from "../tool-name-aliases.js";
 import { pathToUri } from "../lsp-protocol.js";
-import { DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, firstPartyOffloadPolicy, InMemoryToolResultStore, RunnerSharedToolResultStore, ScopedToolResultStore, isVolatileOffloadStore, OFFLOAD_TOOL_NAME, makeReadToolResultTool, withToolResultOffload, } from "../tool-result-store.js";
-import { OUTPUT_TOOL_NAME, REPORT_FINDINGS_TOOL_NAME, SKILL_CONTENT_MAX_CHARS, SKILL_TOOL_NAME, makeOutputTool, makeReportBlockedTool, makeReportFindingsTool, makeSkillTool, normalizeSkills } from "./synthetic-tools.js";
+import { DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, firstPartyOffloadPolicy, InMemoryToolResultStore, RunnerSharedToolResultStore, ScopedToolResultStore, isVolatileOffloadStore, OFFLOAD_TOOL_NAME, createReadToolResultTool, withToolResultOffload, } from "../tool-result-store.js";
+import { OUTPUT_TOOL_NAME, REPORT_FINDINGS_TOOL_NAME, SKILL_CONTENT_MAX_CHARS, SKILL_TOOL_NAME, createOutputTool, createReportBlockedTool, createReportFindingsTool, createSkillTool, normalizeSkills } from "./synthetic-tools.js";
 import { compileOutputSchema } from "./strict-output-schema.js";
-import { TOOL_SEARCH_NAME, buildDeferredRegistry, classifyDeferred, extractDiscoveredToolNames, makePlaceholderTool, makeToolSearchTool, } from "./tool-disclosure.js";
-import { composeMemoryBlock, normalizeMemorySpec } from "../memory.js";
-import {} from "./memory-consolidation.js";
+import { TOOL_SEARCH_NAME, buildDeferredRegistry, classifyDeferred, extractDiscoveredToolNames, createPlaceholderTool, createToolSearchTool, } from "./tool-disclosure.js";
+import { composeMemoryBlock } from "../memory.js";
+import { prepareMemory } from "./prepare-memory.js";
 import { defaultPromptProvider, buildEnvironmentContext, buildGitSnapshot, formatLocalDate, isValidTimeZone, PROJECT_CONTEXT_FRAMING } from "../../prompts/default.js";
 import { assemblePrompt } from "../../prompt-assembly/assemble.js";
 import { auditToolCollisions, projectToolManifest } from "../../prompt-assembly/tool-catalog.js";
@@ -171,7 +166,7 @@ export function rebaseWorkspacePath(p, fromRaw, toRaw) {
     const suffix = p.slice(fromPrefix.length).replace(/^\/+/, "");
     return to === "/" ? `${to}${suffix}` : `${to}/${suffix}`;
 }
-export async function prepareTask(spec, deps, sessions, resume, _memorySelector, internals, runnerSelf) {
+export async function prepareTask(spec, deps, sessions, resume, internals, runnerSelf) {
     const toolFaceSnapshot = {
         exclude: spec.excludeTools ? Object.freeze([...spec.excludeTools]) : undefined,
         defer: spec.deferTools ? Object.freeze([...spec.deferTools]) : undefined,
@@ -413,19 +408,17 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
     if (extraBodyCollisions.length > 0) {
         deps.onError?.(new Error(`model.extraBody contains reserved key(s) [${extraBodyCollisions.join(", ")}] that core owns and sets itself — they are ignored. Remove them from extraBody.`), { phase: "config", sessionId });
     }
-    const nestedStats = { tokens: 0, turns: 0, tasks: 0, costUsd: 0, costMicroUsd: 0 };
+    const nestedStats = { tokens: 0, turns: 0, tasks: 0, costMicroUsd: 0 };
     if (resume) {
         nestedStats.tokens = resume.seed.nestedStats.tokens;
         nestedStats.turns = resume.seed.nestedStats.turns;
         nestedStats.tasks = resume.seed.nestedStats.tasks;
-        nestedStats.costUsd = resume.seed.nestedStats.costUsd;
         nestedStats.costMicroUsd = resume.seed.nestedStats.costMicroUsd;
     }
     const reportUsage = (u) => {
         nestedStats.tokens += u.tokens;
         nestedStats.turns += u.turns;
         nestedStats.tasks += u.tasks;
-        nestedStats.costUsd += u.costUsd ?? 0;
         nestedStats.costMicroUsd += u.costMicroUsd ?? 0;
     };
     const explicitGlobalThreshold = spec.toolResultThresholdChars ?? deps.toolResultThresholdChars;
@@ -801,10 +794,10 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
         }), t));
         const blockedRef = {};
         if (spec.enableBlockedReport !== false) {
-            tools.push(makeReportBlockedTool(blockedRef));
+            tools.push(createReportBlockedTool(blockedRef));
         }
         if (!(spec.tools ?? []).some((t) => t.name === REPORT_FINDINGS_TOOL_NAME || t.aliases?.includes(REPORT_FINDINGS_TOOL_NAME))) {
-            tools.push(makeReportFindingsTool());
+            tools.push(createReportFindingsTool());
         }
         if (spec.enablePlanMode === true && spec.interactiveTools !== false) {
             const planReviewFace = (spec.checkpointStore ?? deps.checkpointStore) !== undefined;
@@ -963,7 +956,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                 catch {
                 }
             }
-            tools.push(makeOutputTool(outputRef, spec.outputSchema, compiled.strict ? compiled.modelSchema : undefined));
+            tools.push(createOutputTool(outputRef, spec.outputSchema, compiled.strict ? compiled.modelSchema : undefined));
         }
         mcp = spec.mcp?.length
             ? await materializeMcpTools(spec.mcp, spec.principal, deps.onElicit, deps.mcpImageResizer)
@@ -999,9 +992,12 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                     const results = await mcp.refresh(typeof serverArg === "string" && serverArg.length > 0 ? serverArg : undefined);
                     const lines = [];
                     let changed = false;
+                    let anyActiveFailure = false;
                     for (const r of results) {
                         if (r.status !== "refreshed" || r.tools === undefined) {
                             lines.push(`${r.server}: ${r.status}${r.error !== undefined ? ` (${r.error})` : ""}`);
+                            if (r.status === "failed")
+                                anyActiveFailure = true;
                             continue;
                         }
                         const excludedSet = new Set(toolFaceSnapshot.exclude ?? []);
@@ -1012,6 +1008,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                         }
                         catch (foldErr) {
                             lines.push(`${r.server}: failed (${foldErr instanceof Error ? foldErr.message : String(foldErr)})`);
+                            anyActiveFailure = true;
                             continue;
                         }
                         for (let i = tools.length - 1; i >= 0; i--) {
@@ -1041,7 +1038,12 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                         lines.push("WARNING: refreshed tools declare irreversible/egress safety hints, but this task started with no approval gate registered (no policy/hooks and no gated tools at start) — these hints cannot arm a gate mid-task (RB-46); the refreshed tools run ungated on this deployment shape.");
                     }
                     const text = lines.length === 0 ? "No connected MCP servers to refresh." : lines.join("\n");
-                    return { content: [{ type: "text", text }], details: { results }, terminate: false };
+                    return {
+                        content: [{ type: "text", text }],
+                        details: { results },
+                        terminate: false,
+                        ...(anyActiveFailure && !changed ? { isError: true } : {}),
+                    };
                 },
             });
             toolEffects.set("RefreshMcpTools", "read");
@@ -1206,7 +1208,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
         if (backgroundTaskToolsActive || workflowToolsActive) {
             toolEffects.set("TaskOutput", "read");
             toolEffects.set("TaskStop", "write");
-            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, ...(callCapRef ? { deadlineMs: () => toolCutDeadlineMs(callCapRef, Date.now()) } : {}) })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
+            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, ...(callCapRef ? { deadlineMs: () => toolCutDeadlineMs(callCapRef, Date.now()) } : {}) })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
             if (runnerSelf && !(spec.tools ?? []).some((t) => t.name === SEND_MESSAGE_TOOL_NAME)) {
                 const delegationForRevive = (spec.tools ?? []).find((t) => t.agentListing !== undefined);
                 const reviveSpawn = delegationForRevive !== undefined && deps.backgroundAgentStore !== undefined && deps.mailboxStore !== undefined
@@ -1295,7 +1297,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
             tools.push(...createWorktreeTools(executionEnv, { repoRoot: taskRootPath, cwdRef: handsCwdRef, session: worktreeSessionRef }).map((t) => firstPartyOffload(t)));
         }
         if (offloadStore)
-            tools.push(makeReadToolResultTool(offloadStore));
+            tools.push(createReadToolResultTool(offloadStore));
         const onQuestion = spec.onQuestion ?? deps.onQuestion;
         const durableQuestionFace = (spec.checkpointStore ?? deps.checkpointStore) !== undefined &&
             (spec.durableApproval !== undefined || runtimeCaps?.forceDurableGate === true);
@@ -1360,189 +1362,8 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                     .catch(() => undefined);
             }
             : undefined;
-        const memorySpec = normalizeMemorySpec(spec.memory);
-        const useMemoryEngine = Boolean(memorySpec && memorySpec.enabled && deps.memoryBackend);
-        let memoryEngineSession;
-        if (useMemoryEngine && memorySpec) {
-            try {
-                const backend = deps.memoryBackend;
-                const pinned = backend.directoryRoot;
-                const engineRoot = resolveMemoryEngineRoot(deps.memoryEngineDir);
-                const repoRoot = deps.rootPath ?? taskRootPath;
-                let identityKey;
-                if (memorySpec.scopeContract === "v2" && repoRoot) {
-                    const consumesProjectIdentity = [...memorySpec.scopes, ...(memorySpec.writeScope !== null ? [memorySpec.writeScope] : [])]
-                        .map(parseScopeKey)
-                        .some((k) => k.kind === "proj" || k.kind === "userproj");
-                    let marker = null;
-                    try {
-                        marker = resolveProjectId(repoRoot);
-                    }
-                    catch (err) {
-                        if (consumesProjectIdentity)
-                            throw err;
-                        deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
-                    }
-                    if (marker) {
-                        identityKey = marker.projectId;
-                        const firstSwitch = lookupProjectIdHint(engineRoot, repoRoot) !== marker.projectId;
-                        recordProjectIdHint(engineRoot, repoRoot, marker.projectId);
-                        if (firstSwitch) {
-                            try {
-                                const oldCtl = deriveControlPlaneDir(engineRoot, repoRoot);
-                                const newCtl = deriveProjectControlDir(engineRoot, marker.projectId);
-                                const drained = drainMemoryAnnouncements(oldCtl);
-                                for (const ann of drained.queue)
-                                    enqueueMemoryAnnouncement(newCtl, ann);
-                            }
-                            catch {
-                            }
-                        }
-                        if (memorySpec.writeScope !== null) {
-                            const w = parseScopeKey(memorySpec.writeScope);
-                            if ((w.kind === "proj" || w.kind === "userproj") && w.projectId !== marker.projectId) {
-                                const e = new Error(`memory scope contract v2: writeScope ${memorySpec.writeScope} targets projectId ${w.projectId}, ` +
-                                    `but this checkout's marker (.sema/project) declares ${marker.projectId} — refusing a mis-addressed write.`);
-                                e.code = "config.memory_project_identity";
-                                throw e;
-                            }
-                        }
-                    }
-                    else {
-                        const hint = lookupProjectIdHint(engineRoot, repoRoot);
-                        if (hint !== undefined) {
-                            deps.onError?.(new Error(`memory project marker missing but recoverable: ${repoRoot} previously carried projectId ${hint} ` +
-                                `(.sema/project deleted?). Restore the marker to keep the identity-keyed memory mount; this session ` +
-                                `falls back to the path-derived key.`), { phase: "config", sessionId });
-                        }
-                    }
-                }
-                const memoryDir = typeof pinned === "string" && pinned
-                    ? pinned
-                    : identityKey !== undefined
-                        ? deriveProjectMemoryDir(engineRoot, identityKey)
-                        : deriveRepoMemoryDir(engineRoot, repoRoot);
-                const planes = memorySpec.scopeContract === "v2" ? classifyScopePlanes(memorySpec.scopes, memorySpec.writeScope) : undefined;
-                const dual = planes !== undefined && needsDualRoots(planes);
-                const personalOnly = planes !== undefined && !dual && planes.project.length === 0 && planes.writePlane !== "project" && (planes.personal.length > 0 || planes.writePlane === "personal");
-                if (memorySpec.scopeContract === "v2" && !personalOnly) {
-                    assertScopeContractPlacement({
-                        parsedScopes: dual
-                            ? parsedProjectPlane(planes, memorySpec.writeScope)
-                            : [...memorySpec.scopes, ...(memorySpec.writeScope !== null ? [memorySpec.writeScope] : [])].map(parseScopeKey),
-                        memoryDir,
-                        repoRoot,
-                    });
-                }
-                const personalMemoryDir = derivePersonalMemoryDir(engineRoot);
-                const personalControlDir = derivePersonalControlDir(engineRoot);
-                const makePersonalEngine = () => new MemoryEngine({
-                    backend: typeof pinned === "string" && pinned
-                        ? new FileMemoryEngineBackend(personalMemoryDir, { controlDir: personalControlDir })
-                        : backend,
-                    memoryDir: personalMemoryDir,
-                    controlDir: personalControlDir,
-                });
-                let writeEngine;
-                let writeHandle;
-                let injectFn;
-                let harvestBoth;
-                if (dual) {
-                    const projectEngine = new MemoryEngine({
-                        backend,
-                        memoryDir,
-                        controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveControlPlaneDir(engineRoot, repoRoot),
-                    });
-                    const personalEngine = makePersonalEngine();
-                    const p = planes;
-                    const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null);
-                    const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null);
-                    const writeIsPersonal = p.writePlane === "personal";
-                    writeEngine = writeIsPersonal ? personalEngine : projectEngine;
-                    writeHandle = writeIsPersonal ? personalHandle : projectHandle;
-                    injectFn = () => mergeInjections(projectEngine.inject(projectHandle), personalEngine.inject(personalHandle));
-                    harvestBoth = async () => {
-                        const writeFirst = writeIsPersonal ? [personalEngine, personalHandle] : [projectEngine, projectHandle];
-                        const readOther = writeIsPersonal ? [projectEngine, projectHandle] : [personalEngine, personalHandle];
-                        const writeReport = await writeFirst[0].harvest(writeFirst[1]);
-                        let readReport;
-                        let readFailure;
-                        try {
-                            readReport = await readOther[0].harvest(readOther[1]);
-                        }
-                        catch (err) {
-                            readFailure = err instanceof Error ? err.message : String(err);
-                        }
-                        const merged = readReport !== undefined ? mergeHarvestReports(writeReport, readReport) : writeReport;
-                        if (readFailure !== undefined)
-                            merged.warnings.push(`read-plane harvest failed (write-plane yield committed): ${readFailure}`);
-                        return merged;
-                    };
-                }
-                else if (personalOnly) {
-                    const personalEngine = makePersonalEngine();
-                    const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope);
-                    writeEngine = personalEngine;
-                    writeHandle = handle;
-                    injectFn = () => personalEngine.inject(handle);
-                    harvestBoth = () => personalEngine.harvest(handle);
-                }
-                else {
-                    const engine = new MemoryEngine({
-                        backend,
-                        memoryDir,
-                        controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveControlPlaneDir(engineRoot, repoRoot),
-                    });
-                    const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope);
-                    writeEngine = engine;
-                    writeHandle = handle;
-                    injectFn = () => engine.inject(handle);
-                    harvestBoth = () => engine.harvest(handle);
-                }
-                memoryWriteGateRef.current = (w) => writeEngine.gateWrite(writeHandle, w.key, w.content);
-                const harvestSafe = async (phase = "terminal") => {
-                    try {
-                        const report = await harvestBoth();
-                        if (!report.ok && report.incident) {
-                            deps.onError?.(new Error(`memory harvest refused (${report.incident.kind}): ${report.incident.detail}`), { phase: "memory", sessionId });
-                        }
-                        try {
-                            deps.onMemoryHarvestReport?.(report, { sessionId, phase });
-                        }
-                        catch {
-                        }
-                        return report;
-                    }
-                    catch (err) {
-                        try {
-                            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "memory", sessionId });
-                        }
-                        catch {
-                        }
-                        return undefined;
-                    }
-                };
-                memoryEngineSession = { engine: writeEngine, handle: writeHandle, inject: injectFn, harvest: harvestSafe };
-            }
-            catch (err) {
-                if (typeof err.code === "string" && (err.code.startsWith("config.memory_scope") || err.code.startsWith("config.memory_project"))) {
-                    throw err;
-                }
-                deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "memory", sessionId });
-            }
-        }
-        let memoryBlock;
-        if (memorySpec && memorySpec.enabled && !useMemoryEngine) {
-            const detail = deps.memoryStore
-                ? "RunnerDeps.memoryStore is retired (design/138 S4): the legacy remember/recall tools and <user_memory> injection no longer run. Configure RunnerDeps.memoryBackend (memory engine) instead; this task runs memory-less."
-                : "TaskSpec.memory is enabled but RunnerDeps.memoryBackend is not configured; memory is inactive for this task (the legacy memoryStore fallback was retired in design/138 S4).";
-            deps.onError?.(new Error(detail), { phase: "config", sessionId });
-        }
-        if (memoryEngineSession) {
-            const injection = memoryEngineSession.inject();
-            if (injection.block.trim())
-                memoryBlock = injection.block;
-        }
+        const { memoryEngineSession, memoryBlock: memoryBlockFromEngine } = await prepareMemory({ spec, deps, sessionId, taskRootPath, memoryWriteGateRef });
+        let memoryBlock = memoryBlockFromEngine;
         let instructionSources;
         if (deps.loadProjectMemory) {
             let projectMemoryPhase = spec.sessionId ? "resume" : "fresh";
@@ -1616,7 +1437,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                 e.code = "config.reserved_tool_name";
                 throw e;
             }
-            tools.push(makeSkillTool(skillSpecs, skillScope));
+            tools.push(createSkillTool(skillSpecs, skillScope));
         }
         const skillsListing = skillSpecs.length > 0
             ? {
@@ -1852,10 +1673,10 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
         });
         const assembled = assemblePrompt(buildAssembleInputs(centerAdoption !== undefined ? artifactDeclarations(centerAdoption.artifact) : undefined));
         if (centerAdoption !== undefined && assembled.centerMounted !== true) {
-            const ownsWholePrompt = assembled.constitution === "legacy" || assembled.constitution === "provider-assembled";
+            const ownsWholePrompt = assembled.constitution === "provider-assembled";
             const digest = centerAdoption.artifact.artifactDigest.slice(0, 23);
             if (ownsWholePrompt) {
-                const e = new Error(`center prompt artifact ${digest}… cannot mount: this PromptProvider owns the whole prompt (legacy system()/assembled-identity pass-through) — upgrade the provider to stableBlocks/stableSystem or remove RunnerDeps.promptSource for this deployment`);
+                const e = new Error(`center prompt artifact ${digest}… cannot mount: this PromptProvider owns the whole prompt (assembled-identity pass-through) — upgrade the provider to stableBlocks/stableSystem or remove RunnerDeps.promptSource for this deployment`);
                 e.code = "prompt.center_unmountable";
                 throw e;
             }
@@ -1948,7 +1769,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                 throw e;
             }
             const registry = buildDeferredRegistry(deferred, tools);
-            const placeholders = new Map([...registry.values()].map((i) => [i.name, makePlaceholderTool(i)]));
+            const placeholders = new Map([...registry.values()].map((i) => [i.name, createPlaceholderTool(i)]));
             const { messages } = await session.buildContext();
             for (const n of extractDiscoveredToolNames(messages, registry)) {
                 if (deferred.has(n))
@@ -1982,7 +1803,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                 }
             };
             rebuildHarnessToolsRef.current = () => rematerialize(activeTools);
-            toolSearch = makeToolSearchTool({
+            toolSearch = createToolSearchTool({
                 registry,
                 active: activeTools,
                 rematerialize,

package/dist/core/runner/prompt-suggestions.d.ts

@@ -1,5 +1,5 @@
 import type { Model } from "../../internal/llm.js";
-import type { AgentMessage, ThinkingLevel } from "../../internal/harness.js";
+import type { AgentMessage, ThinkingLevel } from "../../internal/harness-types.js";
 import type { Brain } from "../types.js";
 import type { ModelPricing } from "../pricing.js";
 export interface SuggestionLLM {