specrails-core 5.2.3 → 5.4.0

package/dist/agent-runtime/workflow-types.d.ts

@@ -0,0 +1,226 @@
+import type { AnnotationRoot } from '@langchain/langgraph';
+import type { ProviderInvocation } from './efficiency-types.js';
+/** JSON-only contracts keep checkpoints portable and independent of executors. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type StepStatus = 'succeeded' | 'failed' | 'blocked' | 'paused';
+export type WorkflowStatus = 'running' | StepStatus | 'cancelled';
+export interface StepUsage {
+    costUsd?: number | null;
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+}
+export interface WorkflowBudget {
+    maxCostUsd?: number;
+    maxTokens?: number;
+    maxDurationMs?: number;
+}
+/** A node asks the host to pause: the run resumes only with the matching answer. */
+export type InterruptRequest = {
+    kind: 'approval';
+    reason: string;
+} | {
+    kind: 'question';
+    question: string;
+};
+export type InterruptResume = {
+    approved: true;
+} | {
+    answer: string;
+};
+export interface NodeResult<S extends Record<string, unknown>> {
+    /** Nodes pause through `context.interrupt`, never through a result. */
+    status: Exclude<StepStatus, 'paused'>;
+    /** Graph state update, merged through the schema's reducers. */
+    update?: Partial<S>;
+    /** Ledger output: kept in the checkpoint receipt and exposed by `runtime status`. */
+    output?: JsonValue;
+    error?: string;
+    /** Omit for the node's first declared successor; null completes the workflow. */
+    next?: string | null;
+    /** Usage not already reported through `context.reportUsage`. */
+    usage?: StepUsage;
+    retryable?: boolean;
+}
+export interface WorkflowStepContext {
+    runId: string;
+    stepId: string;
+    /** Stable identifier for this invocation, suitable for external idempotency keys. */
+    attemptId: string;
+    attempt: number;
+    input: JsonValue;
+    signal: AbortSignal;
+    /** A detached snapshot; modifying it cannot modify the persisted run. */
+    checkpoint: WorkflowState;
+    /** The interrupt this node raised earlier, when the host now resumes it with an answer or approval. */
+    pending?: InterruptRequest;
+    /**
+     * Pause the workflow until the host resumes it. Throws on the first call; on
+     * a resumed node it returns the host's answer immediately, so collect it
+     * before repeating any work.
+     */
+    interrupt<R extends InterruptResume = InterruptResume>(request: InterruptRequest): R;
+    /** Account provider spend as soon as it is known; a later pause or failure keeps it. */
+    reportUsage(usage: StepUsage): void;
+    /** Persist a completed provider call with its already-reported usage. Optional for custom hosts. */
+    reportEfficiencyActivity?(kind: string, payload: Record<string, string | number | null>): Promise<void>;
+    reportInvocationStarted?(invocation: Omit<import('./efficiency-types.js').PendingProviderInvocation, 'invocationId' | 'ordinal'>): Promise<{
+        invocationId: string;
+        ordinal: number;
+    }>;
+    reportInvocation?(invocation: ProviderInvocation): Promise<void>;
+    /** Budget left for the next provider call, after everything reported so far. */
+    remainingBudget(): {
+        maxTokens?: number;
+        maxCostUsd?: number;
+        maxDurationMs?: number;
+    };
+}
+export interface WorkflowNode<S extends Record<string, unknown>> {
+    effect?: 'read' | 'write';
+    maxAttempts?: number;
+    /** Explicitly opt a write step into retries after a reported retryable failure. */
+    retrySafe?: boolean;
+    /** Declared successors; the first is the default when a result omits `next`. */
+    ends: string[];
+    run(state: S, context: WorkflowStepContext): Promise<NodeResult<S>>;
+}
+export interface WorkflowDefinition<S extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    version: string;
+    /** LangGraph state schema; every field must be plain JSON. Any `Annotation.Root` is accepted. */
+    schema: AnnotationRoot<any>;
+    entry: string;
+    /** Declaration order defines "downstream" for invalidation. */
+    nodes: Record<string, WorkflowNode<S>>;
+    /** Maximum visits across conditional loops, independent of per-visit retries. */
+    maxTransitions?: number;
+}
+export interface StepRecord {
+    id: string;
+    status: 'pending' | 'running' | 'interrupted' | StepStatus;
+    effect: 'read' | 'write';
+    visits: number;
+    attempt: number;
+    attemptId?: string;
+    output?: JsonValue;
+    /** The graph state update of the last successful visit, replayed when a lost checkpoint re-runs the node. */
+    update?: JsonValue;
+    /** The successor chosen by the last successful visit; null completed the workflow. */
+    next?: string | null;
+    error?: string;
+    startedAt?: string;
+    completedAt?: string;
+}
+export interface StepAttemptRecord {
+    id: string;
+    stepId: string;
+    attempt: number;
+    visit: number;
+    status: 'running' | 'interrupted' | StepStatus;
+    startedAt: string;
+    completedAt?: string;
+    output?: JsonValue;
+    error?: string;
+    usage?: StepUsage;
+    pendingInvocations?: import('./efficiency-types.js').PendingProviderInvocation[];
+    invocations?: ProviderInvocation[];
+}
+export interface WorkflowEvent {
+    id: string;
+    sequence: number;
+    runId: string;
+    /** Trace correlation: the run's trace and the attempt span this event belongs to. */
+    traceId: string;
+    spanId?: string;
+    efficiencyActivity?: {
+        kind: string;
+        payload: Record<string, string | number | null>;
+    };
+    efficiency?: ProviderInvocation;
+    type: 'efficiency_updated' | 'workflow_started' | 'workflow_resumed' | 'workflow_invalidated' | 'workflow_succeeded' | 'workflow_failed' | 'workflow_blocked' | 'workflow_paused' | 'workflow_cancelled' | 'step_started' | 'step_succeeded' | 'step_failed' | 'step_blocked' | 'step_paused' | 'step_interrupted';
+    timestamp: string;
+    stepId?: string;
+    attemptId?: string;
+    usage?: StepUsage;
+    message?: string;
+}
+/** One completed step attempt, shaped for tracing back ends (OpenTelemetry or otherwise). */
+export interface WorkflowSpan {
+    traceId: string;
+    spanId: string;
+    name: string;
+    stepId: string;
+    attempt: number;
+    visit: number;
+    startedAt: string;
+    endedAt: string;
+    status: 'running' | 'interrupted' | StepStatus;
+    usage?: StepUsage;
+    error?: string;
+}
+export interface WorkflowState {
+    schemaVersion: 2;
+    runId: string;
+    /** Stable trace identifier for every event and span of this run. */
+    traceId: string;
+    workflowId: string;
+    workflowVersion: string;
+    workflowFingerprint: string;
+    inputFingerprint: string;
+    status: WorkflowStatus;
+    createdAt: string;
+    updatedAt: string;
+    nextStep: string | null;
+    nextAttempt: number;
+    transitions: number;
+    executionCount: number;
+    steps: Record<string, StepRecord>;
+    history: StepAttemptRecord[];
+    events: WorkflowEvent[];
+    budget: WorkflowBudget;
+    usage: {
+        costUsd: number | null;
+        inputTokens: number | null;
+        outputTokens: number | null;
+        /** Known lower bounds, even when some providers omit usage. */
+        knownCostUsd: number;
+        knownTokens: number;
+        durationMs: number;
+    };
+    pendingApproval?: {
+        stepId: string;
+        requestedAt: string;
+        grantedAt?: string;
+        reason?: string;
+    };
+    pendingQuestion?: {
+        stepId: string;
+        requestedAt: string;
+        question: string;
+        answeredAt?: string;
+        answer?: string;
+    };
+    error?: string;
+}
+export interface RunWorkflowOptions<S extends Record<string, unknown> = Record<string, unknown>> {
+    directory: string;
+    runId: string;
+    workflow: WorkflowDefinition<S>;
+    input: JsonValue;
+    budget?: WorkflowBudget;
+    signal?: AbortSignal;
+    resume?: boolean;
+    approve?: string[];
+    /** Answer to the pending question; resumes the node that asked it. */
+    answer?: string;
+    recoverInterrupted?: string[];
+    /** Invalidating a step also invalidates all later declared steps. */
+    invalidate?: string[];
+    validateCompleted?: (stepId: string, record: StepRecord, state: WorkflowState) => Promise<boolean>;
+    /** Notification is after durable commit. Observer failures never replay effects. */
+    onEvent?: (event: WorkflowEvent) => void | Promise<void>;
+    /** One span per finished step attempt, after durable commit. */
+    onSpan?: (span: WorkflowSpan) => void | Promise<void>;
+}

