stageflow 0.18.0 → 0.19.0

package/dist/runtime/reopenSkipped.d.ts

@@ -0,0 +1,13 @@
+import type { RunStore } from "../runstore/port.js";
+import type { StageEnvelope } from "../types/envelope.js";
+import type { ResolvedPipelineDag } from "../types/pipeline.js";
+import type { StageScheduleState } from "./pipelineScheduler.js";
+export declare function isUnchosenForkChild(dag: ResolvedPipelineDag, stageId: string, envelopes: Map<string, StageEnvelope>): boolean;
+export declare function eventsShowStarted(events: ReadonlyArray<{
+    event: string;
+}>): boolean;
+export declare function shouldReopenSkippedStage(dag: ResolvedPipelineDag, stageId: string, states: Map<string, StageScheduleState>, envelopes: Map<string, StageEnvelope>, hasStarted: boolean, options?: {
+    supersededCloneIds?: ReadonlySet<string>;
+}): boolean;
+export declare function persistReopenedStages(store: Pick<RunStore, "appendStageEvent">, runId: string, stageIds: Iterable<string>, states: Map<string, StageScheduleState>): Promise<void>;
+export declare function reopenRunnableSkippedStages(store: Pick<RunStore, "appendStageEvent" | "listStageEvents" | "listForkGenerations">, runId: string, dag: ResolvedPipelineDag, states: Map<string, StageScheduleState>, envelopes: Map<string, StageEnvelope>): Promise<void>;

package/dist/runtime/reopenSkipped.js

@@ -0,0 +1,56 @@
+import { normalizeForkChoice } from "../envelope/forkChoice.js";
+import { forkCohortMapsFromStore } from "./forkGeneration.js";
+import { joinAllowsRun } from "./joinReadiness.js";
+export function isUnchosenForkChild(dag, stageId, envelopes) {
+    for (const node of dag.nodes) {
+        const envelope = envelopes.get(node.id);
+        if (envelope?.fork_choice === undefined || envelope.fork_choice === null) {
+            continue;
+        }
+        const children = dag.childrenOf[node.id] ?? [];
+        if (!children.includes(stageId))
+            continue;
+        const chosen = normalizeForkChoice(envelope.fork_choice, "stored");
+        if (!chosen.has(stageId))
+            return true;
+    }
+    return false;
+}
+export function eventsShowStarted(events) {
+    return events.some((event) => event.event === "started" || event.event === "resumed");
+}
+export function shouldReopenSkippedStage(dag, stageId, states, envelopes, hasStarted, options) {
+    if (hasStarted)
+        return false;
+    if (options?.supersededCloneIds?.has(stageId))
+        return false;
+    if (states.get(stageId) !== "skipped")
+        return false;
+    if (isUnchosenForkChild(dag, stageId, envelopes))
+        return false;
+    const hypothetical = new Map(states);
+    hypothetical.set(stageId, "pending");
+    return joinAllowsRun(dag, stageId, hypothetical, envelopes);
+}
+export async function persistReopenedStages(store, runId, stageIds, states) {
+    for (const id of stageIds) {
+        if (states.get(id) !== "skipped")
+            continue;
+        await store.appendStageEvent(runId, id, { event: "reopened" });
+        states.set(id, "pending");
+    }
+}
+export async function reopenRunnableSkippedStages(store, runId, dag, states, envelopes) {
+    const { supersededCloneIds } = await forkCohortMapsFromStore(store, runId);
+    const ids = [];
+    for (const [id, state] of states) {
+        if (state !== "skipped")
+            continue;
+        const events = await store.listStageEvents(runId, id);
+        if (!shouldReopenSkippedStage(dag, id, states, envelopes, eventsShowStarted(events), { supersededCloneIds })) {
+            continue;
+        }
+        ids.push(id);
+    }
+    await persistReopenedStages(store, runId, ids, states);
+}

package/dist/runtime/resumeTimedOut.d.ts

