@inflexa-ai/harness 0.48.0 → 0.48.2

package/dist/loop/tool-value.js

@@ -0,0 +1,249 @@
+/**
+ * The shown values of a tool call: its input, its result, and its error.
+ *
+ * The emit site makes each value one time, and a host only shows it. A tool declares what it shows through its view
+ * (`tools/tool-view.ts`), and {@link makeToolCallValue} turns the output of a view member into a value with a kind.
+ * Each leaf of a value gets the steps below on its own. The steps run in this order, because each step
+ * protects the next one: the control characters go first, thus a control byte inside a secret cannot stop a pattern.
+ * The secrets go before the cut, thus a cut cannot divide a secret and let one half pass. The shown text can differ
+ * from the text that the model reads.
+ */
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+import { TOOL_CALL_FIELDS_MAX, ToolCallValueSchema } from "../contracts/schemas/chat-events.js";
+import { isUnknownArray } from "../lib/unknown-array.js";
+import { parseJsonAs } from "../lib/parse-json.js";
+import { describeZodIssueShapes } from "../lib/zod-issue-shape.js";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
+import { normalizeUnicode, redactSecretFields, redactSecretForms, redactSecrets } from "../input-sanitization.js";
+import { ViewCode, ViewFields, ViewJson, ViewText } from "../tools/tool-view.js";
+import { pairSafeIndex } from "./tool-output.js";
+/** A text longer than this is cut. The unit is the UTF-16 code unit. */
+export const TOOL_VALUE_CAP = 8 * 1024;
+/** The start of a cut text holds the shape of a value. */
+export const TOOL_VALUE_HEAD_CHARS = 3 * 1024;
+/** The end of a cut text holds the errors of a command, thus it gets more room than the start. */
+export const TOOL_VALUE_TAIL_CHARS = 5 * 1024;
+/**
+ * The text past each shown part that the rules also read. A secret at the edge of a shown part is whole in its window
+ * when it is shorter than this margin, thus the rules see it as they see it in the whole text.
+ */
+export const TOOL_VALUE_CLEAN_MARGIN = 8 * 1024;
+const HEAD_WINDOW = TOOL_VALUE_HEAD_CHARS + TOOL_VALUE_CLEAN_MARGIN;
+const TAIL_WINDOW = TOOL_VALUE_TAIL_CHARS + TOOL_VALUE_CLEAN_MARGIN;
+/**
+ * A text up to this length gets the rules whole. A longer text gets them on its two windows only, thus the cost of a
+ * value does not grow with the size of a result.
+ */
+const WHOLE_CLEAN_MAX = HEAD_WINDOW + TAIL_WINDOW;
+function cleanText(text) {
+    return redactSecrets(redactSecretForms(normalizeUnicode(text)));
+}
+function cleanStrings(value) {
+    if (typeof value === "string")
+        return cleanText(value);
+    if (isUnknownArray(value))
+        return value.map(cleanStrings);
+    const record = parseUnknownRecord(value);
+    if (record === undefined)
+        return value;
+    const out = {};
+    for (const [name, field] of Object.entries(record))
+        out[cleanText(name)] = cleanStrings(field);
+    return out;
+}
+/** The shown start of `head` and the shown end of `tail`, with a marker that counts the code units of `length` not shown. */
+function cutParts(head, tail, length) {
+    const shownHead = head.slice(0, pairSafeIndex(head, TOOL_VALUE_HEAD_CHARS, -1));
+    const shownTail = tail.slice(pairSafeIndex(tail, Math.max(0, tail.length - TOOL_VALUE_TAIL_CHARS), 1));
+    const marker = `[... ${Math.max(0, length - shownHead.length - shownTail.length)} characters not shown ...]`;
+    return { text: `${shownHead}\n${marker}\n${shownTail}`, cut: true };
+}
+function cutText(clean) {
+    return clean.length <= TOOL_VALUE_CAP ? { text: clean, cut: false } : cutParts(clean, clean, clean.length);
+}
+/** The shown text of a plain text. A long text gets the rules on its two windows, and its marker counts the original text. */
+function shownText(text) {
+    if (text.length <= WHOLE_CLEAN_MAX)
+        return cutText(cleanText(text));
+    const head = cleanText(text.slice(0, pairSafeIndex(text, HEAD_WINDOW, -1)));
+    const tail = cleanText(text.slice(pairSafeIndex(text, text.length - TAIL_WINDOW, 1)));
+    return cutParts(head, tail, text.length);
+}
+/** The JSON text of a value, or `undefined` for a function, a symbol, and `undefined`, which the lib type omits. */
+function jsonText(value) {
+    return JSON.stringify(value);
+}
+function serializeClean(value) {
+    return jsonText(cleanStrings(redactSecretFields(value)) ?? null) ?? "null";
+}
+/** The fields of a plain record whose JSON text is its own fields, or `undefined` for each other value. */
+function plainFields(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return undefined;
+    const fields = Object.entries(value);
+    return fields.some(([name, field]) => name === "toJSON" && typeof field === "function") ? undefined : fields;
+}
+/**
+ * A copy of one end of `value`: the JSON text of the copy starts (`head`) or ends (`tail`) with at least `budget.left`
+ * code units of the JSON text of `value`. The count of a string ignores its escapes, and an escape only makes the text
+ * longer, thus the copy never holds less than the budget. A value that is not an array, a plain record, or a string
+ * stays whole, because its JSON text comes from its own `toJSON`.
+ */
+function endOf(value, budget, end) {
+    if (typeof value === "string") {
+        const keep = Math.max(0, budget.left);
+        const kept = end === "head" ? value.slice(0, keep) : value.slice(Math.max(0, value.length - keep));
+        budget.left -= kept.length + 2;
+        return kept;
+    }
+    if (isUnknownArray(value)) {
+        budget.left -= 2;
+        const kept = [];
+        for (let index = 0; index < value.length && budget.left > 0; index += 1) {
+            kept.push(endOf(value[end === "head" ? index : value.length - 1 - index], budget, end));
+            budget.left -= 1;
+        }
+        return end === "head" ? kept : kept.reverse();
+    }
+    const fields = plainFields(value);
+    if (fields !== undefined) {
+        budget.left -= 2;
+        const kept = [];
+        for (let index = 0; index < fields.length && budget.left > 0; index += 1) {
+            const entry = fields[end === "head" ? index : fields.length - 1 - index];
+            // JSON text omits such a field, and a test of the field by its own serialization would read all of it.
+            if (entry === undefined || entry[1] === undefined || typeof entry[1] === "function" || typeof entry[1] === "symbol")
+                continue;
+            budget.left -= entry[0].length + 4;
+            kept.push([entry[0], endOf(entry[1], budget, end)]);
+        }
+        return Object.fromEntries(end === "head" ? kept : kept.reverse());
+    }
+    budget.left -= jsonText(value)?.length ?? 0;
+    return value;
+}
+/**
+ * The shown JSON text of a value: `ok(undefined)` when the value has no JSON text, and an error with the reason when
+ * the value does not serialize, for example a cycle.
+ */
+function shownJson(value) {
+    try {
+        const raw = jsonText(value);
+        if (raw === undefined)
+            return ok(undefined);
+        if (raw.length <= WHOLE_CLEAN_MAX)
+            return ok(cutText(serializeClean(value)));
+        const head = serializeClean(endOf(value, { left: HEAD_WINDOW }, "head"));
+        const tail = serializeClean(endOf(value, { left: TAIL_WINDOW }, "tail"));
+        return ok(cutParts(head, tail, raw.length));
+    }
+    catch {
+        return err("the value does not serialize to JSON");
+    }
+}
+function jsonLeaf(value) {
+    return shownJson(value).map((shown) => (shown === undefined ? undefined : { kind: "json", ...shown }));
+}
+/** The leaf of a plain text: control characters out, each secret out, then the cut. */
+export function textToolValue(text) {
+    return { kind: "text", ...shownText(text) };
+}
+/** The leaf of source code. The rules and the cut are those of {@link textToolValue}. `language` is checked with the whole value. */
+export function codeToolValue(language, text) {
+    return { kind: "code", language, ...shownText(text) };
+}
+/**
+ * The leaf of a JSON value. A string shows as a JSON string, and each other value shows as its JSON text.
+ * The field-name rule runs first, then the text rules on each string, then the serialization, then the cut: a text
+ * rule never meets a JSON escape, which would hide the end of a quoted secret.
+ * A long JSON text gets the rules on a copy of each end of the value only, and its marker counts the JSON text of the
+ * original value. Only the serialization of the whole value grows with its size, and the model path pays it already.
+ * A value with no JSON text, and a value that does not serialize, for example a cycle, give no leaf: a value is a
+ * diagnostic and never fails a call.
+ */
+export function jsonToolValue(value) {
+    return jsonLeaf(value).unwrapOr(undefined);
+}
+const AdapterErrorSchema = z.object({ error: z.string() });
+/**
+ * The leaf of an error text. The adapter writes the error of a tool as the JSON text `{ "error": message, ... }`, and
+ * the leaf shows the message. Each other error text, for example a refusal of the call policy, shows whole.
+ */
+export function errorToolValue(text) {
+    try {
+        return textToolValue(parseJsonAs(text, AdapterErrorSchema).error);
+    }
+    catch {
+        return textToolValue(text);
+    }
+}
+function leafValue(leaf) {
+    if (leaf instanceof ViewText)
+        return ok(textToolValue(leaf.text));
+    if (leaf instanceof ViewCode)
+        return ok(codeToolValue(leaf.language, leaf.text));
+    return jsonLeaf(leaf.value);
+}
+function fieldsValue(view) {
+    if (view.fields.length > TOOL_CALL_FIELDS_MAX)
+        return err(`a fields value holds more than ${TOOL_CALL_FIELDS_MAX} fields`);
+    const fields = [];
+    for (const { name, leaf } of view.fields) {
+        // A leaf that is not a leaf class is a nested `fields` value, which the kinds refuse.
+        if (!(leaf instanceof ViewText || leaf instanceof ViewCode || leaf instanceof ViewJson))
+            return err("a fields value holds a fields value");
+        const value = leafValue(leaf);
+        if (value.isErr())
+            return err(`the field ${name.slice(0, 40)}: ${value.error}`);
+        if (value.value !== undefined)
+            fields.push({ name, ...value.value });
+    }
+    return ok(fields.length === 0 ? undefined : { kind: "fields", fields });
+}
+function leafOfOutput(output) {
+    if (typeof output === "string")
+        return ok(textToolValue(output));
+    if (output instanceof ViewText || output instanceof ViewCode || output instanceof ViewJson)
+        return leafValue(output);
+    return jsonLeaf(output).andThen((leaf) => (leaf === undefined ? err("the value has no JSON text") : ok(leaf)));
+}
+/**
+ * The value of the output of a view member: a helper object gives its kind, a string gives a `text` leaf, and each other
+ * value gives a `json` leaf. Each leaf gets the cleaning and the cap of its kind. The result holds no value for an output
+ * that is absent (silent), and for a `fields` value with no field. It holds the reason for an output that cannot show: a
+ * value with no JSON text, a value that does not serialize, and a value that breaks a rule of the kinds (more fields than
+ * the limit, a nested `fields` value, a bad field name, a bad language). The caller logs the reason. It never throws.
+ */
+export function makeToolCallValue(output) {
+    if (output === undefined)
+        return ok(undefined);
+    const made = output instanceof ViewFields ? fieldsValue(output) : leafOfOutput(output);
+    return made.andThen((value) => {
+        if (value === undefined)
+            return ok(undefined);
+        const checked = ToolCallValueSchema.safeParse(value);
+        return checked.success ? ok(checked.data) : err(describeZodIssueShapes(checked.error, ToolCallValueSchema).join("; "));
+    });
+}
+/**
+ * The event without the three values. A forwarder of loop events to the stream of a run calls it, because no reader
+ * of that stream shows a value, and a value costs bytes on each event.
+ */
+export function withoutToolValues(event) {
+    switch (event.type) {
+        case "tool-started": {
+            const { input: _input, ...rest } = event;
+            return rest;
+        }
+        case "tool-finished": {
+            const { input: _input, result: _result, error: _error, ...rest } = event;
+            return rest;
+        }
+        default:
+            return event;
+    }
+}

