cueline 0.1.2 → 0.1.4

package/dist/src/core/run-status.d.ts

@@ -0,0 +1,53 @@
+import type { CueLineRunState, StoredJobStatus } from "./state-machine.js";
+import type { RuntimeLeaseObservation } from "../state/runtime-lease.js";
+import type { CancellationObservation } from "../state/cancellation.js";
+import type { RunEvent } from "../state/event-log.js";
+declare const OBSERVED_JOB_STATUSES: readonly ["pending", "running", "succeeded", "failed", "timed_out", "cancelled", "ambiguous", "orphaned"];
+export type CueLineObservedJobStatus = (typeof OBSERVED_JOB_STATUSES)[number];
+export type CueLineRunPhase = "starting" | "controller_response_pending" | "jobs_running" | "controller_decision_pending" | "caller_jobs_pending" | "runtime_active" | "runtime_stale" | "runtime_ownership_unknown" | "cancellation_pending" | "reconciliation_required" | "job_recovery_required" | "round_limit_reached" | "resume_ready" | "complete" | "blocked" | "cancelled";
+export type CueLineSafeNextAction = "observe" | "reconcile" | "inspect_jobs_then_continue" | "inspect_runtime" | "continue" | "execute_caller_jobs" | "return_result";
+export interface CueLineRunStatusSummary {
+    runId: string;
+    status: CueLineRunState["status"];
+    executor: CueLineRunState["executor"];
+    phase: CueLineRunPhase;
+    round: number;
+    maxRounds: number;
+    lastEventSequence: number;
+    runtime: RuntimeLeaseObservation;
+    cancellation: CancellationObservation;
+    controller: {
+        pendingTurns: number;
+        acceptedCommands: number;
+        responseAccepted: boolean;
+        lastAcceptedAction: "dispatch" | "wait" | "inspect" | "complete" | "blocked" | null;
+        lastAcceptedRequestId: string | null;
+        lastAcceptedJobKeys: string[];
+    };
+    jobs: {
+        total: number;
+        counts: Record<CueLineObservedJobStatus, number>;
+        items: Array<{
+            jobId: string;
+            jobKey: string;
+            required: boolean;
+            lane: string;
+            mode: string;
+            task: string;
+            status: CueLineObservedJobStatus;
+            persistedStatus: StoredJobStatus;
+        }>;
+    };
+    continueAllowed: boolean;
+    safeNextAction: CueLineSafeNextAction;
+}
+export interface AcceptedControllerCommandEvidence {
+    action: CueLineRunStatusSummary["controller"]["lastAcceptedAction"];
+    requestId: string | null;
+    jobKeys: string[];
+}
+export declare function acceptedControllerCommandEvidence(events: readonly RunEvent[]): AcceptedControllerCommandEvidence;
+export declare function cueLineRunPhase(state: CueLineRunState, runtime: RuntimeLeaseObservation, cancellation?: CancellationObservation): CueLineRunPhase;
+export declare function assertRunCanContinue(state: CueLineRunState, runtime: RuntimeLeaseObservation, cancellation?: CancellationObservation): void;
+export declare function summarizeCueLineRunState(state: CueLineRunState, lastEventSequence: number, runtime: RuntimeLeaseObservation, cancellation?: CancellationObservation, acceptedCommand?: AcceptedControllerCommandEvidence): CueLineRunStatusSummary;
+export {};

package/dist/src/core/run-status.js

