@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/tools/research/guarded-address.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The guarded-address classifier of the web research tools.
+ *
+ * One pure function over one address: `isGuardedAddress` answers whether the
+ * address falls in a range that `web_fetch` asks the user about before it
+ * connects. The ranges are a pinned subset of the special-purpose address
+ * ranges of the IANA registries — loopback, private, shared, link-local,
+ * multicast, reserved, documentation, and benchmarking space, IPv4 and IPv6.
+ * A public unicast address is never guarded.
+ *
+ * The caller owns the question "which address does the connection use": the
+ * classifier never resolves a name and it never reads the network.
+ */
+/**
+ * Is this address one the web tools guard? An IP literal of either family
+ * classifies against the pinned table; the IPv4-mapped IPv6 form
+ * (`::ffff:10.0.0.1`) classifies as its IPv4 half. A value that is not an IP
+ * address gives false — the caller resolves names before it reaches here.
+ */
+export declare function isGuardedAddress(ip: string): boolean;

package/dist/tools/research/guarded-address.js

@@ -0,0 +1,149 @@
+/**
+ * The guarded-address classifier of the web research tools.
+ *
+ * One pure function over one address: `isGuardedAddress` answers whether the
+ * address falls in a range that `web_fetch` asks the user about before it
+ * connects. The ranges are a pinned subset of the special-purpose address
+ * ranges of the IANA registries — loopback, private, shared, link-local,
+ * multicast, reserved, documentation, and benchmarking space, IPv4 and IPv6.
+ * A public unicast address is never guarded.
+ *
+ * The caller owns the question "which address does the connection use": the
+ * classifier never resolves a name and it never reads the network.
+ */
+import { isIP } from "node:net";
+import { isAllDigits, isAllHex } from "../../lib/text.js";
+/** Parse a dotted-quad IPv4 address into its 32-bit value. Anything else gives null. */
+function ipv4ToNumber(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4)
+        return null;
+    let value = 0;
+    for (const part of parts) {
+        if (part.length === 0 || part.length > 3 || !isAllDigits(part))
+            return null;
+        const octet = Number(part);
+        if (octet > 255)
+            return null;
+        value = (value << 8) | octet;
+    }
+    return value >>> 0;
+}
+/** Parse an IPv6 address into its 128-bit value. Anything else gives null. */
+function ipv6ToBigInt(ip) {
+    let text = ip.toLowerCase();
+    // An embedded IPv4 tail stands for its two low-order groups.
+    if (text.includes(".")) {
+        const lastColon = text.lastIndexOf(":");
+        const tail = ipv4ToNumber(text.slice(lastColon + 1));
+        if (tail === null)
+            return null;
+        const high = ((tail >>> 16) & 0xffff).toString(16);
+        const low = (tail & 0xffff).toString(16);
+        text = `${text.slice(0, lastColon + 1)}${high}:${low}`;
+    }
+    const groupsOf = (half) => {
+        if (half === "")
+            return [];
+        const groups = [];
+        for (const group of half.split(":")) {
+            if (group.length === 0 || group.length > 4 || !isAllHex(group))
+                return null;
+            groups.push(BigInt(`0x${group}`));
+        }
+        return groups;
+    };
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const left = groupsOf(halves[0] ?? "");
+    const right = halves.length === 2 ? groupsOf(halves[1] ?? "") : [];
+    if (left === null || right === null)
+        return null;
+    const fill = 8 - left.length - right.length;
+    if (halves.length === 2 ? fill < 0 : fill !== 0)
+        return null;
+    return [...left, ...new Array(Math.max(fill, 0)).fill(0n), ...right].reduce((acc, group) => (acc << 16n) | group, 0n);
+}
+const ipv4Span = (first, last) => {
+    const low = ipv4ToNumber(first);
+    const high = ipv4ToNumber(last);
+    if (low === null || high === null)
+        throw new Error(`Bad IPv4 range literal: ${first}..${last}`);
+    return { first: low, last: high };
+};
+const ipv6Span = (first, last) => {
+    const low = ipv6ToBigInt(first);
+    const high = ipv6ToBigInt(last);
+    if (low === null || high === null)
+        throw new Error(`Bad IPv6 range literal: ${first}..${last}`);
+    return { first: low, last: high };
+};
+/**
+ * The pinned IPv4 table. `240.0.0.0/4` holds the reserved and the broadcast
+ * space together, and it ends at the top of the address family.
+ */
+const GUARDED_IPV4_RANGES = [
+    ipv4Span("0.0.0.0", "0.255.255.255"), // 0.0.0.0/8
+    ipv4Span("10.0.0.0", "10.255.255.255"), // 10.0.0.0/8
+    ipv4Span("100.64.0.0", "100.127.255.255"), // 100.64.0.0/10
+    ipv4Span("127.0.0.0", "127.255.255.255"), // 127.0.0.0/8
+    ipv4Span("169.254.0.0", "169.254.255.255"), // 169.254.0.0/16
+    ipv4Span("172.16.0.0", "172.31.255.255"), // 172.16.0.0/12
+    ipv4Span("192.0.0.0", "192.0.0.255"), // 192.0.0.0/24
+    ipv4Span("192.0.2.0", "192.0.2.255"), // 192.0.2.0/24
+    ipv4Span("192.88.99.0", "192.88.99.255"), // 192.88.99.0/24
+    ipv4Span("192.168.0.0", "192.168.255.255"), // 192.168.0.0/16
+    ipv4Span("198.18.0.0", "198.19.255.255"), // 198.18.0.0/15
+    ipv4Span("198.51.100.0", "198.51.100.255"), // 198.51.100.0/24
+    ipv4Span("203.0.113.0", "203.0.113.255"), // 203.0.113.0/24
+    ipv4Span("224.0.0.0", "239.255.255.255"), // 224.0.0.0/4
+    ipv4Span("240.0.0.0", "255.255.255.255"), // 240.0.0.0/4
+];
+/**
+ * The pinned IPv6 table, without `::ffff:0:0/96`: an IPv4-mapped address
+ * normalizes to its IPv4 half first, thus that range classifies through the
+ * IPv4 table above.
+ */
+const GUARDED_IPV6_RANGES = [
+    ipv6Span("::", "::"), // ::/128
+    ipv6Span("::1", "::1"), // ::1/128
+    ipv6Span("64:ff9b::", "64:ff9b::ffff:ffff"), // 64:ff9b::/96
+    ipv6Span("64:ff9b:1::", "64:ff9b:1:ffff:ffff:ffff:ffff:ffff"), // 64:ff9b:1::/48
+    ipv6Span("100::", "100::ffff:ffff:ffff:ffff"), // 100::/64
+    ipv6Span("2001::", "2001:0:ffff:ffff:ffff:ffff:ffff:ffff"), // 2001::/32
+    ipv6Span("2001:db8::", "2001:db8:ffff:ffff:ffff:ffff:ffff:ffff"), // 2001:db8::/32
+    ipv6Span("2002::", "2002:ffff:ffff:ffff:ffff:ffff:ffff:ffff"), // 2002::/16
+    ipv6Span("fc00::", "fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"), // fc00::/7
+    ipv6Span("fe80::", "febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff"), // fe80::/10
+    ipv6Span("ff00::", "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"), // ff00::/8
+];
+function isGuardedIpv4(value) {
+    return GUARDED_IPV4_RANGES.some((range) => value >= range.first && value <= range.last);
+}
+function isGuardedIpv6(value) {
+    return GUARDED_IPV6_RANGES.some((range) => value >= range.first && value <= range.last);
+}
+/**
+ * Is this address one the web tools guard? An IP literal of either family
+ * classifies against the pinned table; the IPv4-mapped IPv6 form
+ * (`::ffff:10.0.0.1`) classifies as its IPv4 half. A value that is not an IP
+ * address gives false — the caller resolves names before it reaches here.
+ */
+export function isGuardedAddress(ip) {
+    const family = isIP(ip);
+    if (family === 4) {
+        const value = ipv4ToNumber(ip);
+        return value !== null && isGuardedIpv4(value);
+    }
+    if (family === 6) {
+        const value = ipv6ToBigInt(ip);
+        if (value === null)
+            return false;
+        // The IPv4-mapped form, ::ffff:0:0/96, classifies as its IPv4 half.
+        if (value >> 32n === 0xffffn)
+            return isGuardedIpv4(Number(value & 0xffffffffn));
+        return isGuardedIpv6(value);
+    }
+    return false;
+}

