@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/memory/thread-history.js

@@ -29,7 +29,7 @@ import { hasReportedUsage } from "../loop/metrics.js";
 import { countTokens } from "./count-tokens.js";
 import { conversationView, groupTurns, isGenuineUserStart } from "./conversation-view.js";
 import { HARNESS_PROVIDER_NAMESPACE, SYNTHETIC_MESSAGE_KEY, envelopeMessage, parseStoredMessageEnvelope, syntheticRecordMessage, } from "./ai-sdk-message-storage.js";
-import { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./conversation-display-storage.js";
+import { conversationDisplayPart, envelopeDisplayMessages, parseStoredDisplayEnvelope, } from "./conversation-display-storage.js";
 /** A resolved `ok(undefined)` ResultAsync — the empty/seed transaction step. */
 function okVoid() {
     return new ResultAsync(Promise.resolve(ok(undefined)));
@@ -44,11 +44,21 @@ function okVoid() {
  * never shown. The harness owns the record-to-`system` mapping for the same
  * reason it owns the marker — a host that hand-assembled either could produce a
  * message the turn-boundary predicates fail to recognise.
+ *
+ * With `displayParts`, the display message holds those parts in place of the
+ * text part, and the model message is still the record of `text`. The text then
+ * stays for the model alone.
  */
-export function conversationRecordTurn(text) {
+export function conversationRecordTurn(text, displayParts) {
     return {
         modelMessages: [syntheticRecordMessage(text)],
-        displayMessages: [{ id: randomUUID(), role: "system", parts: [{ type: "text", text, state: "done" }] }],
+        displayMessages: [
+            {
+                id: randomUUID(),
+                role: "system",
+                parts: displayParts !== undefined && displayParts.length > 0 ? displayParts.map(conversationDisplayPart) : [{ type: "text", text, state: "done" }],
+            },
+        ],
     };
 }
 /**
@@ -214,6 +224,102 @@ function closeTurnRecord(client, threadId, startSeq, close) {
                 SET status = $3, reason = $4, reported_usage = $5::jsonb, turn_duration_ms = $6, closed_at = NOW()
               WHERE thread_id = $1 AND start_seq = $2 AND status = 'open'`, [threadId, startSeq, close.status, close.reason === undefined ? null : stripNulCharacters(close.reason), rollup, close.turnDurationMs ?? null])).map(() => undefined);
 }
+/** The columns of a display-read row, and the join that the turn record needs. Both display reads select them. */
+const STORED_ROW_COLUMNS = `messages.seq::text AS seq, messages.message_envelope, messages.display_envelope, messages.reported_usage,
+                messages.turn_duration_ms::text AS turn_duration_ms, messages.author, messages.created_at,
+                turns.status AS turn_status, turns.reason AS turn_reason, turns.reported_usage AS turn_usage,
+                turns.turn_duration_ms::text AS turn_record_duration_ms`;
+function storedRowFrom(turnJoinBounds = "") {
+    return `FROM messages
+         LEFT JOIN cortex_thread_turns turns ON turns.thread_id = messages.thread_id AND turns.start_seq = messages.seq${turnJoinBounds}`;
+}
+/** The largest `bigint`, the bound of a cursor that the caller did not give. */
+const MAX_SEQ = "9223372036854775807";
+/** The smallest `bigint`, below every `seq`. */
+const MIN_SEQ = "'-9223372036854775808'";
+const PAGE_LOWER_BOUND = `COALESCE((SELECT seq FROM page_lower), ${MIN_SEQ}::bigint)`;
+const PAGE_UPPER_BOUND = `COALESCE((SELECT seq FROM page_upper), ${MAX_SEQ}::bigint)`;
+/**
+ * The statement of one page of the display read (`$1` thread, `$2` cursor or `NULL`, `$3` limit).
+ *
+ * One statement reads one snapshot, thus an append or a retract cannot add a turn between the
+ * read of the page edges and the read of the rows. The parts:
+ *
+ * - `page_walk`: a walk down from the cursor, one row for each step, that counts the turn starts
+ *   and stops at the `$3`-th. Each step is a `LIMIT 1` read of the primary key `(thread_id, seq)`
+ *   that evaluates the start predicate in the select list.
+ * - `page_lower`: the row where the walk reached `$3` starts, else `NULL`. A page that is not
+ *   full reaches the start of the thread and holds the rows before the first turn start.
+ * - `page_climb` and `page_upper`: a walk up from the cursor to the first turn start at or above
+ *   it, else `NULL`. For a cursor that a page gave this is the cursor row. For a cursor inside a
+ *   turn it is the start of the next turn, thus the turn of the cursor stays whole.
+ * - `page_next`: `page_lower` when a row lies below it. The `EXISTS` reads no envelope.
+ *
+ * The start predicate is never a `WHERE` condition of a scan that has an `ORDER BY` and a `LIMIT`.
+ * The planner has no statistics for a JSON path, so it estimates that very few rows match. It then
+ * chooses a bitmap scan and a sort of each row of the thread, and it evaluates the predicate on the
+ * envelope of each row (a tool result can be many KB). A walk of `LIMIT 1` reads of the key does
+ * not depend on that estimate, and its work grows with the rows of the page.
+ *
+ * An absent cursor, `page_lower`, and `page_upper` each become a `bigint` extreme through
+ * `COALESCE`, never a `NULL` in a comparison: `seq >= NULL` matches no row, and a form such as
+ * `($2 IS NULL OR seq < $2)` is a filter, which would visit each newer row. Each bound is an
+ * index condition on `(thread_id, seq)`. The join to the turn records carries the same bounds,
+ * because the planner estimates a bounded range as a fixed fraction of the thread and then reads
+ * each turn record of the thread through a hash join.
+ */
+const PAGE_SQL = `WITH RECURSIVE page_walk(seq, starts) AS (
+           SELECT COALESCE($2::bigint, ${MAX_SEQ}::bigint), 0::bigint
+           UNION ALL
+           SELECT below.seq, page_walk.starts + below.is_start::int
+             FROM page_walk
+            CROSS JOIN LATERAL (
+              SELECT messages.seq, COALESCE(${GENUINE_USER_START_SQL}, false) AS is_start FROM messages
+               WHERE messages.thread_id = $1 AND messages.seq < page_walk.seq
+               ORDER BY messages.seq DESC
+               LIMIT 1
+            ) below
+            WHERE page_walk.starts < $3::bigint
+         ),
+         page_lower AS (
+           SELECT (SELECT page_walk.seq FROM page_walk WHERE page_walk.starts = $3::bigint) AS seq
+         ),
+         page_climb(seq, is_start) AS (
+           SELECT above.seq, above.is_start FROM (
+             SELECT messages.seq, COALESCE(${GENUINE_USER_START_SQL}, false) AS is_start FROM messages
+              WHERE messages.thread_id = $1 AND messages.seq >= COALESCE($2::bigint, ${MAX_SEQ}::bigint)
+              ORDER BY messages.seq ASC
+              LIMIT 1
+           ) above
+           UNION ALL
+           SELECT above.seq, above.is_start
+             FROM page_climb
+            CROSS JOIN LATERAL (
+              SELECT messages.seq, COALESCE(${GENUINE_USER_START_SQL}, false) AS is_start FROM messages
+               WHERE messages.thread_id = $1 AND messages.seq > page_climb.seq
+               ORDER BY messages.seq ASC
+               LIMIT 1
+            ) above
+            WHERE NOT page_climb.is_start
+         ),
+         page_upper AS (
+           SELECT page_climb.seq FROM page_climb WHERE page_climb.is_start
+         ),
+         page_next AS (
+           SELECT page_lower.seq FROM page_lower
+            WHERE page_lower.seq IS NOT NULL
+              AND EXISTS (SELECT 1 FROM messages WHERE thread_id = $1 AND seq < page_lower.seq)
+         )
+         SELECT ${STORED_ROW_COLUMNS}, (SELECT seq::text FROM page_next) AS next_before
+         ${storedRowFrom(` AND turns.start_seq >= ${PAGE_LOWER_BOUND} AND turns.start_seq < ${PAGE_UPPER_BOUND}`)}
+         WHERE messages.thread_id = $1
+           AND messages.seq >= ${PAGE_LOWER_BOUND}
+           AND messages.seq < ${PAGE_UPPER_BOUND}
+         ORDER BY messages.seq ASC`;
+/** The limit that the page statement receives: an integer, at least 1, and a bigint-safe size. */
+function pageLimit(limit) {
+    return Number.isFinite(limit) ? Math.min(Math.max(1, Math.trunc(limit)), Number.MAX_SAFE_INTEGER) : 1;
+}
 /**
  * Create a `ThreadHistory` bound to a Postgres pool — a factory closure
  * capturing `pool` (dependency injection per the harness-durable-runtime spec). The `messages` table is
@@ -286,59 +392,72 @@ export function createThreadHistory(pool, logger) {
             return view.messages;
         });
     }
-    // Display reads are turn-bounded, not row-bounded. A serial-tool assistant
-    // turn is persisted as one row per step (plus its tool_result `user` rows),
-    // so a row-windowed page could split a turn — truncating the trailing
-    // report card/text out of the page the UI fetches. Read the thread and group
-    // into turns, so a turn always reloads intact. Threads are conversation-scoped
-    // and bounded, so reading every row here matches `loadRecent`'s existing
+    // A display read is turn-bounded, not row-bounded. A serial-tool assistant
+    // turn is persisted as one row per step (plus its tool_result rows), so a
+    // row-windowed read could split a turn and truncate the trailing report
+    // card or text out of what the UI fetches. Both reads group rows into turns,
+    // so a turn always reloads intact.
+    // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
+    // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
+    // The duration and the author obey the same rule, each from its own column.
+    // The creation time is unconditional: its column is NOT NULL, thus it has no
+    // absence to represent.
+    async function toStoredMessage(threadId, r) {
+        const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
+        const displayEnvelope = r.display_envelope == null ? undefined : await parseStoredDisplayEnvelope(r.display_envelope, `${threadId}/${r.seq}/display`, logger);
+        const turn = r.turn_status === null
+            ? undefined
+            : {
+                status: r.turn_status,
+                ...(r.turn_reason === null ? {} : { reason: r.turn_reason }),
+                ...(r.turn_usage === null ? {} : { usage: r.turn_usage }),
+                ...(r.turn_record_duration_ms === null ? {} : { durationMs: Number(r.turn_record_duration_ms) }),
+            };
+        return {
+            seq: Number(r.seq),
+            envelope,
+            message: envelope.message,
+            ...(displayEnvelope ? { displayEnvelope } : {}),
+            ...(r.reported_usage === null ? {} : { usage: r.reported_usage }),
+            ...(r.turn_duration_ms === null ? {} : { durationMs: Number(r.turn_duration_ms) }),
+            ...(turn === undefined ? {} : { turn }),
+            ...(r.author === null ? {} : { author: r.author }),
+            createdAt: r.created_at,
+        };
+    }
+    async function toTurns(threadId, rows) {
+        const stored = await Promise.all(rows.map((row) => toStoredMessage(threadId, row)));
+        return groupTurns(stored, (row) => isGenuineUserStart(row.message));
+    }
     async function readTurns(threadId) {
         const { rows } = await pool.query(
         // ORDER BY must qualify `messages.seq` — a bare `seq` would bind to the
         // `seq::text AS seq` output alias (Postgres resolves an unqualified
         // ORDER BY name to the output column), sorting the bigint as text:
         // "10" before "2". The qualified name forces the bigint column.
-        `SELECT messages.seq::text AS seq, messages.message_envelope, messages.display_envelope, messages.reported_usage,
-                messages.turn_duration_ms::text AS turn_duration_ms, messages.author, messages.created_at,
-                turns.status AS turn_status, turns.reason AS turn_reason, turns.reported_usage AS turn_usage,
-                turns.turn_duration_ms::text AS turn_record_duration_ms
-         FROM messages
-         LEFT JOIN cortex_thread_turns turns ON turns.thread_id = messages.thread_id AND turns.start_seq = messages.seq
+        `SELECT ${STORED_ROW_COLUMNS}
+         ${storedRowFrom()}
          WHERE messages.thread_id = $1
          ORDER BY messages.seq ASC`, [threadId]);
-        // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
-        // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
-        // The duration and the author obey the same rule, each from its own column.
-        // The creation time is unconditional: its column is NOT NULL, thus it has no
-        // absence to represent.
-        const stored = await Promise.all(rows.map(async (r) => {
-            const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
-            const displayEnvelope = r.display_envelope == null ? undefined : await parseStoredDisplayEnvelope(r.display_envelope, `${threadId}/${r.seq}/display`, logger);
-            const turn = r.turn_status === null
-                ? undefined
-                : {
-                    status: r.turn_status,
-                    ...(r.turn_reason === null ? {} : { reason: r.turn_reason }),
-                    ...(r.turn_usage === null ? {} : { usage: r.turn_usage }),
-                    ...(r.turn_record_duration_ms === null ? {} : { durationMs: Number(r.turn_record_duration_ms) }),
-                };
-            return {
-                seq: Number(r.seq),
-                envelope,
-                message: envelope.message,
-                ...(displayEnvelope ? { displayEnvelope } : {}),
-                ...(r.reported_usage === null ? {} : { usage: r.reported_usage }),
-                ...(r.turn_duration_ms === null ? {} : { durationMs: Number(r.turn_duration_ms) }),
-                ...(turn === undefined ? {} : { turn }),
-                ...(r.author === null ? {} : { author: r.author }),
-                createdAt: r.created_at,
-            };
-        }));
-        return groupTurns(stored, (row) => isGenuineUserStart(row.message));
+        return toTurns(threadId, rows);
+    }
+    async function readPage(threadId, options) {
+        const { rows } = await pool.query(PAGE_SQL, [
+            threadId,
+            options.before === undefined ? null : String(options.before),
+            pageLimit(options.limit),
+        ]);
+        // The cursor rides each row, and an empty page has no row. An empty page has no cursor either:
+        // `page_lower` is set only when its row is in the page.
+        const next = rows[0]?.next_before ?? null;
+        return { turns: await toTurns(threadId, rows), before: next === null ? null : Number(next) };
     }
     function loadAll(threadId) {
         return tryQuery("thread-history.loadAll", () => readTurns(threadId));
     }
+    function loadPage(threadId, options) {
+        return tryQuery("thread-history.loadPage", () => readPage(threadId, options));
+    }
     function retractLastTurn(threadId) {
         return withTransaction(pool, "thread-history.retractLastTurn", (client) => 
         // Take the SAME per-thread advisory lock `appendTurn` takes, and take it
@@ -416,5 +535,5 @@ export function createThreadHistory(pool, logger) {
                 AND seq > $2::bigint
                 AND ${GENUINE_USER_START_SQL}`, [threadId, seq])).map(({ rows }) => Number(rows[0].turns));
     }
-    return { appendTurn, writeTurn, loadRecent, loadAll, retractLastTurn, latestSeq, latestTurnAt, countUserTurnsAfter };
+    return { appendTurn, writeTurn, loadRecent, loadAll, loadPage, retractLastTurn, latestSeq, latestTurnAt, countUserTurnsAfter };
 }

package/dist/memory/thread-store.d.ts

@@ -169,6 +169,12 @@ export interface ListThreadsInput {
     /** Narrow to one thread's direct children, exact match. Same polarity as `type`: omitting it narrows nothing. */
     readonly parentThreadId?: string;
 }
+export interface ListRecentThreadsInput {
+    /** The most threads to give. It clamps to 1 to 200, the bounds of a page of `listThreads`. */
+    readonly limit: number;
+    /** Narrow to one kind of session, exact match. Omitting it narrows nothing. */
+    readonly type?: ThreadType;
+}
 export interface ThreadPage {
     readonly threads: Thread[];
     readonly total: number;
@@ -247,6 +253,13 @@ export interface ThreadStore {
      * always describe whichever set the page was drawn from.
      */
     listThreads(input: ListThreadsInput): ResultAsync<ThreadPage, DbError>;
+    /**
+     * The newest live threads over every analysis, newest-updated first, with
+     * `thread_id` breaking a tie in ascending order. One statement that walks
+     * the live-row index on the update time. `type` narrows the result, and an
+     * archived thread is never in it.
+     */
+    listRecentThreads(input: ListRecentThreadsInput): ResultAsync<Thread[], DbError>;
 }
 /**
  * Create a `ThreadStore` bound to a Postgres pool — a factory closure

package/dist/memory/thread-store.js

@@ -366,5 +366,19 @@ export function createThreadStore(pool) {
             }));
         });
     }
-    return { createThread, getThread, updateTitle, setAutoTitle, archiveThread, unarchiveThread, purgeThread, listThreads };
+    function listRecentThreads(input) {
+        const limit = Math.min(Math.max(input.limit, 1), MAX_PER_PAGE);
+        const values = [limit];
+        let typePredicate = "";
+        if (input.type !== undefined) {
+            values.push(input.type);
+            typePredicate = " AND thread_type = $2";
+        }
+        return tryQuery("thread-store.listRecentThreads", () => pool.query(`SELECT ${THREAD_COLUMNS}
+         FROM cortex_analysis_threads
+         WHERE deleted_at IS NULL${typePredicate}
+         ORDER BY updated_at DESC, thread_id
+         LIMIT $1`, values)).map(({ rows }) => rows.map(toThread));
+    }
+    return { createThread, getThread, updateTitle, setAutoTitle, archiveThread, unarchiveThread, purgeThread, listThreads, listRecentThreads };
 }

package/dist/prompts/briefing.d.ts

@@ -24,14 +24,20 @@
 import { type WorkingMemory } from "../memory/working-memory.js";
 import type { DataProfileResult } from "../state/data-profile.js";
 import type { AnalysisStep } from "../schemas/workflow-state.js";
+import type { TemplateParameter } from "../tools/knowledge/client.js";
+import type { TemplateBindingValue } from "../tools/knowledge/template.js";
 /** Completed dependencies rendered as upstream blocks; the tail is counted, not rendered. */
 export declare const MAX_UPSTREAM_DEPS = 5;
 /** Characters of each dependency's summary carried in the seed — the gist, not the document. */
 export declare const UPSTREAM_SUMMARY_MAX_CHARS = 500;
 /** Artifact paths listed per dependency; the rest are reachable from its output directory. */
 export declare const MAX_UPSTREAM_ARTIFACTS = 8;
+/** Adaptable slots rendered in the Template contract section; the tail is counted, not rendered. */
+export declare const MAX_TEMPLATE_SLOTS = 24;
+/** Characters of one slot description carried in the seed — the constraint, not the manual. */
+export declare const TEMPLATE_SLOT_DESCRIPTION_MAX_CHARS = 160;
 /** Fields whose content is agent-facing and MUST appear in the rendered task. */
-export declare const STEP_TASK_FIELDS: readonly ["name", "question", "description", "context", "constraints", "acceptance_criteria", "caveats"];
+export declare const STEP_TASK_FIELDS: readonly ["name", "question", "description", "context", "constraints", "acceptance_criteria", "caveats", "grounding"];
 /**
  * Fields deliberately excluded from the task section: identity/DAG structure
  * threaded separately through the workflow input, execution knobs, and result
@@ -41,7 +47,7 @@ export declare const STEP_TASK_FIELDS: readonly ["name", "question", "descriptio
  * {@link renderResources} section, because the budget is an execution bound,
  * not a task instruction.
  */
-export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type", "depends_on", "status", "resources", "agent", "timeout", "maxSteps", "summary", "artifactIds", "error", "packages"];
+export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type", "depends_on", "status", "resources", "agent", "timeout", "maxSteps", "summary", "artifactIds", "error", "packages", "capability"];
 /**
  * The step's own instructions. Only `question` is guaranteed present; the
  * remaining task fields are appended as dedicated sections when populated, so a
@@ -50,7 +56,7 @@ export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type",
  * folded in here — otherwise the agent runs against the bare question and
  * improvises the rest.
  */
-export declare function renderTask(step: AnalysisStep): string;
+export declare function renderTask(step: AnalysisStep, contract?: Pick<StepBriefing, "template" | "templateNotRetrieved">): string;
 /**
  * The heading of the analysis-memory section. The orient core of the sandbox
  * prompt names this same text, thus a test pins the two together.
@@ -75,6 +81,46 @@ export declare function emptyStepMemory(): StepMemory;
  * entry — it has no memory tool.
  */
 export declare function renderMemory(memory: StepMemory): string;
+/** A file the script of the template reads. `path` names the slot that gives it, for example `{{counts_path}}`. */
+export interface TemplateBriefInput {
+    readonly name: string;
+    readonly path: string;
+    readonly description?: string;
+}
+/** One plan setting bound to an adaptable slot of the template. */
+export interface TemplateBoundSetting {
+    readonly name: string;
+    readonly value: TemplateBindingValue;
+    /** The source of the value (a doi or a document), or `plan` when the procedure names none. */
+    readonly source: string;
+}
+/**
+ * The contract of the template a step renders, projected for the seed. The
+ * parent fetches it at dispatch and binds the plan settings to it; the
+ * section is what lets an agent that has never seen the template make one
+ * valid render call.
+ */
+export interface TemplateBrief {
+    /** The template reference of the plan step, with its version when the plan names one. */
+    readonly ref: string;
+    /** The version the service serves. Differs from the version of `ref` when the snapshot moved on. */
+    readonly version_served: string;
+    /** The adaptable slots of the contract, in the order the template declares them. A pinned slot is never rendered. */
+    readonly slots: readonly TemplateParameter[];
+    readonly inputs: readonly TemplateBriefInput[];
+    /** The plan settings bound to a slot, in plan order. Empty when the served version differs from the plan. */
+    readonly bound: readonly TemplateBoundSetting[];
+    /** The plan settings no bound slot carries, one line each with the reason. */
+    readonly unbound_settings: readonly string[];
+}
+/**
+ * The Template contract section. Only the adaptable slots render, bounded by
+ * {@link MAX_TEMPLATE_SLOTS} and the description clamp, so a wide template
+ * cannot blow the seed. A served version that differs from the plan renders
+ * as a caveat: the render refuses the plan version, and the settings are not
+ * bound to a version the plan did not name.
+ */
+export declare function renderTemplateContract(brief: TemplateBrief | undefined): string;
 /**
  * What anchors every path the agent writes or reads: the id the tree is mounted
  * at, and the step's writable directory.
@@ -136,6 +182,14 @@ export interface StepBriefing {
     readonly upstream: readonly UpstreamHandoff[];
     /** The goal and the constraints of the analysis, read from the working memory at dispatch. */
     readonly memory: StepMemory;
+    /** The contract of the template the step renders, with the plan settings bound to it. Absent when none was retrieved. */
+    readonly template?: TemplateBrief;
+    /**
+     * Why the seed carries no template contract for a step whose grounding
+     * names one: no client is bound, the service did not answer, or the
+     * service does not hold the template. Read only when `template` is absent.
+     */
+    readonly templateNotRetrieved?: string;
 }
 /**
  * Compose the seed. Absent sections collapse out entirely — an independent step

package/dist/prompts/briefing.js

@@ -30,6 +30,10 @@ export const MAX_UPSTREAM_DEPS = 5;
 export const UPSTREAM_SUMMARY_MAX_CHARS = 500;
 /** Artifact paths listed per dependency; the rest are reachable from its output directory. */
 export const MAX_UPSTREAM_ARTIFACTS = 8;
+/** Adaptable slots rendered in the Template contract section; the tail is counted, not rendered. */
+export const MAX_TEMPLATE_SLOTS = 24;
+/** Characters of one slot description carried in the seed — the constraint, not the manual. */
+export const TEMPLATE_SLOT_DESCRIPTION_MAX_CHARS = 160;
 // ── Field partition (the coverage guard's two halves) ─────────────────
 /** Fields whose content is agent-facing and MUST appear in the rendered task. */
 export const STEP_TASK_FIELDS = [
@@ -40,6 +44,9 @@ export const STEP_TASK_FIELDS = [
     "constraints",
     "acceptance_criteria",
     "caveats",
+    // The step agent reads the template id and the claim identifiers from the
+    // step, not from prose: the grounding renders beside the task fields.
+    "grounding",
 ];
 /**
  * Fields deliberately excluded from the task section: identity/DAG structure
@@ -70,6 +77,11 @@ export const STEP_NON_TASK_FIELDS = [
     // the agent does need to know about them — a dropped entry, or a step that
     // declares none — rides in `caveats`.
     "packages",
+    // Withheld for the same reason as `packages`, one layer up: the phrase is how the router and
+    // the planner name what they routed on, and the launch has already resolved the reference data
+    // it declares. The step agent learns the work from its skill pack, which names each dataset by
+    // what it is. Handing it a routing phrase would invite it to treat that phrase as the method.
+    "capability",
 ];
 // ── Formatting primitives ─────────────────────────────────────────────
 function section(heading, body) {
@@ -95,7 +107,7 @@ function clamp(text, max) {
  * folded in here — otherwise the agent runs against the bare question and
  * improvises the rest.
  */
-export function renderTask(step) {
+export function renderTask(step, contract = {}) {
     const parts = [`# ${step.name}`, section("Task", step.question)];
     if (step.description?.trim()) {
         parts.push(section("What this step produces", step.description.trim()));
@@ -112,8 +124,46 @@ export function renderTask(step) {
     if (step.caveats && step.caveats.length > 0) {
         parts.push(section("Caveats", bullets(step.caveats)));
     }
+    if (step.grounding) {
+        parts.push(section("Grounding", renderGrounding(step.grounding, contract)));
+    }
     return parts.join("\n\n");
 }
+/**
+ * The grounding as data lines. The template id is the one value the agent
+ * acts on (it names it to `knowledge_template`), thus it renders first after
+ * the status. The claim identifiers and the digest are for the record.
+ *
+ * A grounding that names a template promises a Template contract section.
+ * When the seed carries none, one line says so with the reason, thus the
+ * agent knows the contract was not fetched rather than guessing at slots.
+ *
+ * The settings of the procedure ride here as vetted values, not as
+ * constraints: the agent uses each one unless the data gives a reason for
+ * another value, and then it states the reason. They render only when the
+ * seed carries no template contract, because the bound and the unbound
+ * lists of the contract hold every setting already.
+ */
+function renderGrounding(grounding, contract) {
+    const lines = [`- Status: ${grounding.status}`];
+    if (grounding.template) {
+        lines.push(`- Template: \`${grounding.template}\``);
+        if (!contract.template)
+            lines.push(`- Template contract: not retrieved (${contract.templateNotRetrieved ?? "no contract was fetched for this step"})`);
+    }
+    lines.push(`- Snapshot: ${grounding.snapshot}`);
+    lines.push(`- Claims: ${grounding.claims.length > 0 ? grounding.claims.join(", ") : "none"}`);
+    lines.push(`- Reason: ${grounding.reason}`);
+    const settings = grounding.settings ?? [];
+    if (settings.length > 0 && !contract.template) {
+        lines.push("- Settings (the vetted values of the procedure; another value is permitted when your summary states the reason):");
+        for (const setting of settings) {
+            const value = Array.isArray(setting.value) ? setting.value.join(", ") : String(setting.value);
+            lines.push(`  - ${setting.step}: ${setting.name} = ${value}${setting.source ? ` (${setting.source})` : ""}`);
+        }
+    }
+    return lines.join("\n");
+}
 // ── (1b) Analysis memory ──────────────────────────────────────────────
 /**
  * The heading of the analysis-memory section. The orient core of the sandbox
@@ -155,6 +205,82 @@ export function renderMemory(memory) {
     }
     return section(ANALYSIS_MEMORY_HEADING, parts.join("\n\n"));
 }
+/** A value as the render request carries it: JSON, thus `"apeglm"` and `10` cannot be confused. */
+function slotValue(value) {
+    return JSON.stringify(value);
+}
+/** The version of a template reference (`tpl-x@1.0.0` gives `1.0.0`), or `undefined` when the reference has none. */
+function versionOfRef(ref) {
+    const at = ref.indexOf("@");
+    return at < 0 ? undefined : ref.slice(at + 1);
+}
+/**
+ * One adaptable slot as a bullet: the name, the type, the default with its
+ * source or the required state, the description, and the constraints the
+ * render enforces. A slot without a default is required unless the contract
+ * says otherwise, which is the rule of the renderer.
+ */
+function renderSlot(slot) {
+    const facts = [slot.type];
+    // A local slot is bound on this machine: the agent sends it as any other slot, and the value never leaves.
+    if (slot.local)
+        facts.push("local");
+    if (slot.default !== undefined) {
+        facts.push(`default ${slotValue(slot.default)}${slot.default_source ? ` [${slot.default_source}]` : ""}`);
+    }
+    else {
+        facts.push(slot.required === false ? "optional" : "required");
+    }
+    if (slot.minimum !== undefined)
+        facts.push(`min ${slot.minimum}`);
+    if (slot.maximum !== undefined)
+        facts.push(`max ${slot.maximum}`);
+    const tail = [];
+    if (slot.enum && slot.enum.length > 0)
+        tail.push(`Permitted: ${slot.enum.map(slotValue).join(", ")}.`);
+    if (slot.pattern)
+        tail.push(`Pattern: \`${slot.pattern}\`.`);
+    const description = clamp(slot.description.trim(), TEMPLATE_SLOT_DESCRIPTION_MAX_CHARS);
+    return `\`${slot.name}\` (${facts.join("; ")})${description ? `: ${description}` : ""}${tail.length > 0 ? ` ${tail.join(" ")}` : ""}`;
+}
+/**
+ * The Template contract section. Only the adaptable slots render, bounded by
+ * {@link MAX_TEMPLATE_SLOTS} and the description clamp, so a wide template
+ * cannot blow the seed. A served version that differs from the plan renders
+ * as a caveat: the render refuses the plan version, and the settings are not
+ * bound to a version the plan did not name.
+ */
+export function renderTemplateContract(brief) {
+    if (!brief)
+        return "";
+    const refVersion = versionOfRef(brief.ref);
+    const lead = [
+        `\`${brief.ref}\` (the service serves version ${brief.version_served}). Send only the slots listed here to \`knowledge_template\`; a slot not listed is pinned or unknown, and the render refuses it.`,
+    ];
+    if (refVersion !== undefined && refVersion !== brief.version_served) {
+        lead.push(`Caveat: the plan names version ${refVersion}, and the service serves version ${brief.version_served}. The plan settings are not bound to this render. Render the served version, and state each plan value yourself.`);
+    }
+    const blocks = [lead.join("\n")];
+    const adaptable = brief.slots.filter((slot) => slot.adaptable);
+    if (adaptable.length > 0) {
+        const shown = adaptable.slice(0, MAX_TEMPLATE_SLOTS);
+        const lines = [bullets(shown.map(renderSlot))];
+        const omitted = adaptable.length - shown.length;
+        if (omitted > 0)
+            lines.push(`(+${omitted} more adaptable ${omitted === 1 ? "slot" : "slots"} not listed. The render answer names a required one that is absent.)`);
+        blocks.push(`Slots:\n${lines.join("\n")}`);
+    }
+    if (brief.inputs.length > 0) {
+        blocks.push(`Inputs the script reads:\n${bullets(brief.inputs.map((input) => `${input.name}: \`${input.path}\`${input.description ? ` — ${input.description}` : ""}`))}`);
+    }
+    if (brief.bound.length > 0) {
+        blocks.push(`Bound by the plan (send each value as it is, or add an \`overrides\` entry with the slot and the reason for the change; a changed value without an override is refused):\n${bullets(brief.bound.map((setting) => `\`${setting.name}\` = ${slotValue(setting.value)} (${setting.source})`))}`);
+    }
+    if (brief.unbound_settings.length > 0) {
+        blocks.push(`Unbound settings (the plan states them, and no bound slot carries them):\n${bullets(brief.unbound_settings)}`);
+    }
+    return section("Template contract", blocks.join("\n\n"));
+}
 /** The in-sandbox analysis root of a frame — the read-only mount of the whole tree. */
 export function analysisRootOf(frame) {
     return `/${frame.analysisId}`;
@@ -240,7 +366,8 @@ function renderHandoff(handoff) {
  */
 export function composeStepBriefing(briefing) {
     return [
-        renderTask(briefing.step),
+        renderTask(briefing.step, briefing),
+        renderTemplateContract(briefing.template),
         renderMemory(briefing.memory),
         renderWorkspace(briefing.workspace),
         renderResources(briefing.step.resources),