@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/loop/run-step.d.ts

@@ -1,29 +0,0 @@
-/**
- * `RunStep` adapters.
- *
- * `runAgent` wraps every LLM and tool call in an injected `RunStep`. Two
- * adapters cover the two execution modes:
- *
- * - `passthroughStep` — the chat route. In-process, single-replica, no
- *   durability. Just runs the function.
- * - `durableStep` — workflow contexts. Wraps the call as a `DBOS.runStep`
- *   so a crashed workflow replays without re-issuing completed LLM/tool
- *   calls. The step name (`llm-${i}`, `tool-${name}-${toolUseId}`) is the
- *   cache key on replay (see the harness-thread-store spec) and must not be reformatted.
- *
- * The loop body never imports DBOS — it depends only on the `RunStep`
- * shape, which is what lets the same `runAgent` serve chat and (in change
- * 8) durable workflows.
- */
-import type { Result } from "neverthrow";
-import type { RunStep } from "./types.js";
-export declare const passthroughStep: RunStep;
-export declare const durableStep: RunStep;
-/**
- * Adapt a `RunStep` to a `Result`-returning body. This is THE seam where
- * `Result` meets durability: a step is recorded as failed — and retried /
- * fails fast — only when its body throws, so an `err` MUST become a throw at
- * the step boundary. The body stays Result-shaped; `unwrapOrThrow` isolates
- * the throw. Pass `durableStep` in workflows, `passthroughStep` in chat.
- */
-export declare function resultStep(runStep: RunStep): <T, E>(name: string, fn: () => PromiseLike<Result<T, E>>) => Promise<T>;

package/dist/loop/run-step.js

@@ -1,34 +0,0 @@
-/**
- * `RunStep` adapters.
- *
- * `runAgent` wraps every LLM and tool call in an injected `RunStep`. Two
- * adapters cover the two execution modes:
- *
- * - `passthroughStep` — the chat route. In-process, single-replica, no
- *   durability. Just runs the function.
- * - `durableStep` — workflow contexts. Wraps the call as a `DBOS.runStep`
- *   so a crashed workflow replays without re-issuing completed LLM/tool
- *   calls. The step name (`llm-${i}`, `tool-${name}-${toolUseId}`) is the
- *   cache key on replay (see the harness-thread-store spec) and must not be reformatted.
- *
- * The loop body never imports DBOS — it depends only on the `RunStep`
- * shape, which is what lets the same `runAgent` serve chat and (in change
- * 8) durable workflows.
- */
-import { DBOS } from "@dbos-inc/dbos-sdk";
-import { unwrapOrThrow } from "../lib/result.js";
-export const passthroughStep = (_name, fn) => fn();
-export const durableStep = (name, fn) => DBOS.runStep(fn, { name });
-/**
- * Adapt a `RunStep` to a `Result`-returning body. This is THE seam where
- * `Result` meets durability: a step is recorded as failed — and retried /
- * fails fast — only when its body throws, so an `err` MUST become a throw at
- * the step boundary. The body stays Result-shaped; `unwrapOrThrow` isolates
- * the throw. Pass `durableStep` in workflows, `passthroughStep` in chat.
- */
-export function resultStep(runStep) {
-    return (name, 
-    // `PromiseLike`, not `Promise` — a `ResultAsync` (what `provider.chat`
-    // returns) is a `PromiseLike<Result>`, awaited to its inner `Result`.
-    fn) => runStep(name, async () => unwrapOrThrow(await fn()));
-}

package/dist/loop/run-to-terminal.d.ts