@@ -0,0 +1,33 @@
+import type { AgentPort } from "../agent/port.js";
+import type { RunStore } from "../runstore/port.js";
+import type { StageExecutionMode } from "./stageConcurrency.js";
+import type { StageProcessLauncher } from "./stageProcessLauncher.js";
+import { StageHitlController } from "./stageHitl.js";
+import { type OperatorCatalog } from "./stageAttemptBootstrap.js";
+export type ResumeTimedOutContext = {
+    runId: string;
+    stageId: string;
+    agent: AgentPort;
+    store: RunStore;
+    hitl: StageHitlController;
+    executionMode: StageExecutionMode;
+    stageProcessLauncher?: StageProcessLauncher;
+    cwd: string;
+    factoryCwd?: string;
+    maxActiveStagesPerRun: number;
+    operatorCatalog?: OperatorCatalog;
+};
+export declare function assertTimedOutStageEligible(status: string, events: ReadonlyArray<{
+    event: string;
+    reason?: string;
+}>): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    status: 409;
+};
+export declare function reconstructTimedOutAndContinue(ctx: ResumeTimedOutContext): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;

package/dist/runtime/resumeTimedOut.js

@@ -0,0 +1,165 @@
+import { existsSync } from "node:fs";
+import { fakeHitlResumePath } from "../agent/fakeAgent.js";
+import { definitionIdForInstance } from "../runstore/stageInstanceId.js";
+import { attemptSessionPath } from "../runstore/workspaceLayout.js";
+import { WAIT_WITHOUT_WORKER_DISPATCH } from "./answerResume.js";
+import { resumeRun } from "./pipelineScheduler.js";
+import { loadRunContext } from "./resumeReconstruct.js";
+import { isRunStageWaiting, runStage } from "./stageRunner.js";
+import { attemptContext } from "./stageAttemptContext.js";
+import { openStageAttempt, } from "./stageAttemptBootstrap.js";
+import { buildStageRoots, withResolvedAuthPath } from "./stageRoots.js";
+import { isStageTimeoutReason, lastFailedReason, } from "../agent/stageTimeout.js";
+import { deriveExecutionPatchFromEvent } from "../runstore/stageExecution.js";
+export function assertTimedOutStageEligible(status, events) {
+    if (status !== "failed") {
+        return {
+            ok: false,
+            reason: `Stage is not timed out (status=${status})`,
+            status: 409,
+        };
+    }
+    if (!isStageTimeoutReason(lastFailedReason(events))) {
+        return {
+            ok: false,
+            reason: "Stage did not fail due to timeout; use retry to start a new attempt",
+            status: 409,
+        };
+    }
+    return { ok: true };
+}
+export async function reconstructTimedOutAndContinue(ctx) {
+    const { runId, stageId, agent, store, cwd } = ctx;
+    const factoryCwd = ctx.factoryCwd ?? cwd;
+    try {
+        const latestExecution = await store.getLatestStageExecution(runId, stageId);
+        const attempt = latestExecution?.attempt ?? 1;
+        const attemptCtx = attemptContext(attempt);
+        const attemptOpt = attemptCtx.eventOptions();
+        const { meta, task, loaded } = await loadRunContext(store, runId, cwd);
+        const definitionId = definitionIdForInstance(meta.pipeline_dag, stageId);
+        const stageIndex = loaded.stages.findIndex((s) => s.id === definitionId);
+        if (stageIndex < 0) {
+            const reason = `Stage ${stageId} not in pipeline ${meta.pipeline_id}`;
+            await store.appendStageEvent(runId, stageId, { event: "failed", reason }, attemptOpt);
+            await store.updateRunStatus(runId, "failed");
+            return { ok: false, reason };
+        }
+        const stage = loaded.stages[stageIndex];
+        const dag = meta.pipeline_dag ?? loaded.dag;
+        const workspaceDir = store.getWorkspaceDir(runId);
+        const checkoutRoot = meta.checkout_root;
+        const roots = withResolvedAuthPath(buildStageRoots(workspaceDir, stageId, checkoutRoot, attemptCtx), factoryCwd);
+        const sessionFile = attemptSessionPath(workspaceDir, stageId, attempt);
+        const fakeResume = fakeHitlResumePath(roots, stageId);
+        if (!existsSync(sessionFile) && !existsSync(fakeResume)) {
+            return {
+                ok: false,
+                reason: "missing session to resume; use retry to start a new attempt",
+            };
+        }
+        const resumed = { event: "resumed" };
+        await store.appendStageEvent(runId, stageId, resumed, attemptOpt);
+        try {
+            const execution = await store.getStageExecution(runId, stageId, attempt);
+            const patch = deriveExecutionPatchFromEvent(resumed, execution);
+            if (Object.keys(patch).length > 0) {
+                await store.updateStageExecution(runId, stageId, attempt, patch);
+            }
+        }
+        catch {
+            // no execution row yet
+        }
+        await store.updateRunStatus(runId, "running");
+        const opened = await openStageAttempt({
+            agent,
+            store,
+            runId,
+            stage,
+            stageId,
+            task,
+            dag,
+            checkoutRoot,
+            workspaceDir,
+            factoryCwd,
+            attemptCtx,
+            operatorCatalog: ctx.operatorCatalog,
+            sessionMode: "timeout_resume",
+            resumeToken: sessionFile,
+            onActivity: (event) => {
+                void store.appendStageEvent(runId, stageId, event, attemptOpt);
+            },
+        });
+        if (!opened.ok) {
+            await store.appendStageEvent(runId, stageId, { event: "failed", reason: opened.reason }, attemptOpt);
+            await store.updateRunStatus(runId, "failed");
+            return { ok: false, reason: opened.reason };
+        }
+        const result = await runStage({
+            agent,
+            store,
+            runId,
+            stage,
+            stageId,
+            task,
+            dag,
+            checkoutRoot,
+            workspaceDir,
+            hitl: ctx.hitl,
+            skipStarted: true,
+            existingHandle: opened.handle,
+            attemptCtx,
+            factoryCwd,
+            operatorCatalog: ctx.operatorCatalog,
+            sessionMode: "timeout_resume",
+            resumeToken: sessionFile,
+        });
+        if (isRunStageWaiting(result)) {
+            await store.updateRunStatus(runId, "failed");
+            return {
+                ok: false,
+                reason: WAIT_WITHOUT_WORKER_DISPATCH,
+            };
+        }
+        if (!result.ok) {
+            await store.updateRunStatus(runId, "failed");
+            return { ok: false, reason: result.reason };
+        }
+        const rest = await resumeRun({
+            prepared: {
+                task,
+                loaded,
+                run: { runId, workspaceDir },
+                agent,
+                store,
+                cwd,
+                projectRoot: factoryCwd,
+                checkoutRoot,
+                hitl: ctx.hitl,
+                operatorCatalog: ctx.operatorCatalog,
+            },
+            maxActiveStagesPerRun: ctx.maxActiveStagesPerRun,
+            resumeFromStageId: stageId,
+            initialPrior: result.envelope ?? null,
+            executionMode: ctx.executionMode,
+            stageProcessLauncher: ctx.stageProcessLauncher,
+        });
+        if (rest.outcome === "failed") {
+            return { ok: false, reason: rest.reason };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : `timeout resume failed: ${String(err)}`;
+        try {
+            const latestExecution = await store.getLatestStageExecution(runId, stageId);
+            const attemptCtx = attemptContext(latestExecution?.attempt ?? 1);
+            await store.appendStageEvent(runId, stageId, { event: "failed", reason }, attemptCtx.eventOptions());
+            await store.updateRunStatus(runId, "failed");
+        }
+        catch {
+            // ignore secondary failures
+        }
+        return { ok: false, reason };
+    }
+}

package/dist/runtime/runManager.d.ts

@@ -135,6 +135,7 @@ export declare class RunManager {
     }): Promise<StartRunResult>;
     rerun(runId: string): Promise<StartRunResult>;
     retryStage(runId: string, stageId: string): Promise<RetryStageResult>;
