@anchrd/intel-api 0.6.4 → 0.6.5

package/dist/adapters/cloudflare/cloudflare-flow-workflow.d.ts

@@ -15,6 +15,27 @@ interface FlowWorkflowParams {
 interface IntelFlowWorkflowInstance {
     run(event: Readonly<WorkflowEvent<FlowWorkflowParams>>, step: WorkflowStep): Promise<unknown>;
 }
+/**
+ * What the durable wait actually does, with storage handed in.
+ *
+ * ⚠️ Separated from the class because `WorkflowEntrypoint` is a runtime class that cannot be
+ * constructed outside workerd's workflow context — so as long as this logic lived inside it, none
+ * of it could be tested, including the rule that keeps a caller alive while its child runs. That
+ * rule is the one that decides whether this feature destroys work or not, and it had to be
+ * provable. The shell below is now only bindings and SQL, which is what `CLAUDE.md` asks of it.
+ */
+export declare function driveFlowRun(step: WorkflowStep, deps: {
+    readStatus(): Promise<{
+        status: string;
+        error: string | null;
+    }>;
+    hasRunningChild(): Promise<boolean>;
+    markFailed(error: string): Promise<void>;
+    stallTimeout: string;
+}): Promise<{
+    status: string;
+    error: string | null;
+}>;
 export declare const IntelFlowWorkflow: {
     new (context: unknown, env: CloudflareEnv): IntelFlowWorkflowInstance;
 };

package/dist/adapters/cloudflare/cloudflare-flow-workflow.js

@@ -3,37 +3,87 @@
 import { WorkflowEntrypoint as RuntimeWorkflowEntrypoint } from "cloudflare:workers";
 class WorkflowEntrypoint extends RuntimeWorkflowEntrypoint {
 }
+/**
+ * How long a run may stand on one step before nobody is working on it any more (#83).
+ *
+ * ⚠️ This is a product decision and not a constant somebody may tune while reading the code. Too
+ * short is worse than the problem it fixes: it ends runs that were only slow, which destroys work
+ * instead of merely displaying it wrongly. 30 minutes covers a large document, a sluggish API and
+ * a person who walks away from an approval; it does not cover a tab that was closed yesterday.
+ *
+ * The deployment may override it with `FLOW_RUN_STALL_TIMEOUT` (a Workflows duration, e.g. "2
+ * hours"), which is what makes the figure readable in operation rather than buried here.
+ */
+const DefaultStallTimeout = "30 minutes";
+/**
+ * What the durable wait actually does, with storage handed in.
+ *
+ * ⚠️ Separated from the class because `WorkflowEntrypoint` is a runtime class that cannot be
+ * constructed outside workerd's workflow context — so as long as this logic lived inside it, none
+ * of it could be tested, including the rule that keeps a caller alive while its child runs. That
+ * rule is the one that decides whether this feature destroys work or not, and it had to be
+ * provable. The shell below is now only bindings and SQL, which is what `CLAUDE.md` asks of it.
+ */
+export async function driveFlowRun(step, deps) {
+    const fail = async (name, error) => await step.do(name, async () => {
+        await deps.markFailed(error);
+        return { status: "failed", error };
+    });
+    for (let iteration = 0; iteration < 500; iteration += 1) {
+        const state = await step.do(`inspect flow run ${iteration}`, async () => await deps.readStatus());
+        if (["completed", "failed", "cancelled"].includes(state.status))
+            return state;
+        try {
+            await step.waitForEvent(`wait for flow run ${iteration}`, {
+                type: "advance",
+                // ⚠️ The clock starts HERE, which is what makes it "since the last step" rather than "since
+                // the run began": every `advance` returns to the top of the loop and waits anew. A flow
+                // with one genuinely long step is measured against that step, not against its total length.
+                timeout: deps.stallTimeout,
+            });
+        }
+        catch {
+            // ⚠️ A caller standing on a sub-flow node looks exactly like a run nobody is working on — it
+            // is waiting, by design, for the called run to finish. Ending it here would tear down a
+            // caller because its child was slow, which is the one way this fix could destroy work rather
+            // than merely display it wrongly. So the timeout asks first, and waits again if a child is
+            // still going.
+            const waiting = await step.do(`check called run ${iteration}`, async () => await deps.hasRunningChild());
+            if (waiting)
+                continue;
+            return await fail(`expire flow run ${iteration}`, "Nothing has moved this run forward, so it was ended. Whatever was running it stopped without reporting a result — start it again if it is still needed.");
+        }
+    }
+    return await fail("fail flow step limit", "Flow exceeded the maximum durable step count");
+}
 class IntelFlowWorkflowImplementation extends WorkflowEntrypoint {
     async run(event, step) {
-        const fail = async (name, error) => await step.do(name, async () => {
-            const occurredAt = new Date().toISOString();
-            await this.env.DB.prepare(`UPDATE flow_runs
-          SET status = 'failed', error = ?, completed_at = ?, updated_at = ?
-          WHERE id = ? AND status NOT IN ('completed', 'failed', 'cancelled')`)
-                .bind(error, occurredAt, occurredAt, event.payload.runId)
-                .run();
-            return { status: "failed", error };
-        });
-        for (let iteration = 0; iteration < 500; iteration += 1) {
-            const state = await step.do(`inspect flow run ${iteration}`, async () => {
+        const runId = event.payload.runId;
+        return await driveFlowRun(step, {
+            readStatus: async () => {
                 const row = await this.env.DB.prepare("SELECT status, error FROM flow_runs WHERE id = ?")
-                    .bind(event.payload.runId)
+                    .bind(runId)
                     .first();
                 return row ?? { status: "failed", error: "Flow run disappeared" };
-            });
-            if (["completed", "failed", "cancelled"].includes(state.status))
-                return state;
-            try {
-                await step.waitForEvent(`wait for flow run ${iteration}`, {
-                    type: "advance",
-                    timeout: "365 days",
-                });
-            }
-            catch {
-                return await fail(`expire flow run ${iteration}`, "Flow run timed out waiting for progress");
-            }
-        }
-        return await fail("fail flow step limit", "Flow exceeded the maximum durable step count");
+            },
+            hasRunningChild: async () => {
+                const row = await this.env.DB.prepare(`SELECT id FROM flow_runs
+          WHERE parent_run_id = ? AND status IN ('queued', 'running')
+          LIMIT 1`)
+                    .bind(runId)
+                    .first();
+                return row !== null;
+            },
+            markFailed: async (error) => {
+                const occurredAt = new Date().toISOString();
+                await this.env.DB.prepare(`UPDATE flow_runs
+          SET status = 'failed', error = ?, completed_at = ?, updated_at = ?
+          WHERE id = ? AND status NOT IN ('completed', 'failed', 'cancelled')`)
+                    .bind(error, occurredAt, occurredAt, runId)
+                    .run();
+            },
+            stallTimeout: this.env.FLOW_RUN_STALL_TIMEOUT || DefaultStallTimeout,
+        });
     }
 }
 export const IntelFlowWorkflow = IntelFlowWorkflowImplementation;

package/dist/adapters/cloudflare/cloudflare.types.d.ts

@@ -22,6 +22,7 @@ export interface CloudflareEnv {
     TOOL_SOURCE_ORIGINS: string;
     MCP_PORTAL_URL?: string;
     ALLOW_INSECURE_OAUTH?: string;
+    FLOW_RUN_STALL_TIMEOUT?: string;
 }
 export interface CloudflareExecutionContext {
     waitUntil(promise: Promise<unknown>): void;

package/dist/flows/flows.js

@@ -320,9 +320,26 @@ export function createFlows(deps) {
             .filter(([, callees]) => callees.some((callee) => reachable.has(callee)))
             .map(([flowId]) => flowId);
     }
-    async function requireRunnableFlow(actor, flowId) {
+    /**
+     * The flow a run already belongs to, as this actor may see it.
+     *
+     * ⚠️ The same ACL as `requireRunnableFlow` and deliberately without its archived refusal. This is
+     * the answer to "what should archiving do to a run in flight" (#112): archiving decides what may
+     * be STARTED, never what happens to what is already going. The other reading — refusing here —
+     * is what produced the state that ticket was written about: the step was recorded and the caller
+     * was told 404, with no way to read the run afterwards to find out otherwise.
+     */
+    async function requireStartedFlow(actor, flowId) {
         const flow = await deps.repository.getCallable(actor, flowId);
-        if (!flow || flow.archivedAt)
+        if (!flow)
+            throw new IntelError(404, "flow_not_found", "Flow was not found");
+        return flow;
+    }
+    // The same flow for something that is about to START — a run, a validation. An archived flow is
+    // absent here, which is the whole of what archiving does.
+    async function requireRunnableFlow(actor, flowId) {
+        const flow = await requireStartedFlow(actor, flowId);
+        if (flow.archivedAt)
             throw new IntelError(404, "flow_not_found", "Flow was not found");
         return flow;
     }
@@ -569,13 +586,33 @@ export function createFlows(deps) {
         const found = await deps.repository.visibleCallRuns(actor, sites);
         return new Map(found.map((call) => [callKey(call.runId, call.nodeId), call.calledRunId]));
     }
-    async function step(actor, run) {
-        await requireRunnableFlow(actor, run.flowId);
-        const version = await requireVersion(run.versionId, run.flowId);
+    /**
+     * What a run looks like right now: the run as this actor may read it, the node it stands on, and
+     * the trail it belongs to. Data only — it asks nothing.
+     *
+     * ⚠️ Split out of `step` because of the order this used to be in (#112). `completeStep` writes
+     * the step and then shapes its answer, and shaping used to authorize a second time — so a check
+     * that failed AFTER the write told the caller "404" about work that had happened, and the retry
+     * replayed into the same 404 forever. Whoever just completed a step may be told what became of
+     * it. Whether they may run the NEXT one is asked when they run it, by the call that runs it.
+     *
+     * `narrowed` stays: it decides how much of a failure's text this reader may see, which is
+     * disclosure and not permission.
+     */
+    // ⚠️ The version is passed in rather than looked up. Both callers already hold it, and reading it
+    // again here cost one extra round trip per answer — which the query-count test caught (#30).
+    async function runState(actor, run, version) {
         const node = nodeFor(version, run.currentNodeId);
-        await requireNodeAuthorized(actor, node, version.graph);
         return { run: await narrowed(actor, run, version), node, trail: await trailFor(run, version) };
     }
+    // The same picture for somebody ASKING for it rather than having just acted: the flow has to
+    // resolve and the node they would be handed has to be one they may execute.
+    async function step(actor, run) {
+        await requireStartedFlow(actor, run.flowId);
+        const version = await requireVersion(run.versionId, run.flowId);
+        await requireNodeAuthorized(actor, nodeFor(version, run.currentNodeId), version.graph);
+        return await runState(actor, run, version);
+    }
     // A failed run carries the text of the step that failed, and for a call that text came out of
     // another run. It is narrowed here rather than at the door it entered through: what storage keeps
     // is what happened, and who may read it is a question about the person asking, not about the row.
@@ -1328,7 +1365,9 @@ export function createFlows(deps) {
          * and no output, because a run reaches Knowledge and tools with the rights of whoever started it.
          */
         async listRuns(actor, input) {
-            const flow = await requireRunnableFlow(actor, input.flowId);
+            // The history of a flow that has since been archived stays readable — the runs happened, and
+            // archiving is about what may start next (#112).
+            const flow = await requireStartedFlow(actor, input.flowId);
             // One row beyond the page: it answers "is there more" and is dropped rather than shown, so a
             // count over the whole table is never needed to draw a "next" affordance.
             const rows = await deps.repository.listRunsVisible(actor, {
@@ -1556,7 +1595,9 @@ export function createFlows(deps) {
                 throw new IntelError(409, "flow_step_conflict", "Flow step was already completed");
             }
             await deps.runtime.signal(next.id);
-            return await step(actor, next);
+            // ⚠️ `runState`, not `step`: the write above has happened. Asking again here is what turned a
+            // completed step into a 404 for the caller (#112).
+            return await runState(actor, next, version);
         },
     };
 }

package/migrations/0010_no_run_waits_a_year.sql

@@ -0,0 +1,27 @@
+-- Runs that nobody is carrying forward, ended (#83).
+--
+-- The workflow used to wait `365 days` for the next step to be reported, so a run whose agent
+-- stopped — context full, tab closed, session over — stood as "running" for a year and was
+-- indistinguishable from one that really was running. The wait is now the stall timeout; this
+-- clears the ones that were left behind before it existed.
+--
+-- ⚠️ The cut-off is deliberately far past the new timeout rather than equal to it. This runs once,
+-- against rows whose `updated_at` is whatever it happened to be, and a run that is genuinely mid-
+-- step when the migration is applied must not be swept up. A day is long enough that anything
+-- older stopped for good; anything younger is left to the timeout, which measures properly.
+--
+-- ⚠️ `parent_run_id IS NULL OR the child is finished`: a caller standing on a sub-flow node looks
+-- exactly like a stalled run. Ending a caller whose child is still going is the one way this could
+-- destroy work, and it is the same rule the workflow applies at its timeout.
+UPDATE flow_runs
+SET status = 'failed',
+    error = 'Nothing has moved this run forward, so it was ended. Whatever was running it stopped without reporting a result — start it again if it is still needed.',
+    completed_at = datetime('now'),
+    updated_at = datetime('now')
+WHERE status IN ('queued', 'running')
+  AND updated_at < datetime('now', '-1 day')
+  AND NOT EXISTS (
+    SELECT 1 FROM flow_runs child
+    WHERE child.parent_run_id = flow_runs.id
+      AND child.status IN ('queued', 'running')
+  );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {