@tangle-network/agent-runtime 0.43.0 → 0.45.0

package/dist/workflow.d.ts

@@ -0,0 +1,551 @@
+import { AgentProfile, CreateSandboxOptions, PromptOptions, TaskOptions, SandboxEvent } from '@tangle-network/sandbox';
+import { b as LoopSandboxClient, O as OutputAdapter, g as LoopSandboxPlacement, c as LoopResult } from './types-DdzkffAm.js';
+import { R as RunLoopOptions } from './run-loop--hSoIknW.js';
+import '@tangle-network/agent-eval';
+import './runtime-hooks-C7JwKb9E.js';
+
+/**
+ * @experimental
+ *
+ * Dynamic workflow substrate.
+ *
+ * A workflow is driver-authored code executed by a restricted runtime. The
+ * runtime owns orchestration mechanics (phase/progress, fanout, budget,
+ * cancellation, trace emission); product code supplies delegates that actually
+ * run agents and loops. That boundary keeps this package generic while still
+ * letting consumers wire real sandboxes underneath `agent()` and `loop()`.
+ */
+interface WorkflowPhaseMeta {
+    title: string;
+}
+interface WorkflowMeta {
+    name: string;
+    description: string;
+    phases?: WorkflowPhaseMeta[];
+}
+type JsonSchema = {
+    type: 'string';
+    minLength?: number;
+    maxLength?: number;
+    enum?: string[];
+} | {
+    type: 'number';
+    minimum?: number;
+    maximum?: number;
+    enum?: number[];
+} | {
+    type: 'integer';
+    minimum?: number;
+    maximum?: number;
+    enum?: number[];
+} | {
+    type: 'boolean';
+    enum?: boolean[];
+} | {
+    type: 'null';
+} | {
+    type: 'array';
+    items?: JsonSchema;
+    minItems?: number;
+    maxItems?: number;
+} | {
+    type: 'object';
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+};
+interface WorkflowTokenUsage {
+    input: number;
+    output: number;
+}
+interface WorkflowBudgetSnapshot {
+    costUsd: number;
+    tokens: WorkflowTokenUsage;
+    agentCalls: number;
+    loopCalls: number;
+    elapsedMs: number;
+}
+interface WorkflowBudgetRemaining {
+    costUsd?: number;
+    tokens?: number;
+    agentCalls?: number;
+    loopCalls?: number;
+    wallMs?: number;
+}
+interface WorkflowBudgetCaps {
+    maxCostUsd?: number;
+    maxTokens?: number;
+    maxWallMs?: number;
+    maxAgentCalls?: number;
+    maxLoopCalls?: number;
+    maxFanout?: number;
+    maxDepth?: number;
+}
+interface WorkflowBudgetView {
+    readonly total: WorkflowBudgetCaps;
+    spent(): WorkflowBudgetSnapshot;
+    remaining(): WorkflowBudgetRemaining;
+}
+interface WorkflowAgentOptions<TOutput = unknown> {
+    label?: string;
+    schema?: JsonSchema;
+    metadata?: Record<string, unknown>;
+    /**
+     * Nested workflows are denied by default. Consumers that expose them through
+     * a delegate must also honor `ctx.depth` and `ctx.caps.maxDepth`.
+     */
+    allowWorkflow?: boolean;
+    decode?: (value: unknown) => TOutput;
+}
+interface WorkflowLoopOptions<TOutput = unknown> {
+    label?: string;
+    schema?: JsonSchema;
+    metadata?: Record<string, unknown>;
+    decode?: (value: unknown) => TOutput;
+}
+interface WorkflowCheckpointOptions<TOutput = unknown> {
+    label?: string;
+    schema?: JsonSchema;
+    metadata?: Record<string, unknown>;
+    decode?: (value: unknown) => TOutput;
+}
+interface WorkflowDelegateResult {
+    output: unknown;
+    costUsd?: number;
+    tokenUsage?: Partial<WorkflowTokenUsage>;
+    /** Additional downstream workflow agent calls consumed inside this delegate. */
+    agentCalls?: number;
+    /** Additional downstream workflow loop calls consumed inside this delegate. */
+    loopCalls?: number;
+    trace?: unknown;
+}
+interface WorkflowDelegateContext {
+    workflowRunId: string;
+    depth: number;
+    phase?: string;
+    signal: AbortSignal;
+    caps: WorkflowBudgetCaps;
+    budget: WorkflowBudgetView;
+    metadata?: Record<string, unknown>;
+}
+type WorkflowAgentDelegate = (prompt: string, options: WorkflowAgentOptions, ctx: WorkflowDelegateContext) => Promise<WorkflowDelegateResult>;
+type WorkflowLoopDelegate = (input: unknown, options: WorkflowLoopOptions, ctx: WorkflowDelegateContext) => Promise<WorkflowDelegateResult>;
+type WorkflowVerifierDelegate = (input: unknown, options: WorkflowCheckpointOptions, ctx: WorkflowDelegateContext) => Promise<WorkflowDelegateResult>;
+type WorkflowAnalystDelegate = (input: unknown, options: WorkflowCheckpointOptions, ctx: WorkflowDelegateContext) => Promise<WorkflowDelegateResult>;
+type WorkflowReviewerDelegate = (input: unknown, options: WorkflowCheckpointOptions, ctx: WorkflowDelegateContext) => Promise<WorkflowDelegateResult>;
+type WorkflowTraceEvent = {
+    kind: 'workflow.started';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowStartedPayload;
+} | {
+    kind: 'workflow.phase';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowPhasePayload;
+} | {
+    kind: 'workflow.log';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowLogPayload;
+} | {
+    kind: 'workflow.parallel.started';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowParallelStartedPayload;
+} | {
+    kind: 'workflow.parallel.ended';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowParallelEndedPayload;
+} | {
+    kind: 'workflow.pipeline.started';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowPipelineStartedPayload;
+} | {
+    kind: 'workflow.pipeline.ended';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowPipelineEndedPayload;
+} | {
+    kind: 'workflow.branch.started';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowBranchStartedPayload;
+} | {
+    kind: 'workflow.branch.ended';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowBranchEndedPayload;
+} | {
+    kind: 'workflow.branch.failed';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowBranchFailedPayload;
+} | {
+    kind: 'workflow.agent.started';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowAgentStartedPayload;
+} | {
+    kind: 'workflow.agent.ended';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowAgentEndedPayload;
+} | {
+    kind: 'workflow.agent.failed';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowDelegateFailedPayload;
+} | {
+    kind: 'workflow.loop.started';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowLoopStartedPayload;
+} | {
+    kind: 'workflow.loop.ended';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowLoopEndedPayload;
+} | {
+    kind: 'workflow.loop.failed';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowDelegateFailedPayload;
+} | {
+    kind: 'workflow.verifier.started';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowCheckpointStartedPayload;
+} | {
+    kind: 'workflow.verifier.ended';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowCheckpointEndedPayload;
+} | {
+    kind: 'workflow.verifier.failed';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowDelegateFailedPayload;
+} | {
+    kind: 'workflow.analyst.started';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowCheckpointStartedPayload;
+} | {
+    kind: 'workflow.analyst.ended';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowCheckpointEndedPayload;
+} | {
+    kind: 'workflow.analyst.failed';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowDelegateFailedPayload;
+} | {
+    kind: 'workflow.reviewer.started';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowCheckpointStartedPayload;
+} | {
+    kind: 'workflow.reviewer.ended';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowCheckpointEndedPayload;
+} | {
+    kind: 'workflow.reviewer.failed';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowDelegateFailedPayload;
+} | {
+    kind: 'workflow.failed';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowFailedPayload;
+} | {
+    kind: 'workflow.ended';
+    runId: string;
+    timestamp: number;
+    payload: WorkflowEndedPayload;
+};
+interface WorkflowStartedPayload {
+    meta: WorkflowMeta;
+    depth: number;
+    caps: WorkflowBudgetCaps;
+}
+interface WorkflowPhasePayload {
+    title: string;
+}
+interface WorkflowLogPayload {
+    message: string;
+    phase?: string;
+}
+interface WorkflowParallelStartedPayload {
+    branchCount: number;
+    phase?: string;
+}
+interface WorkflowParallelEndedPayload {
+    branchCount: number;
+    durationMs: number;
+    phase?: string;
+}
+interface WorkflowPipelineStartedPayload {
+    itemCount: number;
+    stageCount: number;
+    phase?: string;
+}
+interface WorkflowPipelineEndedPayload {
+    itemCount: number;
+    stageCount: number;
+    durationMs: number;
+    phase?: string;
+}
+type WorkflowBranchOperation = 'parallel' | 'pipeline';
+interface WorkflowBranchStartedPayload {
+    operation: WorkflowBranchOperation;
+    branchIndex: number;
+    phase?: string;
+    stageCount?: number;
+}
+interface WorkflowBranchEndedPayload {
+    operation: WorkflowBranchOperation;
+    branchIndex: number;
+    durationMs: number;
+    phase?: string;
+    stageCount?: number;
+}
+interface WorkflowBranchFailedPayload {
+    operation: WorkflowBranchOperation;
+    branchIndex: number;
+    durationMs: number;
+    message: string;
+    code?: string;
+    phase?: string;
+    stageIndex?: number;
+}
+interface WorkflowAgentStartedPayload {
+    index: number;
+    label?: string;
+    promptChars: number;
+    phase?: string;
+    metadata?: Record<string, unknown>;
+}
+interface WorkflowAgentEndedPayload {
+    index: number;
+    label?: string;
+    durationMs: number;
+    costUsd: number;
+    tokenUsage: WorkflowTokenUsage;
+    phase?: string;
+    trace?: unknown;
+}
+interface WorkflowLoopStartedPayload {
+    index: number;
+    label?: string;
+    phase?: string;
+    metadata?: Record<string, unknown>;
+}
+interface WorkflowLoopEndedPayload {
+    index: number;
+    label?: string;
+    durationMs: number;
+    costUsd: number;
+    tokenUsage: WorkflowTokenUsage;
+    phase?: string;
+    trace?: unknown;
+}
+interface WorkflowCheckpointStartedPayload {
+    index: number;
+    label?: string;
+    phase?: string;
+    metadata?: Record<string, unknown>;
+}
+interface WorkflowCheckpointEndedPayload {
+    index: number;
+    label?: string;
+    durationMs: number;
+    costUsd: number;
+    tokenUsage: WorkflowTokenUsage;
+    phase?: string;
+    trace?: unknown;
+}
+interface WorkflowDelegateFailedPayload {
+    index: number;
+    label?: string;
+    durationMs: number;
+    message: string;
+    code?: string;
+    phase?: string;
+}
+interface WorkflowFailedPayload {
+    message: string;
+    code?: string;
+    phase?: string;
+}
+interface WorkflowEndedPayload {
+    durationMs: number;
+    costUsd: number;
+    tokenUsage: WorkflowTokenUsage;
+    agentCalls: number;
+    loopCalls: number;
+}
+interface WorkflowTraceEmitter {
+    emit(event: WorkflowTraceEvent): void | Promise<void>;
+}
+interface WorkflowRuntimeOptions {
+    source: string;
+    agent: WorkflowAgentDelegate;
+    loop?: WorkflowLoopDelegate;
+    verifier?: WorkflowVerifierDelegate;
+    analyst?: WorkflowAnalystDelegate;
+    reviewer?: WorkflowReviewerDelegate;
+    runId?: string;
+    depth?: number;
+    caps?: WorkflowBudgetCaps;
+    metadata?: Record<string, unknown>;
+    signal?: AbortSignal;
+    traceEmitter?: WorkflowTraceEmitter;
+    now?: () => number;
+    syncTimeoutMs?: number;
+}
+interface WorkflowResult<TOutput = unknown> {
+    runId: string;
+    meta: WorkflowMeta;
+    output: TOutput;
+    events: WorkflowTraceEvent[];
+    durationMs: number;
+    costUsd: number;
+    tokenUsage: WorkflowTokenUsage;
+    agentCalls: number;
+    loopCalls: number;
+}
+
+type WorkflowSandboxAgentStream = 'prompt' | 'task';
+type WorkflowSandboxAgentProfileResolver = AgentProfile | ((prompt: string, options: WorkflowAgentOptions, ctx: WorkflowDelegateContext) => AgentProfile);
+type WorkflowSandboxPromptOptionsResolver<TOptions extends PromptOptions> = TOptions | ((prompt: string, options: WorkflowAgentOptions, ctx: WorkflowDelegateContext) => TOptions);
+interface WorkflowSandboxAgentTrace<TOutput = unknown> {
+    prompt: string;
+    options: WorkflowAgentOptions;
+    ctx: WorkflowDelegateContext;
+    profile: AgentProfile;
+    output: TOutput;
+    events: SandboxEvent[];
+    stream: WorkflowSandboxAgentStream;
+    placement: LoopSandboxPlacement;
+    costUsd: number;
+    tokenUsage: WorkflowTokenUsage;
+}
+interface CreateSandboxWorkflowAgentDelegateOptions<TOutput = unknown> {
+    client: LoopSandboxClient;
+    profile: WorkflowSandboxAgentProfileResolver;
+    output?: OutputAdapter<TOutput>;
+    stream?: WorkflowSandboxAgentStream;
+    sandboxOverrides?: Partial<Omit<CreateSandboxOptions, 'backend'>> & {
+        backend?: Omit<NonNullable<CreateSandboxOptions['backend']>, 'profile'>;
+    };
+    promptOptions?: WorkflowSandboxPromptOptionsResolver<PromptOptions>;
+    taskOptions?: WorkflowSandboxPromptOptionsResolver<TaskOptions>;
+    deleteAfter?: boolean;
+    includeEventsInTrace?: boolean;
+    toTrace?: (trace: WorkflowSandboxAgentTrace<TOutput>) => unknown;
+}
+interface WorkflowSandboxAgentDefaultTrace {
+    stream: WorkflowSandboxAgentStream;
+    placement: LoopSandboxPlacement['kind'];
+    sandboxId?: string;
+    fleetId?: string;
+    machineId?: string;
+    profileName?: string;
+    eventCount: number;
+    eventTypes: string[];
+    events?: SandboxEvent[];
+}
+declare function createSandboxWorkflowAgentDelegate<TOutput = unknown>(options: CreateSandboxWorkflowAgentDelegateOptions<TOutput>): WorkflowAgentDelegate;
+declare function parseSandboxAgentDefaultOutput(events: SandboxEvent[]): unknown;
+
+declare class WorkflowBudget implements WorkflowBudgetView {
+    readonly total: WorkflowBudgetCaps;
+    private readonly startedAt;
+    private readonly now;
+    private costUsd;
+    private tokens;
+    private agentCallCount;
+    private loopCallCount;
+    constructor(total: WorkflowBudgetCaps, now: () => number);
+    spent(): WorkflowBudgetSnapshot;
+    remaining(): WorkflowBudgetRemaining;
+    nextAgentIndex(): number;
+    nextLoopIndex(): number;
+    assertFanout(count: number): void;
+    observe(result: WorkflowDelegateResult): {
+        costUsd: number;
+        tokenUsage: WorkflowTokenUsage;
+    };
+    assertWall(): void;
+    remainingWallMs(): number | undefined;
+    private elapsedMs;
+    private assertSpend;
+}
+
+interface CreateRunLoopWorkflowDelegateOptions<Input, Task, Output, Decision> {
+    toRunLoopOptions(input: Input, options: WorkflowLoopOptions, ctx: WorkflowDelegateContext): RunLoopOptions<Task, Output, Decision>;
+    toOutput?: (result: LoopResult<Task, Output, Decision>) => unknown;
+    toTrace?: (result: LoopResult<Task, Output, Decision>) => unknown;
+}
+declare function createRunLoopWorkflowDelegate<Input, Task, Output, Decision>(options: CreateRunLoopWorkflowDelegateOptions<Input, Task, Output, Decision>): WorkflowLoopDelegate;
+
+interface NestedWorkflowDelegateInput {
+    source: string;
+    options: WorkflowAgentOptions;
+    parent: WorkflowDelegateContext;
+}
+type NestedWorkflowCapsResolver = WorkflowBudgetCaps | ((input: NestedWorkflowDelegateInput) => WorkflowBudgetCaps);
+type NestedWorkflowMetadataResolver = Record<string, unknown> | ((input: NestedWorkflowDelegateInput) => Record<string, unknown> | undefined);
+interface NestedWorkflowTrace {
+    nested: true;
+    runId: string;
+    parentRunId: string;
+    depth: number;
+    metaName: string;
+    eventCount: number;
+    eventKinds: string[];
+    durationMs: number;
+    costUsd: number;
+    tokenUsage: WorkflowResult['tokenUsage'];
+    agentCalls: number;
+    loopCalls: number;
+    events?: WorkflowResult['events'];
+}
+interface CreateNestedWorkflowAgentDelegateOptions {
+    /**
+     * Real worker delegate used for normal agent() calls and for child workflow
+     * agent() calls that do not opt into allowWorkflow.
+     */
+    agent: WorkflowAgentDelegate;
+    caps: NestedWorkflowCapsResolver;
+    loop?: WorkflowLoopDelegate;
+    verifier?: WorkflowVerifierDelegate;
+    analyst?: WorkflowAnalystDelegate;
+    reviewer?: WorkflowReviewerDelegate;
+    metadata?: NestedWorkflowMetadataResolver;
+    traceEmitter?: WorkflowTraceEmitter;
+    includeEventsInTrace?: boolean;
+    runId?: (input: NestedWorkflowDelegateInput) => string;
+    toOutput?: (result: WorkflowResult, input: NestedWorkflowDelegateInput) => unknown;
+    toTrace?: (result: WorkflowResult, input: NestedWorkflowDelegateInput) => unknown;
+}
+declare function createNestedWorkflowAgentDelegate(options: CreateNestedWorkflowAgentDelegateOptions): WorkflowAgentDelegate;
+
+declare function runWorkflow<TOutput = unknown>(options: WorkflowRuntimeOptions): Promise<WorkflowResult<TOutput>>;
+
+declare function validateJsonSchema(value: unknown, schema: JsonSchema, path?: string): void;
+
+interface ParsedWorkflowScript {
+    meta: WorkflowMeta;
+    body: string;
+}
+declare function parseWorkflowScript(source: string): ParsedWorkflowScript;
+declare function validateWorkflowBody(body: string): void;
+
+export { type CreateNestedWorkflowAgentDelegateOptions, type CreateRunLoopWorkflowDelegateOptions, type CreateSandboxWorkflowAgentDelegateOptions, type JsonSchema, type NestedWorkflowCapsResolver, type NestedWorkflowDelegateInput, type NestedWorkflowMetadataResolver, type NestedWorkflowTrace, type ParsedWorkflowScript, type WorkflowAgentDelegate, type WorkflowAgentEndedPayload, type WorkflowAgentOptions, type WorkflowAgentStartedPayload, type WorkflowAnalystDelegate, type WorkflowBranchEndedPayload, type WorkflowBranchFailedPayload, type WorkflowBranchOperation, type WorkflowBranchStartedPayload, WorkflowBudget, type WorkflowBudgetCaps, type WorkflowBudgetRemaining, type WorkflowBudgetSnapshot, type WorkflowBudgetView, type WorkflowCheckpointEndedPayload, type WorkflowCheckpointOptions, type WorkflowCheckpointStartedPayload, type WorkflowDelegateContext, type WorkflowDelegateResult, type WorkflowEndedPayload, type WorkflowFailedPayload, type WorkflowLogPayload, type WorkflowLoopDelegate, type WorkflowLoopEndedPayload, type WorkflowLoopOptions, type WorkflowLoopStartedPayload, type WorkflowMeta, type WorkflowParallelEndedPayload, type WorkflowParallelStartedPayload, type WorkflowPhaseMeta, type WorkflowPhasePayload, type WorkflowPipelineEndedPayload, type WorkflowPipelineStartedPayload, type WorkflowResult, type WorkflowReviewerDelegate, type WorkflowRuntimeOptions, type WorkflowSandboxAgentDefaultTrace, type WorkflowSandboxAgentProfileResolver, type WorkflowSandboxAgentStream, type WorkflowSandboxAgentTrace, type WorkflowSandboxPromptOptionsResolver, type WorkflowStartedPayload, type WorkflowTokenUsage, type WorkflowTraceEmitter, type WorkflowTraceEvent, type WorkflowVerifierDelegate, createNestedWorkflowAgentDelegate, createRunLoopWorkflowDelegate, createSandboxWorkflowAgentDelegate, parseSandboxAgentDefaultOutput, parseWorkflowScript, runWorkflow, validateJsonSchema, validateWorkflowBody };