Skip to main content

FlowEffect

@forge/monorepo

@forge/monorepo / backend/src / FlowEffect

Type Alias: FlowEffect

FlowEffect = { agentId: string; budgetRemaining: { costMinorUnits?: number; steps: number; wallClockMs?: number; }; idempotencyKey: string; instructions?: string; kind: "run-agent"; member?: string; prompt: string; } | { idempotencyKey: string; kind: "run-team"; prompt: string; teamId: string; } | { idempotencyKey: string; input: Readonly<Record<string, unknown>>; kind: "call-tool"; tool: string; } | { kind: "ask-human"; options?: readonly string[]; question: string; } | { kind: "sleep"; untilMs: number; } | { kind: "await-signal"; signal: string; } | { depth: number; flowId: string; idempotencyKey: string; kind: "run-subflow"; } | { kind: "settled"; }

Defined in: backend/src/flows/interpreter.ts:44

One unit of work the host performs and reports back.

Data, not a callback. A callback would put the host's control flow inside the interpreter's, which is exactly what makes a host-written workflow undurable in the first place — the thing this module exists to replace.

Union Members​

Type Literal​

{ agentId: string; budgetRemaining: { costMinorUnits?: number; steps: number; wallClockMs?: number; }; idempotencyKey: string; instructions?: string; kind: "run-agent"; member?: string; prompt: string; }

agentId​

readonly agentId: string

budgetRemaining​

readonly budgetRemaining: object

What the flow has left to spend — #202 AC-3.

Handed over rather than left for the handler to work out, and re-derived on every step because the remainder changes. A child run given its own independent ceiling is a member that can outspend the team, which is #186 AC-4 defeated by the composition that was supposed to honour it.

budgetRemaining.costMinorUnits?​

readonly optional costMinorUnits?: number

budgetRemaining.steps​

readonly steps: number

budgetRemaining.wallClockMs?​

readonly optional wallClockMs?: number

idempotencyKey​

readonly idempotencyKey: string

instructions?​

readonly optional instructions?: string

kind​

readonly kind: "run-agent"

member?​

readonly optional member?: string

Which team member this step is, so the child run and its usage carry the attribution.

prompt​

readonly prompt: string

Type Literal​

{ idempotencyKey: string; kind: "run-team"; prompt: string; teamId: string; }

Type Literal​

{ idempotencyKey: string; input: Readonly<Record<string, unknown>>; kind: "call-tool"; tool: string; }

Type Literal​

{ kind: "ask-human"; options?: readonly string[]; question: string; }

Type Literal​

{ kind: "sleep"; untilMs: number; }

Type Literal​

{ kind: "await-signal"; signal: string; }

Type Literal​

{ depth: number; flowId: string; idempotencyKey: string; kind: "run-subflow"; }

Type Literal​

{ kind: "settled"; }

Nothing more to do. status says why.