package/dist/agent-runtime/workflow-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workflow-types.js.map

package/dist/agent-runtime/workflow-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-types.js","sourceRoot":"","sources":["../../src/agent-runtime/workflow-types.ts"],"names":[],"mappings":""}

package/dist/agent-runtime/workflow.d.ts

@@ -0,0 +1,17 @@
+import type { RunWorkflowOptions, WorkflowState } from './workflow-types.js';
+export * from './workflow-types.js';
+export { readWorkflowState, readWorkflowEnvelope, writeWorkflowEnvelope, WorkflowStoreError, type WorkflowEnvelope } from './durable-store.js';
+export declare class WorkflowError extends Error {
+    readonly code: 'INVALID_WORKFLOW' | 'ALREADY_EXISTS' | 'NOT_FOUND' | 'INCOMPATIBLE_RESUME';
+    constructor(code: 'INVALID_WORKFLOW' | 'ALREADY_EXISTS' | 'NOT_FOUND' | 'INCOMPATIBLE_RESUME', message: string);
+}
+/**
+ * Execute a LangGraph state graph with a durable host ledger at every effect
+ * boundary. LangGraph owns traversal, state reducers, checkpoints, interrupts
+ * and time travel; the ledger owns receipts, usage, budgets, leases and
+ * interrupted-write recovery, and it is authoritative for which node runs
+ * next. Both are written through one atomic envelope, so they cannot disagree
+ * after a crash. Cancellation is cooperative; node callbacks must settle only
+ * after their owned subprocesses/tools have stopped.
+ */
+export declare function runWorkflow<S extends Record<string, unknown>>(options: RunWorkflowOptions<S>): Promise<WorkflowState>;