@sema-agent/core 7.5.0 → 7.5.1

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

@@ -0,0 +1,76 @@
+import { formatLocalDate } from "../../prompts/default.js";
+import { SKILL_TOOL_NAME } from "./synthetic-tools.js";
+import { renderAgentListingDelta } from "./turn-attachments.js";
+export function prepareListings(input) {
+    const { spec, tools, onceLedger, sessionId, toolFaceSnapshot, activeTools, resume, skillsListing, listingRideRef, renderWithDate, envFacts, tzValid, userTz } = input;
+    if (spec.agents !== undefined && spec.agents.length > 0) {
+        const known = new Set(tools.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+        for (const def of spec.agents) {
+            const unknownAllow = (def.allowTools ?? []).filter((n) => n !== "*" && !known.has(n));
+            if (unknownAllow.length > 0) {
+                try {
+                    onceLedger.onError(new Error(`TaskSpec.agents: agent "${def.name}" allows tool(s) ${unknownAllow.join(", ")} not present in this task's assembled roster — likely a typo (the entry would be item-filtered at spawn; the agent stays usable). Advisory only: the delegation pool can differ from this roster, so a tool mounted only on the delegation tool or produced by per-spawn extraTools makes this spurious.`), { phase: "config", sessionId });
+                }
+                catch {
+                }
+            }
+            for (const n of def.denyTools ?? []) {
+                if (n === "*")
+                    continue;
+                if (!known.has(n)) {
+                    const e = new Error(`TaskSpec.agents: agent "${def.name}" declares tool "${n}" in its denied tools, but no such tool exists in this deployment — fix the agent's tools list or mount the tool.`);
+                    e.code = "config.agent.unknown_tool";
+                    throw e;
+                }
+            }
+        }
+    }
+    const rosterBearingSpec = (spec.tools ?? []).find((t) => t.agentListing !== undefined && t.agentListing.length > 0);
+    const rosterFaceDeferred = rosterBearingSpec !== undefined &&
+        !(toolFaceSnapshot.exclude?.includes(rosterBearingSpec.name) ?? false) &&
+        (toolFaceSnapshot.defer?.includes(rosterBearingSpec.name) ?? false) &&
+        !activeTools.has(rosterBearingSpec.name);
+    const agentListingSpec = rosterBearingSpec !== undefined &&
+        !rosterFaceDeferred &&
+        !(toolFaceSnapshot.exclude?.includes(rosterBearingSpec.name) ?? false)
+        ? rosterBearingSpec
+        : undefined;
+    const agentListing = agentListingSpec
+        ? {
+            entries: agentListingSpec.agentListing,
+            toolName: agentListingSpec.name,
+            seedAnnounced: resume !== undefined || spec.sessionId !== undefined,
+            ...(agentListingSpec.agentModels !== undefined ? { models: agentListingSpec.agentModels } : {}),
+        }
+        :
+            !rosterFaceDeferred && ((resume?.seed.announcedListings?.agents?.length ?? 0) > 0 || spec.sessionId !== undefined)
+                ?
+                    {
+                        entries: [],
+                        toolName: (spec.tools ?? []).find((t) => t.agentListing !== undefined)?.name ?? "Agent",
+                        seedAnnounced: true,
+                    }
+                : undefined;
+    if (spec.attachments?.agentListing === false && agentListing !== undefined && agentListing.entries.length > 0) {
+        onceLedger.onError(new Error(`attachments.agentListing is explicitly false but the "${agentListing.toolName}" delegation tool mounts a ${agentListing.entries.length}-type roster — the model will never see the agent-type listing its tool description points to.`), { phase: "config", sessionId });
+    }
+    if (spec.attachments?.skillsListing === false && skillsListing !== undefined && skillsListing.entries.length > 0) {
+        onceLedger.onError(new Error(`attachments.skillsListing is explicitly false but ${skillsListing.entries.length} skill(s) are mounted — the model will never see the skills listing the ${SKILL_TOOL_NAME} tool description points to.`), { phase: "config", sessionId });
+    }
+    const announcedListingsRef = onceLedger.arms();
+    if (rosterFaceDeferred && rosterBearingSpec !== undefined) {
+        const rideEntries = rosterBearingSpec.agentListing;
+        const rideModels = rosterBearingSpec.agentModels;
+        listingRideRef.current = (newly) => {
+            if (!newly.includes(rosterBearingSpec.name))
+                return undefined;
+            if ((announcedListingsRef.agents?.length ?? 0) > 0)
+                return undefined;
+            return renderAgentListingDelta({ announcedAgentTypes: undefined }, rideEntries, rosterBearingSpec.name, rideModels);
+        };
+    }
+    const dateChange = renderWithDate
+        ? { legDate: envFacts.date, today: () => formatLocalDate(new Date(), tzValid ? userTz : undefined) }
+        : undefined;
+    return { agentListing, announcedListingsRef, dateChange };
+}

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

@@ -0,0 +1,55 @@
+/**
+ * design/390 §1.2 M8 — prepareTask's LSP phase, verbatim from the driver: the manager fold (spec > deps), the
+ * LSP tool mount over the per-task env with its git-ignore filter, the diagnostics lane behind its four
+ * preconditions (a manager whose sessions feed a registry, write-capable hands, not opted out), the run-scoped
+ * registry key, and the edit nudge (raw path → the SAME resolution the tool leg uses → registry reset +
+ * session didChange). No manager ⇒ nothing mounts and both lane seats are undefined. The interface is the
+ * dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between the
+ * fork-governance note before it and the memory trio's occupancy read after it (design/390 §1.5 S1: a stretch
+ * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
+ * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ */
+import type { AgentTool, ExecutionEnv } from "../../internal/harness.js";
+import type { LspDiagnosticsRegistry } from "../lsp-diagnostics.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { Prepared } from "./contracts.js";
+export interface PrepareLspInput {
+    /** borrowed-readonly — the REBOUND spec. Read: `lspManager` (the per-task manager, outranks the deployment's),
+     *  `lspDiagnostics` (the lane's opt-out), `handsReadOnly` (a read-only run has no lane). Never mutated. */
+    spec: Pick<TaskSpec, "lspManager" | "lspDiagnostics" | "handsReadOnly">;
+    /** borrowed-readonly — the deployment's manager seat (read only when the spec carries none). */
+    deps: Pick<RunnerDeps, "lspManager">;
+    /** borrowed-readonly — the run's resolved env: the tool's in-env server and git-ignore filter, and the
+     *  session lookup the nudge performs. */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the SETTLED task root: the tool's git-ignore root, and the nudge's resolution base when
+     *  no cwd is tracked. */
+    taskRootFinal: string;
+    /** borrowed-readonly — whether a real fs env is present (the lane's hands precondition). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the acquired session id: the run's key into the deployment-shared registry. */
+    sessionId: string;
+    /** borrowed-readonly — the tracked-cwd cell the hands band writes; the nudge READS `current` per call as its
+     *  resolution base (identity is the contract — the band's `cd` handling writes this exact cell). */
+    handsCwdRef: Prepared["cwdRef"];
+    /** borrowed-mutable — the run's shared roster (identity is the contract). Writer here: ONE push (the LSP tool)
+     *  when a manager exists. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the env-hand membership set the read-posture observer projects; writer here: `add("LSP")`
+     *  on the mount. */
+    envHandToolNames: Set<string>;
+}
+export interface PrepareLspResult {
+    /** borrowed-readonly — the manager's diagnostics registry when the lane is live, else undefined (the
+     *  registry is a DEPLOYMENT object shared by every task; this run reads and resets it under its own key). */
+    lspDiagnostics: LspDiagnosticsRegistry | undefined;
+    /** owned — the edit nudge (raw path in), or undefined when the lane is not live. */
+    nudgeLspOnEdit: ((rawPath: string) => void) | undefined;
+    /** borrowed-readonly — the run's registry key (= the session id): a session hosts one run at a time and the
+     *  run loop releases the key at the terminal. */
+    lspRunIdent: string;
+}
+/** The M8 phase body — prepareTask's LSP stretch, verbatim (see the module header). */
+export declare function prepareLsp(input: PrepareLspInput): PrepareLspResult;

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

@@ -0,0 +1,27 @@
+import { createLspTool, gitCheckIgnoreFilter, resolveLspPath } from "../lsp.js";
+import { pathToUri } from "../lsp-protocol.js";
+export function prepareLsp(input) {
+    const { spec, deps, executionEnv, taskRootFinal, handsEnabled, sessionId, handsCwdRef, tools, envHandToolNames } = input;
+    const lspManager = spec.lspManager ?? deps.lspManager;
+    if (lspManager) {
+        const lspRoot = taskRootFinal;
+        tools.push(createLspTool(lspManager, { isPathIgnored: gitCheckIgnoreFilter(executionEnv, lspRoot), env: executionEnv }));
+        envHandToolNames.add("LSP");
+    }
+    const lspDiagnostics = spec.lspDiagnostics !== false && lspManager?.diagnostics !== undefined && handsEnabled && spec.handsReadOnly !== true
+        ? lspManager.diagnostics
+        : undefined;
+    const lspRunIdent = sessionId;
+    const nudgeLspOnEdit = lspDiagnostics
+        ? (rawPath) => {
+            const baseDir = handsCwdRef?.current ?? taskRootFinal;
+            const filePath = resolveLspPath(rawPath, baseDir);
+            lspDiagnostics.fileEdited(lspRunIdent, pathToUri(filePath));
+            void lspManager
+                .sessionFor(filePath, undefined, executionEnv)
+                .then((session) => session?.notifyFileChanged?.(filePath))
+                .catch(() => undefined);
+        }
+        : undefined;
+    return { lspDiagnostics, nudgeLspOnEdit, lspRunIdent };
+}

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

@@ -1,6 +1,6 @@
 import type { BeforeWriteHook, EffectiveMemoryScopes, RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
 import { type CaptureEntitlementInput, type MemoryCapturePosture } from "./memory-capture-optout.js";
-import type { Prepared } from "./prepare-task.js";
+import type { Prepared } from "./contracts.js";
 export interface PrepareMemoryInput {
     spec: TaskSpec;
     deps: RunnerDeps;

package/dist/core/runner/prepare-offload-wrappers.d.ts

@@ -0,0 +1,62 @@
+/**
+ * design/390 §1.2 M0 (the offload half of the prelude) — prepareTask's nested-usage accumulator, the
+ * large-tool-result offload store resolution and the THREE offload wrappers every later mount site
+ * applies (caller tools, first-party hand tools, remote MCP/A2A peers), verbatim from the driver.
+ *
+ * SYNCHRONOUS by construction: the segment held no await in the driver, and a phase that yields where
+ * the driver did not would open a microtask window between two steps that used to be adjacent (the
+ * design/238 T1 posture). Nothing here touches the store — the wrappers close over it and only the
+ * wrapped tools' `execute` reach it, at run time.
+ *
+ * What stays in the driver: the trust-axis choice of `offloadScope` (`spec.principal ?? "default"`)
+ * and its disclosure, and the reserved-name door that FOLLOWS these wrappers (it awaits a bounded
+ * session forget, so it belongs with the driver's other refusal legs).
+ */
+import { type ToolResultStore } from "../tool-result-store.js";
+import type { AgentTool } from "../../internal/harness.js";
+import type { NestedUsage, NestedUsageAccum, RunnerDeps, TaskSpec } from "../types.js";
+import type { PrepareResume } from "./contracts.js";
+export interface PrepareOffloadWrappersInput {
+    /** borrowed-readonly — the REBOUND spec (the config-doors result); read for the per-task coarse
+     *  offload knob only. */
+    spec: Pick<TaskSpec, "toolResultThresholdChars">;
+    /** borrowed-readonly — the deployment's coarse offload knob and its injected store (used AS-IS when
+     *  present; a Runner-shared instance is viewed per task, see the body). */
+    deps: Pick<RunnerDeps, "toolResultThresholdChars" | "toolResultStore">;
+    /** borrowed-readonly — the resume leg, read for the checkpoint seed's nested-usage snapshot so
+     *  delegated cost spent before a suspend is not lost; `undefined` on a fresh run. */
+    resume: Pick<PrepareResume, "seed"> | undefined;
+    /** borrowed-readonly — the run's TRUST identity (`spec.principal ?? "default"`, minted by the
+     *  driver): the namespace a Runner-shared store is scoped under. Never the registry domain. */
+    offloadScope: string;
+    /** borrowed-readonly — the acquired session id, the offload wrapper's ref-minting coordinate. */
+    sessionId: string;
+}
+export interface PrepareOffloadWrappersResult {
+    /** borrowed-mutable — the run's nested sub-run usage accumulator (`Prepared.nestedStats`).
+     *  Mutation owners after this call: `reportUsage` below (the only writer — every delegation tool
+     *  reports through it via the tool ctx); the driver reads it into `Prepared`. */
+    nestedStats: NestedUsageAccum;
+    /** borrowed-readonly — the one writer of `nestedStats`; the driver threads it onto the tool ctx. */
+    reportUsage: (u: NestedUsage) => void;
+    /** borrowed-readonly — the store the wrappers close over, or `undefined` when offload is disabled
+     *  (threshold 0 / non-finite). The driver reads it for the reserved-name door, the ReadToolResult
+     *  mount, the durable-suspend gate and the compaction lane. Not a resource: nothing to release. */
+    offloadStore: ToolResultStore | undefined;
+    /** borrowed-mutable — the LIVE "currently callable tools" accessor cell the offload preview's
+     *  pageback hint reads. Mutation owners after this call: the deferred-disclosure branch of the
+     *  driver sets `.current` once the deferred/active sets exist; nothing else writes it. */
+    offloadReachableToolsRef: {
+        current?: () => ReadonlySet<string>;
+    };
+    /** borrowed-readonly — wrap a CALLER tool (per-tool `offload` / `offloadThresholdChars` honored). */
+    maybeOffload: (tool: AgentTool, perTool?: {
+        offload?: boolean;
+        offloadThresholdChars?: number;
+    }) => AgentTool;
+    /** borrowed-readonly — wrap a FIRST-PARTY mount (the per-tool persistence table; Read/Write exempt). */
+    firstPartyOffload: (tool: AgentTool) => AgentTool;
+    /** borrowed-readonly — wrap a REMOTE-PEER mount (MCP `_meta` size declaration, else 50K). */
+    remoteToolOffload: (tool: AgentTool) => AgentTool;
+}
+export declare function prepareOffloadWrappers(input: PrepareOffloadWrappersInput): PrepareOffloadWrappersResult;

package/dist/core/runner/prepare-offload-wrappers.js

@@ -0,0 +1,45 @@
+import { DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, firstPartyOffloadPolicy, InMemoryToolResultStore, RunnerSharedToolResultStore, ScopedToolResultStore, withToolResultOffload, } from "../tool-result-store.js";
+export function prepareOffloadWrappers(input) {
+    const { spec, deps, resume, offloadScope, sessionId } = input;
+    const nestedStats = { tokens: 0, turns: 0, tasks: 0, costMicroUsd: 0, anyUnpriced: false };
+    if (resume) {
+        nestedStats.tokens = resume.seed.nestedStats.tokens;
+        nestedStats.turns = resume.seed.nestedStats.turns;
+        nestedStats.tasks = resume.seed.nestedStats.tasks;
+        nestedStats.costMicroUsd = resume.seed.nestedStats.costMicroUsd;
+        nestedStats.anyUnpriced = resume.seed.nestedStats.anyUnpriced ?? true;
+    }
+    const reportUsage = (u) => {
+        nestedStats.tokens += u.tokens;
+        nestedStats.turns += u.turns;
+        nestedStats.tasks += u.tasks;
+        nestedStats.costMicroUsd += u.costMicroUsd ?? 0;
+        if (u.costMicroUsd === undefined)
+            nestedStats.anyUnpriced = true;
+    };
+    const explicitGlobalThreshold = spec.toolResultThresholdChars ?? deps.toolResultThresholdChars;
+    const offloadThreshold = explicitGlobalThreshold ?? DEFAULT_TOOL_RESULT_THRESHOLD_CHARS;
+    const offloadEnabled = Number.isFinite(offloadThreshold) && offloadThreshold > 0;
+    const rawOffloadStore = offloadEnabled ? (deps.toolResultStore ?? new InMemoryToolResultStore()) : undefined;
+    const offloadStore = rawOffloadStore instanceof RunnerSharedToolResultStore
+        ? new ScopedToolResultStore(rawOffloadStore, offloadScope)
+        : rawOffloadStore;
+    const offloadReachableToolsRef = {};
+    const maybeOffload = (tool, perTool) => {
+        if (!offloadStore || perTool?.offload === false)
+            return tool;
+        return withToolResultOffload(tool, offloadStore, perTool?.offloadThresholdChars ?? offloadThreshold, sessionId, () => offloadReachableToolsRef.current?.());
+    };
+    const firstPartyOffload = (tool) => {
+        const policy = firstPartyOffloadPolicy(tool.name);
+        if (policy.offload === false)
+            return maybeOffload(tool, policy);
+        return maybeOffload(tool, explicitGlobalThreshold === undefined ? policy : undefined);
+    };
+    const remoteToolOffload = (tool) => {
+        if (explicitGlobalThreshold !== undefined)
+            return maybeOffload(tool);
+        return maybeOffload(tool, { offloadThresholdChars: tool.mcpMaxResultSizeChars ?? 50_000 });
+    };
+    return { nestedStats, reportUsage, offloadStore, offloadReachableToolsRef, maybeOffload, firstPartyOffload, remoteToolOffload };
+}

package/dist/core/runner/prepare-project-context.d.ts

@@ -0,0 +1,131 @@
+/**
+ * design/390 M9 — prepareTask's PROJECT-CONTEXT phase: the deployment's project memory snapshot (the
+ * `loadProjectMemory` seam: phase derivation, instruction sources, the framed + fenced project layer
+ * appended to the memory block), the skills roster (declaration rank, normalization, the 1MB load gate,
+ * the manifest-scope door, the `skill` tool mount), the two built-in memory pairs' mount-or-yield
+ * (shared-memory pair, engine-memory pair), and the skills-listing projection the run loop announces.
+ * The body is the driver's stretch moved verbatim; the interface below is the dependency list it had
+ * implicitly (design/238 R-1: a new read is an Input field, i.e. a review event).
+ *
+ * ASYNC BY CONTENT: the stretch awaits the session branch read, the seam itself and the read-state
+ * seeding (all inside the `loadProjectMemory` arm). It already sits past prepareTask's first await, so
+ * the one extra microtask the driver's `await` adds on the seam-less path opens no window any caller
+ * could reach (design/390 §1.5 S1 synchronicity rule: only pre-first-await stretches must stay sync).
+ *
+ * Throws pass through unchanged: `config.reserved_tool_name` (a caller tool named like the skill tool
+ * while skills are present) is the only refusal here; the seam's own throw and the seeding's are
+ * caught and forwarded to `deps.onError` (best-effort, never block the task).
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { StoredSession } from "../session.js";
+import type { RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
+import type { ActiveSkillScope } from "./active-skill-scope.js";
+import type { AnnounceOnceSink, Prepared, PrepareResume, RunInternals, ToolFaceSnapshot } from "./contracts.js";
+import { normalizeSkills } from "./synthetic-tools.js";
+/**
+ * The ONE "has this session seen conversation?" predicate — the freshness question is asked three
+ * times in one prepare (project-memory phase, design/148 center adoption, the epoch-pin
+ * discriminator), and an entry-COUNT proxy at ANY of them re-creates the same lie: a host may write
+ * session_info / model_change / … rows before the first turn (naming a new chat, recording a model
+ * pick), and none of that is evidence of a prior session (5.29 merge-rescan: the count proxy
+ * survived at the adoption arm after the pin arm was fixed, silently costing a pre-named session
+ * its published center prompt for life). Conversation content — and only that — is the evidence.
+ */
+export declare function hasConversationContent(branch: ReadonlyArray<{
+    type: string;
+}>): boolean;
+export interface PrepareProjectContextInput {
+    /** borrowed-readonly — the deployment seams this phase reads: `loadProjectMemory` (the snapshot),
+     *  `onError` (the operator lane for a throwing seam / seeding / oversize skill), `sharedMemoryStores`
+     *  (the shared-memory pair's switch: wired ⇒ mount). Receiver preserved (`deps.onError?.(…)`). */
+    deps: Pick<RunnerDeps, "loadProjectMemory" | "onError" | "sharedMemoryStores">;
+    /** borrowed-readonly — the REBOUND spec (`spec′`). Read: `sessionId` (phase derivation + the
+     *  continuation projections), `skills` (the roster), `principal` (the shared-memory tools' trusted
+     *  identity). Never mutated. */
+    spec: Pick<TaskSpec, "sessionId" | "skills" | "principal">;
+    /** borrowed-readonly — trusted internals: `agentName` (seam ctx), `inheritedManifestScope` (the
+     *  parent's active skill frames, seeded as the base of the LIFO). `undefined` on a standalone prepare. */
+    internals: Pick<RunInternals, "agentName" | "inheritedManifestScope"> | undefined;
+    /** borrowed-readonly — the acquired session; only `getBranch()` is read (phase derivation walk).
+     *  The read is best-effort: a throw keeps the provisional phase. */
+    session: Pick<StoredSession, "getBranch">;
+    /** borrowed-readonly — the acquired session's id (seam ctx cache key; operator-line context). */
+    sessionId: string;
+    /** borrowed-readonly — `spec.taskId ?? sessionId`: the shared-memory tools' trusted task identity. */
+    hostTaskId: string;
+    /** borrowed-readonly — the FINAL task root (post-restore): the seam's `cwd`. */
+    taskRootFinal: string;
+    /** borrowed-readonly — whether a real execution env is mounted (seam ctx flag). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the leg's effective-delegation facts; only `isNonForkChild` is read (the
+     *  seam's `isSubagent` — one derivation shared with the prompt fact, never re-derived here). */
+    delegation: {
+        readonly isNonForkChild: boolean;
+    };
+    /** borrowed-readonly — the hands phase's read-state seeding closure (CREATED there, CALLED here for
+     *  the snapshot's declared `seededFiles`); `undefined` on a hands-less task = nothing to seed. */
+    seedContextFiles: ((files: ReadonlyArray<{
+        path: string;
+        content: string;
+    }>) => Promise<void>) | undefined;
+    /** borrowed-readonly — the memory phase's composed block, as returned (recall discipline + engine
+     *  files). This phase APPENDS the project layer and hands the result back as
+     *  {@link PrepareProjectContextResult.memoryBlock}; the input value itself is never mutated. */
+    memoryBlockFromEngine: string | undefined;
+    /** borrowed-mutable — the run's LIFO skill-scope stack (identity is the contract: the scope policy
+     *  and the `skill` tool alias this exact object). Mutated here: `push` of every inherited parent
+     *  frame; after this phase only the `skill` tool's execute pushes/pops. */
+    skillScope: ActiveSkillScope;
+    /** borrowed-mutable — the shared mount array (later refs alias it; in-place contract). Mutated
+     *  here: `push` of the `skill` tool, the shared-memory pair and the engine-memory pair. Occupancy
+     *  is judged on this ALREADY-MOUNTED roster (names + aliases). */
+    tools: AgentTool[];
+    /** borrowed-readonly — the frozen task-start tool face; only `exclude` is read (pair yield ①). */
+    toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude">;
+    /** borrowed-readonly — the once-per-session announcement ledger; only its deduplicated `onError`
+     *  sink is invoked (a pair's mount shape is a session-level fact, announced once). */
+    onceLedger: AnnounceOnceSink;
+    /** borrowed-readonly — the memory phase's engine-pair ToolSpecs (present iff the pair may mount). */
+    memoryTools: ToolSpec[] | undefined;
+    /** borrowed-readonly — the memory phase's session seat; only `!== undefined` is read (the
+     *  blocked-mount disclosure fires only when a session mounted). */
+    memoryEngineSession: Prepared["memoryEngineSession"];
+    /** borrowed-readonly — the engine pair's early conjuncts (computed before the memory phase). */
+    memorySearchToolsPlanned: boolean;
+    /** borrowed-readonly — the engine-pair name the exclusion valve removed, if any (disclosure text). */
+    memoryPairExcludedName: string | undefined;
+    /** borrowed-readonly — the engine-pair name a declared tool already occupies, if any (disclosure text). */
+    memoryPairOccupiedName: string | undefined;
+    /** borrowed-readonly — the durable-resume carrier; read for `!== undefined` (seedAnnounced) and
+     *  `seed.announcedListings.skills` (the removal-to-zero projection's gate). */
+    resume: Pick<PrepareResume, "seed"> | undefined;
+}
+export interface PrepareProjectContextResult {
+    /** owned — the memory block with the project layer appended at the tail (unchanged when the seam is
+     *  unwired or returns null/blank). The driver binds it under a NEW name; the defer-classification
+     *  stretch may still strip the recall-discipline segment from it. */
+    memoryBlock: string | undefined;
+    /** owned — the snapshot's declared instruction sources (non-empty only), for the run loop's
+     *  instructions_change lane (`Prepared.instructionSources`). */
+    instructionSources: ReadonlyArray<{
+        path: string;
+        contentHash: string | null;
+    }> | undefined;
+    /** owned — the RAW snapshot text (pre-compose) for the compaction lanes' instruction-file seat
+     *  (`Prepared.projectInstructionContent`). */
+    projectInstructionContent: string | undefined;
+    /** owned — the normalized, load-gated skills (first-wins dedupe, name-sorted). Consumed inside this
+     *  phase (tool + listing); exposed as the phase's own product. */
+    skillSpecs: ReturnType<typeof normalizeSkills>;
+    /** owned — whether THIS task carries a manifested skill or inherits a parent frame (the skill-scope
+     *  policy's activation predicate). */
+    hasSkillManifest: boolean;
+    /** owned — the skills-listing projection the run loop's announce lane consumes (`Prepared.skillsListing`). */
+    skillsListing: Prepared["skillsListing"];
+    /** owned — whether the shared-memory pair mounted here (the support-name pre-check reads it). */
+    sharedMemoryPairMounted: boolean;
+    /** owned — whether the engine-memory pair mounted here (the support-name pre-check reads it). */
+    memoryEnginePairMounted: boolean;
+}
+/** The M9 phase body — prepareTask's project-context stretch, verbatim (see the module header). */
+export declare function prepareProjectContext(input: PrepareProjectContextInput): Promise<PrepareProjectContextResult>;

package/dist/core/runner/prepare-project-context.js

@@ -0,0 +1,150 @@
+import { PROJECT_CONTEXT_FRAMING } from "../../prompts/default.js";
+import { MEMORY_ENGINE_TOOL_NAMES } from "../memory-engine/tools.js";
+import { composeMemoryBlock } from "../memory.js";
+import { createSharedMemoryTools } from "../shared-memory/tools.js";
+import { SHARED_MEMORY_TOOL_NAMES } from "../shared-memory/types.js";
+import { defineTool } from "../tools.js";
+import { SKILL_CONTENT_MAX_CHARS, SKILL_TOOL_NAME, createSkillTool, normalizeSkills } from "./synthetic-tools.js";
+export function hasConversationContent(branch) {
+    return branch.some((e) => e.type === "message" || e.type === "custom_message" || e.type === "compaction");
+}
+export async function prepareProjectContext(input) {
+    const { deps, spec, internals, session, sessionId, hostTaskId, taskRootFinal, handsEnabled, delegation, seedContextFiles, memoryBlockFromEngine, skillScope, tools, toolFaceSnapshot, onceLedger, memoryTools, memoryEngineSession, memorySearchToolsPlanned, memoryPairExcludedName, memoryPairOccupiedName, resume } = input;
+    let memoryBlock = memoryBlockFromEngine;
+    let instructionSources;
+    let projectInstructionContent;
+    if (deps.loadProjectMemory) {
+        let projectMemoryPhase = spec.sessionId ? "resume" : "fresh";
+        if (spec.sessionId) {
+            try {
+                const branch = await session.getBranch();
+                const hasConversation = hasConversationContent(branch);
+                if (!hasConversation)
+                    projectMemoryPhase = "fresh";
+                else {
+                    for (let i = branch.length - 1; i >= 0; i--) {
+                        const e = branch[i];
+                        if (e.type === "compaction") {
+                            projectMemoryPhase = "post-compact";
+                            break;
+                        }
+                        if (e.type === "message" && e.message.role === "user")
+                            break;
+                    }
+                }
+            }
+            catch {
+            }
+        }
+        let loaded = null;
+        try {
+            loaded = await Promise.resolve(deps.loadProjectMemory({
+                cwd: taskRootFinal,
+                handsEnabled,
+                isSubagent: delegation.isNonForkChild,
+                ...(internals?.agentName ? { agentName: internals.agentName } : {}),
+                sessionId,
+                phase: projectMemoryPhase,
+            }));
+        }
+        catch (err) {
+            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
+        }
+        const projectMem = loaded !== null && typeof loaded === "object" ? loaded.content : loaded;
+        const seededFiles = loaded !== null && typeof loaded === "object" ? loaded.seededFiles : undefined;
+        const declaredSources = loaded !== null && typeof loaded === "object" ? loaded.instructionSources : undefined;
+        if (declaredSources !== undefined && declaredSources.length > 0)
+            instructionSources = declaredSources;
+        if (seededFiles?.length && seedContextFiles) {
+            try {
+                await seedContextFiles(seededFiles);
+            }
+            catch (err) {
+                deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
+            }
+        }
+        if (projectMem != null && projectMem.trim()) {
+            projectInstructionContent = projectMem;
+            const projectBlock = `${PROJECT_CONTEXT_FRAMING}\n\n${composeMemoryBlock(projectMem, "project")}`;
+            memoryBlock = memoryBlock ? `${memoryBlock}\n\n${projectBlock}` : projectBlock;
+        }
+    }
+    const declaredSkillRank = new Map();
+    for (const s of spec.skills ?? [])
+        if (!declaredSkillRank.has(s.name))
+            declaredSkillRank.set(s.name, declaredSkillRank.size);
+    const skillSpecs = normalizeSkills(spec.skills ?? []).filter((s) => {
+        if (s.content.length <= SKILL_CONTENT_MAX_CHARS)
+            return true;
+        deps.onError?.(new Error(`Skill "${s.name}" content is ${s.content.length} chars, over the ${SKILL_CONTENT_MAX_CHARS}-char load limit — skill not loaded (skills are never truncated; shrink the body or move material to attachments/files).`), { phase: "config", sessionId });
+        return false;
+    });
+    const inheritedFrames = internals?.inheritedManifestScope ?? [];
+    for (const frame of inheritedFrames) {
+        skillScope.push(frame);
+    }
+    const hasSkillManifest = skillSpecs.some((s) => s.manifest !== undefined) || inheritedFrames.length > 0;
+    if (skillSpecs.length > 0) {
+        if (tools.some((t) => t.name === SKILL_TOOL_NAME)) {
+            const e = new Error(`Tool name "${SKILL_TOOL_NAME}" is reserved when spec.skills is present.`);
+            e.code = "config.reserved_tool_name";
+            throw e;
+        }
+        tools.push(createSkillTool(skillSpecs, skillScope));
+    }
+    const sharedMemoryProvider = deps.sharedMemoryStores;
+    let sharedMemoryPairMounted = false;
+    if (sharedMemoryProvider !== undefined) {
+        const excluded = new Set(toolFaceSnapshot.exclude ?? []);
+        const mountedNameDomain = new Set();
+        for (const t of tools) {
+            mountedNameDomain.add(t.name);
+            for (const alias of t.aliases ?? [])
+                mountedNameDomain.add(alias);
+        }
+        const excludedName = SHARED_MEMORY_TOOL_NAMES.find((n) => excluded.has(n));
+        const occupiedName = SHARED_MEMORY_TOOL_NAMES.find((n) => mountedNameDomain.has(n));
+        if (excludedName !== undefined || occupiedName !== undefined) {
+            onceLedger.onError(new Error(`Shared memory tools ${SHARED_MEMORY_TOOL_NAMES.join("/")} were NOT mounted: ` +
+                (excludedName !== undefined
+                    ? `excludeTools removes "${excludedName}"`
+                    : `this task already declares a tool named "${occupiedName}" (the built-in yields to it)`) +
+                " — the pair mounts together or not at all."), { phase: "config", sessionId, classification: "shared-memory-not-mounted" });
+        }
+        else {
+            tools.push(...createSharedMemoryTools({
+                provider: sharedMemoryProvider,
+                context: { sessionId, taskId: hostTaskId, ...(spec.principal !== undefined ? { principal: spec.principal } : {}) },
+            }).map((s) => defineTool(s)));
+            sharedMemoryPairMounted = true;
+        }
+    }
+    let memoryEnginePairMounted = false;
+    if (memoryTools !== undefined && memoryTools.length > 0) {
+        tools.push(...memoryTools.map((s) => defineTool(s)));
+        memoryEnginePairMounted = true;
+    }
+    else if (memoryEngineSession !== undefined && !memorySearchToolsPlanned) {
+        onceLedger.onError(new Error(`Memory tools ${MEMORY_ENGINE_TOOL_NAMES.join("/")} were NOT mounted: ` +
+            (memoryPairExcludedName !== undefined
+                ? `excludeTools removes "${memoryPairExcludedName}"`
+                : `this task already declares a tool named "${memoryPairOccupiedName}" (the built-in yields to it)`) +
+            " — these tools mount together or not at all."), { phase: "config", sessionId, classification: "memory-tools-not-mounted" });
+    }
+    const skillsListing = skillSpecs.length > 0
+        ? {
+            entries: skillSpecs.map((s) => ({
+                name: s.name,
+                description: s.description,
+                ...(s.files !== undefined ? { files: s.files.map((f) => ({ path: f.path })) } : {}),
+                ...(declaredSkillRank.get(s.name) !== undefined ? { declaredRank: declaredSkillRank.get(s.name) } : {}),
+            })),
+            seedAnnounced: resume !== undefined || spec.sessionId !== undefined,
+        }
+        :
+            (resume?.seed.announcedListings?.skills?.length ?? 0) > 0 || spec.sessionId !== undefined
+                ?
+                    { entries: [], seedAnnounced: true }
+                : undefined;
+    return { memoryBlock, instructionSources, projectInstructionContent, skillSpecs, hasSkillManifest, skillsListing, sharedMemoryPairMounted, memoryEnginePairMounted };
+}