@@ -0,0 +1,224 @@
+import { CueLineError } from "./errors.js";
+const JOB_STATUSES = [
+    "pending",
+    "running",
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled",
+    "ambiguous",
+];
+const OBSERVED_JOB_STATUSES = [...JOB_STATUSES, "orphaned"];
+export function acceptedControllerCommandEvidence(events) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event?.type !== "controller_command_accepted")
+            continue;
+        const payload = event.payload;
+        const command = payload.command;
+        if (typeof command !== "object" || command === null || Array.isArray(command))
+            continue;
+        const record = command;
+        const action = record.action === "dispatch" ||
+            record.action === "wait" ||
+            record.action === "inspect" ||
+            record.action === "complete" ||
+            record.action === "blocked"
+            ? record.action
+            : null;
+        if (action === null)
+            continue;
+        const jobs = Array.isArray(record.jobs) ? record.jobs : [];
+        return {
+            action,
+            requestId: typeof record.request_id === "string" ? record.request_id : null,
+            jobKeys: jobs.flatMap((job) => {
+                if (typeof job !== "object" || job === null || Array.isArray(job))
+                    return [];
+                const jobKey = job.job_key;
+                return typeof jobKey === "string" ? [jobKey] : [];
+            }),
+        };
+    }
+    return { action: null, requestId: null, jobKeys: [] };
+}
+function activeJobCount(state) {
+    return Object.values(state.jobs).filter((job) => job.status === "pending" || job.status === "running").length;
+}
+function isPristineRun(state) {
+    return (state.round === 0 &&
+        state.pendingControllerTurns.length === 0 &&
+        state.commandHashes.length === 0 &&
+        Object.keys(state.jobs).length === 0);
+}
+function roundLimitReached(state) {
+    return (state.status === "failed" &&
+        state.lastFailure?.code === "MAX_ROUNDS_EXCEEDED" &&
+        state.pendingControllerTurns.length === 0 &&
+        activeJobCount(state) === 0 &&
+        state.round >= state.maxRounds);
+}
+function safeNextActionFor(state, runtime, cancellation) {
+    if (state.status === "complete" || state.status === "blocked" || state.status === "cancelled") {
+        return "return_result";
+    }
+    if (cancellation.runRequested) {
+        return runtime.ownership === "active" ? "observe" : "inspect_runtime";
+    }
+    if (runtime.ownership === "active")
+        return "observe";
+    if (state.executor === "caller" && activeJobCount(state) > 0) {
+        return "execute_caller_jobs";
+    }
+    if (runtime.ownership === "stale" || runtime.ownership === "invalid") {
+        return "inspect_runtime";
+    }
+    if (state.pendingControllerTurns.length > 0) {
+        const turn = state.pendingControllerTurns[0];
+        const normallySubmitted = state.pendingControllerTurns.length === 1 &&
+            turn?.submissionState === "submitted" &&
+            !turn.manualSendConfirmed;
+        return normallySubmitted ? "observe" : "reconcile";
+    }
+    if (roundLimitReached(state))
+        return "return_result";
+    if (isPristineRun(state) && state.status === "running")
+        return "continue";
+    if (state.executor === "caller" && state.status === "running")
+        return "continue";
+    if (state.status === "running")
+        return "inspect_runtime";
+    if (activeJobCount(state) > 0)
+        return "inspect_jobs_then_continue";
+    return "continue";
+}
+export function cueLineRunPhase(state, runtime, cancellation = { runRequested: false, jobRequests: [] }) {
+    if (state.status === "complete")
+        return "complete";
+    if (state.status === "blocked")
+        return "blocked";
+    if (state.status === "cancelled")
+        return "cancelled";
+    if (cancellation.runRequested)
+        return "cancellation_pending";
+    if (state.status === "failed" && runtime.ownership === "active")
+        return "runtime_active";
+    if (runtime.ownership === "stale")
+        return "runtime_stale";
+    if (isPristineRun(state) && runtime.ownership !== "active")
+        return "starting";
+    if (state.status === "running" && state.pendingControllerTurns.length > 0) {
+        return "controller_response_pending";
+    }
+    if (state.executor === "caller" &&
+        runtime.ownership !== "active" &&
+        activeJobCount(state) > 0) {
+        return "caller_jobs_pending";
+    }
+    if (state.status === "failed") {
+        if (state.pendingControllerTurns.length > 0)
+            return "reconciliation_required";
+        if (activeJobCount(state) > 0)
+            return "job_recovery_required";
+        if (roundLimitReached(state))
+            return "round_limit_reached";
+        return "resume_ready";
+    }
+    if (runtime.ownership !== "active") {
+        if (state.executor === "caller") {
+            return state.commandHashes.length > 0 ? "controller_decision_pending" : "starting";
+        }
+        return "runtime_ownership_unknown";
+    }
+    if (activeJobCount(state) > 0)
+        return "jobs_running";
+    if (state.commandHashes.length > 0)
+        return "controller_decision_pending";
+    return "starting";
+}
+export function assertRunCanContinue(state, runtime, cancellation = { runRequested: false, jobRequests: [] }) {
+    if (cancellation.runRequested) {
+        throw new CueLineError("RUN_CANCELLATION_PENDING", `CueLine run '${state.runId}' has a durable cancellation request; continuation is forbidden.`, { details: { run_id: state.runId, phase: "cancellation_pending" } });
+    }
+    const inspect = `Inspect it with 'cueline run status ${state.runId} --json'; do not resend it.`;
+    if (runtime.ownership === "active") {
+        throw new CueLineError("RUN_ALREADY_ACTIVE", `CueLine run '${state.runId}' still has an active controller loop. ${inspect}`, { details: { run_id: state.runId, phase: cueLineRunPhase(state, runtime) } });
+    }
+    if (runtime.ownership === "stale") {
+        throw new CueLineError("RUN_STALE_REQUIRES_TAKEOVER", `CueLine run '${state.runId}' stopped heartbeating; explicit recovery is required. ${inspect}`, { details: { run_id: state.runId, phase: cueLineRunPhase(state, runtime) } });
+    }
+    if (runtime.ownership === "invalid") {
+        throw new CueLineError("RUNTIME_LEASE_INVALID", `CueLine run '${state.runId}' has unreadable runtime ownership evidence. ${inspect}`, { details: { run_id: state.runId, phase: cueLineRunPhase(state, runtime) } });
+    }
+    if (state.status !== "running")
+        return;
+    if (isPristineRun(state) &&
+        (runtime.ownership === "missing" || runtime.ownership === "released")) {
+        return;
+    }
+    if (state.executor === "caller" &&
+        (runtime.ownership === "missing" || runtime.ownership === "released")) {
+        return;
+    }
+    throw new CueLineError("RUN_OWNERSHIP_UNVERIFIED", `CueLine run '${state.runId}' is marked running but has no verifiable active owner. ${inspect}`, { details: { run_id: state.runId, phase: cueLineRunPhase(state, runtime) } });
+}
+export function summarizeCueLineRunState(state, lastEventSequence, runtime, cancellation = { runRequested: false, jobRequests: [] }, acceptedCommand = {
+    action: null,
+    requestId: null,
+    jobKeys: [],
+}) {
+    const counts = Object.fromEntries(OBSERVED_JOB_STATUSES.map((status) => [status, 0]));
+    const items = Object.values(state.jobs).map((job) => {
+        const status = (job.status === "pending" || job.status === "running") &&
+            state.executor !== "caller" &&
+            runtime.ownership !== "active"
+            ? "orphaned"
+            : job.status;
+        counts[status] += 1;
+        return {
+            jobId: job.jobId,
+            jobKey: job.jobKey,
+            required: job.required,
+            lane: job.spec.lane,
+            mode: job.spec.mode,
+            task: job.spec.task,
+            status,
+            persistedStatus: job.status,
+        };
+    });
+    const phase = cueLineRunPhase(state, runtime, cancellation);
+    const continueAllowed = !cancellation.runRequested &&
+        !roundLimitReached(state) &&
+        (runtime.ownership === "missing" || runtime.ownership === "released") &&
+        ((state.status === "failed") ||
+            (state.executor === "caller" && activeJobCount(state) === 0));
+    const safeNextAction = safeNextActionFor(state, runtime, cancellation);
+    return {
+        runId: state.runId,
+        status: state.status,
+        executor: state.executor,
+        phase,
+        round: state.round,
+        maxRounds: state.maxRounds,
+        lastEventSequence,
+        runtime,
+        cancellation,
+        controller: {
+            pendingTurns: state.pendingControllerTurns.length,
+            acceptedCommands: state.commandHashes.length,
+            responseAccepted: state.pendingControllerTurns.length === 0 &&
+                (acceptedCommand.action !== null || state.commandHashes.length > 0),
+            lastAcceptedAction: acceptedCommand.action,
+            lastAcceptedRequestId: acceptedCommand.requestId,
+            lastAcceptedJobKeys: acceptedCommand.jobKeys,
+        },
+        jobs: {
+            total: items.length,
+            counts,
+            items,
+        },
+        continueAllowed,
+        safeNextAction,
+    };
+}
+//# sourceMappingURL=run-status.js.map

