Core Type Reference

type SmithersWorkflow<Schema> = {
  db: unknown;
  build: (ctx: SmithersCtx<Schema>) => React.ReactElement;
  opts: SmithersWorkflowOptions;
  schemaRegistry?: Map<string, SchemaRegistryEntry>;
};

type SmithersWorkflowOptions = {
  cache?: boolean;
};

type SchemaRegistryEntry = {
  table: any;
  zodSchema: import("zod").ZodObject<any>;
};

interface SmithersCtx<Schema> {
  runId: string;
  iteration: number;
  iterations?: Record<string, number>;
  input: Schema extends { input: infer T } ? T : any;
  auth: RunAuthContext | null;
  outputs: OutputAccessor<Schema>;

  output<T extends keyof Schema>(
    table: Schema[T],
    key: OutputKey,
  ): InferRow<Schema[T]>;

  outputMaybe<T extends keyof Schema>(
    table: Schema[T],
    key: OutputKey,
  ): InferRow<Schema[T]> | undefined;

  latest(table: any, nodeId: string): any;

  latestArray(value: unknown, schema: import("zod").ZodType): any[];

  iterationCount(table: any, nodeId: string): number;
}

type OutputKey = {
  nodeId: string;
  iteration?: number;
};

type OutputAccessor<Schema> = ((table: any) => any[]) & Record<string, any[]>;

type InferRow<TTable> = TTable extends { $inferSelect: infer R } ? R : never;

type RunOptions = {
  runId?: string;
  parentRunId?: string;
  input: Record<string, unknown>;
  maxConcurrency?: number;
  onProgress?: (e: SmithersEvent) => void;
  signal?: AbortSignal;
  resume?: boolean;
  force?: boolean;
  workflowPath?: string;
  rootDir?: string;
  logDir?: string | null;
  allowNetwork?: boolean;
  maxOutputBytes?: number;
  toolTimeoutMs?: number;
  hot?: boolean | HotReloadOptions;
  auth?: RunAuthContext;
  cliAgentToolsDefault?: "all" | "explicit-only";
};

type HotReloadOptions = {
  rootDir?: string;
  outDir?: string;
  maxGenerations?: number;
  cancelUnmounted?: boolean;
  debounceMs?: number;
};

type RunResult = {
  runId: string;
  status: "finished" | "failed" | "cancelled" | "continued" | "waiting-approval" | "waiting-event" | "waiting-timer";
  output?: unknown;
  error?: unknown;
};

type RunStatus =
  | "running"
  | "waiting-approval"
  | "waiting-event"
  | "waiting-timer"
  | "finished"
  | "continued"
  | "failed"
  | "cancelled";

type TaskDescriptor = {
  nodeId: string;
  ordinal: number;
  iteration: number;
  ralphId?: string;
  dependsOn?: string[];
  needs?: Record<string, string>;
  worktreeId?: string;
  worktreePath?: string;
  worktreeBranch?: string;

  outputTable: Table | null;
  outputTableName: string;
  outputRef?: import("zod").ZodObject<any>;
  outputSchema?: import("zod").ZodObject<any>;

  parallelGroupId?: string;
  parallelMaxConcurrency?: number;

  needsApproval: boolean;
  approvalMode?: "gate" | "decision";
  approvalOnDeny?: "fail" | "continue" | "skip";
  skipIf: boolean;
  retries: number;
  retryPolicy?: RetryPolicy;
  timeoutMs: number | null;
  continueOnFail: boolean;
  cachePolicy?: CachePolicy;

  agent?: AgentLike | AgentLike[];
  prompt?: string;
  staticPayload?: unknown;
  computeFn?: () => unknown | Promise<unknown>;

  label?: string;
  meta?: Record<string, unknown>;
};

type AgentLike = Agent<any, any, any>;

type RetryBackoff = "fixed" | "linear" | "exponential";

type RetryPolicy = {
  backoff?: RetryBackoff;
  initialDelayMs?: number;
};

type RetryTaskOptions = {
  runId: string;
  nodeId: string;
  iteration?: number;
  resetDependents?: boolean;
  force?: boolean;
  onProgress?: (event: SmithersEvent) => void;
};

type RetryTaskResult = {
  success: boolean;
  resetNodes: string[];
  error?: string;
};

type CachePolicy<Ctx = any> = {
  by?: (ctx: Ctx) => unknown;
  version?: string;
};

type GraphSnapshot = {
  runId: string;
  frameNo: number;
  xml: XmlNode | null;
  tasks: TaskDescriptor[];
};

type XmlNode = XmlElement | XmlText;

type XmlElement = {
  kind: "element";
  tag: string;
  props: Record<string, string>;
  children: XmlNode[];
};