package/dist/tools/research/inspect-data-profile.d.ts

@@ -29,21 +29,23 @@
  * form names a file that does not exist in the frame of the caller. The same
  * projection guards the step briefing (`app/data-profile-orientation.ts`).
  */
-import type { Pool } from "pg";
+import type { Querier } from "../../state/db.js";
+import { z } from "zod";
 import { type DataProfileFile, type DataProfileResult } from "../../state/index.js";
+import { type Tool } from "../define-tool.js";
 /**
  * Whether the served profile can be trusted to describe the analysis's CURRENT inputs.
  * `"stale"` still carries the full profile — a stale profile is far better than none —
  * but says plainly why it may be wrong.
  */
 type Freshness = "ready" | "stale";
-interface ProfileEnvelope {
+type ProfileEnvelope = {
     readonly state: Freshness;
     /** Why the profile may not describe the current inputs. Present only when `state` is `"stale"`. */
     readonly staleReason?: string;
     readonly profiledAt: string;
-}
-interface OverviewOutput extends ProfileEnvelope {
+};
+type OverviewOutput = ProfileEnvelope & {
     readonly scope: "overview";
     readonly summary: string;
     readonly domain?: string;
@@ -76,7 +78,7 @@ interface OverviewOutput extends ProfileEnvelope {
      */
     readonly partition?: DataProfileResult["partition"];
     readonly coverage?: DataProfileResult["coverage"];
-}
+};
 /**
  * The dataset's structure. A snapshot carrying none reports `available: false` rather
  * than an empty list: "this profile predates the structure" and "this dataset has no
@@ -85,7 +87,7 @@ interface OverviewOutput extends ProfileEnvelope {
  * A snapshot written under the previous model is served through `kinds`/`axes`, labelled
  * — the structure exists, and an agent must not be told the dataset has none.
  */
-interface GroupsOutput extends ProfileEnvelope {
+type GroupsOutput = ProfileEnvelope & {
     readonly scope: "groups";
     readonly available: boolean;
     /** Authored under the previous model — `kinds`/`axes` rather than resolved groups. */
@@ -99,13 +101,13 @@ interface GroupsOutput extends ProfileEnvelope {
     readonly axes?: DataProfileResult["axes"];
     readonly coverage?: DataProfileResult["coverage"];
     readonly message?: string;
-}
+};
 /**
  * The members the profile describes individually — annotated members on a resolved
  * snapshot, the notable-file records on an older one. Never the dataset: `datasetFileCount`
  * on the overview is what says how big that is.
  */
-interface FilesOutput extends ProfileEnvelope {
+type FilesOutput = ProfileEnvelope & {
     readonly scope: "files";
     readonly page: number;
     readonly pageSize: number;
@@ -116,7 +118,7 @@ interface FilesOutput extends ProfileEnvelope {
     /** How many files the dataset holds, so a page of 20 never reads as the whole of it. */
     readonly datasetFileCount: number | null;
     readonly files: DataProfileFile[];
-}
+};
 /**
  * No profile to serve — the honest lifecycle states, in the ok channel.
  *
@@ -128,15 +130,15 @@ interface FilesOutput extends ProfileEnvelope {
  * constant here, and a constant field carries no information while implying
  * that it does. `FailedOutput` omits one for the same reason — see its note.
  */
-interface AbsentOutput {
+type AbsentOutput = {
     readonly state: "absent";
     readonly message: string;
-}
-interface PendingOutput {
+};
+type PendingOutput = {
     readonly state: "pending";
     readonly status: "pending" | "running";
     readonly message: string;
-}
+};
 /**
  * A recorded failure with no profile to fall back on.
  *
@@ -152,17 +154,22 @@ interface PendingOutput {
  * `failedAt` is reported instead: a fact the row actually holds, and one an agent
  * that knows when the input set last changed can act on.
  */
-interface FailedOutput {
+type FailedOutput = {
     readonly state: "failed";
     readonly error: string | null;
     /** When the failure was recorded; `null` when the row holds no time. */
     readonly failedAt: string | null;
     readonly message: string;
-}
+};
 export type InspectDataProfileOutput = OverviewOutput | GroupsOutput | FilesOutput | AbsentOutput | PendingOutput | FailedOutput;
-export declare function createInspectDataProfileTool(pool: Pool): import("../define-tool.js").Tool<{
-    scope?: "groups" | "files" | "overview" | undefined;
-    page?: number | undefined;
-    pageSize?: number | undefined;
-}, InspectDataProfileOutput>;
+declare const InspectDataProfileInputSchema: z.ZodObject<{
+    scope: z.ZodOptional<z.ZodEnum<{
+        files: "files";
+        groups: "groups";
+        overview: "overview";
+    }>>;
+    page: z.ZodOptional<z.ZodNumber>;
+    pageSize: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createInspectDataProfileTool(pool: Querier): Tool<z.infer<typeof InspectDataProfileInputSchema>, InspectDataProfileOutput>;
 export {};

package/dist/tools/research/inspect-data-profile.js

@@ -90,6 +90,22 @@ function stalenessReasons(status) {
 const FAILURE_SCOPE_NOTE = "This records an earlier attempt; this row cannot establish whether it covered the input files the analysis " +
     "holds now, so do not read it as a verdict on the current data. Compare failedAt against when the input set " +
     "last changed, and re-profile if they have moved apart.";
+const InspectDataProfileInputSchema = z.object({
+    scope: z
+        .enum(["overview", "groups", "files"])
+        .optional()
+        .describe("'overview' (default): dataset-level facts, the partition accounting, the annotated-member count, and the dataset file count. " +
+        "'groups': the groups the dataset is made of, with their slots, and the dimensions that vary across it. " +
+        "'files': paged records for the individually annotated members."),
+    page: z.number().int().min(1).optional().describe("1-based page of member records. Only used when scope is 'files'. Default 1."),
+    pageSize: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_PAGE_SIZE)
+        .optional()
+        .describe(`Member records per page. Only used when scope is 'files'. Default ${DEFAULT_PAGE_SIZE}, max ${MAX_PAGE_SIZE}.`),
+});
 export function createInspectDataProfileTool(pool) {
     return defineTool({
         id: "inspect_data_profile",
@@ -119,22 +135,7 @@ export function createInspectDataProfileTool(pool) {
             "input files you are holding now, and this tool cannot tell you whether that attempt covered them. Compare failedAt " +
             "against when the input set last changed before you conclude anything: if the data moved since, say the profile " +
             "needs re-running rather than diagnosing the data itself.",
-        inputSchema: z.object({
-            scope: z
-                .enum(["overview", "groups", "files"])
-                .optional()
-                .describe("'overview' (default): dataset-level facts, the partition accounting, the annotated-member count, and the dataset file count. " +
-                "'groups': the groups the dataset is made of, with their slots, and the dimensions that vary across it. " +
-                "'files': paged records for the individually annotated members."),
-            page: z.number().int().min(1).optional().describe("1-based page of member records. Only used when scope is 'files'. Default 1."),
-            pageSize: z
-                .number()
-                .int()
-                .min(1)
-                .max(MAX_PAGE_SIZE)
-                .optional()
-                .describe(`Member records per page. Only used when scope is 'files'. Default ${DEFAULT_PAGE_SIZE}, max ${MAX_PAGE_SIZE}.`),
-        }),
+        inputSchema: InspectDataProfileInputSchema,
         // `execute` defaults both fields internally, and the hook applies the same
         // defaults. Without them the ordinary call, which names no field at all,
         // gives no detail. `page` acts only on the `files` scope, as in `execute`.
@@ -214,9 +215,9 @@ export function createInspectDataProfileTool(pool) {
                     // nothing of carries `groups: []`, and "zero groups" is a finding — reading
                     // it as "no structure record" would report the analysis unprofiled.
                     groupCount: result.groups !== undefined || result.kinds !== undefined ? groups.length : null,
-                    ...(structureNote ? { structureNote } : {}),
-                    ...(result.partition ? { partition: result.partition } : {}),
-                    ...(result.coverage ? { coverage: result.coverage } : {}),
+                    structureNote,
+                    partition: result.partition,
+                    coverage: result.coverage,
                 });
             }
             if (scope === "groups") {
@@ -226,10 +227,10 @@ export function createInspectDataProfileTool(pool) {
                         scope: "groups",
                         available: true,
                         groups: rootGroupPatterns(result.groups, resourceId),
-                        ...(result.dimensions ? { dimensions: result.dimensions } : {}),
-                        ...(result.probes ? { probes: result.probes } : {}),
-                        ...(result.partition ? { partition: result.partition } : {}),
-                        ...(result.recipe ? { recipe: result.recipe } : {}),
+                        dimensions: result.dimensions,
+                        probes: result.probes,
+                        partition: result.partition,
+                        recipe: result.recipe,
                     });
                 }
                 if (result.kinds === undefined) {
@@ -251,8 +252,8 @@ export function createInspectDataProfileTool(pool) {
                     available: true,
                     legacy: true,
                     kinds: rootKindPatterns(result.kinds, resourceId),
-                    ...(result.axes ? { axes: result.axes } : {}),
-                    ...(result.coverage ? { coverage: result.coverage } : {}),
+                    axes: result.axes,
+                    coverage: result.coverage,
                     message: "Authored under the previous model: these are kinds and axes, not resolved groups and dimensions. " +
                         "Counts and patterns were the profiler's own claims rather than a computed partition, and there is no " +
                         "unclassified sweep or quarantine accounting on a profile of that era.",

package/dist/tools/research/inspect-run.d.ts

@@ -5,10 +5,24 @@
  * conversation. List mode puts the running runs first and is paged. Targeted mode makes
  * readiness explicit and can perform one bounded, abort-aware wait.
  */
-import type { Pool } from "pg";
+import type { QueryConfig } from "pg";
+import { z } from "zod";
+import type { PauseCause } from "../../contracts/chat-parts.js";
 import type { CortexRunRow } from "../../state/schema.js";
-type FormattedRun = ReturnType<typeof formatRun>;
-interface FormattedStep {
+import { type Tool } from "../define-tool.js";
+type FormattedRun = {
+    runId: string;
+    workflowName: string;
+    status: CortexRunRow["status"];
+    startedAt: string;
+    completedAt: string | null;
+    planId: string | null;
+    synthesisPath: string | null;
+    synthesisStatus: CortexRunRow["synthesisStatus"];
+    error: string | null | undefined;
+    synthesisReason?: string;
+};
+type FormattedStep = {
     stepId: string;
     agentId: string;
     wave: number;
@@ -20,11 +34,11 @@ interface FormattedStep {
     lastErrorClass?: string | null;
     finishReason?: string | null;
     hitMaxSteps?: boolean | null;
-}
-interface WaitMetadata {
+};
+type WaitMetadata = {
     readonly requestedSeconds: number;
     readonly cutoffReached: boolean;
-}
+};
 type InspectRunOutput = {
     runs: FormattedRun[];
     total: number;
@@ -36,7 +50,20 @@ type InspectRunOutput = {
     message: string;
     wait?: WaitMetadata;
 } | {
-    inspectionState: "in_progress" | "suspended" | "terminal";
+    inspectionState: "paused";
+    message: string;
+    run: FormattedRun;
+    steps: FormattedStep[];
+    /** Each workflow of the run that waits: a step, or the synthesis. */
+    pauses: {
+        state: "retrying" | "paused";
+        cause: PauseCause;
+        attempt: number;
+        retryAt?: string;
+    }[];
+    wait?: WaitMetadata;
+} | {
+    inspectionState: "in_progress" | "terminal";
     message: string;
     run: FormattedRun;
     steps: FormattedStep[];
@@ -44,31 +71,31 @@ type InspectRunOutput = {
     wait?: WaitMetadata;
     selfWaitPrevented?: boolean;
 };
-interface InspectRunClock {
+type InspectRunClock = {
     now(): number;
     wait(ms: number, signal: AbortSignal): Promise<void>;
-}
-declare function formatRun(r: CortexRunRow, verbose: boolean, exposePaths?: boolean): {
-    error?: string | null | undefined;
-    synthesisReason?: string | undefined;
-    runId: string;
-    workflowName: string;
-    status: "failed" | "running" | "completed" | "partial" | "canceled" | "suspended_insufficient_funds";
-    startedAt: string;
-    completedAt: string | null;
-    planId: string | null;
-    synthesisPath: string | null;
-    synthesisStatus: "failed" | "produced" | "skipped_no_summaries" | "skipped_blocker" | null;
+};
+declare const inputSchema: z.ZodObject<{
+    runId: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    pageSize: z.ZodOptional<z.ZodNumber>;
+    waitForTerminalSeconds: z.ZodOptional<z.ZodNumber>;
+    includeDiagnostics: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * The pool surface this tool reads: one query whose rows the state row parsers type. A computed test fake
+ * satisfies this shape directly, where the row-generic of `Querier` cannot be implemented by a fake that
+ * computes its rows.
+ */
+export type InspectRunQuerier = {
+    query(queryTextOrConfig: string | QueryConfig, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+        rowCount: number | null;
+    }>;
 };
 /**
  * Build the run-inspection tool. The optional clock is an internal testing
  * seam for deterministic cutoff and transition coverage.
  */
-export declare function createInspectRunTool(pool: Pool, clock?: InspectRunClock): import("../define-tool.js").Tool<{
-    runId?: string | undefined;
-    page?: number | undefined;
-    pageSize?: number | undefined;
-    waitForTerminalSeconds?: number | undefined;
-    includeDiagnostics?: boolean | undefined;
-}, InspectRunOutput>;
+export declare function createInspectRunTool(pool: InspectRunQuerier, clock?: InspectRunClock): Tool<z.infer<typeof inputSchema>, InspectRunOutput>;
 export {};

package/dist/tools/research/inspect-run.js

@@ -11,6 +11,7 @@ import { z } from "zod";
 import { scopeResource } from "../../auth/types.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 import { queryRun, queryRunsForInspection, queryStepsByRun } from "../../state/index.js";
+import { queryPausesOfWork } from "../../state/paused-work.js";
 import { SYNTHESIS_STEP_ID } from "../../workspace/paths.js";
 import { defineTool } from "../define-tool.js";
 const DEFAULT_PAGE_SIZE = 50;
@@ -20,10 +21,10 @@ const systemClock = {
     wait: (ms, signal) => sleep(ms, undefined, { signal }),
 };
 function isTerminal(status) {
-    return status === "completed" || status === "partial" || status === "failed" || status === "canceled" || status === "suspended_insufficient_funds";
+    return status === "completed" || status === "partial" || status === "failed" || status === "canceled";
 }
 function formatRun(r, verbose, exposePaths = isTerminal(r.status)) {
-    return {
+    const run = {
         runId: r.runId,
         workflowName: r.workflowName,
         status: r.status,
@@ -32,30 +33,33 @@ function formatRun(r, verbose, exposePaths = isTerminal(r.status)) {
         planId: r.planId,
         synthesisPath: exposePaths && r.synthesisStatus === "produced" ? `runs/${r.runId}/synthesis.json` : null,
         synthesisStatus: r.synthesisStatus,
-        ...(r.synthesisReason !== null ? { synthesisReason: r.synthesisReason } : {}),
-        ...(verbose ? { error: r.error } : {}),
+        error: verbose ? (r.error ?? null) : undefined,
     };
+    if (r.synthesisReason !== null)
+        return { ...run, synthesisReason: r.synthesisReason };
+    return run;
 }
 function formatSteps(runId, stepRows, verbose, exposePaths) {
-    return stepRows.map((s) => ({
-        stepId: s.stepId,
-        agentId: s.agentId,
-        wave: s.wave,
-        status: s.status,
-        ...(exposePaths && s.status !== "pending" && s.status !== "skipped" && s.stepId !== SYNTHESIS_STEP_ID
-            ? { summaryPath: `runs/${runId}/${s.stepId}/output/summary.md` }
-            : {}),
-        ...(verbose
-            ? {
-                durationMs: s.durationMs,
-                error: s.error,
-                attempts: s.attempts,
-                lastErrorClass: s.lastErrorClass,
-                finishReason: s.finishReason,
-                hitMaxSteps: s.hitMaxSteps,
-            }
-            : {}),
-    }));
+    return stepRows.map((s) => {
+        const step = {
+            stepId: s.stepId,
+            agentId: s.agentId,
+            wave: s.wave,
+            status: s.status,
+        };
+        if (exposePaths && s.status !== "pending" && s.status !== "skipped" && s.stepId !== SYNTHESIS_STEP_ID) {
+            step.summaryPath = `runs/${runId}/${s.stepId}/output/summary.md`;
+        }
+        if (verbose) {
+            step.durationMs = s.durationMs;
+            step.error = s.error;
+            step.attempts = s.attempts;
+            step.lastErrorClass = s.lastErrorClass;
+            step.finishReason = s.finishReason;
+            step.hitMaxSteps = s.hitMaxSteps;
+        }
+        return step;
+    });
 }
 const inputSchema = z
     .object({
@@ -77,14 +81,14 @@ const inputSchema = z
     .superRefine((input, refinement) => {
     if (input.runId && (input.page !== undefined || input.pageSize !== undefined)) {
         refinement.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: "custom",
             message: "page and pageSize are valid only when runId is omitted",
             path: input.page !== undefined ? ["page"] : ["pageSize"],
         });
     }
     if (!input.runId && input.waitForTerminalSeconds !== undefined) {
         refinement.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: "custom",
             message: "waitForTerminalSeconds requires runId",
             path: ["waitForTerminalSeconds"],
         });
@@ -99,9 +103,9 @@ export function createInspectRunTool(pool, clock = systemClock) {
         id: "inspect_run",
         description: "Inspect workflow runs for this analysis. A run never posts its completion into the conversation; this tool is how you read it. " +
             "Without a runId, returns a paged list (running runs first, then each other run) with total and hasMore. " +
-            "With a runId, returns the run, its steps, and an inspectionState: not_found; in_progress; suspended (the host suspended the run, it does not progress, and a new run of the plan can start); " +
+            "With a runId, returns the run, its steps, and an inspectionState: not_found; in_progress; paused (a step waits until the user resumes or stops the run, and pauses gives each cause); " +
             "or terminal (run.status completed, partial, failed, or canceled). " +
-            "Output paths appear only on a suspended or terminal run: run.synthesisPath when synthesisStatus is produced, and the summaryPath of each step that ran. " +
+            "Output paths appear only on a terminal run: run.synthesisPath when synthesisStatus is produced, and the summaryPath of each step that ran. " +
             "For a user-directed check, waitForTerminalSeconds can wait once for 1-30 seconds; if the cutoff returns in_progress, stop polling for that turn. " +
             "A wait on the run that the caller itself runs inside returns at once with selfWaitPrevented. " +
             "Default response is lightweight — pass includeDiagnostics:true to add error/duration/retry telemetry.",
@@ -132,14 +136,17 @@ export function createInspectRunTool(pool, clock = systemClock) {
                 return ok({
                     inspectionState: "not_found",
                     message: `Run ${input.runId} was not found in this analysis.`,
-                    ...(waitSeconds === undefined ? {} : { wait: { requestedSeconds: waitSeconds, cutoffReached: false } }),
+                    wait: waitSeconds === undefined ? undefined : { requestedSeconds: waitSeconds, cutoffReached: false },
                 });
             }
             const selfWait = waitSeconds !== undefined && ctx.session.runFrame?.runId === input.runId;
+            const runId = input.runId;
+            const pausesOf = async (status) => status === "running" ? unwrapOrThrow(await queryPausesOfWork(pool, resourceId, runId)) : [];
+            let pauses = await pausesOf(run.status);
             let cutoffReached = false;
-            if (waitSeconds !== undefined && run.status === "running" && !selfWait) {
+            if (waitSeconds !== undefined && run.status === "running" && pauses.length === 0 && !selfWait) {
                 const deadline = clock.now() + waitSeconds * 1_000;
-                while (run.status === "running") {
+                while (run.status === "running" && pauses.length === 0) {
                     const remaining = deadline - clock.now();
                     if (remaining <= 0) {
                         cutoffReached = true;
@@ -154,12 +161,24 @@ export function createInspectRunTool(pool, clock = systemClock) {
                             wait: { requestedSeconds: waitSeconds, cutoffReached: false },
                         });
                     }
+                    pauses = await pausesOf(run.status);
                 }
             }
             const terminal = isTerminal(run.status);
             const stepRows = unwrapOrThrow(await queryStepsByRun(pool, input.runId));
             const steps = formatSteps(input.runId, stepRows, verbose, terminal);
             const wait = waitSeconds === undefined ? {} : { wait: { requestedSeconds: waitSeconds, cutoffReached } };
+            if (run.status === "running" && pauses.length > 0) {
+                return ok({
+                    inspectionState: "paused",
+                    message: "This run waits in a pause, and results are not ready. Tell the user the cause of each pause. " +
+                        "The user can resume the run or stop it. A pause in the state retrying also sends its request again at retryAt.",
+                    run: formatRun(run, verbose, false),
+                    steps,
+                    pauses: pauses.map((pause) => ({ state: pause.state, cause: pause.cause, attempt: pause.attempt, retryAt: pause.retryAt })),
+                    ...wait,
+                });
+            }
             if (run.status === "running") {
                 const message = selfWait
                     ? "This run is still in progress. Results are not ready, and the enclosing workflow cannot finish while its current step waits for itself."
@@ -173,16 +192,7 @@ export function createInspectRunTool(pool, clock = systemClock) {
                     steps,
                     elapsedMs: Math.max(0, clock.now() - Date.parse(run.startedAt)),
                     ...wait,
-                    ...(selfWait ? { selfWaitPrevented: true } : {}),
-                });
-            }
-            if (run.status === "suspended_insufficient_funds") {
-                return ok({
-                    inspectionState: "suspended",
-                    message: "The host suspended this run. The run does not progress. A new run of the plan can start.",
-                    run: formatRun(run, verbose, true),
-                    steps,
-                    ...wait,
+                    selfWaitPrevented: selfWait ? true : undefined,
                 });
             }
             return ok({