package/dist/src/core/run-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-status.js","sourceRoot":"","sources":["../../../src/core/run-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAS3C,MAAM,YAAY,GAAG;IACnB,SAAS;IACT,SAAS;IACT,WAAW;IACX,QAAQ;IACR,WAAW;IACX,WAAW;IACX,WAAW;CACkC,CAAC;AAChD,MAAM,qBAAqB,GAAG,CAAC,GAAG,YAAY,EAAE,UAAU,CAAU,CAAC;AAwErE,MAAM,UAAU,iCAAiC,CAC/C,MAA2B;IAE3B,KAAK,IAAI,KAAK,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,KAAK,EAAE,IAAI,KAAK,6BAA6B;YAAE,SAAS;QAC5D,MAAM,OAAO,GAAG,KAAK,CAAC,OAAkC,CAAC;QACzD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,SAAS;QACxF,MAAM,MAAM,GAAG,OAAkC,CAAC;QAClD,MAAM,MAAM,GACV,MAAM,CAAC,MAAM,KAAK,UAAU;YAC5B,MAAM,CAAC,MAAM,KAAK,MAAM;YACxB,MAAM,CAAC,MAAM,KAAK,SAAS;YAC3B,MAAM,CAAC,MAAM,KAAK,UAAU;YAC5B,MAAM,CAAC,MAAM,KAAK,SAAS;YACzB,CAAC,CAAC,MAAM,CAAC,MAAM;YACf,CAAC,CAAC,IAAI,CAAC;QACX,IAAI,MAAM,KAAK,IAAI;YAAE,SAAS;QAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,OAAO;YACL,MAAM;YACN,SAAS,EAAE,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI;YAC3E,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;gBAC5B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;oBAAE,OAAO,EAAE,CAAC;gBAC7E,MAAM,MAAM,GAAI,GAA+B,CAAC,OAAO,CAAC;gBACxD,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,CAAC,CAAC;SACH,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AACxD,CAAC;AAED,SAAS,cAAc,CAAC,KAAsB;IAC5C,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CACrC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,CAC9D,CAAC,MAAM,CAAC;AACX,CAAC;AAED,SAAS,aAAa,CAAC,KAAsB;IAC3C,OAAO,CACL,KAAK,CAAC,KAAK,KAAK,CAAC;QACjB,KAAK,CAAC,sBAAsB,CAAC,MAAM,KAAK,CAAC;QACzC,KAAK,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC;QAChC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CACrC,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAsB;IAC/C,OAAO,CACL,KAAK,CAAC,MAAM,KAAK,QAAQ;QACzB,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,qBAAqB;QACjD,KAAK,CAAC,sBAAsB,CAAC,MAAM,KAAK,CAAC;QACzC,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC;QAC3B,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,SAAS,CAC/B,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CACxB,KAAsB,EACtB,OAAgC,EAChC,YAAqC;IAErC,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QAC9F,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,IAAI,YAAY,CAAC,YAAY,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC;IACxE,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACrD,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7D,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,KAAK,OAAO,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACrE,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IACD,IAAI,KAAK,CAAC,sBAAsB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,KAAK,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;QAC7C,MAAM,iBAAiB,GACrB,KAAK,CAAC,sBAAsB,CAAC,MAAM,KAAK,CAAC;YACzC,IAAI,EAAE,eAAe,KAAK,WAAW;YACrC,CAAC,IAAI,CAAC,mBAAmB,CAAC;QAC5B,OAAO,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;IACrD,CAAC;IACD,IAAI,iBAAiB,CAAC,KAAK,CAAC;QAAE,OAAO,eAAe,CAAC;IACrD,IAAI,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC1E,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IACjF,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,iBAAiB,CAAC;IACzD,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,4BAA4B,CAAC;IACnE,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,KAAsB,EACtB,OAAgC,EAChC,YAAY,GAA4B,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE;IAEhF,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU;QAAE,OAAO,UAAU,CAAC;IACnD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACjD,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,WAAW,CAAC;IACrD,IAAI,YAAY,CAAC,YAAY;QAAE,OAAO,sBAAsB,CAAC;IAC7D,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,CAAC,SAAS,KAAK,QAAQ;QAAE,OAAO,gBAAgB,CAAC;IACzF,IAAI,OAAO,CAAC,SAAS,KAAK,OAAO;QAAE,OAAO,eAAe,CAAC;IAC1D,IAAI,aAAa,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,SAAS,KAAK,QAAQ;QAAE,OAAO,UAAU,CAAC;IAC9E,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,sBAAsB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1E,OAAO,6BAA6B,CAAC;IACvC,CAAC;IACD,IACE,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAC3B,OAAO,CAAC,SAAS,KAAK,QAAQ;QAC9B,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,EACzB,CAAC;QACD,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,sBAAsB,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,yBAAyB,CAAC;QAC9E,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC;YAAE,OAAO,uBAAuB,CAAC;QAC9D,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO,qBAAqB,CAAC;QAC3D,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QACnC,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO,KAAK,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,UAAU,CAAC;QACrF,CAAC;QACD,OAAO,2BAA2B,CAAC;IACrC,CAAC;IACD,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,cAAc,CAAC;IACrD,IAAI,KAAK,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,6BAA6B,CAAC;IACzE,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,KAAsB,EACtB,OAAgC,EAChC,YAAY,GAA4B,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE;IAEhF,IAAI,YAAY,CAAC,YAAY,EAAE,CAAC;QAC9B,MAAM,IAAI,YAAY,CACpB,0BAA0B,EAC1B,gBAAgB,KAAK,CAAC,KAAK,kEAAkE,EAC7F,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,EAAE,CACpE,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,uCAAuC,KAAK,CAAC,KAAK,6BAA6B,CAAC;IAChG,IAAI,OAAO,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QACnC,MAAM,IAAI,YAAY,CACpB,oBAAoB,EACpB,gBAAgB,KAAK,CAAC,KAAK,0CAA0C,OAAO,EAAE,EAC9E,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,CAC7E,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;QAClC,MAAM,IAAI,YAAY,CACpB,6BAA6B,EAC7B,gBAAgB,KAAK,CAAC,KAAK,0DAA0D,OAAO,EAAE,EAC9F,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,CAC7E,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,IAAI,YAAY,CACpB,uBAAuB,EACvB,gBAAgB,KAAK,CAAC,KAAK,gDAAgD,OAAO,EAAE,EACpF,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,CAC7E,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO;IACvC,IACE,aAAa,CAAC,KAAK,CAAC;QACpB,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,KAAK,UAAU,CAAC,EACrE,CAAC;QACD,OAAO;IACT,CAAC;IACD,IACE,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAC3B,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,KAAK,UAAU,CAAC,EACrE,CAAC;QACD,OAAO;IACT,CAAC;IACD,MAAM,IAAI,YAAY,CACpB,0BAA0B,EAC1B,gBAAgB,KAAK,CAAC,KAAK,2DAA2D,OAAO,EAAE,EAC/F,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,CAC7E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,KAAsB,EACtB,iBAAyB,EACzB,OAAgC,EAChC,YAAY,GAA4B,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,EAChF,eAAe,GAAsC;IACnD,MAAM,EAAE,IAAI;IACZ,SAAS,EAAE,IAAI;IACf,OAAO,EAAE,EAAE;CACZ;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAC/B,qBAAqB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CACP,CAAC;IAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QAClD,MAAM,MAAM,GACV,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC;YACtD,KAAK,CAAC,QAAQ,KAAK,QAAQ;YAC3B,OAAO,CAAC,SAAS,KAAK,QAAQ;YAC5B,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;QACjB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACpB,OAAO;YACL,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI;YACnB,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI;YACnB,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI;YACnB,MAAM;YACN,eAAe,EAAE,GAAG,CAAC,MAAM;SAC5B,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IAC5D,MAAM,eAAe,GACnB,CAAC,YAAY,CAAC,YAAY;QAC1B,CAAC,iBAAiB,CAAC,KAAK,CAAC;QACzB,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,KAAK,UAAU,CAAC;QACrE,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC;YAC1B,CAAC,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAClE,MAAM,cAAc,GAAG,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IACvE,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK;QACL,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,iBAAiB;QACjB,OAAO;QACP,YAAY;QACZ,UAAU,EAAE;YACV,YAAY,EAAE,KAAK,CAAC,sBAAsB,CAAC,MAAM;YACjD,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,MAAM;YAC5C,gBAAgB,EACd,KAAK,CAAC,sBAAsB,CAAC,MAAM,KAAK,CAAC;gBACzC,CAAC,eAAe,CAAC,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;YACrE,kBAAkB,EAAE,eAAe,CAAC,MAAM;YAC1C,qBAAqB,EAAE,eAAe,CAAC,SAAS;YAChD,mBAAmB,EAAE,eAAe,CAAC,OAAO;SAC7C;QACD,IAAI,EAAE;YACJ,KAAK,EAAE,KAAK,CAAC,MAAM;YACnB,MAAM;YACN,KAAK;SACN;QACD,eAAe;QACf,cAAc;KACf,CAAC;AACJ,CAAC"}