@@ -1,66 +0,0 @@
-/**
- * `runToTerminal` — terminal-salvage wrapper around `runAgent`.
- *
- * Some agents communicate their result EXCLUSIVELY through a terminal tool
- * (`submit_plan`, `submit_profile`, `submit_synthesis`, …):
- * the loop's text reply is discarded and the outcome is read from a closure
- * cell the terminal tool writes. The wrap-up of a capped run lets no tool run,
- * so an agent that burns its whole iteration budget — or simply stops on
- * prose — without ever submitting leaves that cell empty and forces the caller
- * to hard-fail.
- *
- * `runToTerminal` runs the agent, then — if the outcome cell is still empty
- * and the run was not aborted — runs ONE salvage continuation of the same
- * conversation (`continueAgent`), opened by a corrective nudge. The salvage
- * still declares every tool of the agent, masked to the terminal tools only,
- * because the tool set is part of the prefix a signed thinking block and the
- * prompt cache bind to.
- *
- * Salvage steps are namespaced (`salvage:…`) so a durable (DBOS) caller does
- * not collide the continuation's `llm-*` / `tool-*` cache keys with the first
- * run's — replaying them would silently return the first run's cached results.
- */
-import type { AgentSession } from "../auth/types.js";
-import type { Tool } from "../tools/define-tool.js";
-import { type AgentFinish, type RunAgentOptions, type RunAgentResult } from "./run-agent.js";
-import type { AgentDefinition, LoopMessage } from "./types.js";
-/** Default salvage budget: one submit plus a validation-fix retry or two. */
-export declare const DEFAULT_SALVAGE_ITERATIONS = 3;
-/**
- * What a salvage continuation was and how it went — present only when one ran.
- *
- * The two finishes answer different questions and a diagnostician needs both: a
- * first run that ended `max_iterations` spent its whole budget failing to submit,
- * while one that ended `stop` gave up on prose after a single turn. Those call for
- * opposite responses, and the returned `RunAgentResult` carries only the second
- * run's finish, which is the same for either. Its token rollups are the sole
- * exception — those are summed across both attempts, since they measure the run
- * rather than diagnose it.
- */
-export interface SalvageRecord {
-    /** How the FIRST run ended — the reason a salvage was needed at all. */
-    readonly firstFinish: AgentFinish;
-    /** How the salvage continuation itself ended. */
-    readonly finish: AgentFinish;
-}
-/** A `runToTerminal` outcome: the driving run's result, plus the salvage account. */
-export interface RunToTerminalResult extends RunAgentResult {
-    /** Null when the first run reached its terminal tool and no salvage was needed. */
-    readonly salvage: SalvageRecord | null;
-}
-/** Describes how to salvage a run that never reached its terminal tool. */
-export interface TerminalSalvage {
-    /** Their ids become the mask of the salvage continuation, so each must already be a declared tool of the agent. */
-    readonly tools: readonly Tool[];
-    /** Opens the salvage continuation as a synthetic user message. */
-    readonly nudge: string;
-    /** The cap of salvage requests. Defaults to {@link DEFAULT_SALVAGE_ITERATIONS}. */
-    readonly maxIterations?: number;
-}
-/**
- * Drive `agent` to its terminal tool, salvaging once if it does not get there.
- * A salvage result carries both runs' messages and summed rollups, with the
- * salvage's own finish. Throws first if a terminal tool is not declared on the
- * agent.
- */
-export declare function runToTerminal(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions, salvage: TerminalSalvage): Promise<RunToTerminalResult>;

package/dist/loop/run-to-terminal.js