+    resumeTimedOutStage(runId: string, stageId: string): Promise<RetryStageResult>;
     recoverManualStage(runId: string, stageId: string, guidance?: string): Promise<RetryStageResult>;
     recoverManualStageUntilStop(runId: string, stageId: string, guidance?: string): Promise<{
         ok: true;

package/dist/runtime/runManager.js

@@ -3,6 +3,7 @@ import { readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import { normalizeCatalogPath } from "../runstore/normalizeCatalogPath.js";
 import { loadRunContext } from "./resumeReconstruct.js";
+import { assertTimedOutStageEligible, reconstructTimedOutAndContinue, } from "./resumeTimedOut.js";
 import { loadTaskFromYaml } from "../config/loadTask.js";
 import { deriveStatusFromStages, findUnhandledFailedStage, } from "../runstore/port.js";
 import { PipelineValidationError, startPipeline, } from "./pipelineRunner.js";
@@ -417,6 +418,81 @@ export class RunManager {
     async retryStage(runId, stageId) {
         return this.retryStageInternal(runId, stageId, true);
     }
+    async resumeTimedOutStage(runId, stageId) {
+        const resumeKey = waitKey(runId, stageId);
+        if (this.resumeInFlight.has(resumeKey) || this.retryInFlight.has(resumeKey)) {
+            return {
+                ok: false,
+                reason: `Resume already in progress for run ${runId} stage ${stageId}`,
+                status: 409,
+            };
+        }
+        this.resumeInFlight.add(resumeKey);
+        let detail;
+        try {
+            detail = await this.options.store.readRun(runId);
+        }
+        catch {
+            this.resumeInFlight.delete(resumeKey);
+            return { ok: false, reason: `Run not found: ${runId}`, status: 404 };
+        }
+        const stageSnap = detail.stages.find((s) => s.stage_id === stageId);
+        if (!stageSnap) {
+            this.resumeInFlight.delete(resumeKey);
+            return { ok: false, reason: `Stage not found: ${stageId}`, status: 404 };
+        }
+        const eligibility = assertTimedOutStageEligible(stageSnap.status, stageSnap.events);
+        if (!eligibility.ok) {
+            this.resumeInFlight.delete(resumeKey);
+            return eligibility;
+        }
+        const latest = await this.options.store.getLatestStageExecution(runId, stageId);
+        const attemptIndex = latest?.attempt ?? 1;
+        const wasActive = this.active.has(runId);
+        const tracked = await this.ensureResumeTracked(runId);
+        if (!tracked.ok) {
+            this.resumeInFlight.delete(resumeKey);
+            return { ok: false, reason: tracked.reason, status: 409 };
+        }
+        const insertedForResume = !wasActive;
+        try {
+            const done = reconstructTimedOutAndContinue({
+                runId,
+                stageId,
+                agent: this.options.agent,
+                store: this.options.store,
+                hitl: this.hitl,
+                executionMode: this.executionMode,
+                cwd: this.cwd,
+                maxActiveStagesPerRun: this.maxActiveStagesPerRun,
+                factoryCwd: this.projectRoot,
+                ...(this.stageProcessLauncher !== undefined
+                    ? { stageProcessLauncher: this.stageProcessLauncher }
+                    : {}),
+                ...(this.options.operatorCatalog !== undefined
+                    ? { operatorCatalog: this.options.operatorCatalog }
+                    : {}),
+            });
+            this.registerResumeUntrack(runId, done);
+            const outcome = await done;
+            if (!outcome.ok) {
+                if (insertedForResume) {
+                    this.removeActiveEntry(runId, false);
+                }
+                const missingSession = outcome.reason !== undefined &&
+                    outcome.reason.startsWith("missing session to resume");
+                return {
+                    ok: false,
+                    reason: outcome.reason ?? "timeout resume failed",
+                    status: missingSession ? 409 : 500,
+                };
+            }
+            return { ok: true, runId, stageId, attemptIndex };
+        }
+        finally {
+            this.resumeInFlight.delete(resumeKey);
+        }
+    }
     async recoverManualStage(runId, stageId, guidance) {
         return this.recoverManualStageInternal(runId, stageId, guidance, true);
     }

package/dist/runtime/stageRecovery.js

@@ -35,10 +35,10 @@ export async function failStageAsInterrupted(options) {
 }
 export async function syncRunStatusFromStages(store, runId) {
     const meta = await store.readRunMeta(runId);
-    if (meta.status === "succeeded")
-        return;
     const run = await store.readRun(runId);
     const derived = deriveStatusFromStages(run.stages, meta.pipeline_dag);
+    if (meta.status === "succeeded" && derived !== "running")
+        return;
     if ((meta.status ?? "created") !== derived) {
         await store.updateRunStatus(runId, derived);
     }

package/dist/runtime/stageRunner.js

@@ -3,6 +3,7 @@ import { buildStageRoots, withResolvedAuthPath, } from "./stageRoots.js";
 import { createDefaultHitlQaHooks, recordWaitEnter, } from "./stageHitl.js";
 import { openStageAttempt, } from "./stageAttemptBootstrap.js";
 import { createVerifiedStageExecution } from "./verifiedStageExecution.js";
+import { isStageTimeoutReason } from "../agent/stageTimeout.js";
 export function isRunStageWaiting(outcome) {
     return "waiting" in outcome && outcome.waiting === true;
 }
@@ -220,7 +221,9 @@ export async function runStage(options) {
             attemptCtx,
         });
         console.error(`Stage ${stageId} failed: ${reason}`);
-        await handle.close().catch(() => undefined);
+        await handle
+            .close(isStageTimeoutReason(reason) ? { park: true } : undefined)
+            .catch(() => undefined);
         return { ok: false, reason };
     }
     if (isRunStageWaiting(outcome)) {
@@ -251,6 +254,7 @@ export async function runStage(options) {
         });
     }
     finally {
-        await handle.close().catch(() => undefined);
+        const timedOut = isStageTimeoutReason(outcome.ok ? undefined : outcome.reason);
+        await handle.close(timedOut ? { park: true } : undefined).catch(() => undefined);
     }
 }

