@sapiom/harness 0.1.4 → 0.1.6

package/dist/core/render-run-state.js

@@ -0,0 +1,120 @@
+/**
+ * renderRunState — the ONE pure mapper from a decoded {@link ExecutionProjection}
+ * to the canvas's {@link RunView} render state.
+ *
+ * Pure and deterministic: no LLM, no I/O, no clock. Every field is derived from
+ * the decoded projection, so the same function drives the polling path today and
+ * a future WebSocket push (only the data source swaps, never this mapping).
+ * Latency is read straight from the projection and rendered statically — the
+ * LLM is only ever invoked later by an explicit debug-macro press, never to
+ * compute what's shown here.
+ *
+ * Honest absence is preserved end to end: a still-running step gets no
+ * `latencyMs`, and a step with no logs gets no `logSlice`. The inspector
+ * surfaces logs, latency, and pass/fail only — no cost.
+ */
+import { isExecutionTerminal } from "@sapiom/agent-core";
+// The log-buffer formatter lives in its own dependency-free module so the
+// local-run mapper (imported by the browser SPA) can share the SAME formatter
+// WITHOUT dragging this file's `@sapiom/agent-core` runtime import — and its
+// `node:fs` reach — into the web bundle.
+import { toLogSlice } from "./render-log-slice.js";
+/**
+ * Fold the run's lifecycle status into the four states the UI distinguishes.
+ * Reuses `isExecutionTerminal` (agent-core's single source of truth for "won't
+ * advance on its own") so a newly-added terminal status can never be misdrawn as
+ * still-running: anything non-terminal (running, paused, queued, unknown) is
+ * `running`; the terminal set normalizes `canceled` → `cancelled`.
+ */
+function toRunStatus(raw) {
+    if (!isExecutionTerminal(raw))
+        return "running";
+    if (raw === "completed")
+        return "completed";
+    if (raw === "failed")
+        return "failed";
+    return "cancelled"; // the only remaining terminal statuses: "cancelled" / "canceled"
+}
+/**
+ * Fold a step's raw status into a {@link StepStatus}. Handles the real engine
+ * vocabulary (`succeeded`/`threw` from prod agents surface) plus the earlier
+ * values (`completed`/`failed`/`cancelled`/`canceled`). A cancelled or threw
+ * step folds to `failed` (it did not pass — mirrors run-local.ts); anything
+ * not yet running/passed/failed is `pending` (unstarted, queued, or unknown).
+ */
+function toStepStatus(raw) {
+    if (raw === "completed" || raw === "succeeded")
+        return "passed";
+    if (raw === "failed" ||
+        raw === "threw" ||
+        raw === "cancelled" ||
+        raw === "canceled")
+        return "failed";
+    if (raw === "running")
+        return "running";
+    return "pending";
+}
+/** `finishedAt − startedAt` in ms; `undefined` while still running (no finish)
+ *  or when either timestamp is unparseable. A negative delta (clock skew) is
+ *  dropped rather than shown as a misleading negative latency. */
+function toLatencyMs(startedAt, finishedAt) {
+    if (!startedAt || !finishedAt)
+        return undefined;
+    const start = Date.parse(startedAt);
+    const end = Date.parse(finishedAt);
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return undefined;
+    const delta = end - start;
+    return delta >= 0 ? delta : undefined;
+}
+/** Map one projection step to its render view. Optional fields are assigned only
+ *  when present so absence stays absent (not `undefined`) in the JSON payload. */
+function toStepView(step) {
+    const view = {
+        id: step.spanId ?? `step-${step.stepOrder}-${step.attempt}`,
+        name: step.stepName,
+        status: toStepStatus(step.status),
+    };
+    const latencyMs = toLatencyMs(step.startedAt, step.finishedAt);
+    if (latencyMs !== undefined)
+        view.latencyMs = latencyMs;
+    if (step.error?.message)
+        view.error = step.error.message;
+    const logSlice = toLogSlice(step.logs);
+    if (logSlice !== undefined)
+        view.logSlice = logSlice;
+    // Real per-step IO for the inspector's "Last run" block. The decoder
+    // collapses an absent input/output to `null` (its absence sentinel), so a
+    // `null` here means "the read carried nothing" — surfaced as ABSENT, never a
+    // fabricated payload. Any non-null value (including `0`, `false`, `""`) is a
+    // real payload and passes through. Capability, not model: these are the
+    // step's own values, with no provider/model surfaced.
+    if (step.input !== null)
+        view.input = step.input;
+    if (step.output !== null)
+        view.output = step.output;
+    // `step.events` are capability execution events forwarded by dispatched
+    // capabilities (e.g. tool_use / thinking / result events from a coding run).
+    // They do NOT represent dotted workflow capability calls (search.webSearch,
+    // memory.append, etc.) with args/results in the StepCall format, so we
+    // cannot map them to StepView.calls without fabricating structure that isn't
+    // there. `calls` is left absent for prod steps. The inspector's
+    // input/output/logs already carry the step-level evidence for prod runs;
+    // per-call detail is a fast-follow that requires a server-side addition to
+    // the projection shape (emitting dotted-capability call records alongside
+    // their args/results at the step level).
+    return view;
+}
+/**
+ * Map a decoded {@link ExecutionProjection} to the {@link RunView} the canvas
+ * renders. Order-preserving over `steps`; total (never throws) because the
+ * projection is already the decoded, degradation-tolerant shape.
+ */
+export function renderRunState(decoded) {
+    return {
+        executionId: decoded.id,
+        status: toRunStatus(decoded.status),
+        steps: decoded.steps.map(toStepView),
+    };
+}
+//# sourceMappingURL=render-run-state.js.map