@@ -1,90 +0,0 @@
-/**
- * `runToTerminal` — terminal-salvage wrapper around `runAgent`.
- *
- * Some agents communicate their result EXCLUSIVELY through a terminal tool
- * (`submit_plan`, `submit_profile`, `submit_synthesis`, …):
- * the loop's text reply is discarded and the outcome is read from a closure
- * cell the terminal tool writes. The wrap-up of a capped run lets no tool run,
- * so an agent that burns its whole iteration budget — or simply stops on
- * prose — without ever submitting leaves that cell empty and forces the caller
- * to hard-fail.
- *
- * `runToTerminal` runs the agent, then — if the outcome cell is still empty
- * and the run was not aborted — runs ONE salvage continuation of the same
- * conversation (`continueAgent`), opened by a corrective nudge. The salvage
- * still declares every tool of the agent, masked to the terminal tools only,
- * because the tool set is part of the prefix a signed thinking block and the
- * prompt cache bind to.
- *
- * Salvage steps are namespaced (`salvage:…`) so a durable (DBOS) caller does
- * not collide the continuation's `llm-*` / `tool-*` cache keys with the first
- * run's — replaying them would silently return the first run's cached results.
- */
-import { createNoopLogger } from "../lib/console-logger.js";
-import { continueAgent } from "./continue-agent.js";
-import { addChatUsage } from "./metrics.js";
-import { runAgent } from "./run-agent.js";
-/** Default salvage budget: one submit plus a validation-fix retry or two. */
-export const DEFAULT_SALVAGE_ITERATIONS = 3;
-/**
- * Drive `agent` to its terminal tool, salvaging once if it does not get there.
- * A salvage result carries both runs' messages and summed rollups, with the
- * salvage's own finish. Throws first if a terminal tool is not declared on the
- * agent.
- */
-export async function runToTerminal(agent, initial, session, opts, salvage) {
-    const undeclared = salvage.tools.find((terminal) => !agent.tools.some((tool) => tool.id === terminal.id));
-    if (undeclared !== undefined) {
-        throw new Error(`The terminal tool "${undeclared.id}" is not a declared tool of the agent "${agent.id}", thus the salvage mask cannot let it run.`);
-    }
-    const first = await runAgent(agent, initial, session, opts);
-    if (opts.resolved?.() || opts.signal.aborted)
-        return { ...first, salvage: null };
-    const salvageBudget = salvage.maxIterations ?? DEFAULT_SALVAGE_ITERATIONS;
-    // Reported here rather than in `runAgent` because the loop cannot know it is being
-    // salvaged: it sees a continuation with a small cap and a mask.
-    // Only this wrapper holds the fact that a first attempt ended without its outcome.
-    // The first run's finish rides along because it is the whole diagnosis of WHY a
-    // salvage was needed, and it is the field the second run's result overwrites.
-    (opts.logger ?? createNoopLogger()).named("loop").warn("salvaging a run that never reached its terminal tool", {
-        agentId: agent.id,
-        callPath: session.provenance.callPath,
-        firstFinishReason: first.finish.reason,
-        firstCappedOut: first.finish.cappedOut,
-        salvageTools: salvage.tools.map((t) => t.id),
-        salvageMaxIterations: salvageBudget,
-    });
-    const salvaged = await continueAgent(agent, first.messages, { text: salvage.nudge, mask: { allow: salvage.tools.map((t) => t.id) }, maxRequests: salvageBudget, stepNamespace: "salvage" }, session, opts);
-    // The continuation is the same logical run as the first attempt, so its
-    // rollups must cover both, or the caller reads the salvage's tokens as the whole cost.
-    //
-    // `salvage` deliberately keeps each attempt's OWN finish, unsummed: it is the
-    // per-attempt diagnosis, not a second accounting of the same tokens. The two
-    // views are therefore NOT additive — `finish` is the run's total and already
-    // covers everything `salvage.firstFinish` and `salvage.finish` report.
-    return {
-        messages: [...first.messages, ...salvaged.messages],
-        finish: {
-            ...salvaged.finish,
-            ...sumUsage("usage", first.finish, salvaged.finish),
-            ...sumUsage("turnUsage", first.finish, salvaged.finish),
-        },
-        salvage: { firstFinish: first.finish, finish: salvaged.finish },
-    };
-}
-/**
- * Sum one rollup field across the two runs, keeping it absent when neither
- * reported. Both runs are roots or neither is — `runToTerminal` forwards its
- * caller's options unchanged — so summing `turnUsage` never mixes a turn total
- * with a bare own-rollup.
- */
-function sumUsage(field, first, second) {
-    const a = first[field];
-    const b = second[field];
-    if (a === undefined && b === undefined)
-        return {};
-    const total = {};
-    addChatUsage(total, a);
-    addChatUsage(total, b);
-    return { [field]: total };
-}

package/dist/loop/tool-mask.d.ts