package/dist/server/http.js

@@ -91,6 +91,7 @@ function isMutatingApi(method, pathname) {
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/answer$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/feedback-decision$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/retry$/.test(pathname) ||
+        /^\/api\/runs\/[^/]+\/stages\/[^/]+\/resume$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/recovery$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/recovery\/stop$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/abandon$/.test(pathname) ||
@@ -390,6 +391,23 @@ export async function startUiServer(options) {
                     });
                     return true;
                 }
+                const resumeMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/resume$/);
+                if (method === "POST" && resumeMatch) {
+                    await readJsonBody(req);
+                    const runId = decodeURIComponent(resumeMatch[1] ?? "");
+                    const stageId = decodeURIComponent(resumeMatch[2] ?? "");
+                    const result = await manager.resumeTimedOutStage(runId, stageId);
+                    if (!result.ok) {
+                        json(res, result.status ?? 500, mapRetryStageFailure(result));
+                        return true;
+                    }
+                    json(res, 202, {
+                        runId: result.runId,
+                        stageId: result.stageId,
+                        attemptIndex: result.attemptIndex,
+                    });
+                    return true;
+                }
                 const recoverMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/recovery$/);
                 if (method === "POST" && recoverMatch) {
                     let body;

package/dist/tools/askOperator.d.ts

@@ -330,6 +330,7 @@ export declare function createAskOperatorTool(options: AskOperatorToolOptions):
         artifacts: Type.TArray<Type.TString>;
         id: Type.TOptional<Type.TString>;
     }>)[]]>;
