@anchrd/intel-contract 0.13.0 → 0.15.0

package/dist/contract/flow-run.d.ts

@@ -0,0 +1,346 @@
+import { z } from "zod";
+export declare const FlowRunStatus: z.ZodEnum<{
+    queued: "queued";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+    cancelled: "cancelled";
+}>;
+export type FlowRunStatus = z.infer<typeof FlowRunStatus>;
+export declare const FlowRun: z.ZodObject<{
+    id: z.ZodString;
+    flowId: z.ZodString;
+    versionId: z.ZodString;
+    status: z.ZodEnum<{
+        queued: "queued";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>;
+    currentNodeId: z.ZodNullable<z.ZodString>;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    output: z.ZodNullable<z.ZodUnknown>;
+    error: z.ZodNullable<z.ZodString>;
+    initiatedBy: z.ZodString;
+    parentRunId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    parentNodeId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+    completedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type FlowRun = z.infer<typeof FlowRun>;
+export declare const FlowRunTrailEntry: z.ZodObject<{
+    runId: z.ZodString;
+    flowId: z.ZodString;
+    flowTitle: z.ZodString;
+    nodeId: z.ZodNullable<z.ZodString>;
+    nodeLabel: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type FlowRunTrailEntry = z.infer<typeof FlowRunTrailEntry>;
+export declare const FlowRunStep: z.ZodObject<{
+    run: z.ZodObject<{
+        id: z.ZodString;
+        flowId: z.ZodString;
+        versionId: z.ZodString;
+        status: z.ZodEnum<{
+            queued: "queued";
+            running: "running";
+            completed: "completed";
+            failed: "failed";
+            cancelled: "cancelled";
+        }>;
+        currentNodeId: z.ZodNullable<z.ZodString>;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        output: z.ZodNullable<z.ZodUnknown>;
+        error: z.ZodNullable<z.ZodString>;
+        initiatedBy: z.ZodString;
+        parentRunId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        parentNodeId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+        completedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>;
+    node: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"trigger">;
+        configuration: z.ZodObject<{
+            mode: z.ZodLiteral<"manual">;
+        }, z.core.$strict>;
+        id: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>;
+        label: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"instruction">;
+        configuration: z.ZodObject<{
+            prompt: z.ZodString;
+        }, z.core.$strict>;
+        id: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>;
+        label: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"folder">;
+        configuration: z.ZodObject<{
+            resourceId: z.ZodString;
+        }, z.core.$strict>;
+        id: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>;
+        label: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"document">;
+        configuration: z.ZodObject<{
+            resourceId: z.ZodString;
+        }, z.core.$strict>;
+        id: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>;
+        label: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"upload">;
+        configuration: z.ZodObject<{
+            resourceId: z.ZodString;
+        }, z.core.$strict>;
+        id: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>;
+        label: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"table">;
+        configuration: z.ZodObject<{
+            resourceId: z.ZodString;
+        }, z.core.$strict>;
+        id: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>;
+        label: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"tool">;
+        configuration: z.ZodObject<{
+            toolName: z.ZodString;
+            fingerprint: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strict>;
+        id: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>;
+        label: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"condition">;
+        configuration: z.ZodObject<{
+            mode: z.ZodLiteral<"semantic">;
+            instruction: z.ZodString;
+        }, z.core.$strict>;
+        id: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>;
+        label: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"subflow">;
+        configuration: z.ZodObject<{
+            flowId: z.ZodString;
+            version: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                mode: z.ZodLiteral<"latest">;
+            }, z.core.$strict>, z.ZodObject<{
+                mode: z.ZodLiteral<"follows">;
+            }, z.core.$strict>, z.ZodObject<{
+                mode: z.ZodLiteral<"pinned">;
+                versionId: z.ZodString;
+            }, z.core.$strict>], "mode">>;
+        }, z.core.$strict>;
+        id: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>;
+        label: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"output">;
+        configuration: z.ZodObject<{}, z.core.$strict>;
+        id: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>;
+        label: z.ZodString;
+    }, z.core.$strict>], "kind">>;
+    trail: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        runId: z.ZodString;
+        flowId: z.ZodString;
+        flowTitle: z.ZodString;
+        nodeId: z.ZodNullable<z.ZodString>;
+        nodeLabel: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type FlowRunStep = z.infer<typeof FlowRunStep>;
+export declare const StartFlowRunInput: z.ZodObject<{
+    flowId: z.ZodString;
+    input: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    parent: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        runId: z.ZodString;
+        nodeId: z.ZodString;
+    }, z.core.$strict>>>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type StartFlowRunInput = z.infer<typeof StartFlowRunInput>;
+export declare const GetFlowRunInput: z.ZodObject<{
+    runId: z.ZodString;
+}, z.core.$strict>;
+export type GetFlowRunInput = z.infer<typeof GetFlowRunInput>;
+export declare const CancelFlowRunInput: z.ZodObject<{
+    runId: z.ZodString;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type CancelFlowRunInput = z.infer<typeof CancelFlowRunInput>;
+export declare const CompleteFlowRunStepInput: z.ZodObject<{
+    runId: z.ZodString;
+    nodeId: z.ZodString;
+    outcome: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+    }>;
+    branch: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    output: z.ZodDefault<z.ZodNullable<z.ZodUnknown>>;
+    error: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type CompleteFlowRunStepInput = z.infer<typeof CompleteFlowRunStepInput>;
+export declare const FlowRunTrigger: z.ZodEnum<{
+    subflow: "subflow";
+    manual: "manual";
+}>;
+export type FlowRunTrigger = z.infer<typeof FlowRunTrigger>;
+export declare const FlowRunFailure: z.ZodObject<{
+    nodeId: z.ZodString;
+    nodeLabel: z.ZodString;
+    detail: z.ZodString;
+    calledRunId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type FlowRunFailure = z.infer<typeof FlowRunFailure>;
+export declare const FlowRunSummary: z.ZodObject<{
+    id: z.ZodString;
+    flowId: z.ZodString;
+    versionId: z.ZodString;
+    status: z.ZodEnum<{
+        queued: "queued";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>;
+    trigger: z.ZodEnum<{
+        subflow: "subflow";
+        manual: "manual";
+    }>;
+    startedAt: z.ZodISODateTime;
+    completedAt: z.ZodNullable<z.ZodISODateTime>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+    initiatedBy: z.ZodString;
+    parentRunId: z.ZodNullable<z.ZodString>;
+    failure: z.ZodNullable<z.ZodObject<{
+        nodeId: z.ZodString;
+        nodeLabel: z.ZodString;
+        detail: z.ZodString;
+        calledRunId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type FlowRunSummary = z.infer<typeof FlowRunSummary>;
+export declare const ListFlowRunsInput: z.ZodObject<{
+    flowId: z.ZodString;
+    failedOnly: z.ZodDefault<z.ZodBoolean>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    cursor: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type ListFlowRunsInput = z.infer<typeof ListFlowRunsInput>;
+export declare const FlowRunList: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        flowId: z.ZodString;
+        versionId: z.ZodString;
+        status: z.ZodEnum<{
+            queued: "queued";
+            running: "running";
+            completed: "completed";
+            failed: "failed";
+            cancelled: "cancelled";
+        }>;
+        trigger: z.ZodEnum<{
+            subflow: "subflow";
+            manual: "manual";
+        }>;
+        startedAt: z.ZodISODateTime;
+        completedAt: z.ZodNullable<z.ZodISODateTime>;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+        initiatedBy: z.ZodString;
+        parentRunId: z.ZodNullable<z.ZodString>;
+        failure: z.ZodNullable<z.ZodObject<{
+            nodeId: z.ZodString;
+            nodeLabel: z.ZodString;
+            detail: z.ZodString;
+            calledRunId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type FlowRunList = z.infer<typeof FlowRunList>;
+export declare const FlowRunStepRecord: z.ZodObject<{
+    nodeId: z.ZodString;
+    nodeLabel: z.ZodString;
+    outcome: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+    }>;
+    branch: z.ZodNullable<z.ZodString>;
+    detail: z.ZodNullable<z.ZodString>;
+    calledRunId: z.ZodNullable<z.ZodString>;
+    completedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type FlowRunStepRecord = z.infer<typeof FlowRunStepRecord>;
+export declare const FlowRunHistory: z.ZodObject<{
+    runId: z.ZodString;
+    flowId: z.ZodString;
+    status: z.ZodEnum<{
+        queued: "queued";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>;
+    steps: z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        nodeLabel: z.ZodString;
+        outcome: z.ZodEnum<{
+            completed: "completed";
+            failed: "failed";
+        }>;
+        branch: z.ZodNullable<z.ZodString>;
+        detail: z.ZodNullable<z.ZodString>;
+        calledRunId: z.ZodNullable<z.ZodString>;
+        completedAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    trail: z.ZodArray<z.ZodObject<{
+        runId: z.ZodString;
+        flowId: z.ZodString;
+        flowTitle: z.ZodString;
+        nodeId: z.ZodNullable<z.ZodString>;
+        nodeLabel: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type FlowRunHistory = z.infer<typeof FlowRunHistory>;

package/dist/contract/flow-run.js

@@ -0,0 +1,181 @@
+import { z } from "zod";
+import { IdempotencyKey, IntelId, IsoDateTime } from "./contract.js";
+import { FlowNode, FlowNodeId } from "./flow.js";
+// ⚠️ No `waiting`. It was written for the approval node and never set by anything — the two places
+// that tested for it only ever saw `running` (#73). The column's CHECK constraint still allows the
+// value, deliberately: rewriting it means rebuilding the table in D1 for a value nothing writes,
+// and migration 0007 turns any row that somehow carries it into `failed` rather than leave a status
+// the contract cannot parse.
+export const FlowRunStatus = z.enum(["queued", "running", "completed", "failed", "cancelled"]);
+export const FlowRun = z.strictObject({
+    id: IntelId,
+    flowId: IntelId,
+    versionId: IntelId,
+    status: FlowRunStatus,
+    currentNodeId: FlowNodeId.nullable(),
+    input: z.record(z.string(), z.unknown()),
+    output: z.unknown().nullable(),
+    error: z.string().max(2_000).nullable(),
+    initiatedBy: IntelId,
+    // The subflow node this run was called from, and the run that node belongs to. A called run is a
+    // run of its own: it has its own version, its own steps and its own authorization, and only these
+    // two fields say where its result goes back to.
+    parentRunId: IntelId.nullable().default(null),
+    parentNodeId: FlowNodeId.nullable().default(null),
+    createdAt: IsoDateTime,
+    updatedAt: IsoDateTime,
+    completedAt: IsoDateTime.nullable(),
+});
+// Which step of which flow is running, outermost caller first. Readable rather than reconstructed
+// from `parentRunId` by whoever is looking (#17).
+export const FlowRunTrailEntry = z.strictObject({
+    runId: IntelId,
+    flowId: IntelId,
+    flowTitle: z.string().min(1).max(240),
+    nodeId: FlowNodeId.nullable(),
+    nodeLabel: z.string().max(160).nullable(),
+});
+export const FlowRunStep = z.strictObject({
+    run: FlowRun,
+    node: FlowNode.nullable(),
+    trail: z.array(FlowRunTrailEntry).default([]),
+});
+export const StartFlowRunInput = z.strictObject({
+    flowId: IntelId.describe("Flow to run. It has to be published; the run takes the published version, not the newest one."),
+    input: z
+        .record(z.string(), z.unknown())
+        .default({})
+        .describe("The values the flow's trigger node declares. An empty object is right for a flow that asks for nothing."),
+    // Present when this run is the call a subflow node makes. It names a place, never a permission:
+    // the callee's `execute` is asked of the user exactly as it is for a run they start themselves,
+    // and the parent run must be the caller's own and standing on that very node.
+    parent: z
+        .strictObject({
+        runId: IntelId.describe("The calling run."),
+        nodeId: FlowNodeId.describe("The subflow node in that run which is making the call."),
+    })
+        .nullable()
+        .default(null)
+        .describe("Leave at `null`. It is set only when a subflow node makes this call, and it names a place rather than a permission: the callee's `execute` is still asked of the user."),
+    idempotencyKey: IdempotencyKey,
+});
+export const GetFlowRunInput = z.strictObject({
+    runId: IntelId.describe("Run to read. A run has an address of its own because it outlives its flow; the id comes from flow_run_start or flow_run_list."),
+});
+// Ending a run on purpose (#145). Until this existed the only way off a parked manual step was
+// `completeStep` with `outcome: "failed"` — which recorded a step failure that never happened.
+// Cancelling records nothing into the step history: the run ends, the history stays true.
+export const CancelFlowRunInput = z.strictObject({
+    runId: IntelId.describe("Run to end on purpose. This is the way off a run parked on a manual step — it records nothing into the step history, unlike completing the step as `failed`, which would report a failure that never happened."),
+    idempotencyKey: IdempotencyKey,
+});
+export const CompleteFlowRunStepInput = z.strictObject({
+    runId: IntelId.describe("Run that is waiting."),
+    nodeId: FlowNodeId.describe("The node the run is standing on, from flow_run_get. Answering any other node is refused: this completes the step that is waiting, not a step of one's choosing."),
+    outcome: z
+        .enum(["completed", "failed"])
+        .describe("Whether the step is done or could not be done. `failed` ends the run at this node."),
+    branch: z
+        .string()
+        .min(1)
+        .max(120)
+        .nullable()
+        .default(null)
+        .describe("Which way out of a branching node the run takes, by the label on the edge. `null` for a node with one way out."),
+    output: z
+        .unknown()
+        .nullable()
+        .default(null)
+        .describe("What the step produced, for the nodes after it to read. `null` when it produced nothing."),
+    error: z
+        .string()
+        .max(2_000)
+        .nullable()
+        .default(null)
+        .describe('Why it could not be done. Belongs with `outcome: "failed"` and is what the run\'s failure will say.'),
+    idempotencyKey: IdempotencyKey,
+});
+// Why a run started. Derived when it is read and deliberately not a column: `subflow` when the run
+// is the call another run made, otherwise the mode of the trigger node in the immutable version the
+// run took. A stored copy would be a second answer that could disagree with the graph that ran.
+//
+// ⚠️ `webhook` and `schedule` stood here until #39 took them out of the trigger node. Being derived
+// rather than stored is exactly what makes that safe: no run carries a trigger of its own, so once
+// the 0005 migration has rewritten every stored trigger to `manual`, there is nowhere left for the
+// old values to come from. Had this been a column, the enum would have had to keep reading them or
+// every old run would have failed to parse the moment somebody opened the list.
+export const FlowRunTrigger = z.enum(["manual", "subflow"]);
+// Which step ended a run, and why, in the words the failure already used (#20).
+//
+// ⚠️ A call that failed carries its reason in the *called* run, and that run is a run of its own
+// with its own authorization. `calledRunId` is therefore filled only when the asking user may see
+// that run through the very rule every other run answer uses; otherwise the failure is named by the
+// calling step alone — the caller's own label — and `detail` says no more than that it did not
+// finish. Naming a callee's step or document here would be the leak #17, #19 and #20 each closed.
+export const FlowRunFailure = z.strictObject({
+    nodeId: FlowNodeId,
+    nodeLabel: z.string().max(160),
+    detail: z.string().max(2_000),
+    calledRunId: IntelId.nullable(),
+});
+// One run as a list shows it: what it did, never what it produced.
+//
+// ⚠️ Neither `input` nor `output` is in here, on purpose. A run reaches its nodes and its tools
+// with the rights of whoever started it, so its result is a way to content the next reader of this
+// list may have no claim to. Whoever wants a result asks for the run itself, where the same rule
+// decides again.
+export const FlowRunSummary = z.strictObject({
+    id: IntelId,
+    flowId: IntelId,
+    // The version the run took. Together with the run's stored input it is what a later "run this
+    // again with the old data" would need; replaying is a separate ticket, this only keeps it possible.
+    versionId: IntelId,
+    status: FlowRunStatus,
+    trigger: FlowRunTrigger,
+    startedAt: IsoDateTime,
+    completedAt: IsoDateTime.nullable(),
+    durationMs: z.number().int().nonnegative().nullable(),
+    initiatedBy: IntelId,
+    parentRunId: IntelId.nullable(),
+    failure: FlowRunFailure.nullable(),
+});
+// One filter and nothing else: "only the failed ones" is the question asked in almost every case,
+// and every further facet is a report rather than a search for a fault.
+export const ListFlowRunsInput = z.strictObject({
+    flowId: IntelId.describe("Flow whose runs to list, newest first."),
+    failedOnly: z.boolean().default(false).describe("List only the runs that failed."),
+    limit: z.number().int().min(1).max(50).default(20).describe("How many runs per page."),
+    // The `nextCursor` of the previous page. Keyset rather than an offset, because runs arrive while
+    // someone reads and an offset would skip or repeat rows exactly when a flow is busy.
+    cursor: z
+        .string()
+        .min(1)
+        .max(400)
+        .nullable()
+        .default(null)
+        .describe("The `nextCursor` of the previous page, or `null` for the first. It is a keyset rather than an offset, so runs arriving while someone reads neither skip nor repeat a row."),
+});
+export const FlowRunList = z.strictObject({
+    items: z.array(FlowRunSummary),
+    nextCursor: z.string().max(400).nullable(),
+});
+// One completed step of one run. `detail` is the step's own error text; an output is absent for the
+// same reason it is absent from the summary.
+export const FlowRunStepRecord = z.strictObject({
+    nodeId: FlowNodeId,
+    nodeLabel: z.string().max(160),
+    outcome: z.enum(["completed", "failed"]),
+    branch: z.string().max(120).nullable(),
+    detail: z.string().max(2_000).nullable(),
+    calledRunId: IntelId.nullable(),
+    completedAt: IsoDateTime,
+});
+// What one run did, step by step, oldest first, with the call chain it belongs to (#17). The trail
+// is what makes a nested run readable: which step of which flow this run is.
+export const FlowRunHistory = z.strictObject({
+    runId: IntelId,
+    flowId: IntelId,
+    status: FlowRunStatus,
+    steps: z.array(FlowRunStepRecord),
+    trail: z.array(FlowRunTrailEntry),
+});