@@ -1,23 +0,0 @@
-/**
- * A signed thinking block is bound to the exact prefix of its request, so a
- * request always declares the full tool set
- * of its agent; the mask and the budget act at dispatch instead. Provider-native
- * masking is out of scope, because the vendors do it differently and an
- * OpenAI-compatible endpoint has neither form.
- */
-import type { ToolCallPart } from "ai";
-import type { Tool } from "../tools/define-tool.js";
-/** An absent mask lets each declared tool run. */
-export type ToolMask = "none" | {
-    readonly allow: readonly string[];
-};
-/** A tool with no entry has no limit. */
-export type ToolBudget = Readonly<Record<string, number>>;
-export declare function maskExcept(tools: readonly Tool[], ids: readonly string[]): ToolMask;
-/**
- * `undefined` for a call that passes, otherwise the model-visible refusal
- * text. A passing call takes one unit from `used` regardless of its later
- * result, because the check reads only the mask, the budget, and the run's
- * calls — so a durable replay refuses the same calls again.
- */
-export declare function refusalsFor(calls: readonly ToolCallPart[], mask: ToolMask | undefined, budget: ToolBudget | undefined, used: Map<string, number>): (string | undefined)[];

package/dist/loop/tool-mask.js

@@ -1,46 +0,0 @@
-/**
- * A signed thinking block is bound to the exact prefix of its request, so a
- * request always declares the full tool set
- * of its agent; the mask and the budget act at dispatch instead. Provider-native
- * masking is out of scope, because the vendors do it differently and an
- * OpenAI-compatible endpoint has neither form.
- */
-export function maskExcept(tools, ids) {
-    return { allow: tools.map((t) => t.id).filter((id) => !ids.includes(id)) };
-}
-function maskLets(mask, toolName) {
-    if (mask === undefined)
-        return true;
-    if (mask === "none")
-        return false;
-    return mask.allow.includes(toolName);
-}
-/** Matches the `{ error, retryable }` shape of every other tool error. */
-function refusal(error) {
-    return JSON.stringify({ error, retryable: false });
-}
-function maskRefusal(mask, toolName) {
-    if (mask === "none")
-        return refusal(`No tool can run for this request, thus ${toolName} did not run. Answer in text.`);
-    const available = mask.allow.length === 0 ? "none" : mask.allow.join(", ");
-    return refusal(`The tool ${toolName} is not available for this request, thus it did not run. The tools that can run now: ${available}.`);
-}
-/**
- * `undefined` for a call that passes, otherwise the model-visible refusal
- * text. A passing call takes one unit from `used` regardless of its later
- * result, because the check reads only the mask, the budget, and the run's
- * calls — so a durable replay refuses the same calls again.
- */
-export function refusalsFor(calls, mask, budget, used) {
-    return calls.map((call) => {
-        if (mask !== undefined && !maskLets(mask, call.toolName))
-            return maskRefusal(mask, call.toolName);
-        const limit = budget?.[call.toolName];
-        const count = used.get(call.toolName) ?? 0;
-        if (limit !== undefined && count >= limit) {
-            return refusal(`The tool ${call.toolName} reached its limit of ${limit} calls in this run, thus this call did not run.`);
-        }
-        used.set(call.toolName, count + 1);
-        return undefined;
-    });
-}

package/dist/providers/streaming-chat.d.ts

@@ -1,32 +0,0 @@
-/**
- * `createStreamingChat` — a streaming `AgentChat`.
- *
- * The agent loop depends on `AgentChat`: one request in, one collapsed
- * `ChatResponse` out. A `ChatProvider` satisfies that directly — its `chat`
- * collapses the stream silently. This builds a SECOND `AgentChat` from the
- * same provider's `chatStream` primitive: its `chat` drives the stream,
- * forwards every text delta to `onText`, and returns the same collapsed
- * `ChatResponse`. `runAgent` calls `chat` and never knows it streamed.
- *
- * The chat route is the one caller — it is the single place token streaming
- * is wired. Sub-agent loops (planner, literature-reviewer) and workflow
- * loops run on the plain `ChatProvider`, so they never stream.
- *
- * This wrapper is also where a client abort stops being control flow: it sees
- * every delta, so it alone can assemble the partial. On the stream's abort it
- * resolves an `"aborted"` `ChatResponse` carrying that partial rather than
- * re-throwing, letting the interactive turn keep what the model produced. The
- * plain provider keeps throwing on abort, so durable loops are untouched.
- */
-import type { AgentChat, ChatProvider } from "./types.js";
-/**
- * Wrap a `ChatProvider` as a streaming `AgentChat`. `onText` is called once
- * per text delta, in arrival order, as a side effect of `chat`. `chat` is
- * Result-returning: it consumes the throwing `chatStream` and maps a thrown
- * SDK failure to `err(ProviderError)`. A client abort is not an error here — it
- * resolves `ok` with finish reason `"aborted"` and an assistant message holding
- * exactly the deltas already forwarded (empty when the abort beat the first
- * delta), so the interactive turn keeps the partial reply instead of losing it
- * to a throw.
- */
-export declare function createStreamingChat(provider: ChatProvider, onText: (text: string) => void): AgentChat;

package/dist/providers/streaming-chat.js

@@ -1,91 +0,0 @@
-/**
- * `createStreamingChat` — a streaming `AgentChat`.
- *
- * The agent loop depends on `AgentChat`: one request in, one collapsed
- * `ChatResponse` out. A `ChatProvider` satisfies that directly — its `chat`
- * collapses the stream silently. This builds a SECOND `AgentChat` from the
- * same provider's `chatStream` primitive: its `chat` drives the stream,
- * forwards every text delta to `onText`, and returns the same collapsed
- * `ChatResponse`. `runAgent` calls `chat` and never knows it streamed.
- *
- * The chat route is the one caller — it is the single place token streaming
- * is wired. Sub-agent loops (planner, literature-reviewer) and workflow
- * loops run on the plain `ChatProvider`, so they never stream.
- *
- * This wrapper is also where a client abort stops being control flow: it sees
- * every delta, so it alone can assemble the partial. On the stream's abort it
- * resolves an `"aborted"` `ChatResponse` carrying that partial rather than
- * re-throwing, letting the interactive turn keep what the model produced. The
- * plain provider keeps throwing on abort, so durable loops are untouched.
- */
-import { ResultAsync, err, ok } from "neverthrow";
-import { scopeWorkloadId } from "../auth/types.js";
-import { toProviderError } from "./errors.js";
-/**
- * Wrap a `ChatProvider` as a streaming `AgentChat`. `onText` is called once
- * per text delta, in arrival order, as a side effect of `chat`. `chat` is
- * Result-returning: it consumes the throwing `chatStream` and maps a thrown
- * SDK failure to `err(ProviderError)`. A client abort is not an error here — it
- * resolves `ok` with finish reason `"aborted"` and an assistant message holding
- * exactly the deltas already forwarded (empty when the abort beat the first
- * delta), so the interactive turn keeps the partial reply instead of losing it
- * to a throw.
- */
-export function createStreamingChat(provider, onText) {
-    return {
-        capabilities: provider.capabilities,
-        chat(req, session, signal) {
-            const workload = `${session.scope.kind}:${scopeWorkloadId(session.scope)}`;
-            const run = async () => {
-                let final;
-                let partial = "";
-                try {
-                    for await (const event of provider.chatStream(req, session, signal)) {
-                        if (event.type === "text-delta") {
-                            partial += event.text;
-                            onText(event.text);
-                        }
-                        else {
-                            final = event.response;
-                        }
-                    }
-                }
-                catch (e) {
-                    // A client abort resolves with what streamed so far, never through
-                    // the error channel: the interactive turn persists the partial. The
-                    // gate here must be at least as wide as the underlying provider's
-                    // re-throw gate — an abort-named error OR an already-aborted client
-                    // signal — or a transport failure that lands while the signal is
-                    // aborted slips past into the error channel. Once the user has
-                    // aborted, that raced failure is noise: resolving with the partial
-                    // serves their intent, while an error banner would blame their own
-                    // keypress.
-                    const aborted = ((e instanceof DOMException || e instanceof Error) && e.name === "AbortError") || signal?.aborted === true;
-                    if (aborted) {
-                        // A complete response already in hand beats a partial reconstruction: if the
-                        // stream had yielded its terminal `done` before the abort threw, that whole
-                        // response is authoritative, so return it rather than the assembled deltas.
-                        if (final !== undefined)
-                            return ok(final);
-                        // The partial carries no model identity and no usage: it is
-                        // assembled from deltas rather than from a provider response, so
-                        // nothing here reported which model answered or what it cost.
-                        // Stamping the requested id would manufacture a claim the
-                        // endpoint never made.
-                        return ok({ message: { role: "assistant", content: partial }, finishReason: "aborted" });
-                    }
-                    return err(toProviderError(e, workload));
-                }
-                if (final === undefined) {
-                    return err({
-                        type: "provider",
-                        retryable: false,
-                        message: "createStreamingChat: chatStream ended without a final message",
-                    });
-                }
-                return ok(final);
-            };
-            return new ResultAsync(run());
-        },
-    };
-}