type XmlText = {
  kind: "text";
  text: string;
};

type SmithersEvent =
  | RunStarted
  | RunStatusChanged
  | RunFinished
  | RunFailed
  | RunCancelled
  | RunContinuedAsNew
  | RunHijackRequested
  | RunHijacked
  | FrameCommitted
  | NodePending
  | NodeStarted
  | NodeFinished
  | NodeFailed
  | NodeCancelled
  | NodeSkipped
  | NodeRetrying
  | NodeWaitingApproval
  | ApprovalRequested
  | ApprovalGranted
  | ApprovalDenied
  | ToolCallStarted
  | ToolCallFinished
  | NodeOutput
  | AgentEvent
  | RevertStarted
  | RevertFinished
  | WorkflowReloadDetected
  | WorkflowReloaded
  | WorkflowReloadFailed
  | WorkflowReloadUnsafe
  | ScorerStarted
  | ScorerFinished
  | ScorerFailed
  | TokenUsageReported;

type WorkflowProps = {
  name: string;
  cache?: boolean;
  children?: React.ReactNode;
};

type TaskProps<Row, Output, D extends DepsSpec = {}> = {
  key?: string;
  id: string;
  output: Output;
  outputSchema?: import("zod").ZodObject<any>;
  agent?: AgentLike | AgentLike[];
  fallbackAgent?: AgentLike;
  dependsOn?: string[];
  needs?: Record<string, string>;
  deps?: D;
  skipIf?: boolean;
  needsApproval?: boolean;
  timeoutMs?: number;
  retries?: number;
  retryPolicy?: RetryPolicy;
  continueOnFail?: boolean;
  cache?: CachePolicy;
  scorers?: ScorersMap;
  label?: string;
  meta?: Record<string, unknown>;
  children: string | Row | (() => Row | Promise<Row>) | React.ReactNode | ((deps: InferDeps<D>) => Row | React.ReactNode);
};

type SequenceProps = {
  skipIf?: boolean;
  children?: React.ReactNode;
};

type ParallelProps = {
  id?: string;
  maxConcurrency?: number;
  skipIf?: boolean;
  children?: React.ReactNode;
};

type BranchProps = {
  if: boolean;
  then: React.ReactElement;
  else?: React.ReactElement;
  skipIf?: boolean;
};

type LoopProps = {
  id?: string;
  until: boolean;
  maxIterations?: number;
  onMaxReached?: "fail" | "return-last";
  skipIf?: boolean;
  children?: React.ReactNode;
};

type RalphProps = LoopProps;

type ApprovalProps<Row = ApprovalDecision> = {
  id: string;
  output: ZodObject<any> | Table | string;
  outputSchema?: import("zod").ZodObject<any>;
  request: ApprovalRequest;
  onDeny?: "fail" | "continue" | "skip";
  dependsOn?: string[];
  needs?: Record<string, string>;
  skipIf?: boolean;
  timeoutMs?: number;
  retries?: number;
  retryPolicy?: RetryPolicy;
  continueOnFail?: boolean;
  cache?: CachePolicy;
  label?: string;
  meta?: Record<string, unknown>;
  key?: string;
  children?: React.ReactNode;
};

type ApprovalRequest = {
  title: string;
  summary?: string;
  metadata?: Record<string, unknown>;
};

type ApprovalDecision = {
  approved: boolean;
  note: string | null;
  decidedBy: string | null;
  decidedAt: string | null;
};

type SmithersError = {
  code: SmithersErrorCode;
  message: string;
  summary: string;
  docsUrl: string;
  details?: Record<string, unknown>;
  cause?: unknown;
};

type SmithersErrorCode =
  | KnownSmithersErrorCode
  | (string & {});

type KnownSmithersErrorCode =
  | "INVALID_INPUT"
  | "MISSING_INPUT"
  | "MISSING_INPUT_TABLE"
  // ... all built-in Smithers runtime codes

type ServerOptions = {
  port?: number;
  db?: BunSQLiteDatabase<any>;
  authToken?: string;
  maxBodyBytes?: number;
  rootDir?: string;
  allowNetwork?: boolean;
};

type ServeOptions = {
  workflow: SmithersWorkflow<any>;
  adapter: SmithersDb;
  runId: string;
  abort: AbortController;
  authToken?: string;
  metrics?: boolean;
};

type ToolContext = {
  db: SmithersDb;
  runId: string;
  nodeId: string;
  iteration: number;
  attempt: number;
  rootDir: string;
  allowNetwork: boolean;
  maxOutputBytes: number;
  timeoutMs: number;
  seq: number;
};