package/dist/src/core/state-machine.d.ts

@@ -1,8 +1,10 @@
-import type { ControllerJobSpec, JobObservation } from "../protocol/types.js";
+import type { ControllerCommand, ControllerJobSpec, JobObservation } from "../protocol/types.js";
 import type { RunEvent } from "../state/event-log.js";
-export type CueLineRunStatus = "running" | "complete" | "blocked" | "failed";
+export type CueLineRunStatus = "running" | "complete" | "blocked" | "cancelled" | "failed";
+export type CueLineExecutor = "caller" | "process";
+export declare const DEFAULT_MAX_ROUNDS = 12;
 export type StoredJobStatus = JobObservation["status"];
-export type ControllerSubmissionState = "requested" | "possibly_sent" | "submitted";
+export type ControllerSubmissionState = "requested" | "submitting" | "possibly_sent" | "submitted";
 export interface PendingControllerTurn {
     round: number;
     requestId: string;
@@ -13,6 +15,8 @@ export interface PendingControllerTurn {
     conversationUrl: string | null;
     selectedModelLabel: string | null;
     baselineAssistantMessageCount: number | null;
+    composerPromptState: "inline_ready" | "attachment_ready" | null;
+    manualSendConfirmed: boolean;
 }
 export interface RunFailureEvidence {
     code: string;
@@ -31,20 +35,29 @@ export interface StoredJob {
     output: string | null;
     error: string | null;
 }
+export interface PendingCommandExecution {
+    command: ControllerCommand;
+    commandHash: string;
+}
 export interface CueLineRunState {
     runId: string;
     request: string;
+    executor: CueLineExecutor;
+    maxRounds: number;
     status: CueLineRunStatus;
     round: number;
     conversationUrl: string | null;
     pendingControllerTurns: PendingControllerTurn[];
+    abandonedControllerTurns: PendingControllerTurn[];
     lastFailure: RunFailureEvidence | null;
     jobs: Record<string, StoredJob>;
     notices: string[];
     commandHashes: string[];
+    pendingCommandExecution: PendingCommandExecution | null;
     finalDeliveryText: string | null;
     blockedReason: string | null;
+    cancelledReason: string | null;
 }
-export declare function initialRunState(runId: string, request: string): CueLineRunState;
+export declare function initialRunState(runId: string, request: string, executor?: CueLineExecutor, maxRounds?: number): CueLineRunState;
 export declare function reduceRunState(state: CueLineRunState, event: RunEvent): CueLineRunState;
 export declare function jobObservations(state: CueLineRunState): JobObservation[];

package/dist/src/core/state-machine.js

@@ -1,29 +1,78 @@
+export const DEFAULT_MAX_ROUNDS = 12;
+const STORED_JOB_STATUSES = new Set([
+    "pending",
+    "running",
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled",
+    "ambiguous",
+]);
+const TERMINAL_JOB_STATUSES = new Set([
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled",
+    "ambiguous",
+]);
 function recordPayload(event) {
     if (typeof event.payload !== "object" || event.payload === null || Array.isArray(event.payload)) {
         return {};
     }
     return event.payload;
 }
-export function initialRunState(runId, request) {
+function normalizedConversationUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return `${parsed.origin}${parsed.pathname}`;
+    }
+    catch {
+        return value;
+    }
+}
+function preserveCanonicalConversationUrl(canonical, candidate) {
+    if (typeof candidate !== "string" || candidate === "")
+        return canonical;
+    if (canonical !== null &&
+        normalizedConversationUrl(candidate) !== normalizedConversationUrl(canonical)) {
+        return canonical;
+    }
+    return canonical ?? candidate;
+}
+export function initialRunState(runId, request, executor = "process", maxRounds = DEFAULT_MAX_ROUNDS) {
     return {
         runId,
         request,
+        executor,
+        maxRounds,
         status: "running",
         round: 0,
         conversationUrl: null,
         pendingControllerTurns: [],
+        abandonedControllerTurns: [],
         lastFailure: null,
         jobs: {},
         notices: [],
         commandHashes: [],
+        pendingCommandExecution: null,
         finalDeliveryText: null,
         blockedReason: null,
+        cancelledReason: null,
     };
 }
 export function reduceRunState(state, event) {
     const payload = recordPayload(event);
     if (event.type === "run_created" && typeof payload.request === "string") {
-        return { ...state, request: payload.request };
+        return {
+            ...state,
+            request: payload.request,
+            executor: payload.executor === "caller" ? "caller" : state.executor ?? "process",
+            maxRounds: typeof payload.max_rounds === "number" &&
+                Number.isSafeInteger(payload.max_rounds) &&
+                payload.max_rounds >= 1
+                ? payload.max_rounds
+                : state.maxRounds ?? DEFAULT_MAX_ROUNDS,
+        };
     }
     if (event.type === "run_resumed") {
         return { ...state, status: "running" };
@@ -48,18 +97,28 @@ export function reduceRunState(state, event) {
                     conversationUrl: state.conversationUrl,
                     selectedModelLabel: null,
                     baselineAssistantMessageCount: null,
+                    composerPromptState: null,
+                    manualSendConfirmed: false,
                 },
             ],
+            abandonedControllerTurns: (state.abandonedControllerTurns ?? []).filter((turn) => turn.requestId !== payload.request_id),
         };
     }
     if (event.type === "controller_conversation_bound" &&
         typeof payload.conversation_url === "string" &&
         payload.conversation_url !== "") {
+        const boundTurn = typeof payload.request_id === "string"
+            ? (state.pendingControllerTurns ?? []).find((turn) => turn.requestId === payload.request_id)
+            : undefined;
+        const conversationUrl = preserveCanonicalConversationUrl(state.conversationUrl ?? boundTurn?.conversationUrl ?? null, payload.conversation_url);
         return {
             ...state,
-            conversationUrl: payload.conversation_url,
+            conversationUrl,
             pendingControllerTurns: (state.pendingControllerTurns ?? []).map((turn) => typeof payload.request_id === "string" && turn.requestId === payload.request_id
-                ? { ...turn, conversationUrl: payload.conversation_url }
+                ? {
+                    ...turn,
+                    conversationUrl: preserveCanonicalConversationUrl(turn.conversationUrl ?? state.conversationUrl, payload.conversation_url),
+                }
                 : turn),
         };
     }