+    prepareArguments: (args: unknown) => never;
     execute: (_toolCallId: string, params: unknown) => Promise<{
         content: {
             type: "text";

package/dist/tools/askOperator.js

@@ -9,6 +9,7 @@
  */
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
+import { prepareAskOperatorArguments } from "./prepareToolArguments.js";
 export class AskOperatorError extends Error {
     constructor(message) {
         super(message);
@@ -168,10 +169,11 @@ function parseSubQuestion(value, path) {
     };
 }
 export function parseAskOperatorParams(value) {
-    if (!isRecord(value)) {
+    const prepared = prepareAskOperatorArguments(value);
+    if (!isRecord(prepared)) {
         throw new AskOperatorError("ask_operator params must be an object");
     }
-    const kind = value.kind;
+    const kind = prepared.kind;
     if (typeof kind !== "string") {
         throw new AskOperatorError("kind is required");
     }
@@ -181,36 +183,36 @@ export function parseAskOperatorParams(value) {
         kind !== "artifact_backed") {
         throw new AskOperatorError(`unsupported prompt kind "${kind}" (allowed: free_text, confirm, multi_question, artifact_backed)`);
     }
-    const id = optionalId(value.id, "id");
+    const id = optionalId(prepared.id, "id");
     if (kind === "free_text" || kind === "confirm") {
         return {
             kind,
-            message: requireNonEmptyString(value.message, "message"),
+            message: requireNonEmptyString(prepared.message, "message"),
             ...(id !== undefined ? { id } : {}),
         };
     }
     if (kind === "artifact_backed") {
-        if (!Array.isArray(value.artifacts)) {
+        if (!Array.isArray(prepared.artifacts)) {
             throw new AskOperatorError("artifacts must be an array");
         }
-        if (value.artifacts.length < 1) {
+        if (prepared.artifacts.length < 1) {
             throw new AskOperatorError("artifacts must contain at least one path");
         }
-        const artifacts = value.artifacts.map((item, index) => requireNonEmptyString(item, `artifacts[${index}]`));
+        const artifacts = prepared.artifacts.map((item, index) => requireNonEmptyString(item, `artifacts[${index}]`));
         return {
             kind,
-            message: requireNonEmptyString(value.message, "message"),
+            message: requireNonEmptyString(prepared.message, "message"),
             artifacts,
             ...(id !== undefined ? { id } : {}),
         };
     }
-    if (!Array.isArray(value.questions)) {
+    if (!Array.isArray(prepared.questions)) {
         throw new AskOperatorError("questions must be an array");
     }
-    if (value.questions.length < 1) {
+    if (prepared.questions.length < 1) {
         throw new AskOperatorError("questions must contain at least one item");
     }
-    const questions = value.questions.map((item, index) => parseSubQuestion(item, `questions[${index}]`));
+    const questions = prepared.questions.map((item, index) => parseSubQuestion(item, `questions[${index}]`));
     return {
         kind,
         questions,
@@ -401,6 +403,7 @@ export function createAskOperatorTool(options) {
         label: "Ask operator",
         description: `Ask the operator a question and wait for their answer. Supports ${kindList} prompts. Does not complete the stage — call emit_stage_envelope when finished.`,
         parameters: askOperatorParamsSchemaFor(allowedKinds),
+        prepareArguments: prepareAskOperatorArguments,
         execute: async (_toolCallId, params) => {
             let prompt;
             try {

package/dist/tools/emitStageEnvelope.d.ts

@@ -37,6 +37,7 @@ export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloa
         stage_id: Type.TOptional<Type.TString>;
         notes: Type.TOptional<Type.TString>;
     }>;
+    prepareArguments: (args: unknown) => never;
     execute: (_toolCallId: string, params: unknown) => Promise<{
         content: {
             type: "text";

package/dist/tools/emitStageEnvelope.js

@@ -15,6 +15,7 @@ import { assertFeedbackLoopAction } from "../envelope/feedbackLoop.js";
 import { normalizeForkChoice } from "../envelope/forkChoice.js";
 import { assertEnvelopePayload, compilePayloadSchema, } from "../envelope/payloadSchema.js";
 import { assertPreEmitChecks, } from "../envelope/preEmitChecks.js";
+import { prepareEmitStageEnvelopeArguments } from "./prepareToolArguments.js";
 function stringLiteralsSchema(values) {
     if (values.length === 1) {
         return Type.Literal(values[0]);
@@ -78,12 +79,13 @@ export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitCont
             stage_id: Type.Optional(Type.String()),
             notes: Type.Optional(Type.String()),
         }),
+        prepareArguments: prepareEmitStageEnvelopeArguments,
         execute: async (_toolCallId, params) => {
             if (capture.envelope) {
                 return toolResult("Envelope already accepted; later emits are ignored.", { advancing: isAdvancingEnvelope(capture.envelope), error: "" }, { terminate: true });
             }
             try {
-                const envelope = assertRequiredEnvelope(params);
+                const envelope = assertRequiredEnvelope(prepareEmitStageEnvelopeArguments(params));
                 assertFeedbackLoopAction(envelope, feedbackLoopEmitContext);
                 const isSendBack = envelope.feedback_loop?.action === "send_back";
                 if (envelope.status !== "failure" &&

package/dist/tools/prepareToolArguments.d.ts

@@ -0,0 +1,4 @@
+export declare function coerceJsonArrayField(args: Record<string, unknown>, key: string): void;
+export declare function coerceJsonObjectField(args: Record<string, unknown>, key: string): void;
+export declare function prepareAskOperatorArguments(input: unknown): unknown;
+export declare function prepareEmitStageEnvelopeArguments(input: unknown): unknown;

package/dist/tools/prepareToolArguments.js

@@ -0,0 +1,79 @@
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseJsonArrayString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed.startsWith("["))
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseJsonObjectString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed.startsWith("{"))
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function coerceJsonArrayField(args, key) {
+    const parsed = parseJsonArrayString(args[key]);
+    if (parsed !== undefined) {
+        args[key] = parsed;
+    }
+}
+export function coerceJsonObjectField(args, key) {
+    const parsed = parseJsonObjectString(args[key]);
+    if (parsed !== undefined) {
+        args[key] = parsed;
+    }
+}
+function coerceJsonObjectArrayElements(args, key) {
+    const value = args[key];
+    if (!Array.isArray(value))
+        return;
+    args[key] = value.map((item) => parseJsonObjectString(item) ?? item);
+}
+export function prepareAskOperatorArguments(input) {
+    if (!isRecord(input))
+        return input;
+    const args = { ...input };
+    coerceJsonArrayField(args, "questions");
+    coerceJsonObjectArrayElements(args, "questions");
+    coerceJsonArrayField(args, "artifacts");
+    return args;
+}
+export function prepareEmitStageEnvelopeArguments(input) {
+    if (!isRecord(input))
+        return input;
+    const args = { ...input };
+    coerceJsonObjectField(args, "payload");
+    coerceJsonObjectField(args, "feedback_loop");
+    coerceJsonArrayField(args, "artifacts");
+    coerceJsonArrayField(args, "fork_choice");
+    coerceJsonArrayField(args, "checklist_attestations");
+    coerceJsonObjectArrayElements(args, "checklist_attestations");
+    if (Array.isArray(args.checklist_attestations)) {
+        args.checklist_attestations = args.checklist_attestations.map((item) => {
+            if (!isRecord(item))
+                return item;
+            const next = { ...item };
+            coerceJsonArrayField(next, "items");
+            return next;
+        });
+    }
+    return args;
+}