package/dist/tasks/derive-table-exec.d.ts

@@ -1,54 +0,0 @@
-/**
- * The container of one report-session derivation, as a registered DBOS workflow.
- *
- * The `derive_table` tool runs inside one live chat turn, and a chat turn is not a workflow. An exec runs as
- * a durable step of a workflow, and the reaper maps each container to the workflow that owns it. Thus the
- * container lives here, behind a registered workflow, and the tool starts it and awaits the handle.
- *
- * The shape is the shape of `tasks/extract-values.ts`: a body that a test drives directly, a registration
- * that closes over the construction-time deps, and a trigger that starts the workflow and gives the result
- * back. The tool holds the trigger as a plain function, thus no module under `tools/` imports DBOS.
- *
- * The body owns the whole machine lifetime. It creates the container, runs one exec to its terminal
- * result, and tears the container down on both paths. A teardown fault reaches the log alone, because the
- * work is done by then.
- */
-import { type Result } from "neverthrow";
-import type { Logger } from "../lib/logger.js";
-import type { SandboxClient } from "../sandbox/client.js";
-import { type Suspension } from "../workflows/suspension.js";
-import type { ExecResult } from "../sandbox/types.js";
-import { type DeriveTableExecInput } from "../tools/report-session/derive-table.js";
-/** The construction-time deps of the body. The registration closes over them, thus the trigger holds none. */
-export interface DeriveTableExecDeps {
-    readonly sandboxClient: SandboxClient;
-    /**
-     * The checkpointed clock of the deadline. It defaults to `DBOS.now()`, which a replay reads again from
-     * the checkpoint. A test injects a fixed clock, thus it drives this body with no launched runtime.
-     */
-    readonly now?: () => Promise<number>;
-    readonly logger?: Logger;
-}
-/**
- * The body, exported so a test drives it without a registered workflow.
- *
- * A fault of any seam call throws. The tool reads a rejection as one short detail. A chat turn awaits this
- * workflow, thus a suspension is the `err` of the result, and the workflow does not cancel
- * (workflow-suspension spec). The body does not mark the analysis: the tool reports the suspension to the
- * conversation agent.
- */
-export declare function runDeriveTableExecBody(input: DeriveTableExecInput, deps: DeriveTableExecDeps): Promise<Result<ExecResult, Suspension>>;
-/**
- * Register the derivation workflow with DBOS. It gives back the registered callable, thus a trigger
- * dispatches with `DBOS.startWorkflow`.
- */
-export declare function registerDeriveTableExecWorkflow(deps: DeriveTableExecDeps): (input: DeriveTableExecInput) => Promise<Result<ExecResult, Suspension>>;
-/** The workflow id of one derivation. The execution id is unique already, thus no nonce joins it. */
-export declare function deriveTableExecWorkflowId(executionId: string): string;
-/**
- * The async edge. It starts the registered workflow and it awaits the terminal result.
- *
- * The tool authorizes the derivation before this call and it revokes after, thus this edge holds no
- * lifecycle of its own. A workflow fault rejects the returned promise, and a suspension is the `err`.
- */
-export declare function triggerDeriveTableExec(workflow: (input: DeriveTableExecInput) => Promise<Result<ExecResult, Suspension>>, input: DeriveTableExecInput): Promise<Result<ExecResult, Suspension>>;

package/dist/tasks/derive-table-exec.js

