@retinue/agentkit 0.1.0

package/dist/files/turn-parts.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Turning stored attachments into turn parts — REQ-036 (#185), AC-3.
+ *
+ * `TurnContentPart` carries bytes or a URL, never a platform file id: the SDK boundary knows nothing about the
+ * file store. Something has to bridge the two, and that something is the place where a modality bridge either
+ * respects file authorization or quietly becomes a way around it.
+ *
+ * So this reads through `FileService` — the same call `read_attachment` makes, not the stores underneath it.
+ * Entitlement, existence and state all come from the service, so a turn cannot carry a file the person could not
+ * have opened. That is not a convention here; it is the only read path this module has.
+ *
+ * ## What it refuses, and why each one is a refusal rather than a silence
+ *
+ * Every skip comes back with a reason, and the caller is expected to say so in the transcript. A dropped
+ * attachment that nobody mentions is the worst outcome available: the person sees their screenshot in the
+ * thread, the model never received it, and the answer reads as though the model looked and disagreed.
+ *
+ * - **A media type the model cannot take.** Sending a `.docx` as an image part produces a provider error at best
+ *   and a confidently wrong answer at worst.
+ * - **A file over the byte ceiling.** Base64 inflates by a third, and an image is a single indivisible part —
+ *   there is no paging a picture. A 20MB photo is a request that fails after the money is spent.
+ * - **More attachments than the ceiling.** Ten images in one turn is a context window, not a question.
+ * - **A file the caller may not read.** `FileService.get` throws; the throw is caught and reported as a skip, so
+ *   one inaccessible attachment does not fail a turn that had three others.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { FileService } from "./index.js";
+import type { InputModality } from "../models/index.js";
+import type { TurnContentPart } from "../models/streaming.js";
+/**
+ * Media types that may travel as an image part, by modality.
+ *
+ * An allow-list, not a `image/*` wildcard — the same choice `read_attachment` makes for text. A wildcard admits
+ * every future format a provider does not accept, and the failure arrives from the provider as a 400 nobody can
+ * act on. `image/svg+xml` is deliberately absent: an SVG is a document that can fetch, and a model asked to
+ * "look at" one is being handed markup.
+ */
+export declare const IMAGE_PART_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+/** PDFs travel as a file part where the model accepts the `pdf` modality. */
+export declare const FILE_PART_MEDIA_TYPES: readonly ["application/pdf"];
+/**
+ * The per-attachment ceiling.
+ *
+ * Smaller than `read_attachment`'s 32KB window is *larger*, not smaller, and the difference is the point: text
+ * can be paged, so its tool reads a window. An image cannot be paged, so the whole thing travels or none of it
+ * does — and the ceiling is what stops "the whole thing" from being 20MB.
+ */
+export declare const MAX_ATTACHMENT_PART_BYTES: number;
+/** How many attachments one turn may carry. Ten images is a context window, not a question. */
+export declare const MAX_ATTACHMENT_PARTS = 4;
+export type SkippedAttachment = {
+    readonly fileId: string;
+    readonly filename?: string;
+    /** `unreadable` covers both "does not exist" and "not yours" — the service does not distinguish, deliberately. */
+    readonly reason: "unsupported-media-type" | "too-large" | "too-many" | "unreadable" | "modality-not-accepted";
+    /** A sentence the caller can put in the transcript verbatim. */
+    readonly message: string;
+};
+export type ResolvedAttachments = {
+    readonly parts: readonly TurnContentPart[];
+    /**
+     * What did not make it, and why.
+     *
+     * Never empty-and-silent: a caller that ignores this is a caller whose users watch their attachment vanish.
+     */
+    readonly skipped: readonly SkippedAttachment[];
+};
+export type AttachmentResolverDeps = {
+    readonly files: FileService;
+    readonly maxBytes?: number;
+    readonly maxParts?: number;
+};
+export type ResolveInput = {
+    readonly fileIds: readonly string[];
+    /**
+     * What the resolved model accepts.
+     *
+     * Passed in rather than looked up, because the model is chosen by the caller and this module has no registry.
+     * Omitted means "do not filter" — which is only correct when the caller applies `modelModalities` to the turn
+     * afterwards, and `streamModelTurn` does exactly that. Both checks existing is not redundancy: this one can
+     * say *which file* was dropped, and that one can only refuse the whole turn.
+     */
+    readonly accepts?: readonly InputModality[];
+};
+export type AttachmentResolver = {
+    resolve(context: ExecutionContext, input: ResolveInput): Promise<ResolvedAttachments>;
+};
+export declare const createAttachmentResolver: (deps: AttachmentResolverDeps) => AttachmentResolver;
+/**
+ * The sentence a caller puts in the transcript when something was left out.
+ *
+ * Provided rather than left to each host, because "say so in the transcript" is the half of AC-2 that a host
+ * forgets: the parts arrive, the turn works, and the skip is a field nobody read. One sentence, already written.
+ */
+export declare const describeSkipped: (skipped: readonly SkippedAttachment[]) => string | null;
+//# sourceMappingURL=turn-parts.d.ts.map

package/dist/files/turn-parts.js

@@ -0,0 +1,171 @@
+/**
+ * Turning stored attachments into turn parts — REQ-036 (#185), AC-3.
+ *
+ * `TurnContentPart` carries bytes or a URL, never a platform file id: the SDK boundary knows nothing about the
+ * file store. Something has to bridge the two, and that something is the place where a modality bridge either
+ * respects file authorization or quietly becomes a way around it.
+ *
+ * So this reads through `FileService` — the same call `read_attachment` makes, not the stores underneath it.
+ * Entitlement, existence and state all come from the service, so a turn cannot carry a file the person could not
+ * have opened. That is not a convention here; it is the only read path this module has.
+ *
+ * ## What it refuses, and why each one is a refusal rather than a silence
+ *
+ * Every skip comes back with a reason, and the caller is expected to say so in the transcript. A dropped
+ * attachment that nobody mentions is the worst outcome available: the person sees their screenshot in the
+ * thread, the model never received it, and the answer reads as though the model looked and disagreed.
+ *
+ * - **A media type the model cannot take.** Sending a `.docx` as an image part produces a provider error at best
+ *   and a confidently wrong answer at worst.
+ * - **A file over the byte ceiling.** Base64 inflates by a third, and an image is a single indivisible part —
+ *   there is no paging a picture. A 20MB photo is a request that fails after the money is spent.
+ * - **More attachments than the ceiling.** Ten images in one turn is a context window, not a question.
+ * - **A file the caller may not read.** `FileService.get` throws; the throw is caught and reported as a skip, so
+ *   one inaccessible attachment does not fail a turn that had three others.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { asId } from "../core/ids.js";
+/**
+ * Media types that may travel as an image part, by modality.
+ *
+ * An allow-list, not a `image/*` wildcard — the same choice `read_attachment` makes for text. A wildcard admits
+ * every future format a provider does not accept, and the failure arrives from the provider as a 400 nobody can
+ * act on. `image/svg+xml` is deliberately absent: an SVG is a document that can fetch, and a model asked to
+ * "look at" one is being handed markup.
+ */
+export const IMAGE_PART_MEDIA_TYPES = ["image/png", "image/jpeg", "image/webp", "image/gif"];
+/** PDFs travel as a file part where the model accepts the `pdf` modality. */
+export const FILE_PART_MEDIA_TYPES = ["application/pdf"];
+/**
+ * The per-attachment ceiling.
+ *
+ * Smaller than `read_attachment`'s 32KB window is *larger*, not smaller, and the difference is the point: text
+ * can be paged, so its tool reads a window. An image cannot be paged, so the whole thing travels or none of it
+ * does — and the ceiling is what stops "the whole thing" from being 20MB.
+ */
+export const MAX_ATTACHMENT_PART_BYTES = 4 * 1024 * 1024;
+/** How many attachments one turn may carry. Ten images is a context window, not a question. */
+export const MAX_ATTACHMENT_PARTS = 4;
+const modalityFor = (mediaType) => {
+    const type = mediaType.split(";")[0]?.trim().toLowerCase() ?? "";
+    if (IMAGE_PART_MEDIA_TYPES.includes(type))
+        return "image";
+    if (FILE_PART_MEDIA_TYPES.includes(type))
+        return "pdf";
+    return undefined;
+};
+export const createAttachmentResolver = (deps) => {
+    const maxBytes = deps.maxBytes ?? MAX_ATTACHMENT_PART_BYTES;
+    const maxParts = deps.maxParts ?? MAX_ATTACHMENT_PARTS;
+    return {
+        async resolve(context, input) {
+            const parts = [];
+            const skipped = [];
+            for (const raw of input.fileIds) {
+                const fileId = raw.replace(/^file:/, "");
+                if (parts.length >= maxParts) {
+                    skipped.push({
+                        fileId,
+                        reason: "too-many",
+                        message: `Only ${maxParts} attachments can travel with one message; this one was left out.`,
+                    });
+                    continue;
+                }
+                let file;
+                try {
+                    // Through the service, so entitlement, existence and state are its answer and not ours.
+                    file = await deps.files.get(context, asId(fileId));
+                }
+                catch (error) {
+                    skipped.push({
+                        fileId,
+                        reason: "unreadable",
+                        // Deliberately not distinguishing "missing" from "not yours": the service does not, because saying
+                        // which would tell a caller that a file they cannot read exists.
+                        message: error instanceof AgentPlatformError && error.code === "not_found"
+                            ? "That attachment could not be read."
+                            : "That attachment could not be read.",
+                    });
+                    continue;
+                }
+                const modality = modalityFor(file.mediaType);
+                if (modality === undefined) {
+                    skipped.push({
+                        fileId,
+                        filename: file.filename,
+                        reason: "unsupported-media-type",
+                        message: `${file.filename} is ${file.mediaType}, which cannot be shown to a model directly. Read it with a tool instead.`,
+                    });
+                    continue;
+                }
+                if (input.accepts !== undefined && !input.accepts.includes(modality)) {
+                    skipped.push({
+                        fileId,
+                        filename: file.filename,
+                        reason: "modality-not-accepted",
+                        message: `${file.filename} is ${modality}, which the selected model does not accept.`,
+                    });
+                    continue;
+                }
+                if (file.byteSize > maxBytes) {
+                    skipped.push({
+                        fileId,
+                        filename: file.filename,
+                        reason: "too-large",
+                        // The number, so the sentence is actionable rather than a policy statement.
+                        message: `${file.filename} is ${Math.round(file.byteSize / 1024)}KB, over the ` +
+                            `${Math.round(maxBytes / 1024)}KB limit for an attachment sent to a model. An image cannot be ` +
+                            `read in pages, so it travels whole or not at all.`,
+                    });
+                    continue;
+                }
+                /**
+                 * Read to the ceiling and *stop*, then check.
+                 *
+                 * `byteSize` is metadata, and metadata can disagree with the object — a truncated upload, a store
+                 * someone wrote to directly. Reading with its own bound means a file that lies about its size costs the
+                 * ceiling rather than whatever it actually is.
+                 */
+                const chunks = [];
+                let read = 0;
+                let overflowed = false;
+                for await (const chunk of await deps.files.read(context, asId(fileId))) {
+                    read += chunk.byteLength;
+                    if (read > maxBytes) {
+                        overflowed = true;
+                        break;
+                    }
+                    chunks.push(chunk);
+                }
+                if (overflowed) {
+                    skipped.push({
+                        fileId,
+                        filename: file.filename,
+                        reason: "too-large",
+                        message: `${file.filename} is larger than its recorded size and over the attachment limit.`,
+                    });
+                    continue;
+                }
+                const bytes = Buffer.concat(chunks.map((c) => Buffer.from(c)));
+                const data = `data:${file.mediaType};base64,${bytes.toString("base64")}`;
+                parts.push(modality === "image"
+                    ? { kind: "image", image: data, mediaType: file.mediaType }
+                    : { kind: "file", data, mediaType: file.mediaType, filename: file.filename });
+            }
+            return { parts, skipped };
+        },
+    };
+};
+/**
+ * The sentence a caller puts in the transcript when something was left out.
+ *
+ * Provided rather than left to each host, because "say so in the transcript" is the half of AC-2 that a host
+ * forgets: the parts arrive, the turn works, and the skip is a field nobody read. One sentence, already written.
+ */
+export const describeSkipped = (skipped) => {
+    if (skipped.length === 0)
+        return null;
+    const lines = skipped.map((s) => `- ${s.message}`);
+    return `Some attachments were not sent to the model:\n${lines.join("\n")}`;
+};
+//# sourceMappingURL=turn-parts.js.map

package/dist/flows/index.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Flows and teams — REQ-038 (#187) and REQ-037 (#186).
+ *
+ * Designed as one thing because both issues say so, and they are right: a flow's step and a team's member turn
+ * are the same idea, and modelling them separately produces two overlapping notions of "a step" that then have to
+ * be kept in agreement forever. So **a team is a kind of step**, and a team's members execute steps.
+ *
+ * ## The one design decision everything else follows from
+ *
+ * **The interpreter is a pure function.** `advance(definition, execution, outcome)` returns the next execution
+ * state and *one effect to perform* — it performs nothing itself. Every property these two REQs ask for falls out
+ * of that rather than being arranged separately:
+ *
+ * - **Durability** is persisting the returned state. There is no in-flight interpreter state to lose, because
+ *   there is no interpreter instance.
+ * - **Resume after a restart** is loading the state and asking for the effect again. A host does not have to
+ *   reconstruct where it was; the state *is* where it was.
+ * - **Idempotency across a resume** works because the effect carries a key derived from the execution and step,
+ *   not from a counter in memory. A step that wrote externally and then crashed produces the same key on resume,
+ *   and the idempotency store answers with the stored result.
+ * - **Testing** is exhaustive without mocks: feeding outcomes to a function and asserting the next state needs no
+ *   agent, no database and no clock.
+ *
+ * The alternative — an async interpreter that awaits its own effects — is shorter to write and cannot be made
+ * durable without a checkpoint after every await, which is the same state machine with the states implicit.
+ *
+ * ## A definition and an execution are different things
+ *
+ * `FlowExecution.flowVersion` is pinned when the execution starts, and the definition is read at that version
+ * forever. Editing a flow does not change one already running. Conflating them is how a running automation
+ * silently changes shape halfway through — the person who edited step 4 has no idea an execution is sitting at
+ * step 3.
+ */
+import type { AgentId, ConversationId, PrincipalId, RunId, TenantId } from "../core/ids.js";
+/**
+ * What a flow or a team may spend before it is stopped.
+ *
+ * Three dimensions because they fail differently, and a ceiling on one says nothing about the others. Steps bound
+ * a loop that makes no progress. Cost bounds a loop that makes expensive progress. Wall-clock bounds a step that
+ * hangs, which neither of the others catches — a flow waiting on a webhook consumes no steps and no money.
+ */
+export type FlowBudget = {
+    readonly maxSteps: number;
+    readonly maxCostMinorUnits?: number;
+    readonly maxWallClockMs?: number;
+};
+/** Spent so far. Compared against the budget before every step, never after. */
+export type FlowSpend = {
+    readonly steps: number;
+    readonly costMinorUnits: number;
+    readonly startedAtMs: number;
+};
+/**
+ * What happens when a step fails — chosen in the definition, not by whichever error surfaced.
+ *
+ * `escalate` is the one worth explaining: it hands the failure to the enclosing scope rather than deciding here. A
+ * team member escalates to its manager; a flow step escalates to its parent flow. Without it, "retry or die" is
+ * the whole vocabulary, and a manager-led team cannot react to a member failing, which is most of the point of
+ * having a manager.
+ */
+export declare const FAILURE_ACTIONS: readonly ["retry", "skip", "escalate", "fail"];
+export type FailureAction = (typeof FAILURE_ACTIONS)[number];
+export type FailurePolicy = {
+    readonly action: FailureAction;
+    /** Only meaningful for `retry`. Bounded, because an unbounded retry is a loop with a good excuse. */
+    readonly maxAttempts?: number;
+    /** Milliseconds before the first retry; doubles each attempt. */
+    readonly backoffMs?: number;
+};
+export declare const DEFAULT_FAILURE_POLICY: FailurePolicy;
+/**
+ * A reference into the execution's state, for a step's input and a branch's condition.
+ *
+ * A path, not an expression. `"$.order.total"` reads a value; there is no arithmetic, no comparison operators and
+ * no function calls, because an expression language in a stored definition is an interpreter that runs whatever a
+ * definition author typed — and the definitions will eventually be authored in a UI by someone who is not an
+ * engineer (REQ-042). Comparison lives in the *branch*, which has a closed set of operators.
+ */
+export type StatePath = string;
+export declare const BRANCH_OPERATORS: readonly ["equals", "not-equals", "exists", "absent", "greater-than", "less-than", "contains"];
+export type BranchOperator = (typeof BRANCH_OPERATORS)[number];
+export type BranchCase = {
+    readonly path: StatePath;
+    readonly operator: BranchOperator;
+    /** Absent for `exists` and `absent`, which are about presence rather than value. */
+    readonly value?: string | number | boolean;
+    readonly next: string;
+};
+export declare const STEP_KINDS: readonly ["agent", "team", "tool", "branch", "wait", "checkpoint", "subflow", "done"];
+export type StepKind = (typeof STEP_KINDS)[number];
+type StepBase = {
+    readonly name: string;
+    readonly onFailure?: FailurePolicy;
+    /**
+     * Where the step's result is written in the execution state.
+     *
+     * Absent means the result is discarded, which is a real choice: a step whose output nothing reads should say so,
+     * rather than accumulating state a later reader has to guess the relevance of.
+     */
+    readonly assignTo?: string;
+};
+export type FlowStep = (StepBase & {
+    readonly kind: "agent";
+    readonly agentId: AgentId;
+    /** Appended to the agent's own instructions for this step only. */
+    readonly instructions?: string;
+    /** What the agent is asked, with `{{path}}` interpolated from state. */
+    readonly prompt: string;
+    readonly next?: string;
+}) | (StepBase & {
+    readonly kind: "team";
+    readonly teamId: string;
+    readonly prompt: string;
+    readonly next?: string;
+}) | (StepBase & {
+    readonly kind: "tool";
+    readonly tool: string;
+    /** Literal values, or `{{path}}` references resolved from state. */
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly next?: string;
+}) | (StepBase & {
+    readonly kind: "branch";
+    readonly cases: readonly BranchCase[];
+    readonly otherwise?: string;
+}) | (StepBase & {
+    readonly kind: "wait";
+    /** A duration, or a named signal something outside the flow delivers. */
+    readonly forMs?: number;
+    readonly forSignal?: string;
+    readonly next?: string;
+}) | (StepBase & {
+    readonly kind: "checkpoint";
+    /** Asked through the existing HITL path, so a parked flow is the object the assistant surface already answers. */
+    readonly question: string;
+    readonly options?: readonly string[];
+    readonly next?: string;
+}) | (StepBase & {
+    readonly kind: "subflow";
+    readonly flowId: string;
+    readonly next?: string;
+}) | (StepBase & {
+    readonly kind: "done";
+    readonly outcome?: string;
+});
+export type FlowDefinition = {
+    readonly id: string;
+    /** Immutable per version. An execution pins one and reads it forever — see the module comment. */
+    readonly version: number;
+    readonly name: string;
+    readonly description?: string;
+    readonly steps: readonly FlowStep[];
+    readonly start: string;
+    readonly budget: FlowBudget;
+    /**
+     * How deep a subflow or a team may nest.
+     *
+     * Enforced rather than documented, and it is what makes A → B → A terminate: each level carries its depth, and
+     * a step that would exceed the bound fails the flow with a message naming the chain. A cycle detector over the
+     * definition graph would not be enough, because a subflow reference is resolved at run time and the graph is
+     * only known then.
+     */
+    readonly maxDepth?: number;
+};
+export declare const DEFAULT_MAX_DEPTH = 5;
+/** One member of a team. Its own instructions, its own tools, its own limits. */
+export type TeamMember = {
+    readonly name: string;
+    readonly agentId: AgentId;
+    readonly instructions?: string;
+    /**
+     * Tool names this member may use, narrowing the team's own set.
+     *
+     * A narrowing, never a widening: the delegation tool intersects this with what the delegating context could
+     * reach, so a member cannot be granted something the team was not. #186 AC-3 — "a delegated agent cannot reach
+     * a tool the delegating one could not" — is that intersection, and it is enforced where the tool set is built
+     * rather than checked afterwards.
+     */
+    readonly tools?: readonly string[];
+    readonly maxSteps?: number;
+};
+export declare const TEAM_PROCESSES: readonly ["sequential", "manager-led"];
+export type TeamProcess = (typeof TEAM_PROCESSES)[number];
+export type TeamDefinition = {
+    readonly id: string;
+    readonly version: number;
+    readonly name: string;
+    /**
+     * Sequential or manager-led, as a **property** rather than two code paths — #186 AC-2.
+     *
+     * The interpreter branches on this in one place: which member runs next. Everything else — budgets, delegation,
+     * failure handling, attribution — is identical, which is the point. Two code paths would mean two places for
+     * every later property to be added, and one of them would eventually not get it.
+     */
+    readonly process: TeamProcess;
+    readonly members: readonly TeamMember[];
+    /** Required when `process` is `manager-led`, and refused otherwise: a sequential team with a manager is ambiguous. */
+    readonly manager?: string;
+    readonly budget: FlowBudget;
+    readonly maxDelegationDepth?: number;
+};
+export declare const FLOW_STATUSES: readonly ["running", "waiting", "completed", "failed", "cancelled"];
+export type FlowStatus = (typeof FLOW_STATUSES)[number];
+export type StepRecord = {
+    readonly step: string;
+    readonly kind: StepKind;
+    readonly startedAt: string;
+    readonly finishedAt?: string;
+    readonly outcome: "ok" | "failed" | "skipped" | "waiting";
+    readonly attempt: number;
+    /** Which team member ran it, when a team step did — #186 AC-9, so "which agent costs the money" is answerable. */
+    readonly member?: string;
+    readonly costMinorUnits?: number;
+    readonly error?: string;
+};
+export type FlowExecution = {
+    readonly id: string;
+    readonly tenantId: TenantId;
+    readonly flowId: string;
+    /** Pinned at start. The definition is read at this version for the execution's whole life. */
+    readonly flowVersion: number;
+    /** The platform run this execution is, so quotas, usage and events apply as they do to any run. */
+    readonly runId: RunId;
+    readonly principalId: PrincipalId;
+    readonly conversationId?: ConversationId;
+    readonly status: FlowStatus;
+    /** The step about to run, or the one being waited on. `null` once terminal. */
+    readonly currentStep: string | null;
+    /**
+     * State between steps, durable, and **readable by a person** — #187 AC-3.
+     *
+     * A flat JSON object rather than an opaque blob, because "what state is this flow in" is a question someone
+     * asks while it is stuck, and an answer they cannot read is not an answer.
+     */
+    readonly state: Readonly<Record<string, unknown>>;
+    readonly spend: FlowSpend;
+    readonly history: readonly StepRecord[];
+    /** Attempts for the current step, so a retry policy survives a restart. */
+    readonly attempt: number;
+    readonly depth: number;
+    readonly startedAt: string;
+    readonly finishedAt?: string;
+    /** Why it stopped, when it stopped for a reason worth reading. */
+    readonly detail?: string;
+    /** Set while `waiting`: the interaction a checkpoint is parked on, or the signal a wait needs. */
+    readonly waitingFor?: {
+        readonly kind: "human";
+        readonly interactionId: string;
+    } | {
+        readonly kind: "signal";
+        readonly signal: string;
+    } | {
+        readonly kind: "time";
+        readonly untilMs: number;
+    }
+    /**
+     * A child run — #202.
+     *
+     * An agent step is a run of its own, so the flow parks on it. The `runId` is stored rather than held, which
+     * is what makes both wake-up paths work: a notification when the child settles, and a *poll* on resume for
+     * when the notification never arrived. Depending only on the notification would be depending on a message
+     * that a crash between the child completing and the parent being told simply loses.
+     */
+     | {
+        readonly kind: "run";
+        readonly runId: string;
+        readonly member?: string;
+    };
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/flows/index.js

@@ -0,0 +1,62 @@
+/**
+ * Flows and teams — REQ-038 (#187) and REQ-037 (#186).
+ *
+ * Designed as one thing because both issues say so, and they are right: a flow's step and a team's member turn
+ * are the same idea, and modelling them separately produces two overlapping notions of "a step" that then have to
+ * be kept in agreement forever. So **a team is a kind of step**, and a team's members execute steps.
+ *
+ * ## The one design decision everything else follows from
+ *
+ * **The interpreter is a pure function.** `advance(definition, execution, outcome)` returns the next execution
+ * state and *one effect to perform* — it performs nothing itself. Every property these two REQs ask for falls out
+ * of that rather than being arranged separately:
+ *
+ * - **Durability** is persisting the returned state. There is no in-flight interpreter state to lose, because
+ *   there is no interpreter instance.
+ * - **Resume after a restart** is loading the state and asking for the effect again. A host does not have to
+ *   reconstruct where it was; the state *is* where it was.
+ * - **Idempotency across a resume** works because the effect carries a key derived from the execution and step,
+ *   not from a counter in memory. A step that wrote externally and then crashed produces the same key on resume,
+ *   and the idempotency store answers with the stored result.
+ * - **Testing** is exhaustive without mocks: feeding outcomes to a function and asserting the next state needs no
+ *   agent, no database and no clock.
+ *
+ * The alternative — an async interpreter that awaits its own effects — is shorter to write and cannot be made
+ * durable without a checkpoint after every await, which is the same state machine with the states implicit.
+ *
+ * ## A definition and an execution are different things
+ *
+ * `FlowExecution.flowVersion` is pinned when the execution starts, and the definition is read at that version
+ * forever. Editing a flow does not change one already running. Conflating them is how a running automation
+ * silently changes shape halfway through — the person who edited step 4 has no idea an execution is sitting at
+ * step 3.
+ */
+// ---------------------------------------------------------------------------------------------------
+// Failure policy
+// ---------------------------------------------------------------------------------------------------
+/**
+ * What happens when a step fails — chosen in the definition, not by whichever error surfaced.
+ *
+ * `escalate` is the one worth explaining: it hands the failure to the enclosing scope rather than deciding here. A
+ * team member escalates to its manager; a flow step escalates to its parent flow. Without it, "retry or die" is
+ * the whole vocabulary, and a manager-led team cannot react to a member failing, which is most of the point of
+ * having a manager.
+ */
+export const FAILURE_ACTIONS = ["retry", "skip", "escalate", "fail"];
+export const DEFAULT_FAILURE_POLICY = { action: "fail" };
+export const BRANCH_OPERATORS = ["equals", "not-equals", "exists", "absent", "greater-than", "less-than", "contains"];
+export const STEP_KINDS = ["agent", "team", "tool", "branch", "wait", "checkpoint", "subflow", "done"];
+export const DEFAULT_MAX_DEPTH = 5;
+export const TEAM_PROCESSES = ["sequential", "manager-led"];
+// ---------------------------------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------------------------------
+export const FLOW_STATUSES = [
+    "running",
+    /** Parked on a `checkpoint` or a `wait` for a signal. Not failed, and not finished. */
+    "waiting",
+    "completed",
+    "failed",
+    "cancelled",
+];
+//# sourceMappingURL=index.js.map