package/dist/core/render-run-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-run-state.js","sourceRoot":"","sources":["../../src/core/render-run-state.ts"],"names":[],"mappings":"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"}

package/dist/core/run-local-bootstrap.d.ts

@@ -0,0 +1,93 @@
+/**
+ * run-local bootstrap — the child-process entrypoint behind
+ * `POST /api/runs/local`.
+ *
+ * It runs an agent entirely in-process against stub capabilities
+ * (`runLocalFromDir` from @sapiom/agent-core) and writes the result as an
+ * NDJSON stream to stdout: one line per {@link LocalStepTrace}, then a single
+ * terminal summary line `{ outcome, output, error, unusedStubs, stubWarnings }`.
+ * Fully offline and zero-cost — run-local resolves every `ctx.sapiom.*` call
+ * from stubs and never touches the network.
+ *
+ * Why a separate child process (not an in-process import):
+ *  1. `runLocalFromDir` esbuild-bundles and dynamically `import()`s a workflow
+ *     project the harness doesn't control, so a stray top-level side effect,
+ *     infinite loop, or crash in someone else's step body is bounded to this
+ *     one child instead of taking the long-lived harness server down.
+ *  2. It sidesteps a Vite/Vitest limitation: the dynamic `import(\`file://…\`)`
+ *     inside the loader gets intercepted by the SSR dynamic-import-vars
+ *     transform when pulled into a Vitest module graph, and mishandles the
+ *     tmpdir `file://` URL on darwin. A plain child `node` process never goes
+ *     through that transform. (Mirrors the reasoning in canvas-manifest-check.)
+ *
+ * Contract with the route ({@link createActionsRouter}):
+ *  - Request arrives as one JSON object on **stdin**: `{ sourceDir, input?,
+ *    stubs?, maxAttemptsPerStep? }`.
+ *  - Output is line-oriented JSON on **stdout** — the route forwards each line
+ *    through unchanged, so the shapes here ARE the wire shapes the SPA parses.
+ *  - Diagnostics go to **stderr**; the route keeps a bounded tail for failures.
+ *  - Exit 0 once the terminal line is written (even for a failed run — a failed
+ *    *run* is a successful *invocation*); exit 1 only when no run happened
+ *    (bad request, load error) after writing a terminal `error` line.
+ */
+import { type LocalRunOutcome, type StubFile } from "@sapiom/agent-core";
+/** The request shape the route writes to this child's stdin. */
+export interface RunLocalRequest {
+    /** Absolute path to the agent project directory (contains `index.ts`). */
+    sourceDir: string;
+    /** The workflow's entry-step input (optional; agent-core defaults it). */
+    input?: unknown;
+    /** Explicit stub overrides. When omitted the project's committed
+     *  `.sapiom-dev/stubs.json` is used (agent-core's own precedence). */
+    stubs?: StubFile;
+    /** Per-step attempt cap (optional; agent-core defaults it). */
+    maxAttemptsPerStep?: number;
+}
+/**
+ * The terminal NDJSON line, written after every per-step trace line. Carries
+ * the run-level outcome and the two stub-hygiene signals the inspector surfaces
+ * (WB15-2): `unusedStubs` (supplied keys that matched no capability call) and
+ * `stubWarnings` (keys that matched but carried the wrong shape).
+ *
+ * `kind: "summary"` discriminates it from a step-trace line so a consumer never
+ * has to guess which line is terminal.
+ */
+export interface RunLocalSummaryLine {
+    kind: "summary";
+    outcome: LocalRunOutcome;
+    output?: unknown;
+    error?: unknown;
+    unusedStubs: Array<{
+        step: string;
+        key: string;
+    }>;
+    stubWarnings: string[];
+}
+/**
+ * The terminal line written when the run could not be *invoked* at all — a
+ * malformed request, an unreadable stub file, a project that fails to load.
+ * `outcome` is always `"failed"`; the child then exits non-zero. Distinct from
+ * a `summary` line, which represents a run that actually executed (even if that
+ * run's own outcome was `failed`).
+ */
+export interface RunLocalErrorLine {
+    kind: "error";
+    outcome: "failed";
+    error: string;
+}
+/**
+ * Parse the stdin payload into a {@link RunLocalRequest}. Throws a plain Error
+ * with a caller-safe message (no key material, no provider names) on anything
+ * that isn't a JSON object carrying a non-empty string `sourceDir`.
+ */
+export declare function parseRunLocalRequest(raw: string): RunLocalRequest;
+/**
+ * Run the request and emit its NDJSON stream to `out`. Returns the process exit
+ * code: 0 when a run executed (any outcome), 1 when the run could not be
+ * invoked (a terminal `error` line is emitted first). Never throws — every
+ * failure becomes an in-band terminal line, because a half-written stream with
+ * a thrown stack on stderr is far harder for the route to reason about than a
+ * clean terminal line plus an exit code.
+ */
+export declare function runBootstrap(request: RunLocalRequest, out: NodeJS.WritableStream): Promise<number>;
+//# sourceMappingURL=run-local-bootstrap.d.ts.map

package/dist/core/run-local-bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-local-bootstrap.d.ts","sourceRoot":"","sources":["../../src/core/run-local-bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,QAAQ,EACd,MAAM,oBAAoB,CAAC;AAE5B,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;0EACsE;IACtE,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAWD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAwBjE;AAYD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,MAAM,CAAC,cAAc,GACzB,OAAO,CAAC,MAAM,CAAC,CAkCjB"}

package/dist/core/run-local-bootstrap.js

@@ -0,0 +1,155 @@
+/**
+ * run-local bootstrap — the child-process entrypoint behind
+ * `POST /api/runs/local`.
+ *
+ * It runs an agent entirely in-process against stub capabilities
+ * (`runLocalFromDir` from @sapiom/agent-core) and writes the result as an
+ * NDJSON stream to stdout: one line per {@link LocalStepTrace}, then a single
+ * terminal summary line `{ outcome, output, error, unusedStubs, stubWarnings }`.
+ * Fully offline and zero-cost — run-local resolves every `ctx.sapiom.*` call
+ * from stubs and never touches the network.
+ *
+ * Why a separate child process (not an in-process import):
+ *  1. `runLocalFromDir` esbuild-bundles and dynamically `import()`s a workflow
+ *     project the harness doesn't control, so a stray top-level side effect,
+ *     infinite loop, or crash in someone else's step body is bounded to this
+ *     one child instead of taking the long-lived harness server down.
+ *  2. It sidesteps a Vite/Vitest limitation: the dynamic `import(\`file://…\`)`
+ *     inside the loader gets intercepted by the SSR dynamic-import-vars
+ *     transform when pulled into a Vitest module graph, and mishandles the
+ *     tmpdir `file://` URL on darwin. A plain child `node` process never goes
+ *     through that transform. (Mirrors the reasoning in canvas-manifest-check.)
+ *
+ * Contract with the route ({@link createActionsRouter}):
+ *  - Request arrives as one JSON object on **stdin**: `{ sourceDir, input?,
+ *    stubs?, maxAttemptsPerStep? }`.
+ *  - Output is line-oriented JSON on **stdout** — the route forwards each line
+ *    through unchanged, so the shapes here ARE the wire shapes the SPA parses.
+ *  - Diagnostics go to **stderr**; the route keeps a bounded tail for failures.
+ *  - Exit 0 once the terminal line is written (even for a failed run — a failed
+ *    *run* is a successful *invocation*); exit 1 only when no run happened
+ *    (bad request, load error) after writing a terminal `error` line.
+ */
+import { runLocalFromDir, } from "@sapiom/agent-core";
+/** Read the entire request payload from a readable stream as one UTF-8 string. */
+async function readAll(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * Parse the stdin payload into a {@link RunLocalRequest}. Throws a plain Error
+ * with a caller-safe message (no key material, no provider names) on anything
+ * that isn't a JSON object carrying a non-empty string `sourceDir`.
+ */
+export function parseRunLocalRequest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("run-local request is not valid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new Error("run-local request must be a JSON object");
+    }
+    const body = parsed;
+    const sourceDir = body.sourceDir;
+    if (typeof sourceDir !== "string" || sourceDir.trim() === "") {
+        throw new Error("run-local request requires a non-empty sourceDir");
+    }
+    return {
+        sourceDir,
+        input: body.input,
+        stubs: body.stubs,
+        maxAttemptsPerStep: typeof body.maxAttemptsPerStep === "number"
+            ? body.maxAttemptsPerStep
+            : undefined,
+    };
+}
+/** Serialize one step trace as a single NDJSON line (newline-terminated). */
+function traceLine(step) {
+    return JSON.stringify(step) + "\n";
+}
+/** Serialize the terminal summary as a single NDJSON line. */
+function summaryLine(line) {
+    return JSON.stringify(line) + "\n";
+}
+/**
+ * Run the request and emit its NDJSON stream to `out`. Returns the process exit
+ * code: 0 when a run executed (any outcome), 1 when the run could not be
+ * invoked (a terminal `error` line is emitted first). Never throws — every
+ * failure becomes an in-band terminal line, because a half-written stream with
+ * a thrown stack on stderr is far harder for the route to reason about than a
+ * clean terminal line plus an exit code.
+ */
+export async function runBootstrap(request, out) {
+    try {
+        const result = await runLocalFromDir({
+            sourceDir: request.sourceDir,
+            input: request.input,
+            stubs: request.stubs,
+            maxAttemptsPerStep: request.maxAttemptsPerStep,
+        });
+        // One line per step-attempt, in execution order — the consumer parses them
+        // incrementally rather than buffering the whole trace as a single blob.
+        for (const step of result.steps) {
+            out.write(traceLine(step));
+        }
+        const summary = {
+            kind: "summary",
+            outcome: result.outcome,
+            output: result.output,
+            error: result.error,
+            unusedStubs: result.unusedStubs,
+            stubWarnings: result.stubWarnings,
+        };
+        out.write(summaryLine(summary));
+        return 0;
+    }
+    catch (err) {
+        const errorLine = {
+            kind: "error",
+            outcome: "failed",
+            error: err instanceof Error ? err.message : String(err),
+        };
+        out.write(JSON.stringify(errorLine) + "\n");
+        return 1;
+    }
+}
+/**
+ * Entrypoint: read the request from stdin, run it, exit with the run's code.
+ * A stdin/read failure (or a request that can't be parsed) also degrades to a
+ * terminal `error` line + exit 1 — the route always sees a well-formed final
+ * line regardless of how the child failed.
+ */
+async function main() {
+    let request;
+    try {
+        request = parseRunLocalRequest(await readAll(process.stdin));
+    }
+    catch (err) {
+        const errorLine = {
+            kind: "error",
+            outcome: "failed",
+            error: err instanceof Error ? err.message : String(err),
+        };
+        process.stdout.write(JSON.stringify(errorLine) + "\n");
+        process.exitCode = 1;
+        return;
+    }
+    process.exitCode = await runBootstrap(request, process.stdout);
+}
+// Only self-invoke when run as the child entrypoint, never when imported by a
+// unit test (which drives runBootstrap / parseRunLocalRequest directly). The
+// built entry is dist/core/run-local-bootstrap.js; import.meta.url ends with
+// this module's own file, and process.argv[1] is the script node was told to
+// run — they share a basename only for the real child launch.
+const invokedAsScript = typeof process.argv[1] === "string" &&
+    import.meta.url === new URL(`file://${process.argv[1]}`).href;
+if (invokedAsScript) {
+    void main();
+}
+//# sourceMappingURL=run-local-bootstrap.js.map

package/dist/core/run-local-bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-local-bootstrap.js","sourceRoot":"","sources":["../../src/core/run-local-bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/core/run-state.d.ts

@@ -0,0 +1,60 @@
+/**
+ * run-state — fetches a prod execution projection from the agents surface and
+ * renders it to a {@link RunView} the canvas can poll.
+ *
+ * WHY the agents surface: deployed agent runs are owned by the agents runtime
+ * (`GET /agents/v1/executions/:id`), not the core-capabilities surface. The
+ * response is the full ExecutionProjection JSON (same shape agent-core's
+ * decodeExecutionProjection consumes).
+ *
+ * WHY the key stays server-side: the Sapiom API key is a harness credential that
+ * must never reach the browser. The harness server fetches on behalf of the
+ * canvas, so the SPA polls a local `/api/runs/:id/state` endpoint (no key in the
+ * request) rather than calling the upstream surface directly.
+ *
+ * NOTE: this env-precedence helper for the agents base URL is duplicated
+ * elsewhere in the harness; consolidate into one shared helper when convenient.
+ */
+import type { RunView } from "../shared/types.js";
+import { type ApiKeyProvider } from "./api-key-provider.js";
+/** Resolve the agents surface base URL from the environment. */
+export declare function resolveAgentsBaseUrl(): string;
+export type RunStateResult = {
+    ok: true;
+    runView: RunView;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+export interface RunStateFetcherOpts {
+    /**
+     * Sapiom API key. Accepts either a plain `string | null` (the boot-time key)
+     * or an {@link ApiKeyProvider} — pass a provider to get the refresh-on-401
+     * recovery path. A bare string never refreshes.
+     */
+    apiKey: string | null | ApiKeyProvider;
+    baseUrl?: string;
+    /** Injectable fetch implementation — defaults to global fetch. Test seam. */
+    fetchImpl?: typeof fetch;
+}
+export interface RunStateFetcher {
+    fetch(executionId: string): Promise<RunStateResult>;
+}
+/** Upstream statuses that mean "the API key was rejected" — worth one refresh
+ *  + retry before we give up. 401 is the common case; 403 covers a key that
+ *  authenticated but lost authorization (e.g. rotated to a new org). */
+export declare function isAuthRejection(status: number): boolean;
+/**
+ * Create a fetcher that resolves an execution's current render state from the
+ * agents surface. The fetcher is intentionally non-throwing: all error paths
+ * return a typed {@link RunStateResult} with `ok: false` so the router can
+ * forward the appropriate HTTP status without a try/catch at the call site.
+ *
+ * When constructed with an {@link ApiKeyProvider}, a 401/403 from the upstream
+ * call triggers exactly one credential refresh + retry: if the shared store has
+ * a newer key (e.g. the user re-logged-in), the retry uses it and the Studio
+ * recovers in place instead of surfacing a dead-end auth error.
+ */
+export declare function createRunStateFetcher(opts: RunStateFetcherOpts): RunStateFetcher;
+//# sourceMappingURL=run-state.d.ts.map

package/dist/core/run-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-state.d.ts","sourceRoot":"","sources":["../../src/core/run-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,uBAAuB,CAAC;AAgB/B,gEAAgE;AAChE,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAAC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACrD;AAED;;wEAEwE;AACxE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,mBAAmB,GACxB,eAAe,CA4EjB"}

package/dist/core/run-state.js

@@ -0,0 +1,122 @@
+/**
+ * run-state — fetches a prod execution projection from the agents surface and
+ * renders it to a {@link RunView} the canvas can poll.
+ *
+ * WHY the agents surface: deployed agent runs are owned by the agents runtime
+ * (`GET /agents/v1/executions/:id`), not the core-capabilities surface. The
+ * response is the full ExecutionProjection JSON (same shape agent-core's
+ * decodeExecutionProjection consumes).
+ *
+ * WHY the key stays server-side: the Sapiom API key is a harness credential that
+ * must never reach the browser. The harness server fetches on behalf of the
+ * canvas, so the SPA polls a local `/api/runs/:id/state` endpoint (no key in the
+ * request) rather than calling the upstream surface directly.
+ *
+ * NOTE: this env-precedence helper for the agents base URL is duplicated
+ * elsewhere in the harness; consolidate into one shared helper when convenient.
+ */
+import { decodeExecutionProjection } from "@sapiom/agent-core";
+import { renderRunState } from "./render-run-state.js";
+import { staticApiKeyProvider, } from "./api-key-provider.js";
+/**
+ * Normalize the polymorphic `apiKey` option to an {@link ApiKeyProvider}. A
+ * plain string (or null) becomes a no-refresh provider so existing static-key
+ * callers keep working unchanged; a provider is used as-is.
+ */
+function toApiKeyProvider(apiKey) {
+    if (apiKey === null || typeof apiKey === "string") {
+        return staticApiKeyProvider(apiKey);
+    }
+    return apiKey;
+}
+/** Resolve the agents surface base URL from the environment. */
+export function resolveAgentsBaseUrl() {
+    return (process.env.SAPIOM_AGENTS_URL ??
+        process.env.SAPIOM_TOOLS_BASE ??
+        "https://tools.sapiom.ai");
+}
+/** Upstream statuses that mean "the API key was rejected" — worth one refresh
+ *  + retry before we give up. 401 is the common case; 403 covers a key that
+ *  authenticated but lost authorization (e.g. rotated to a new org). */
+export function isAuthRejection(status) {
+    return status === 401 || status === 403;
+}
+/**
+ * Create a fetcher that resolves an execution's current render state from the
+ * agents surface. The fetcher is intentionally non-throwing: all error paths
+ * return a typed {@link RunStateResult} with `ok: false` so the router can
+ * forward the appropriate HTTP status without a try/catch at the call site.
+ *
+ * When constructed with an {@link ApiKeyProvider}, a 401/403 from the upstream
+ * call triggers exactly one credential refresh + retry: if the shared store has
+ * a newer key (e.g. the user re-logged-in), the retry uses it and the Studio
+ * recovers in place instead of surfacing a dead-end auth error.
+ */
+export function createRunStateFetcher(opts) {
+    const { baseUrl = resolveAgentsBaseUrl(), fetchImpl = fetch } = opts;
+    const provider = toApiKeyProvider(opts.apiKey);
+    const requestOnce = async (executionId, apiKey) => {
+        try {
+            const res = await fetchImpl(`${baseUrl}/agents/v1/executions/${encodeURIComponent(executionId)}`, { headers: { "x-sapiom-api-key": apiKey } });
+            return { kind: "ok", res };
+        }
+        catch {
+            return {
+                kind: "err",
+                result: { ok: false, status: 502, error: "gateway unreachable" },
+            };
+        }
+    };
+    const decode = async (res) => {
+        if (res.status === 404) {
+            return { ok: false, status: 404, error: "execution not found" };
+        }
+        if (!res.ok) {
+            return {
+                ok: false,
+                status: 502,
+                error: `gateway responded ${res.status}`,
+            };
+        }
+        try {
+            const raw = (await res.json());
+            const runView = renderRunState(decodeExecutionProjection(raw));
+            return { ok: true, runView };
+        }
+        catch {
+            return { ok: false, status: 502, error: "could not decode execution" };
+        }
+    };
+    return {
+        async fetch(executionId) {
+            // No API key — do not touch the network; the harness is not signed in.
+            let apiKey = provider.getKey();
+            if (!apiKey) {
+                return {
+                    ok: false,
+                    status: 503,
+                    error: "harness is not signed in to Sapiom",
+                };
+            }
+            const first = await requestOnce(executionId, apiKey);
+            if (first.kind === "err")
+                return first.result;
+            // Refresh-on-401: re-read the shared credential store once and retry with
+            // the newer key when the rejection was an auth failure and refresh
+            // actually produced a different key. Any other status (or an unchanged
+            // key) falls through to normal decoding/error mapping — no wasted retry.
+            if (isAuthRejection(first.res.status)) {
+                const refreshed = await provider.refresh();
+                if (refreshed && refreshed !== apiKey) {
+                    apiKey = refreshed;
+                    const second = await requestOnce(executionId, apiKey);
+                    if (second.kind === "err")
+                        return second.result;
+                    return decode(second.res);
+                }
+            }
+            return decode(first.res);
+        },
+    };
+}
+//# sourceMappingURL=run-state.js.map

package/dist/core/run-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-state.js","sourceRoot":"","sources":["../../src/core/run-state.ts"],"names":[],"mappings":"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"}

package/dist/core/stub-feedback.d.ts

@@ -0,0 +1,52 @@
+/**
+ * stub-feedback — the pure, read-only derivations behind the run-inspector's
+ * stub affordances (WB15-2). Given a {@link RunView} (which already carries the
+ * run-level stub facts set by {@link renderLocalRun}), decide:
+ *  - whether a given step should show the "stubbed" chip, and
+ *  - what the read-only stub-hygiene notice should say (or nothing).
+ *
+ * Pure and deterministic: no LLM, no I/O, no clock — every result is a function
+ * of the RunView alone, so both are Stryker targets with mutation-first tests.
+ *
+ * Read-only by design: this surfaces what a stub run DID (served a call, or a
+ * supplied stub matched nothing / had the wrong shape). Editing stubs is a
+ * deferred fast-follow and lives nowhere here.
+ *
+ * Honesty is the whole point: the chip appears only for a step that actually ran
+ * in a stub-served run (never for a prod run, never for a step the run never
+ * reached), and the notice is `null` unless there is a real problem to report —
+ * so a clean run shows no chrome at all.
+ */
+import type { RunView } from "../shared/types.js";
+/**
+ * Should the "stubbed" chip render for the step named `stepName`?
+ *
+ * True only when BOTH hold:
+ *  1. the run was stub-served (`run.stubbed` — set by renderLocalRun for an
+ *     offline local run; never by renderRunState for a prod run), and
+ *  2. that step actually ran this run (it appears in `run.steps`).
+ *
+ * A local run resolves every `ctx.sapiom.*` call from a stub, so a step that ran
+ * was stub-served — that is the honest granularity (agent-core records no
+ * per-CALL stub attribution). A step the run never reached, or any step of a
+ * real run, gets no chip. A null run (nothing observed yet) is never stubbed.
+ */
+export declare function stepIsStubbed(run: RunView | null, stepName: string): boolean;
+/**
+ * The read-only stub-hygiene notice for a run, or `null` when there is nothing
+ * honest to show. Present only the signals that carry real content:
+ *  - `unusedStubs`: supplied stub keys that matched no capability call (a no-op
+ *    mock — almost always a typo or the wrong path form), and
+ *  - `stubWarnings`: stub values that matched a key but had the wrong shape.
+ *
+ * Returns `null` unless at least one non-empty signal exists, so the caller can
+ * render nothing for a clean run (honesty — no empty "0 issues" panel). The
+ * returned arrays are always non-empty when present (empty ones are dropped),
+ * so the component never has to re-check length.
+ */
+export interface StubNotice {
+    unusedStubs?: NonNullable<RunView["unusedStubs"]>;
+    stubWarnings?: NonNullable<RunView["stubWarnings"]>;
+}
+export declare function stubNotice(run: RunView | null): StubNotice | null;
+//# sourceMappingURL=stub-feedback.d.ts.map

package/dist/core/stub-feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-feedback.d.ts","sourceRoot":"","sources":["../../src/core/stub-feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG5E;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;IAClD,YAAY,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;CACrD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,GAAG,UAAU,GAAG,IAAI,CAYjE"}