@@ -1,86 +0,0 @@
-/**
- * The container of one report-session derivation, as a registered DBOS workflow.
- *
- * The `derive_table` tool runs inside one live chat turn, and a chat turn is not a workflow. An exec runs as
- * a durable step of a workflow, and the reaper maps each container to the workflow that owns it. Thus the
- * container lives here, behind a registered workflow, and the tool starts it and awaits the handle.
- *
- * The shape is the shape of `tasks/extract-values.ts`: a body that a test drives directly, a registration
- * that closes over the construction-time deps, and a trigger that starts the workflow and gives the result
- * back. The tool holds the trigger as a plain function, thus no module under `tools/` imports DBOS.
- *
- * The body owns the whole machine lifetime. It creates the container, runs one exec to its terminal
- * result, and tears the container down on both paths. A teardown fault reaches the log alone, because the
- * work is done by then.
- */
-import { DBOS } from "@dbos-inc/dbos-sdk";
-import { err, ok } from "neverthrow";
-import { forStep } from "../auth/types.js";
-import { createNoopLogger } from "../lib/console-logger.js";
-import { mintSandboxIdentity } from "../sandbox/identity.js";
-import { keepSuspendingRefusal } from "../sandbox/sandbox-error.js";
-import { suspensionOfSpawnRefusal } from "../workflows/suspension.js";
-import { buildDerivationExec, DERIVATION_DEADLINE_MS, DERIVATION_RESOURCES, DERIVE_RUN_LITERAL, DERIVE_STEP_LITERAL, } from "../tools/report-session/derive-table.js";
-/** The exec progress callback. A derivation reports no live activity, thus the callback drops each event. */
-const noopEmit = () => { };
-/**
- * The body, exported so a test drives it without a registered workflow.
- *
- * A fault of any seam call throws. The tool reads a rejection as one short detail. A chat turn awaits this
- * workflow, thus a suspension is the `err` of the result, and the workflow does not cancel
- * (workflow-suspension spec). The body does not mark the analysis: the tool reports the suspension to the
- * conversation agent.
- */
-export async function runDeriveTableExecBody(input, deps) {
-    const logger = (deps.logger ?? createNoopLogger()).named("derive-table-exec").with({ analysisId: input.analysisId });
-    const workflowId = DBOS.workflowID ?? deriveTableExecWorkflowId(input.executionId);
-    const spawned = keepSuspendingRefusal(await deps.sandboxClient.createSandbox(forStep(input.runSession, DERIVE_STEP_LITERAL), { childWorkflowId: workflowId, resources: DERIVATION_RESOURCES, writableTail: input.writableTail }, mintSandboxIdentity(DERIVE_RUN_LITERAL)));
-    if (spawned.isErr()) {
-        const suspension = suspensionOfSpawnRefusal(spawned.error);
-        logger.warn("derivation suspended", { reason: suspension.reason });
-        return err(suspension);
-    }
-    const sandbox = spawned.value;
-    try {
-        // A checkpointed clock, not `Date.now()`: a wall-clock deadline would grow on each recovery.
-        const deadline = (await (deps.now ?? (() => DBOS.now()))()) + DERIVATION_DEADLINE_MS;
-        const request = buildDerivationExec({
-            script: input.script,
-            workingDir: input.workingDir,
-            inputs: input.inputs,
-            output: input.output,
-        });
-        return ok(await deps.sandboxClient.exec(sandbox, request, noopEmit, deadline));
-    }
-    finally {
-        try {
-            await deps.sandboxClient.teardown(sandbox);
-        }
-        catch (cause) {
-            logger.warn("the derivation sandbox did not tear down", logger.errorFields(cause));
-        }
-    }
-}
-/**
- * Register the derivation workflow with DBOS. It gives back the registered callable, thus a trigger
- * dispatches with `DBOS.startWorkflow`.
- */
-export function registerDeriveTableExecWorkflow(deps) {
-    return DBOS.registerWorkflow((input) => runDeriveTableExecBody(input, deps), { name: "derive-table-exec" });
-}
-/** The workflow id of one derivation. The execution id is unique already, thus no nonce joins it. */
-export function deriveTableExecWorkflowId(executionId) {
-    return `${DERIVE_RUN_LITERAL}:${executionId}`;
-}
-/**
- * The async edge. It starts the registered workflow and it awaits the terminal result.
- *
- * The tool authorizes the derivation before this call and it revokes after, thus this edge holds no
- * lifecycle of its own. A workflow fault rejects the returned promise, and a suspension is the `err`.
- */
-export async function triggerDeriveTableExec(workflow, input) {
-    const handle = (await DBOS.startWorkflow(workflow, {
-        workflowID: deriveTableExecWorkflowId(input.executionId),
-    })(input));
-    return handle.getResult();
-}