package/dist/loop/types.d.ts

@@ -3,7 +3,7 @@
  * messages, and the flat event sink.
  */
 import type { ModelMessage } from "ai";
-import type { ToolCallDetail, ToolOutcome } from "../contracts/chat-events.js";
+import type { ToolCallDetail, ToolCallValue, ToolOutcome } from "../contracts/chat-events.js";
 import type { ChatStreamEvent, ProviderOptions } from "../providers/types.js";
 import type { Tool } from "../tools/define-tool.js";
 import type { CompactionRules } from "./compaction.js";
@@ -75,13 +75,14 @@ export type EmitEvent = {
     readonly source: EventSource;
     readonly toolUseId: string;
     readonly name: string;
-    readonly input: unknown;
     /**
      * One line naming what this call is doing, from the tool's own
      * `describeCall` hook. Absent — never empty — when the tool declares no
      * hook or the detail could not be produced (see `tool-detail.ts`).
      */
     readonly detail?: ToolCallDetail;
+    /** The input that the view of the tool declares, with each listed secret form removed and a cap. Absent for a call that is not a root call. */
+    readonly input?: ToolCallValue;
 } | {
     readonly type: "tool-finished";
     readonly source: EventSource;
@@ -101,6 +102,12 @@ export type EmitEvent = {
      * can fall back to its own observation.
      */
     readonly durationMs?: number;
+    /** The input again: a replay of a tool step does not give its `tool-started`. */
+    readonly input?: ToolCallValue;
+    /** The result of a call with the outcome `ok`. */
+    readonly result?: ToolCallValue;
+    /** The error text of a call with the outcome `error`. */
+    readonly error?: ToolCallValue;
 } | {
     /** The display recorder of a chat turn emits it, not the loop. See `MessageStartEvent`. */
     readonly type: "message-start";

package/dist/memory/conversation-display-storage.js

@@ -20,7 +20,7 @@ import { isDataUIPart, validateUIMessages } from "ai";
 import { z } from "zod";
 import { parseUnknownRecord } from "../lib/unknown-containers.js";
 import { AskPartSchema, ChildSessionStartedPartSchema, CompactionPartSchema, FileReferencePartSchema, PlanApprovalPartSchema, PlanPartSchema, PresentationPartSchema, ReportRenderedPartSchema, RunCardPartSchema, SubAgentActivityEntrySchema, SubAgentActivityPartSchema, } from "../contracts/schemas/chat-parts.js";
-import { ToolCallOutcomeSchema } from "../contracts/schemas/chat-events.js";
+import { ToolCallOutcomeSchema, ToolCallValueSchema } from "../contracts/schemas/chat-events.js";
 export const SUPPORTED_DISPLAY_SCHEMA_VERSION = 1;
 const DisplayEnvelopeHeaderSchema = z.object({
     kind: z.literal("ai-sdk-ui-messages"),
@@ -48,6 +48,9 @@ const ToolCallDisplaySchema = z.object({
     outcome: ToolCallOutcomeSchema,
     detail: z.string().optional(),
     durationMs: z.number().optional(),
+    input: ToolCallValueSchema.optional(),
+    result: ToolCallValueSchema.optional(),
+    error: ToolCallValueSchema.optional(),
 });
 /**
  * The schema behind each stored part key.

package/dist/memory/count-tokens.js

@@ -16,6 +16,33 @@ function enc() {
     encoder ??= getEncoding("cl100k_base");
     return encoder;
 }
+/**
+ * A run of this many characters with no whitespace is counted in chunks. The BPE merge of `js-tiktoken` is
+ * quadratic in the length of one pre-token, and a run of one repeated character of 20,000 characters takes
+ * about 13 s whole. A base64 blob or a sequence with no line break is such a run in a tool result.
+ */
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- a run of 256 or more characters with no whitespace; no builtin finds a run by its length.
+const LONG_RUN = /\S{256,}/g;
+/** The chunk of a long run. A chunk of 64 characters costs well under a millisecond in the worst case. */
+const RUN_CHUNK = 64;
+/**
+ * The token count of one text. A text with no long run is one encoding, thus its count is exact. Each long run
+ * is counted in chunks, which can add a token at each chunk edge: the count is an approximation already.
+ */
+function encodedLength(text) {
+    let total = 0;
+    let from = 0;
+    for (const run of text.matchAll(LONG_RUN)) {
+        if (run.index > from)
+            total += enc().encode(text.slice(from, run.index)).length;
+        for (let at = 0; at < run[0].length; at += RUN_CHUNK)
+            total += enc().encode(run[0].slice(at, at + RUN_CHUNK)).length;
+        from = run.index + run[0].length;
+    }
+    if (from < text.length)
+        total += enc().encode(text.slice(from)).length;
+    return total;
+}
 /**
  * The token-bearing text of one tool-result output.
  *
@@ -82,13 +109,13 @@ function tokenizableText(block) {
  */
 export function countTokens(content) {
     if (typeof content === "string") {
-        return content.length === 0 ? 0 : enc().encode(content).length;
+        return content.length === 0 ? 0 : encodedLength(content);
     }
     let total = 0;
     for (const block of content) {
         const text = tokenizableText(block);
         if (text.length > 0)
-            total += enc().encode(text).length;
+            total += encodedLength(text);
     }
     return total;
 }

package/dist/runtime/dbos.d.ts

@@ -98,6 +98,12 @@ export type WorkflowSchedule = {
  * schedule of this list. A second call with the same name replaces the first.
  */
 export declare function scheduleWorkflow(schedule: WorkflowSchedule): void;
+/**
+ * Store each schedule of {@link scheduleWorkflow} in the system database, and delete each stored schedule of this
+ * application that no code registers. DBOS only upserts, thus a schedule of a removed workflow fires on each tick and
+ * finds no function. Each schedule of the harness goes through `scheduleWorkflow`.
+ */
+export declare function applyWorkflowSchedules(): Promise<void>;
 /**
  * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
  * the harness twice (or accidentally double-import) don't re-launch.

package/dist/runtime/dbos.js

@@ -130,6 +130,19 @@ const pendingSchedules = new Map();
 export function scheduleWorkflow(schedule) {
     pendingSchedules.set(schedule.scheduleName, schedule);
 }
+/**
+ * Store each schedule of {@link scheduleWorkflow} in the system database, and delete each stored schedule of this
+ * application that no code registers. DBOS only upserts, thus a schedule of a removed workflow fires on each tick and
+ * finds no function. Each schedule of the harness goes through `scheduleWorkflow`.
+ */
+export async function applyWorkflowSchedules() {
+    if (pendingSchedules.size > 0)
+        await DBOS.applySchedules([...pendingSchedules.values()]);
+    for (const stored of await DBOS.listSchedules()) {
+        if (!pendingSchedules.has(stored.scheduleName))
+            await DBOS.deleteSchedule(stored.scheduleName);
+    }
+}
 let resultRecipesRegistered = false;
 /**
  * DBOS refuses a registration after the launch, and the registry of SuperJSON
@@ -160,8 +173,7 @@ export async function launchDbos({ config, logger: injected }) {
     registerResultSerialization();
     const start = performance.now();
     await DBOS.launch();
-    if (pendingSchedules.size > 0)
-        await DBOS.applySchedules([...pendingSchedules.values()]);
+    await applyWorkflowSchedules();
     state.launched = true;
     state.recoveryStarted = true;
     logger.info("launched", {

package/dist/sandbox/sandbox-step-translate.d.ts

@@ -7,7 +7,6 @@
  */
 import type { ActivityEntryPart, StepActivityPart, StepPhase, SynthesisPhase, SynthesisProgressPart } from "../contracts/chat-parts.js";
 import type { ChatDataPart, EmitFn } from "../loop/types.js";
-import type { ToolDetailResolver } from "../tools/detail-resolver.js";
 /**
  * Stable reconciliation id for a step's reconciling parts
  * (`data-step-activity`, `data-step-file-tree`). One id per (runId, stepId)
@@ -49,11 +48,9 @@ export declare function synthesisEmission(runId: string, stepId: string, seq: nu
  * The live-activity phrase for one tool call: the tool's name, then its own
  * description of this call when it has one.
  *
- * The description comes from the tool's `describeCall` hook, resolved through
- * `resolveDetail` — the same resolver the chat chip and the reloaded transcript
- * use. A caller supplies the resolver for the agent whose calls it is
- * describing, because a sandbox agent's tool list is not the conversation
- * roster's and no single list serves both.
+ * The description is the `detail` of the loop event of the call, which the loop
+ * computed with the `describeCall` hook of the tool. The phrase never reads the
+ * input of the call.
  *
  * The name always leads, and that is load-bearing rather than cosmetic. This
  * phrase is rendered alone, with no tool name beside it — unlike the chat chip,
@@ -61,11 +58,10 @@ export declare function synthesisEmission(runId: string, stepId: string, seq: nu
  * `edit_file` both describe a call by its path, so a detail on its own would
  * render a write and an edit of the same file identically.
  *
- * A tool with no hook, an unknown tool, and an input its schema rejects all fall
- * back to the name alone. No verb is added: the phrase is carried on a part that
+ * An event with no detail falls back to the name alone. No verb is added: the phrase is carried on a part that
  * already states the phase, so "Running" would only restate it.
  */
-export declare function activityForTool(name: string, input?: unknown, resolveDetail?: ToolDetailResolver): string;
+export declare function activityForTool(name: string, detail?: string): string;
 /** On-change working-tree delta the sandbox executor posts per exec (paths
  *  only; the executor skips directories). */
 export type SandboxTreeDelta = {

package/dist/sandbox/sandbox-step-translate.js

@@ -54,11 +54,9 @@ export function synthesisEmission(runId, stepId, seq, phase, activity, at, extra
  * The live-activity phrase for one tool call: the tool's name, then its own
  * description of this call when it has one.
  *
- * The description comes from the tool's `describeCall` hook, resolved through
- * `resolveDetail` — the same resolver the chat chip and the reloaded transcript
- * use. A caller supplies the resolver for the agent whose calls it is
- * describing, because a sandbox agent's tool list is not the conversation
- * roster's and no single list serves both.
+ * The description is the `detail` of the loop event of the call, which the loop
+ * computed with the `describeCall` hook of the tool. The phrase never reads the
+ * input of the call.
  *
  * The name always leads, and that is load-bearing rather than cosmetic. This
  * phrase is rendered alone, with no tool name beside it — unlike the chat chip,
@@ -66,12 +64,10 @@ export function synthesisEmission(runId, stepId, seq, phase, activity, at, extra
  * `edit_file` both describe a call by its path, so a detail on its own would
  * render a write and an edit of the same file identically.
  *
- * A tool with no hook, an unknown tool, and an input its schema rejects all fall
- * back to the name alone. No verb is added: the phrase is carried on a part that
+ * An event with no detail falls back to the name alone. No verb is added: the phrase is carried on a part that
  * already states the phase, so "Running" would only restate it.
  */
-export function activityForTool(name, input, resolveDetail) {
-    const detail = resolveDetail?.(name, input);
+export function activityForTool(name, detail) {
     return detail === undefined ? name : `${name} ${detail}`;
 }
 const SandboxTreeDeltaSchema = z.object({

package/dist/state/artifacts.d.ts

@@ -86,6 +86,8 @@ export type ArtifactPageQuery = {
     q?: string;
     /** The whole path, with case. It selects the one row of that path. */
     path?: string;
+    /** The role of the row. `step_output` selects the rows that the grouped run count of {@link countArtifactsByRuns} counts. */
+    role?: ArtifactRole;
     /**
      * Extensions in lower case, with no dot. A row is selected when the extension of its path is a member. A row with
      * no extension never matches, and an empty list selects each row. The read compares the members as they are.
@@ -125,7 +127,8 @@ export type ArtifactPage = {
  * select, grouped by extension, and the page. The count is a separate statement because a page past the end has no
  * row to carry it. `total` is the sum of the groups.
  *
- * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included. The cost
+ * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included, unless the `role`
+ * filter selects one role. `total` and `extensionCounts` follow the filters. The cost
  * grows with the ledger of the one analysis, because the count reads each filtered row.
  */
 export declare function queryArtifactPage(pool: Querier, analysisId: string, query: ArtifactPageQuery): ResultAsync<ArtifactPage, DbError>;

package/dist/state/artifacts.js

@@ -193,7 +193,8 @@ const EXTENSION_SQL = `lower(substring(regexp_replace(path, '^.*/', '') from '^.
  * select, grouped by extension, and the page. The count is a separate statement because a page past the end has no
  * row to carry it. `total` is the sum of the groups.
  *
- * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included. The cost
+ * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included, unless the `role`
+ * filter selects one role. `total` and `extensionCounts` follow the filters. The cost
  * grows with the ledger of the one analysis, because the count reads each filtered row.
  */
 export function queryArtifactPage(pool, analysisId, query) {
@@ -215,6 +216,8 @@ export function queryArtifactPage(pool, analysisId, query) {
             conditions.push(`strpos(lower(path), lower(${bind(query.q)}::text)) > 0`);
         if (query.path !== undefined)
             conditions.push(`path = ${bind(query.path)}`);
+        if (query.role !== undefined)
+            conditions.push(`role = ${bind(query.role)}`);
         if (query.extensions !== undefined && query.extensions.length > 0) {
             conditions.push(`${EXTENSION_SQL} = ANY(${bind([...query.extensions])}::text[])`);
         }

package/dist/state/index.d.ts

@@ -16,8 +16,8 @@ setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis
 export type { InsertRunInput, RunPage, RunReservation } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun, countStepsByRuns, } from "./step-executions.js";
 export type { InsertStepExecutionInput, RunStepCounts, SeedStepExecutionRow, UpdateStepExecutionInput } from "./step-executions.js";
-export { insertPlan, upsertPlan, loadPlan, loadPlanRecord } from "./plans.js";
-export type { InsertPlanInput, UpsertPlanInput, PlanRecord, PlanRowQuerier } from "./plans.js";
+export { insertPlan, upsertPlan, loadPlan, loadPlanRecord, queryPlanPage } from "./plans.js";
+export type { InsertPlanInput, UpsertPlanInput, PlanRecord, PlanRowQuerier, PlanPage, PlanPageEntry } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export type { DataProfileStatus, DataProfileTerminalWrite, DataProfileResult, DataProfileChecked, DataProfileCompanionCompleteness, DataProfileDimension, DataProfileGroup, DataProfileGroupSlot, DataProfileFile, DataProfileMemberAnnotation, DataProfileObservation, DataProfilePartition, DataProfileProbeReport, DataProfileQualityAssessment, DataProfileQuarantine, DataProfileRecipeStep, DataProfileKind, DataProfileAxis, DataProfileInputSignature, DataProfileCoverage, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses, queryLatestRunsByAnalyses, queryRunProgressByRuns, queryRunsEndedSince, } from "./analyses-metrics.js";

package/dist/state/index.js

@@ -12,7 +12,7 @@ export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifact
 export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, reconcileOrphanedRuns, ORPHANED_RUN_GRACE_MS, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
 setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, countRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, queryNewestPlanRun, } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun, countStepsByRuns, } from "./step-executions.js";
-export { insertPlan, upsertPlan, loadPlan, loadPlanRecord } from "./plans.js";
+export { insertPlan, upsertPlan, loadPlan, loadPlanRecord, queryPlanPage } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses, queryLatestRunsByAnalyses, queryRunProgressByRuns, queryRunsEndedSince, } from "./analyses-metrics.js";
 // Not per-entity: one analysis's whole Postgres footprint, reached from its id

package/dist/state/plans.d.ts

@@ -94,3 +94,30 @@ export type PlanRecord = {
 export declare function loadPlanRecord(pool: PlanRowQuerier, planId: string, opts: {
     analysisId: string;
 }): ResultAsync<PlanRecord | null, DbError>;
+/** One plan of {@link queryPlanPage}. */
+export type PlanPageEntry = {
+    planId: string;
+    createdAt: string;
+    /** The `title` of the stored document when it is a string, as the document holds it, else `null`. */
+    title: string | null;
+    parentPlanId: string | null;
+    /** The newest plan of the same analysis that names this plan as its parent. */
+    supersededBy: string | null;
+    /** The newest run of the plan, in the order of {@link queryRunIdsByPlan}, or `null` for a plan with no run. */
+    newestRunId: string | null;
+};
+/** One page of the plans of an analysis, and the exact count of them. */
+export type PlanPage = {
+    entries: PlanPageEntry[];
+    total: number;
+};
+/**
+ * One page of the plans of an analysis, newest first, in two statements: the count of the plans and the page. The
+ * count is a separate statement because a page past the end has no row to carry it. The order is the one of
+ * `supersededBy`: the creation time, then the highest plan id. The page gives the title of the document, not the
+ * document, because a page holds up to 200 plans.
+ */
+export declare function queryPlanPage(pool: Querier, analysisId: string, opts: {
+    limit: number;
+    offset: number;
+}): ResultAsync<PlanPage, DbError>;

package/dist/state/plans.js

@@ -117,6 +117,13 @@ const PlanRecordRowSchema = z.object({
     created_at: z.string(),
     superseded_by: z.string().nullable(),
 });
+/**
+ * The `superseded_by` column of a plan read: the newest plan of the same analysis that names the plan as its parent.
+ * The text refers to the plan row of the outer query as `p`.
+ */
+const SUPERSEDED_BY_SQL = `(SELECT c.plan_id FROM cortex_plans c
+                       WHERE c.parent_plan_id = p.plan_id AND c.analysis_id = p.analysis_id
+                       ORDER BY c.created_at DESC, c.plan_id DESC LIMIT 1) AS superseded_by`;
 /**
  * Analysis-scoped read of one plan with its parent and the newest plan that
  * replaced it, in one statement. Returns `ok(null)` for an unknown planId OR a
@@ -129,9 +136,7 @@ export function loadPlanRecord(pool, planId, opts) {
     return tryQuery("plans.loadPlanRecord", async () => {
         const result = await pool.query({
             text: `SELECT p.plan, p.parent_plan_id, p.created_at,
-                     (SELECT c.plan_id FROM cortex_plans c
-                       WHERE c.parent_plan_id = p.plan_id AND c.analysis_id = p.analysis_id
-                       ORDER BY c.created_at DESC, c.plan_id DESC LIMIT 1) AS superseded_by
+                     ${SUPERSEDED_BY_SQL}
                 FROM cortex_plans p
                WHERE p.plan_id = $1 AND p.analysis_id = $2`,
             values: [planId, opts.analysisId],
@@ -143,3 +148,52 @@ export function loadPlanRecord(pool, planId, opts) {
         return { planId, plan: row.plan, parentPlanId: row.parent_plan_id, supersededBy: row.superseded_by, createdAt: row.created_at };
     });
 }
+const PlanPageRowSchema = z.object({
+    plan_id: z.string(),
+    created_at: z.string(),
+    title: z.string().nullable(),
+    parent_plan_id: z.string().nullable(),
+    superseded_by: z.string().nullable(),
+    newest_run_id: z.string().nullable(),
+});
+/**
+ * One page of the plans of an analysis, newest first, in two statements: the count of the plans and the page. The
+ * count is a separate statement because a page past the end has no row to carry it. The order is the one of
+ * `supersededBy`: the creation time, then the highest plan id. The page gives the title of the document, not the
+ * document, because a page holds up to 200 plans.
+ */
+export function queryPlanPage(pool, analysisId, opts) {
+    return tryQuery("plans.queryPlanPage", async () => {
+        const countResult = await pool.query({
+            text: "SELECT COUNT(*)::int AS total FROM cortex_plans WHERE analysis_id = $1",
+            values: [analysisId],
+        });
+        const rowsResult = await pool.query({
+            text: `SELECT p.plan_id, p.created_at, p.parent_plan_id,
+                     CASE WHEN jsonb_typeof(p.plan->'title') = 'string' THEN p.plan->>'title' END AS title,
+                     ${SUPERSEDED_BY_SQL},
+                     (SELECT r.run_id FROM cortex_runs r
+                       WHERE r.analysis_id = p.analysis_id AND r.plan_id = p.plan_id
+                       ORDER BY r.started_at DESC, r.run_id DESC LIMIT 1) AS newest_run_id
+                FROM cortex_plans p
+               WHERE p.analysis_id = $1
+               ORDER BY p.created_at DESC, p.plan_id DESC
+               LIMIT $2 OFFSET $3`,
+            values: [analysisId, opts.limit, opts.offset],
+        });
+        return {
+            entries: rowsResult.rows.map((raw) => {
+                const row = PlanPageRowSchema.parse(raw);
+                return {
+                    planId: row.plan_id,
+                    createdAt: row.created_at,
+                    title: row.title,
+                    parentPlanId: row.parent_plan_id,
+                    supersededBy: row.superseded_by,
+                    newestRunId: row.newest_run_id,
+                };
+            }),
+            total: countResult.rows[0]?.total ?? 0,
+        };
+    });
+}