@@ -69,9 +128,7 @@ export function reduceRunState(state, event) {
         const pending = (state.pendingControllerTurns ?? []).find((turn) => turn.requestId === payload.request_id);
         if (!pending)
             return state;
-        const conversationUrl = typeof payload.conversation_url === "string" && payload.conversation_url !== ""
-            ? payload.conversation_url
-            : pending.conversationUrl;
+        const conversationUrl = preserveCanonicalConversationUrl(state.conversationUrl ?? pending.conversationUrl, payload.conversation_url);
         return {
             ...state,
             conversationUrl: conversationUrl ?? state.conversationUrl,
@@ -79,7 +136,11 @@ export function reduceRunState(state, event) {
                 ? turn
                 : {
                     ...turn,
-                    submissionState: payload.submission_state === "submitted" ? "submitted" : "possibly_sent",
+                    submissionState: payload.submission_state === "submitted"
+                        ? "submitted"
+                        : payload.submission_state === "possibly_sent"
+                            ? "possibly_sent"
+                            : "submitting",
                     conversationUrl,
                     selectedModelLabel: typeof payload.selected_model_label === "string"
                         ? payload.selected_model_label
@@ -87,29 +148,90 @@ export function reduceRunState(state, event) {
                     baselineAssistantMessageCount: typeof payload.baseline_assistant_message_count === "number"
                         ? payload.baseline_assistant_message_count
                         : turn.baselineAssistantMessageCount,
+                    composerPromptState: payload.composer_prompt_state === "inline_ready" ||
+                        payload.composer_prompt_state === "attachment_ready"
+                        ? payload.composer_prompt_state
+                        : turn.composerPromptState,
                 }),
         };
     }
     if (event.type === "controller_response_received") {
         return {
             ...state,
-            conversationUrl: typeof payload.conversation_url === "string"
-                ? payload.conversation_url
-                : state.conversationUrl,
-            pendingControllerTurns: typeof payload.request_id === "string"
-                ? (state.pendingControllerTurns ?? []).filter((turn) => turn.requestId !== payload.request_id)
-                : state.pendingControllerTurns ?? [],
+            conversationUrl: preserveCanonicalConversationUrl(state.conversationUrl, payload.conversation_url),
+            // A received response is not yet an accepted command. Keep the exact
+            // pending turn recoverable until controller_command_accepted commits;
+            // otherwise a crash between these two events can resend the next round.
+            pendingControllerTurns: state.pendingControllerTurns ?? [],
             lastFailure: null,
         };
     }
     if (event.type === "controller_turn_abandoned" && typeof payload.request_id === "string") {
+        const abandoned = (state.pendingControllerTurns ?? []).find((turn) => turn.requestId === payload.request_id);
         return {
             ...state,
             pendingControllerTurns: (state.pendingControllerTurns ?? []).filter((turn) => turn.requestId !== payload.request_id),
+            abandonedControllerTurns: abandoned === undefined
+                ? state.abandonedControllerTurns ?? []
+                : [
+                    ...(state.abandonedControllerTurns ?? []).filter((turn) => turn.requestId !== abandoned.requestId),
+                    abandoned,
+                ],
+        };
+    }
+    if (event.type === "controller_turn_manual_submission_confirmed" &&
+        typeof payload.request_id === "string") {
+        const existing = (state.pendingControllerTurns ?? []).find((turn) => turn.requestId === payload.request_id) ??
+            (state.abandonedControllerTurns ?? []).find((turn) => turn.requestId === payload.request_id);
+        if (!existing)
+            return state;
+        const restored = {
+            ...existing,
+            submissionState: "submitted",
+            manualSendConfirmed: true,
+            conversationUrl: preserveCanonicalConversationUrl(state.conversationUrl ?? existing.conversationUrl, payload.conversation_url),
+        };
+        return {
+            ...state,
+            conversationUrl: restored.conversationUrl ?? state.conversationUrl,
+            pendingControllerTurns: [
+                ...(state.pendingControllerTurns ?? []).filter((turn) => turn.requestId !== restored.requestId),
+                restored,
+            ],
+            abandonedControllerTurns: (state.abandonedControllerTurns ?? []).filter((turn) => turn.requestId !== restored.requestId),
         };
     }
     if (event.type === "controller_command_accepted" && typeof payload.command_hash === "string") {
-        return { ...state, commandHashes: [...state.commandHashes, payload.command_hash] };
+        const command = typeof payload.command === "object" &&
+            payload.command !== null &&
+            !Array.isArray(payload.command)
+            ? payload.command
+            : {};
+        const requestId = typeof command.request_id === "string" ? command.request_id : undefined;
+        return {
+            ...state,
+            commandHashes: [...state.commandHashes, payload.command_hash],
+            pendingCommandExecution: typeof payload.command === "object" &&
+                payload.command !== null &&
+                !Array.isArray(payload.command)
+                ? {
+                    command: structuredClone(payload.command),
+                    commandHash: payload.command_hash,
+                }
+                : state.pendingCommandExecution ?? null,
+            pendingControllerTurns: requestId === undefined
+                ? state.pendingControllerTurns ?? []
+                : (state.pendingControllerTurns ?? []).filter((turn) => turn.requestId !== requestId),
+        };
+    }
+    if (event.type === "controller_command_execution_completed" &&
+        typeof payload.command_hash === "string") {
+        return {
+            ...state,
+            pendingCommandExecution: state.pendingCommandExecution?.commandHash === payload.command_hash
+                ? null
+                : state.pendingCommandExecution ?? null,
+        };
     }
     if (event.type === "notice" && typeof payload.message === "string") {
         return { ...state, notices: [...state.notices, payload.message] };
@@ -122,9 +244,15 @@ export function reduceRunState(state, event) {
     }
     if (event.type === "job_status" && typeof payload.job_id === "string") {
         const existing = state.jobs[payload.job_id];
-        if (!existing || typeof payload.status !== "string")
+        if (!existing ||
+            typeof payload.status !== "string" ||
+            !STORED_JOB_STATUSES.has(payload.status)) {
             return state;
+        }
         const status = payload.status;
+        if (TERMINAL_JOB_STATUSES.has(existing.status) && status !== existing.status) {
+            return state;
+        }
         return {
             ...state,
             jobs: {
@@ -143,6 +271,8 @@ export function reduceRunState(state, event) {
             ...state,
             status: "complete",
             pendingControllerTurns: [],
+            abandonedControllerTurns: [],
+            pendingCommandExecution: null,
             finalDeliveryText: payload.final_delivery_text,
         };
     }
@@ -151,14 +281,37 @@ export function reduceRunState(state, event) {
             ...state,
             status: "blocked",
             pendingControllerTurns: [],
+            abandonedControllerTurns: [],
+            pendingCommandExecution: null,
             blockedReason: payload.reason,
             finalDeliveryText: typeof payload.final_delivery_text === "string" ? payload.final_delivery_text : null,
         };
     }
+    if (event.type === "run_cancelled" && typeof payload.reason === "string") {
+        return {
+            ...state,
+            status: "cancelled",
+            pendingControllerTurns: [],
+            abandonedControllerTurns: [],
+            pendingCommandExecution: null,
+            cancelledReason: payload.reason,
+        };
+    }
     if (event.type === "run_failed") {
+        const failedRequestId = typeof payload.request_id === "string" ? payload.request_id : undefined;
+        const failedSubmissionState = payload.submission_state === "submitting" ||
+            payload.submission_state === "possibly_sent" ||
+            payload.submission_state === "submitted"
+            ? payload.submission_state
+            : undefined;
         return {
             ...state,
             status: "failed",
+            pendingControllerTurns: failedRequestId === undefined || failedSubmissionState === undefined
+                ? state.pendingControllerTurns ?? []
+                : (state.pendingControllerTurns ?? []).map((turn) => turn.requestId === failedRequestId
+                    ? { ...turn, submissionState: failedSubmissionState }
+                    : turn),
             lastFailure: {
                 code: typeof payload.code === "string" ? payload.code : "CUELINE_INTERNAL",
                 requestId: typeof payload.request_id === "string" ? payload.request_id : null,
@@ -166,6 +319,7 @@ export function reduceRunState(state, event) {
                 stage: typeof payload.stage === "string" ? payload.stage : null,
                 submissionState: payload.submission_state === "definitely_not_sent" ||
                     payload.submission_state === "requested" ||
+                    payload.submission_state === "submitting" ||
                     payload.submission_state === "possibly_sent" ||
                     payload.submission_state === "submitted"
                     ? payload.submission_state