package/dist/workflows/suspension.d.ts

@@ -1,32 +0,0 @@
-/**
- * The suspension of work (workflow-suspension spec).
- *
- * A suspension starts only from a model request that fails with a `suspend`
- * error, or from a gate that refuses with the suspend flag. The harness carries
- * the reason of the host as it is and never reads it: no path compares a
- * reason to a value, and no path reads the text of an error message.
- *
- * The owner of the result of a workflow selects the mechanism. A durable owner
- * (`executeAnalysis`, `sandbox-step`, `data-profile`) records the reason in its
- * stored state and ends in the DBOS state `CANCELLED`, which `resumeWorkflow`
- * reads. A workflow with a live caller (`derive-table-exec`, `extract-values`)
- * returns the suspension as the `err` of its result. A suspension of an
- * analysis run or of a data profile marks the analysis through
- * `suspendAnalysis` (`state/analyses.ts`). A workflow with a live caller does
- * not mark it: the conversation agent reads the suspension as a tool result.
- */
-import type { GateRefusal } from "../lib/hooks.js";
-import type { SuspendingRefusal } from "../sandbox/sandbox-error.js";
-/** Plain data, thus it crosses a DBOS checkpoint as it is. */
-export interface Suspension {
-    readonly kind: "suspended";
-    readonly reason: string;
-}
-export declare function suspensionOfFailure(err: unknown): Suspension | undefined;
-export declare function suspensionOfRefusal(refusal: GateRefusal): Suspension | undefined;
-export declare function suspensionOfSpawnRefusal(refusal: SuspendingRefusal): Suspension;
-/**
- * The cancel lands at the next DBOS operation, thus the named step raises
- * `DBOSWorkflowCancelledError` and nothing after it runs.
- */
-export declare function cancelSelf(stepName: string): Promise<never>;

package/dist/workflows/suspension.js

@@ -1,38 +0,0 @@
-/**
- * The suspension of work (workflow-suspension spec).
- *
- * A suspension starts only from a model request that fails with a `suspend`
- * error, or from a gate that refuses with the suspend flag. The harness carries
- * the reason of the host as it is and never reads it: no path compares a
- * reason to a value, and no path reads the text of an error message.
- *
- * The owner of the result of a workflow selects the mechanism. A durable owner
- * (`executeAnalysis`, `sandbox-step`, `data-profile`) records the reason in its
- * stored state and ends in the DBOS state `CANCELLED`, which `resumeWorkflow`
- * reads. A workflow with a live caller (`derive-table-exec`, `extract-values`)
- * returns the suspension as the `err` of its result. A suspension of an
- * analysis run or of a data profile marks the analysis through
- * `suspendAnalysis` (`state/analyses.ts`). A workflow with a live caller does
- * not mark it: the conversation agent reads the suspension as a tool result.
- */
-import { DBOS } from "@dbos-inc/dbos-sdk";
-import { findSuspendError } from "../providers/errors.js";
-export function suspensionOfFailure(err) {
-    const found = findSuspendError(err);
-    return found === undefined ? undefined : { kind: "suspended", reason: found.reason };
-}
-export function suspensionOfRefusal(refusal) {
-    return refusal.kind === "suspended" ? { kind: "suspended", reason: refusal.reason } : undefined;
-}
-export function suspensionOfSpawnRefusal(refusal) {
-    return { kind: "suspended", reason: refusal.reason };
-}
-/**
- * The cancel lands at the next DBOS operation, thus the named step raises
- * `DBOSWorkflowCancelledError` and nothing after it runs.
- */
-export async function cancelSelf(stepName) {
-    await DBOS.cancelWorkflow(DBOS.workflowID);
-    await DBOS.runStep(async () => undefined, { name: stepName });
-    throw new Error(`unreachable: ${stepName} did not raise the cancellation`);
-}