@stigmer/runner 3.15.0 → 3.15.2-dev.20260913223433

package/dist/activities/execute-deep-agent/hitl.js

@@ -1,67 +1,81 @@
 /**
- * HITL (human-in-the-loop) resume infrastructure for ExecuteDeepAgent.
+ * HITL (human-in-the-loop) resume infrastructure for the native deep-agent
+ * harness — the LangGraph side of an approval round trip.
  *
- * On reinvocation after an approval signal, this module:
- * 1. Reads the persisted execution status from the database
- * 2. Queries the LangGraph checkpoint for pending interrupts
- * 3. Matches each interrupt's tool_call_id to the user's approval decision
- * 4. Builds a `Command(resume={...})` payload for LangGraph
- * 5. Reconciles tool call statuses in the StatusBuilder
+ * The runtime reads the user's decisions off the persisted rows
+ * (`harness/approval-decisions.ts` `approvalDecisionsOf`, on `TurnInput`)
+ * and settles the rows that never run (SKIP, REJECT) after the turn; what is
+ * this harness's is how those decisions reach the ENGINE: the graph
+ * checkpoint's un-resumed interrupts, keyed by the interrupt's own id, become
+ * a `Command(resume)` map ({@link resolveResumeInput}), and after a stream the
+ * interrupts still pending become WAITING_APPROVAL rows
+ * ({@link detectPendingInterrupts}). {@link reconcileUnattendedSkips} is the
+ * one settlement that stays here because its evidence — the gate's registry
+ * of auto-skipped call ids — exists only inside this harness.
  *
- * DB-driven resume: Approval decisions are read from the persisted
- * execution status (via `client.getExecution()`), NOT passed as Temporal
- * activity arguments. This matches the Go workflow contract.
+ * Until S3 M2a this module also read the decisions from the execution itself
+ * and carried the SKIP/REJECT settlement; both are the runtime's now, one
+ * copy for every harness (S3 M1, Q-S3-2).
  */
 import { Command } from "@langchain/langgraph";
 import { ApprovalAction, ApprovalPolicySource, ToolCallStatus, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { POLICY_ENGINE_VERSION, unattendedSkipMessage } from "../../shared/approval-policy.js";
-// APPROVE_ALL resumes the interrupted tool exactly like APPROVE. Its
-// "auto-approve the rest of the run" effect is realized in setup.ts (the
-// approval gate is disabled for the whole execution once any APPROVE_ALL
-// decision exists), not here — this map only resolves the currently
-// interrupted tool calls. REJECT resumes the gate too (the gate returns a
-// denial ToolMessage that the model reads); it denies a single tool, it does
-// NOT fail the run — see reconcileNonExecutingDecisions for the terminal status.
-const ACTION_MAP = new Map([
-    [ApprovalAction.APPROVE, "approve"],
-    [ApprovalAction.APPROVE_ALL, "approve"],
-    [ApprovalAction.SKIP, "skip"],
-    [ApprovalAction.REJECT, "reject"],
-]);
+/**
+ * The gate's resume vocabulary for each decision. APPROVE_ALL resumes the
+ * interrupted tool exactly like APPROVE; its "auto-approve the rest of the
+ * run" effect is a scoped lease the gate config carries, not this map's.
+ * REJECT resumes the gate too (the gate returns a denial ToolMessage the
+ * model reads): it denies one tool and never fails the run — the runtime
+ * settles the row SKIPPED afterwards (`harness/approval-decisions.ts`).
+ */
+function resumeActionOf(action) {
+    switch (action) {
+        case ApprovalAction.APPROVE:
+        case ApprovalAction.APPROVE_ALL:
+            return "approve";
+        case ApprovalAction.SKIP:
+            return "skip";
+        case ApprovalAction.REJECT:
+            return "reject";
+        case ApprovalAction.UNSPECIFIED:
+            return undefined;
+        default: {
+            const exhaustive = action;
+            throw new Error(`hitl: unknown approval action ${String(exhaustive)}`);
+        }
+    }
+}
 /**
  * Resolve the resume input for a reinvocation after approval.
  *
  * Returns a `Command(resume=...)` if there are pending interrupts with
  * matching approval decisions; otherwise reports "not a resume" and the
- * caller falls back to `setup.langgraphInput`.
+ * caller sends the turn's user message.
  *
- * The graph checkpoint snapshot is read once by the caller and passed in: the
- * same snapshot also decides whether status must be seeded from the persisted
- * transcript (see `index.ts`), and on the durable (http) saver an extra
- * `getState` is a network round-trip best avoided.
+ * `decisions` is the runtime's reading of the adjudicated rows
+ * (`TurnInput.approvalDecisions`, keyed by tool-call id) — the one
+ * projection both harnesses agree on; this module never re-derives the
+ * verdict from the rows. The graph checkpoint snapshot is read once by the
+ * caller and passed in: on the durable (http) saver an extra `getState` is a
+ * network round-trip best avoided.
  */
-export function resolveResumeInput(execution, graphState) {
+export function resolveResumeInput(decisions, graphState) {
     const pendingInterrupts = extractPendingInterrupts(graphState);
     if (pendingInterrupts.length === 0) {
         return { isResumeFromApproval: false };
     }
-    const decisions = extractApprovalDecisions(execution);
     if (decisions.size === 0) {
         return { isResumeFromApproval: false };
     }
     const resumeDict = {};
     for (const intr of pendingInterrupts) {
-        const toolCallId = intr.toolCallId;
-        const decision = decisions.get(toolCallId);
-        if (!decision)
+        const decision = decisions.get(intr.toolCallId);
+        if (decision === undefined)
             continue;
-        const actionStr = ACTION_MAP.get(decision.action);
-        if (!actionStr)
+        const action = resumeActionOf(decision);
+        if (!action)
             continue;
-        resumeDict[intr.interruptId] = {
-            action: actionStr,
-            ...(decision.comment ? { comment: decision.comment } : {}),
-        };
+        resumeDict[intr.interruptId] = { action };
     }
     if (Object.keys(resumeDict).length === 0) {
         return { isResumeFromApproval: false };
@@ -95,72 +109,10 @@ function extractPendingInterrupts(state) {
     }
     return result;
 }
-function extractApprovalDecisions(execution) {
-    const decisions = new Map();
-    const status = execution.status;
-    if (!status)
-        return decisions;
-    for (const message of status.messages) {
-        for (const tc of message.toolCalls) {
-            if (tc.approvalAction !== ApprovalAction.UNSPECIFIED &&
-                tc.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL) {
-                decisions.set(tc.id, {
-                    action: tc.approvalAction,
-                    comment: "",
-                });
-            }
-        }
-    }
-    return decisions;
-}
-/**
- * Terminalize tool calls whose approval decision is non-executing — SKIP or
- * REJECT — so a denied or skipped call is never left stuck at WAITING_APPROVAL.
- *
- * This is the single, authoritative, checkpointer-independent reconciliation of
- * the two decisions that never run the tool: their outcome is fully determined
- * by the recorded decision (ToolCall.approval_action), not by any graph event.
- * APPROVE / APPROVE_ALL are intentionally NOT handled here — the tool actually
- * executes, and real tool events (v3 tool_started → tool_finished) terminalize
- * it in place.
- *
- * Why a decision-derived reconciler rather than the resumed stream: on the
- * durable path (sqlite local / http cloud) the gate returns a denial/skip
- * ToolMessage WITHOUT an on_tool_start/on_tool_end pair, and on the memory path
- * the graph replays without ever re-driving the gate — so in both cases the
- * seeded WAITING_APPROVAL row is never flipped by the stream and would persist
- * on a COMPLETED execution. Folding the recorded decision into a terminal status
- * makes every checkpointer backend behave identically by construction.
- *
- * REJECT and SKIP share TOOL_CALL_SKIPPED as the terminal status (the tool did
- * not run); they stay distinguishable by ToolCall.approval_action and by the
- * append-only approval-event stream (REJECTED vs SKIPPED). Idempotent: a row
- * already resolved carries the same decision and re-resolves identically.
- */
-export function reconcileNonExecutingDecisions(status) {
-    const apply = (messages) => {
-        for (const msg of messages) {
-            for (const tc of msg.toolCalls) {
-                if (tc.approvalAction === ApprovalAction.SKIP) {
-                    tc.status = ToolCallStatus.TOOL_CALL_SKIPPED;
-                }
-                else if (tc.approvalAction === ApprovalAction.REJECT) {
-                    tc.status = ToolCallStatus.TOOL_CALL_SKIPPED;
-                    if (!tc.error)
-                        tc.error = "Rejected by user";
-                }
-            }
-        }
-    };
-    apply(status.messages);
-    for (const subAgent of status.subAgentExecutions) {
-        apply(subAgent.messages);
-    }
-}
 /**
  * Terminalize every tool call the approval gate auto-skipped under UNATTENDED
- * approval mode — the sibling of {@link reconcileNonExecutingDecisions} for
- * skips that have no human decision behind them.
+ * approval mode — the sibling of the runtime's `terminalizeNonExecutingDecisions`
+ * for skips that have no human decision behind them.
  *
  * The gate (the single writer of the registry) records each auto-skipped
  * tool-call id at the moment it returns the skip ToolMessage; this reconciler
@@ -203,4 +155,26 @@ export function reconcileUnattendedSkips(status, unattendedSkips) {
         apply(subAgent.messages);
     }
 }
+/**
+ * Normalize the graph checkpoint's un-resumed interrupts into pending
+ * approvals — what a stream that ended on a gate left for the user. The
+ * caller seeds one WAITING_APPROVAL row per entry and ends the turn awaiting
+ * approval; the interrupt carries only `tool_call_id` and `message` beside
+ * the gate's own facts, so the row's args are read from the AI message in
+ * graph state, never from a second copy here.
+ */
+export function detectPendingInterrupts(graphState) {
+    return graphState.tasks.flatMap((task) => (task.interrupts ?? [])
+        .filter((intr) => intr.resumeValue === undefined)
+        .map((intr) => {
+        const val = intr.value;
+        return {
+            toolCallId: val?.tool_call_id ?? "",
+            toolName: val?.tool_name ?? "",
+            mcpServerSlug: val?.mcp_server_slug ?? "",
+            message: val?.message ?? "",
+            policySource: val?.policy_source || undefined,
+        };
+    }));
+}
 //# sourceMappingURL=hitl.js.map

package/dist/activities/execute-deep-agent/hitl.js.map

@@ -1 +1 @@
-{"version":3,"file":"hitl.js","sourceRoot":"","sources":["../../../src/activities/execute-deep-agent/hitl.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hitl.js","sourceRoot":"","sources":["../../../src/activities/execute-deep-agent/hitl.ts"],"names":[],"mappings":"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"}

package/dist/activities/execute-deep-agent/prompt-builder.d.ts

@@ -1,19 +1,43 @@
 /**
- * System prompt construction for deep agent execution.
+ * The native harness's system prompt: what `createDeepAgent` receives as
+ * `systemPrompt`, rebuilt on EVERY invocation (never checkpointed with the
+ * message history), so every standing fact is injected on every turn by
+ * design — a first-turn-only injection would vanish from turn 2 onward.
  *
- * Pure functions: no side effects, no I/O. Accepts pre-computed data
- * (provision results, skill sections, file refs) and returns the
- * assembled system prompt string.
+ * Pure functions: no side effects, no I/O. `turn-setup.ts` gathers the
+ * inputs from the runtime's resolved record and this module renders them.
+ *
+ * What is this harness's and what is shared (S3 M5, Q-S3-10 / Q-M5-2):
+ *  - Shared through `shared/prompt-sections.ts`: WHICH standing sections
+ *    render and in WHAT order (`standingContextSections`), the input-files
+ *    bullet and disclosure lines (`inputFileLines`), which skills a prompt
+ *    highlights (`selectSkillsForPrompt`, called from `turn-setup.ts`) and
+ *    the also-available sentence. Their WORDS come from each fact's own
+ *    module; this builder only frames them.
+ *  - This harness's: the framing — `## Heading` markdown sections, the house
+ *    style for a system prompt — and every text that quotes this engine's
+ *    tools: the `## Skills` activation protocol (`read`, `execute(...)`), the
+ *    response rules, the sub-agent delegation rules, the plan-mode
+ *    read-boundary sentence, and the workspace section (the deepagents
+ *    backend's path resolution is this engine's).
+ *
+ * The rendered bytes are load-bearing for the hermetic tests: `ScriptedModel`
+ * tells its scripted roles apart by the system prompt's text, so this
+ * module's whole output is pinned by `__tests__/prompt-goldens.test.ts`.
  */
 import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { ProvisionResult } from "../../shared/workspace/types.js";
-import { type SenderIdentity } from "../../shared/sender-identity.js";
-import { type DeclaredPreferencesContent } from "../../shared/declared-preferences.js";
-import { type RecalledMemoriesContent } from "../../shared/recalled-memories.js";
-import { type NotViewableEntry } from "../../shared/attachment-vision.js";
-import { type DownloadUrlKind } from "../../shared/attachment-download-urls.js";
-import type { InjectedFile } from "./attachment-injector.js";
+import type { SenderIdentity } from "../../shared/sender-identity.js";
+import type { DeclaredPreferencesContent } from "../../shared/declared-preferences.js";
+import type { RecalledMemoriesContent } from "../../shared/recalled-memories.js";
+import type { DownloadUrlKind } from "../../shared/attachment-download-urls.js";
+import { type VisionPromptInfo } from "../../shared/prompt-sections.js";
+import type { ResolvedAttachment } from "../../shared/attachment-resolver.js";
+import type { SkillMetadata } from "../../shared/skill-resolver.js";
+/** The agent's instructions when the blueprint carries none; the prompt is never empty (S3 M2a, F-M2a-16: was `setup.ts`'s alone). */
+export declare const DEFAULT_INSTRUCTIONS = "You are a helpful AI assistant.";
 export interface PromptBuilderInput {
+    /** The blueprint's instructions, raw; empty falls back to {@link DEFAULT_INSTRUCTIONS}. */
     instructions: string;
     provisionResults: ProvisionResult[];
     containerRoot: string;
@@ -26,7 +50,8 @@ export interface PromptBuilderInput {
     channelTemplatesPromptSection?: string;
     workspaceFileRefs: string[];
     workspaceRoot: string;
-    injectedFiles: InjectedFile[];
+    /** The turn's resolved input files, as the runtime's attachment phase returns them. */
+    inputFiles: readonly ResolvedAttachment[];
     /**
      * Vision facts about this turn's attachments (T04): which images the model
      * sees inline in the user message and which degraded to path-only.
@@ -42,7 +67,7 @@ export interface PromptBuilderInput {
     /**
      * The execution's interaction mode. PLAN appends the shared plan-mode
      * directive so the model knows the turn's deliverable is a plan document.
-     * Tool-level write enforcement is separate (see setup.ts permissions) —
+     * Tool-level write enforcement is separate (see turn-setup.ts permissions) —
      * without this directive the model is silently read-only but never told
      * to produce a plan.
      */
@@ -98,17 +123,7 @@ export interface PromptBuilderInput {
      */
     recalledMemories?: RecalledMemoriesContent;
 }
-export type { InjectedFile } from "./attachment-injector.js";
-/**
- * Which images ride the user message inline (in send order) and which
- * degraded to the file-pointer story — the shared vision wording
- * (attachment-vision.ts) keeps this prompt and the Cursor harness's
- * input-files section telling the agent the same thing.
- */
-export interface VisionPromptInfo {
-    inlineFilenames: string[];
-    notViewable: NotViewableEntry[];
-}
+export type { VisionPromptInfo };
 /**
  * Assemble the full system prompt from base instructions and contextual
  * sections. Pure function with no I/O.
@@ -125,3 +140,16 @@ export declare function buildEnhancedSystemPrompt(input: PromptBuilderInput): st
  * exists only in the graph input.
  */
 export declare function composeUserMessage(message: string, conversationCatchup: string | undefined): string;
+/**
+ * The `## Skills` section of this harness's system prompt, rendered from the
+ * runtime's mounted-skill metadata (`shared/skill-resolver.ts`
+ * `SkillMetadata`), following the Agent Skills spec's progressive
+ * disclosure model: only name, description and location are injected; the
+ * agent reads SKILL.md on demand through its filesystem tools. Byte for byte
+ * the text the orchestrator-era `generatePromptSection` rendered from the
+ * `Skill` proto (deleted with `setup.ts` at S3 M2b); the one difference is
+ * the input — a mounted file's metadata, not a fetched resource — so this
+ * renderer needs no client and serves the root and every sub-agent alike.
+ * Empty for no skills.
+ */
+export declare function renderSkillsSection(skills: readonly SkillMetadata[]): string;

package/dist/activities/execute-deep-agent/prompt-builder.js

@@ -1,23 +1,38 @@
 /**
- * System prompt construction for deep agent execution.
+ * The native harness's system prompt: what `createDeepAgent` receives as
+ * `systemPrompt`, rebuilt on EVERY invocation (never checkpointed with the
+ * message history), so every standing fact is injected on every turn by
+ * design — a first-turn-only injection would vanish from turn 2 onward.
  *
- * Pure functions: no side effects, no I/O. Accepts pre-computed data
- * (provision results, skill sections, file refs) and returns the
- * assembled system prompt string.
+ * Pure functions: no side effects, no I/O. `turn-setup.ts` gathers the
+ * inputs from the runtime's resolved record and this module renders them.
+ *
+ * What is this harness's and what is shared (S3 M5, Q-S3-10 / Q-M5-2):
+ *  - Shared through `shared/prompt-sections.ts`: WHICH standing sections
+ *    render and in WHAT order (`standingContextSections`), the input-files
+ *    bullet and disclosure lines (`inputFileLines`), which skills a prompt
+ *    highlights (`selectSkillsForPrompt`, called from `turn-setup.ts`) and
+ *    the also-available sentence. Their WORDS come from each fact's own
+ *    module; this builder only frames them.
+ *  - This harness's: the framing — `## Heading` markdown sections, the house
+ *    style for a system prompt — and every text that quotes this engine's
+ *    tools: the `## Skills` activation protocol (`read`, `execute(...)`), the
+ *    response rules, the sub-agent delegation rules, the plan-mode
+ *    read-boundary sentence, and the workspace section (the deepagents
+ *    backend's path resolution is this engine's).
+ *
+ * The rendered bytes are load-bearing for the hermetic tests: `ScriptedModel`
+ * tells its scripted roles apart by the system prompt's text, so this
+ * module's whole output is pinned by `__tests__/prompt-goldens.test.ts`.
  */
 import { relative } from "node:path";
 import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { SourceType } from "../../shared/workspace/types.js";
-import { formatContextBridgeText } from "../../shared/context-bridge.js";
 import { formatConversationCatchupText } from "../../shared/conversation-catchup.js";
-import { formatSenderIdentityText, } from "../../shared/sender-identity.js";
-import { formatSessionContextText } from "../../shared/session-context.js";
-import { formatDeclaredPreferencesText, } from "../../shared/declared-preferences.js";
-import { formatRecalledMemoriesText, } from "../../shared/recalled-memories.js";
-import { visionDisclosureLines, } from "../../shared/attachment-vision.js";
-import { downloadUrlDisclosureLine, } from "../../shared/attachment-download-urls.js";
+import { inputFileLines, standingContextSections, } from "../../shared/prompt-sections.js";
 import { PLAN_MODE_DIRECTIVE } from "../../shared/plan-mode-prompt.js";
 import { buildImplementPlanDirective, findApprovedPlanPath, } from "../../shared/implement-plan-prompt.js";
+import { STIGMER_LOCAL_STATE_DIR } from "../../shared/workspace/stigmer-link.js";
 const RESPONSE_RULES = `
 
 ## Response rules
@@ -82,12 +97,27 @@ influence your answer.
 directly over delegating. Only delegate when context isolation \
 or parallelism genuinely helps the user.
 `;
+/** The agent's instructions when the blueprint carries none; the prompt is never empty (S3 M2a, F-M2a-16: was `setup.ts`'s alone). */
+export const DEFAULT_INSTRUCTIONS = "You are a helpful AI assistant.";
+/**
+ * This harness's heading for each shared standing section (the section's
+ * identity and order are `prompt-sections.ts`'s; the `##` framing is the
+ * house style for a system prompt). Exhaustive by the compiler: a new kind
+ * fails here until it is named.
+ */
+const STANDING_SECTION_HEADINGS = {
+    "conversation-sender": "Conversation sender",
+    "declared-preferences": "Declared preferences",
+    "recalled-memories": "Remembered facts",
+    "session-context": "Session context",
+    "previous-conversation": "Previous conversation context",
+};
 /**
  * Assemble the full system prompt from base instructions and contextual
  * sections. Pure function with no I/O.
  */
 export function buildEnhancedSystemPrompt(input) {
-    let prompt = input.instructions;
+    let prompt = input.instructions || DEFAULT_INSTRUCTIONS;
     const workspaceSection = buildWorkspacePromptSection(input.provisionResults, input.containerRoot);
     if (workspaceSection) {
         prompt += workspaceSection;
@@ -104,43 +134,13 @@ export function buildEnhancedSystemPrompt(input) {
             prompt += refSection;
         }
     }
-    if (input.injectedFiles.length > 0) {
-        prompt += buildInjectedFilesSection(input.injectedFiles, input.vision, input.downloadUrlKind);
-    }
-    if (input.senderIdentity) {
-        prompt +=
-            "\n\n## Conversation sender\n\n" +
-                formatSenderIdentityText(input.senderIdentity);
-    }
-    // Platform-declared standing facts precede embedder-supplied context
-    // (DD-002 D3): both are standing background, but the declared preferences
-    // are platform-authored while session context is the embedder's overlay —
-    // the more specific overlay reads later and naturally refines.
-    if (input.declaredPreferences) {
-        prompt +=
-            "\n\n## Declared preferences\n\n" +
-                formatDeclaredPreferencesText(input.declaredPreferences);
-    }
-    // Declared-by-humans precedes learned-and-confirmed (DD-006 D4): both
-    // are platform-authored standing background, but a preference is the
-    // user's exact words while a memory is an agent's confirmed inference —
-    // the exact statement reads first.
-    if (input.recalledMemories) {
-        prompt +=
-            "\n\n## Remembered facts\n\n" +
-                formatRecalledMemoriesText(input.recalledMemories);
-    }
-    // Standing facts about the user (session context) come before the
-    // carried conversation (bridge): the bridge may refer back to them.
-    if (input.sessionContext) {
-        prompt +=
-            "\n\n## Session context\n\n" +
-                formatSessionContextText(input.sessionContext);
+    if (input.inputFiles.length > 0) {
+        prompt += buildInputFilesSection(input.inputFiles, input.vision, input.downloadUrlKind);
     }
-    if (input.contextBridge) {
-        prompt +=
-            "\n\n## Previous conversation context\n\n" +
-                formatContextBridgeText(input.contextBridge);
+    // The standing context, in the shared order (the doctrine is stated once,
+    // on `standingContextSections`); this harness only frames each section.
+    for (const section of standingContextSections(input)) {
+        prompt += `\n\n## ${STANDING_SECTION_HEADINGS[section.kind]}\n\n${section.body}`;
     }
     prompt += RESPONSE_RULES;
     prompt += SUB_AGENT_RULES;
@@ -162,7 +162,7 @@ export function buildEnhancedSystemPrompt(input) {
                 "`.stigmer/` directory); paths outside it are refused.";
     }
     if (input.buildFromPlan) {
-        const planPath = findApprovedPlanPath(input.injectedFiles.map((f) => f.path));
+        const planPath = findApprovedPlanPath(input.inputFiles.map((f) => f.relativePath));
         prompt +=
             "\n\n## Implement the approved plan\n\n" +
                 buildImplementPlanDirective(planPath);
@@ -184,6 +184,58 @@ export function composeUserMessage(message, conversationCatchup) {
         ? `${formatConversationCatchupText(conversationCatchup)}\n\n---\n\n${message}`
         : message;
 }
+/**
+ * The `## Skills` section of this harness's system prompt, rendered from the
+ * runtime's mounted-skill metadata (`shared/skill-resolver.ts`
+ * `SkillMetadata`), following the Agent Skills spec's progressive
+ * disclosure model: only name, description and location are injected; the
+ * agent reads SKILL.md on demand through its filesystem tools. Byte for byte
+ * the text the orchestrator-era `generatePromptSection` rendered from the
+ * `Skill` proto (deleted with `setup.ts` at S3 M2b); the one difference is
+ * the input — a mounted file's metadata, not a fetched resource — so this
+ * renderer needs no client and serves the root and every sub-agent alike.
+ * Empty for no skills.
+ */
+export function renderSkillsSection(skills) {
+    if (skills.length === 0)
+        return "";
+    const lines = [
+        "",
+        "",
+        "## Skills",
+        "",
+        "You have access to the following skills. Each skill provides specialized " +
+            "knowledge or capabilities.",
+        "",
+        "**Activation protocol**: To use a skill, read its SKILL.md file " +
+            "using the `read` tool. The SKILL.md contains detailed instructions, " +
+            "available tools, and usage examples.",
+        "",
+        "**Usage pattern**:",
+        "",
+        "1. Review the skill description below to determine relevance",
+        "2. Read `{location}/SKILL.md` for full instructions",
+        "3. Follow the skill's documented operations:",
+        "",
+        "`read {location}/references/schema.md`",
+        '`execute("python3 {location}/scripts/run.py")`',
+        "",
+    ];
+    for (const skill of skills) {
+        const skillDir = skillDirOf(skill);
+        lines.push(`### ${skill.name}`);
+        lines.push(`**Description**: ${skill.description || "(no description)"}`);
+        lines.push(`**Location**: \`${skillDir}/\``);
+        lines.push(`**Activate**: \`read ${skillDir}/SKILL.md\``);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/** The mount directory a skill's `SKILL.md` path names (`.stigmer/skills/<name>`). */
+function skillDirOf(skill) {
+    const slash = skill.path.lastIndexOf("/");
+    return slash > 0 ? skill.path.slice(0, slash) : `${STIGMER_LOCAL_STATE_DIR}/skills/${skill.name}`;
+}
 function buildWorkspacePromptSection(provisionResults, containerRoot) {
     if (provisionResults.length === 0)
         return "";
@@ -268,7 +320,13 @@ function buildReferencedFilesSection(workspaceFileRefs, _workspaceRoot) {
     }
     return section;
 }
-function buildInjectedFilesSection(files, vision, downloadUrlKind) {
+/**
+ * The `## Input Files` section: this harness's intro (it names this engine's
+ * `read` tool) around the shared lines (`prompt-sections.ts` `inputFileLines`
+ * says what each bullet and disclosure carries and why). Each disclosure
+ * group is set off by a blank line, the markdown idiom.
+ */
+function buildInputFilesSection(files, vision, downloadUrlKind) {
     let section = "\n\n## Input Files\n\n";
     section +=
         "The following files have been provided as read-only reference " +
@@ -278,34 +336,15 @@ function buildInjectedFilesSection(files, vision, downloadUrlKind) {
             "Do NOT echo, reprint, or summarize file contents in your response " +
             "-- they are reference material, not output. " +
             "Do NOT modify or delete these files.\n\n";
-    for (const f of files) {
-        const sizeInfo = ` (${f.sizeBytes} bytes)`;
-        // A duplicate-renamed file (attachment-naming.ts) discloses its original
-        // name so the agent can connect "the two report.pdfs" in the user's
-        // message to distinct files on disk. A file with a minted download URL
-        // (attachment-download-urls.ts) lists it beside the path for the remote
-        // hand-off story.
-        const renameInfo = f.renamedFrom !== undefined
-            ? ` (renamed from duplicate '${f.renamedFrom}')`
-            : "";
-        const urlInfo = f.downloadUrl !== undefined ? ` — download URL: ${f.downloadUrl}` : "";
-        section += `- \`${f.path}\`${sizeInfo}${renameInfo}${urlInfo}\n`;
+    const lines = inputFileLines(files, vision, downloadUrlKind);
+    for (const entry of lines.entries) {
+        section += `${entry}\n`;
     }
-    // The URL hand-off line (shared wording, attachment-download-urls.ts)
-    // renders only when some listed file actually carries a URL — its wording
-    // keys on what kind of URL the storage backend mints.
-    if (downloadUrlKind !== undefined && files.some((f) => f.downloadUrl !== undefined)) {
-        section += "\n" + downloadUrlDisclosureLine(downloadUrlKind) + "\n";
+    if (lines.urlHandoff !== undefined) {
+        section += "\n" + lines.urlHandoff + "\n";
     }
-    // The vision lines (shared wording, attachment-vision.ts) tell the model
-    // which of these files it can already SEE inline in the user message versus
-    // which degraded to path-only — without them an agent silently ignores a
-    // photo the user believes it can see.
-    if (vision) {
-        const lines = visionDisclosureLines(vision.inlineFilenames, vision.notViewable);
-        if (lines.length > 0) {
-            section += "\n" + lines.join("\n") + "\n";
-        }
+    if (lines.vision.length > 0) {
+        section += "\n" + lines.vision.join("\n") + "\n";
     }
     return section;
 }