@anchrd/intel-api 0.6.3 → 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/adapters/db/db-flows.js

@@ -122,15 +122,15 @@ export function createFlowRepository(deps) {
      * same reason `COUNT(*) OVER ()` is a count of those rows alone — the number the graph reports
      * about its own size would otherwise disclose that something else is there.
      */
-    const visibleFlows = (scopeClause, bounded) => `${subtreeCte}
+    const visibleFlows = (scopeClause, bounded, includeArchived = false) => `${subtreeCte}
     SELECT ${flowColumns}${bounded ? ", COUNT(*) OVER () AS total" : ""} FROM flows flow
-    WHERE ${flowInSubtree} AND flow.archived_at IS NULL ${scopeClause}
+    WHERE ${flowInSubtree} ${includeArchived ? "" : "AND flow.archived_at IS NULL"} ${scopeClause}
     ORDER BY lower(flow.title), flow.id${bounded ? " LIMIT ?" : ""}`;
     return {
         async listVisible(actor, input = {}) {
             const scope = scopeOf(input.parentId);
             const result = await deps.db
-                .prepare(visibleFlows(scope.clause, false))
+                .prepare(visibleFlows(scope.clause, false, input.includeArchived === true))
                 .bind(...readableBindings(actor), ...flowInSubtreeBindings(actor), ...scope.bindings)
                 .all();
             return (result.results ?? []).map(mapFlow);
@@ -388,6 +388,55 @@ export function createFlowRepository(deps) {
                 .first();
             return row ? mapFlow(row) : "conflict";
         },
+        // Archiving and restoring are one statement, told apart only by whether `archived_at` is a
+        // timestamp or null. Like `updateFlow` it writes the flow row alone: an archived flow keeps its
+        // versions and its published version, because coming back out of the archive has to return the
+        // flow that went in.
+        //
+        // ⚠️ The idempotency row is written only if the UPDATE actually matched — same guard as
+        // `knowledge.archive` — so a stale `baseUpdatedAt` leaves no key behind that would make the
+        // retry of a *lost* write look like a replay of a successful one.
+        async archiveFlow(input) {
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`UPDATE flows SET archived_at = ?, updated_at = ?
+              WHERE id = ? AND updated_at = ?`)
+                        .bind(input.archivedAt, input.updatedAt, input.flowId, input.baseUpdatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.archive', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM flows WHERE id = ? AND archived_at IS ? AND updated_at = ?
+            )`)
+                        .bind(input.actorId, input.idempotencyKey, input.flowId, input.updatedAt, input.flowId, input.archivedAt, input.updatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.archive', 'flow', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'flows.archive'
+                AND idempotency_key = ? AND resource_id = ?
+            )`)
+                        .bind(input.auditId, input.actorId, input.flowId, JSON.stringify({ archived: input.archivedAt !== null }), input.updatedAt, input.actorId, input.idempotencyKey, input.flowId),
+                ]);
+            }
+            catch (error) {
+                if (!(await this.findIdempotent(input.actorId, "flows.archive", input.idempotencyKey))) {
+                    throw error;
+                }
+            }
+            const replayed = await this.findIdempotent(input.actorId, "flows.archive", input.idempotencyKey);
+            if (!replayed)
+                return "conflict";
+            const row = await deps.db
+                .prepare(`SELECT ${flowColumns} FROM flows WHERE id = ?`)
+                .bind(replayed)
+                .first();
+            return row ? mapFlow(row) : "conflict";
+        },
         // Versions are immutable, so a set of them is a single read by definition: the trail of a nested
         // run needs one per level and the relation graph one per flow it draws, and both used to ask
         // level by level (#30). Missing IDs are simply absent from the answer.

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.
@@ -1053,6 +1090,56 @@ export function createFlows(deps) {
             }
             return updated;
         },
+        /**
+         * Archive a flow, or take it back out again.
+         *
+         * ⚠️ The one place that resolves the flow through `getVisible` instead of `requireFlow`. Every
+         * other entry point treats an archived flow as absent — that is the whole point of archiving —
+         * but the call that restores one has to be able to find it, and `requireFlow` answers 404 for
+         * exactly the rows this call exists for. The visibility predicate is the same one; only the
+         * `archivedAt` refusal is left out.
+         *
+         * `write` and nothing more, asked before the row is touched: archiving is organization, the same
+         * grant that renames and moves (ADR-0004). It appends no version and withdraws no publication.
+         *
+         * ⚠️ It does NOT leave runs in flight alone, however much the word "archive" suggests it would.
+         * `completeStep` writes before it shapes its answer: the step is recorded, and `step()` then
+         * resolves the flow and throws 404 for the archived one. The caller is told the step failed
+         * while storage has it done, and a retry replays into the same 404. Restoring the flow is what
+         * makes the run readable again. That belongs to the run machine and has its own ticket
+         * (issue 112) — archiving is only the easiest way to walk into it.
+         */
+        async archive(actor, input) {
+            const current = await deps.repository.getVisible(actor, input.flowId);
+            if (!current)
+                throw new IntelError(404, "flow_not_found", "Flow was not found");
+            if (!(await deps.repository.can(actor, input.flowId, "write"))) {
+                throw new IntelError(403, "flow_edit_forbidden", "Flow cannot be edited");
+            }
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.archive", input.idempotencyKey);
+            // Read back the way this call reads anything, or replaying an archive would 404 on the row it
+            // just archived.
+            if (replayed) {
+                const flow = await deps.repository.getVisible(actor, replayed);
+                if (!flow)
+                    throw new IntelError(404, "flow_not_found", "Flow was not found");
+                return flow;
+            }
+            const updatedAt = deps.now().toISOString();
+            const updated = await deps.repository.archiveFlow({
+                flowId: current.id,
+                baseUpdatedAt: input.baseUpdatedAt,
+                archivedAt: input.archived ? updatedAt : null,
+                updatedAt,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (updated === "conflict") {
+                throw new IntelError(409, "flow_update_conflict", "Flow was changed by another editor");
+            }
+            return updated;
+        },
         async save(actor, input) {
             const replayed = await deps.repository.findIdempotent(actor.id, "flows.save", input.idempotencyKey);
             if (replayed) {
@@ -1278,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, {
@@ -1506,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/dist/flows/flows.types.d.ts

@@ -1,4 +1,4 @@
-import type { CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowPublishPreview, FlowRequirements, FlowRun, FlowRunHistory, FlowRunList, FlowRunStep, FlowValidation, FlowVersion, KnowledgeNode, ListFlowRunsInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraph, RelationGraphInput, ResourceVerb, SaveFlowVersionInput, StartFlowRunInput, UpdateFlowInput } from "@anchrd/intel-contract";
+import type { ArchiveFlowInput, CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowPublishPreview, FlowRequirements, FlowRun, FlowRunHistory, FlowRunList, FlowRunStep, FlowValidation, FlowVersion, KnowledgeNode, ListFlowRunsInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraph, RelationGraphInput, ResourceVerb, SaveFlowVersionInput, StartFlowRunInput, UpdateFlowInput } from "@anchrd/intel-contract";
 export type FlowPrincipal = Pick<FlowActor, "id" | "email" | "isAdmin">;
 export type FlowCallReach = "subtree" | "library" | "out-of-reach";
 export interface FlowRunChainEntry {
@@ -40,7 +40,7 @@ export interface FlowActor {
     isAdmin?: boolean;
 }
 export type FlowVerb = Extract<ResourceVerb, "read" | "write" | "execute">;
-export type FlowOperation = "flows.create" | "flows.update" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete";
+export type FlowOperation = "flows.create" | "flows.update" | "flows.archive" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete";
 export interface BoundedLevel<T> {
     items: T[];
     total: number;
@@ -76,6 +76,15 @@ export interface FlowRepository {
         idempotencyKey: string;
         auditId: string;
     }): Promise<"conflict" | Flow>;
+    archiveFlow(input: {
+        flowId: string;
+        baseUpdatedAt: string;
+        archivedAt: string | null;
+        updatedAt: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"conflict" | Flow>;
     getVersion(versionId: string): Promise<FlowVersion | null>;
     getVersions(versionIds: string[]): Promise<FlowVersion[]>;
     insertVersion(input: {
@@ -169,6 +178,7 @@ export interface FlowService {
     listRequirements(actor: FlowActor, flowId: string): Promise<FlowRequirements>;
     create(actor: FlowActor, input: CreateFlowInput): Promise<Flow>;
     update(actor: FlowActor, input: UpdateFlowInput): Promise<Flow>;
+    archive(actor: FlowActor, input: ArchiveFlowInput): Promise<Flow>;
     save(actor: FlowActor, input: SaveFlowVersionInput): Promise<FlowDocument>;
     previewPublish(actor: FlowActor, input: PreviewFlowPublishInput): Promise<FlowPublishPreview>;
     publish(actor: FlowActor, input: PublishFlowInput): Promise<Flow>;

package/dist/http/http.js

@@ -1,4 +1,4 @@
-import { AppendKnowledgeTableRowsInput, ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeNodeInput, DefineKnowledgeTableInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, KnowledgeGraphInput, ListFlowRunsInput, ListFlowsInput, ListKnowledgeNodesInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, ResolveKnowledgeLinksInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
+import { AppendKnowledgeTableRowsInput, ArchiveFlowInput, ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeNodeInput, DefineKnowledgeTableInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, KnowledgeGraphInput, ListFlowRunsInput, ListFlowsInput, ListKnowledgeNodesInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, ResolveKnowledgeLinksInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
 import { Hono } from "hono";
 import { z } from "zod";
 import { authorizeBearer, bearer, permits, } from "../shared/gate-authorization/gate-authorization.js";
@@ -250,11 +250,16 @@ export function createHttp(deps) {
     app.get("/flows", async (context) => {
         const auth = requireCapability(context, "flows", "read");
         const url = new URL(context.req.url);
-        requireKnownQuery(url, ["parentId"]);
+        requireKnownQuery(url, ["parentId", "includeArchived"]);
         // Absent means "every flow I may see"; present but empty means the root of the shared tree.
         // Without that distinction a tree level and a full list would be the same request.
         const parentId = url.searchParams.get("parentId");
-        const input = ListFlowsInput.parse(url.searchParams.has("parentId") ? { parentId: parentId === "" ? null : parentId } : {});
+        // Same rule for the archive: absent means "without it". Spelling the default out would put a
+        // field into every call that asks nothing about the archive.
+        const input = ListFlowsInput.parse({
+            ...(url.searchParams.has("parentId") ? { parentId: parentId === "" ? null : parentId } : {}),
+            ...(url.searchParams.get("includeArchived") === "true" ? { includeArchived: true } : {}),
+        });
         return context.json(await deps.flows.list(asFlowActor(auth), input));
     });
     // ⚠️ Before `/flows/:flowId`, or the router would read "graph" as a flow ID. Same order and same
@@ -318,6 +323,16 @@ export function createHttp(deps) {
         }
         return context.json(await deps.flows.update(asFlowActor(auth), input));
     });
+    // `flows/write`, the same capability renaming and moving need: archiving is organization, not a
+    // change to what the flow does.
+    app.post("/flows/:flowId/archive", async (context) => {
+        const auth = requireCapability(context, "flows", "write");
+        const input = ArchiveFlowInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.archive(asFlowActor(auth), input));
+    });
     app.post("/flows/:flowId/versions", async (context) => {
         const auth = requireCapability(context, "flows", "write");
         const input = SaveFlowVersionInput.parse(await context.req.json().catch(() => null));

package/dist/mcp/mcp.js

@@ -1,4 +1,4 @@
-import { AppendKnowledgeTableRowsInput, ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeNodeInput, DefineKnowledgeTableInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetKnowledgeNodeInput, GetKnowledgeTableInput, KnowledgeGraphInput, ListFlowRunsInput, ListFlowsInput, ListKnowledgeGrantsInput, ListKnowledgeNodesInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, ResolveKnowledgeLinksInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
+import { AppendKnowledgeTableRowsInput, ArchiveFlowInput, ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeNodeInput, DefineKnowledgeTableInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetKnowledgeNodeInput, GetKnowledgeTableInput, KnowledgeGraphInput, ListFlowRunsInput, ListFlowsInput, ListKnowledgeGrantsInput, ListKnowledgeNodesInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, ResolveKnowledgeLinksInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod";
@@ -473,6 +473,20 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.flows.update(flowActor, input)));
+        server.registerTool("flow_archive", {
+            title: "Archive flow",
+            description: "Archive or restore one flow using optimistic concurrency. An archived flow keeps its versions but can no longer be opened, started, or called by another flow.",
+            inputSchema: ArchiveFlowInput,
+            annotations: {
+                title: "Archive flow",
+                readOnlyHint: false,
+                // What it takes away is reach, not content: nothing is deleted and `archived: false` puts
+                // it back. Destructive all the same, because a flow another flow calls stops resolving.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.archive(flowActor, input)));
         server.registerTool("flow_save", {
             title: "Save flow",
             description: "Append a validated immutable flow graph version with optimistic concurrency.",

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.3",
+  "version": "0.6.5",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {