SDK API

import { createToolRegistry } from "@little-stack/workflow";
import { tool } from "ai";
import { z } from "zod";

const tools = createToolRegistry({
  parsePdf: tool({
    description: "Parse a PDF file and return structured text.",
    inputSchema: z.object({ url: z.string() }),
    outputSchema: z.object({ text: z.string() }),
    execute: async ({ url }) => { /* … */ return { text: "…" }; },
  }),
  lookupCustomer: tool({
    description: "Look up a customer account by id.",
    inputSchema: z.object({ accountId: z.string() }),
    execute: async ({ accountId }) => ({ accountId, plan: "enterprise" }),
  }),
});

type ToolRegistry = {
  readonly get: (id: string) => AiSdkTool | undefined;
  readonly has: (id: string) => boolean;
  readonly list: () => readonly string[];                       // sorted alphabetically
  readonly snapshotForManifest: () => ToolRegistrySnapshot;    // used in manifests + WorkflowVersion lock
  readonly attachMcpTools: (
    mcpTools: Record<string, AiSdkTool>,
    options?: { prefix?: string }
  ) => void;
  readonly toRecord: () => Record<string, AiSdkTool>;
};

export function createToolRegistry(
  initial?: Record<string, AiSdkTool>,
): ToolRegistry;

import { createMCPClient } from "@ai-sdk/mcp";
import { Experimental_StdioMCPTransport as StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";

const atlasClient = await createMCPClient({
  transport: new StdioMCPTransport({
    command: "node",
    args: ["./mcp-servers/atlas-mcp.mjs"],
  }),
});

const atlasTools = await atlasClient.tools();
tools.attachMcpTools(atlasTools, { prefix: "atlas" });
// registry now includes: parsePdf, lookupCustomer, atlas.search, atlas.fetch, …

await runWorkflow(workflow, input, { tools });
await atlasClient.close();

defineWorkflow(definition);
model(aiSdkModel, metadata?);
skill(pathOrUrl, options?);
asHarnessWorkflow(workflow, { definitionIdentity, executionMode?, ...runDefaults });
loadWorkflow(folder, options?);

import { defineWorkflow, runWorkflow } from "@little-stack/workflow";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";

const reviewApplicants = defineWorkflow({
  id: "applicants.review",
  input: z.object({ role: z.string(), applicants: z.array(z.object({ id: z.string(), resume: z.string() })) }),
  output: z.array(z.object({ id: z.string(), score: z.number(), decision: z.enum(["advance", "reject", "maybe"]) })),
  model: anthropic("claude-sonnet-4-6"),
});

const result = await runWorkflow(reviewApplicants, { role: "Staff Engineer", applicants });
result.output; // typed — no cast

import { defineWorkflow, model, skill } from "@little-stack/workflow";
import { openai } from "@ai-sdk/openai";

const candidateReview = defineWorkflow({
  // Identity
  id: "candidate.review",
  description: "Review one candidate against a job description.",

  // I/O schemas (Zod, Standard Schema or JSON Schema)
  input: z.object({
    jobDescription: z.string(),
    candidate: z.object({ id: z.string(), resume: z.string() }),
  }),
  output: z.object({
    passed: z.boolean(),
    reasoning: z.string(),
  }),

  // Execution model slots (planner chooses among these in LWIR)
  models: [
    model(openai("gpt-4o-mini")),
    model(openai("gpt-4o-mini"), {
      description: "Long-document summarizer.",
    }),
    // slot ids: "gpt-4o-mini" (first wins), "gpt-4o-mini-<animal>" (second)
  ],

  // Planner — optional; defaults to the first model. Its harness defaults to the SDK workflowHarness
  planner: {
    model: openai("gpt-5"),        // raw AI SDK model or ModelSlot
    system: "You design candidate-review workflows.",
    skills: [
      skill("./skills/writing-loop-lwir/"),
      skill("./skills/output-schema-validation.md"),
    ],
    // tools: optional extra tools beyond SDK-injected (bash, memory read)
    // supervise: optional outer-loop supervisor (see Outer Loop section)
  },

  // Worker — optional; defaults to the SDK workflowHarness.
  // worker: { harness: customHarness, skills: [...] },

  // Bash tool sandbox — optional; defaults shown in the field reference below
  bash: {
    network: {
      allow: ["https://api.example.com/"],
      methods: ["GET", "HEAD"],
    },
  },

  // Names of tools the run supplies (runWorkflow(..., { tools })); or AI SDK tools keyed by name
  tools: ["parsePdf", "lookupCustomer"],

  // Memory mount config — optional; defaults shown
  memory: {
    workflow: "rw",   // planner rw to /mnt/memory/workflow/
    org: "ro",        // ro to /mnt/memory/org/
    // attach: [{ id: "peer-workflow-id", mode: "ro" }],
  },
});

const input = z.object({ value: z.string() });

const echo = defineWorkflow({
  id: "starter_echo",
  input,
  tools: { echo: tool({ inputSchema: input, execute: async ({ value }) => ({ echoed: value }) }) },
  plan: {
    steps: [
      { id: "echo", uses: "tool.call", with: { tool: "echo", args: { value: "{{ input.value }}" } }, output: { mode: "json", schema: true } },
    ],
  },
});

type PlannerConfig = {
  readonly model: AiSdkModel | ModelSlot;     // raw AI SDK model OK; SDK auto-wraps
  readonly harness?: Harness;                 // defaults to workflowHarness
  readonly system?: string;                   // merged with SDK role addendum
  readonly skills?: readonly Skill[];
  readonly skillMaxRisk?: SkillRiskLevel;     // max accepted remote-skill risk for this role
  readonly skillOidcToken?: SkillOidcToken;   // token for the Skills API risk audit
  readonly tools?: ToolSet;                   // extra tools beyond SDK-injected
  readonly supervise?: (                      // outer-loop supervisor (optional)
    state: SuperviseOuterLoopState
  ) => Promise<SuperviseDecision>;
};

type WorkerConfig = {
  readonly harness?: Harness;               // defaults to workflowHarness
  readonly skills?: readonly Skill[];
  readonly skillMaxRisk?: SkillRiskLevel;
  readonly skillOidcToken?: SkillOidcToken;
  readonly tools?: ToolSet;                 // merged with the workflow's tools
};

type BashCapabilities = {
  readonly network?:
    | false
    | true
    | {
        readonly allow?: readonly string[];      // URL prefixes
        readonly methods?: readonly string[];    // default for `true`: ["GET", "HEAD"]
        readonly maxRedirects?: number;
        readonly timeoutMs?: number;
        readonly maxResponseSize?: number;
        readonly denyPrivateRanges?: boolean;    // default true
        readonly dangerouslyAllowFullInternetAccess?: boolean;
      };
  readonly python?: boolean;      // default true, inside the sandbox
  readonly javascript?: boolean;  // default true, inside the sandbox
};

type MemoryConfig = {
  readonly workflow?: "rw" | "ro" | "none";   // default: "rw"
  readonly org?: "rw" | "ro" | "none";        // default: "ro"
  readonly attach?: ReadonlyArray<{ id: string; mode: "ro" }>;
};

export function model(
  aiSdkModel: AiSdkModel,
  metadata?: ModelSelectionMetadata,
): ModelSlot;

export type ModelSelectionMetadata = {
  readonly id?: string;           // explicit override; must be unique in the workflow
  readonly description?: string;  // auto-filled from bundled registry if model is known
};

export function skill(pathOrUrl: string, options?: RemoteSkillOptions): Skill;

type Skill = {
  readonly kind: "skill";
  readonly source: string;
  readonly name?: string;
  readonly frontmatterHash?: string;
  readonly remote?: RemoteSkillIdentity;
} & RemoteSkillOptions;

type RemoteSkillOptions = {
  readonly skills?: readonly string[];
  readonly skillMaxRisk?: SkillRiskLevel;
  readonly skillRisk?: Record<string, SkillRiskLevel>;
  readonly auth?: SkillGitAuth;
};

type SkillRiskLevel = "NONE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";

type SkillGitAuth = {
  readonly type: "bearer";
  readonly token: string | undefined;
};

skill("./skills/writing-loop-lwir/");           // directory form
skill("./skills/output-schema-validation.md");  // single-file
skill("https://github.com/anthropics/skills", {
  skills: ["frontend-design"],
});                                             // selected remote skill names

import { createHarness } from "@little-stack/harness";
import { dynamicWorkflows } from "@little-stack/workflow";

createHarness({
  host,
  model,
  tools: { docsSearch },
  dynamicWorkflows: dynamicWorkflows({
    exclude: ["dangerousTool"],           // narrow below the agent's snapshot
    limits: { maxSteps: 6, maxRuntimeMs: 60_000 }, // defaults: 8 / 120000
  }),
});

dynamicWorkflows({
  registry: { resolve: (records) => records.filter((record) => approved.has(record.handle)) },
  world: (run) => tracingWorld(localWorld({ dataDir: run.dataDir }), run),
});

type OutputMode<T> =
  | { kind: "text" }
  | { kind: "object"; schema: Schema<T> }
  | { kind: "array"; element: Schema<T> }
  | { kind: "choice"; values: readonly string[] }
  | { kind: "json"; schema?: Schema<T> };

function runWorkflow<TWorkflow extends WorkflowDefinition>(
  workflow: TWorkflow,
  input: InferWorkflowInput<TWorkflow>,
  options?: RunWorkflowOptions,
): Promise<RunResult<InferWorkflowOutput<TWorkflow>>>;

import { localWorld, runWorkflow } from "@little-stack/workflow";

const result = await runWorkflow(reviewApplicants, { role: "Staff Engineer", applicants });
//                                                  world → localWorld(); inline tools wired in

const custom = await runWorkflow(candidateReview, { jobDescription, candidate }, {
  world: localWorld({ dataDir: ".little-workflow-reviews" }),
  tools,
  timeout: "10m",
});

// The same call, via the defined workflow's own method:
const same = await reviewApplicants.run({ role: "Staff Engineer", applicants });

type RunWorkflowOptions = {
  readonly world?: World;                         // default localWorld()
  readonly tools?: ToolRegistry;                  // default: the workflow's inline tools
  readonly mcp?: HarnessMcpConfig;                // declarative MCP servers → gateway tools
  readonly bash?: BashCapabilities;               // run-level Bash sandbox default
  readonly permissions?: ToolPermissions;         // allow/deny/ask gate over tool calls

  // Outer loop
  readonly maxOuterCycles?: number;               // default 1 (no outer loop); requires planner.supervise when > 1
  readonly outerLoopId?: string;                  // resume an existing outer-loop session

  // Execution
  readonly runId?: RunId;
  readonly signal?: AbortSignal;
  readonly timeout?: number | string;
  readonly maxAttempts?: number;

  // Labels, progress, reuse
  readonly label?: string;                        // overrides the definition's label (default: workflow id)
  readonly tags?: readonly string[];              // free-form tags for filtering runs
  readonly trigger?: RunTrigger;                  // how the run started, on its RunStarted event
  readonly progress?: (event: WorkflowRunProgressEvent) => void | Promise<void>; // { currentStep?, lastEvent? }
  readonly workflowVersionReuseStrategy?: WorkflowVersionReuseStrategy; // overrides the definition's
};

type RunTrigger = {
  readonly kind: string;        // "api", "schedule", "webhook", "harness", or your own word
  readonly source?: string;     // a route, a schedule id, a harness slug
  readonly from?: string;       // who asked, as the channel names them
  readonly label?: string;      // a short label for people
  readonly sessionId?: string;  // kind "harness": the session, turn and tool call that started the run
  readonly turnId?: string;
  readonly toolCallId?: string;
};

import { runOrchestration } from "@little-stack/workflow";

const result = await runOrchestration({
  workflows: [candidateReview, candidateScoring],
  input: { jobDescription, candidates: [...] },
  tools,
  orchestrator: {
    model: openai("gpt-5"),
    system: "Orchestrate candidate evaluation. For batch work, plan once + run many.",
    skills: [skill("./skills/batch-fan-out/")],
  },
  maxConcurrentSubRuns: 10,                       // default 10
});

type OrchestratorConfig = {
  readonly model: AiSdkModel | ModelSlot;
  readonly harness?: Harness;                // defaults to workflowHarness
  readonly system?: string;
  readonly skills?: readonly Skill[];
  readonly skillMaxRisk?: SkillRiskLevel;
  readonly skillOidcToken?: SkillOidcToken;
  readonly tools?: ToolSet;
  readonly bash?: BashCapabilities;          // orchestrator-session override
};

type LocalWorldOptions = {
  dataDir?: string;
  maxConcurrentSteps?: number;
};

localWorld({ dataDir: ".little-workflow", maxConcurrentSteps: 8 });

virtualWorld({ fs, dataDir: "/workflows", maxConcurrentSteps: 8 });

function readWorkflowVersion(world: World, workflowVersionId: string): Promise<StoredWorkflowPlan>;

type StoredWorkflowPlan = {
  readonly workflowVersionId: string;
  readonly workflowId: string;
  readonly lwir: LwirWorkflow;   // the plan; its steps are what the run executed
};

function gradeRun(world: World, runId: string, grade: GradeRunInput): Promise<RunGrade>;
function listRunGrades(
  world: World,
  filter?: { runId?: string; workflowVersionId?: string },
): Promise<readonly RunGrade[]>;

type GradeRunInput = {
  readonly verdict: "pass" | "fail";
  readonly reason?: string;      // the planner reads it when it reviews the plan
  readonly gradedBy?: string;
};

type RunGrade = GradeRunInput & {
  readonly gradeId: string;
  readonly runId: string;
  readonly workflowId: string;
  readonly workflowVersionId: string; // the plan the graded run executed
  readonly gradedAt: string;
};

function asHarnessWorkflow(
  workflow: WorkflowDefinition<any, any>,   // a defineWorkflow result, no cast
  options: HarnessWorkflowAdapterOptions,
): HarnessWorkflow;                          // pass to createHarness({ workflows }) from little-harness

type HarnessWorkflowAdapterOptions = Omit<RunWorkflowOptions, "trigger"> & {   // run defaults: tools, mcp, timeout, world, …
  readonly definitionIdentity: string | { readonly notApplicable: true; readonly reason?: string }; // required
  readonly executionMode?: "inline" | "durable";                       // default "inline"
  readonly allowUntypedInput?: boolean;
  readonly allowLossyStandardSchema?: boolean;
};

function versionedHarnessWorkflow<C>(
  source: WorkflowVersionSource<C>,               // e.g. LittleDB's db.managedWorkflow(...)
  build: (content: C) => WorkflowDefinition<any, any>,
  options?: VersionedHarnessWorkflowOptions,      // asHarnessWorkflow's options; definitionIdentity optional
): HarnessWorkflow;

type WorkflowVersionSource<C> = {
  readonly bootstrap: C;
  prepare(options: { stickyKey?: string }): Promise<{ content: C; world(inner: World): World }>;
};

function agentWorkflow(
  definition: AgentWorkflowDefinition,            // what define_workflow wrote, or a version LittleDB proposes
  bindings: { tools: Record<string, unknown>; models: Record<string, unknown>; planner: unknown },
): DefinedWorkflow;

function loadWorkflow<TInput = unknown, TOutput = unknown>(
  folder: string | URL,                      // contains workflow.ts (+ optional instructions.md, tools/, skills/)
  options?: {
    readonly workspaceRoot?: string | URL;   // default: nearest little-workflow.json, then package.json
    readonly executionMode?: "inline" | "durable";
    readonly allowUntypedInput?: boolean;
    readonly allowLossyStandardSchema?: boolean;
    readonly sourceIdentity?: string;        // required for durable mode with dynamic/unresolved imports
  },
): Promise<LoadedWorkflow<TInput, TOutput>>;

import { localWorld } from "@little-stack/workflow";
import {
  formatRunReport,
  materializeRunState,
  priceModelCall,
  runReport,
} from "@little-stack/workflow/internals";

const report = runReport(await materializeRunState(localWorld(), result.runId));
console.log(formatRunReport(report));      // the `little report --table` rendering

priceModelCall(
  { provider: "openai.responses", modelId: "gpt-4o-mini" },
  { inputTokens: 1_000, cachedInputTokens: 0, outputTokens: 200 },
).costUsd;                                 // number, or null when the model is not in the registry

type Harness = {
  readonly harnessId?: string;               // recorded in session manifests
  run(task: HarnessTask, ctx: HarnessContext): Promise<HarnessResult>;
};

type HarnessTask =
  | { readonly kind: "plan"; readonly workflowSnapshot: WorkflowDefinitionSnapshot; readonly input: unknown; readonly outerLoopContext?: OuterLoopContext }
  | { readonly kind: "orchestrate"; readonly available: readonly WorkflowDefinitionSnapshot[]; readonly input: unknown }
  | { readonly kind: "execute_step"; readonly step: LwirStep; readonly stepInput: unknown; readonly stepContext: { stepPath: string; visitIndex: number } }
  | { readonly kind: "fix_step"; readonly step: LwirStep; readonly stepInput: unknown; readonly originalAttemptError: ErrorEnvelope; readonly priorFixAttempts: number };

type HarnessContext = {
  readonly scope: HarnessScope;
  readonly session: {                        // run id, role, task kind, manifest + hash, parent run id
    readonly runId: string;
    readonly role: HarnessRole;
    readonly task: { readonly kind: HarnessTask["kind"] };
    readonly manifest: unknown;
    readonly manifestHash: string;
    readonly parentRunId?: string;
  };
  readonly model: ResolvedModel;
  readonly system?: string;
  readonly tools: ToolSet;
  readonly memoryMounts: readonly MemoryMount[];
  readonly scratchMounts: readonly ScratchMount[];
  readonly skills: readonly SkillDescriptor[];
  readonly mounts: readonly HarnessRuntimeMount[];
  readonly bashCapabilities?: WorkflowBashCapabilities;
  readonly durability: WorkflowHarnessDurabilitySink;
  readonly trace?: WorkflowHarnessTraceSink;
  readonly abortSignal: AbortSignal;
  readonly permissions?: ToolPermissions;    // the run's allow/deny/ask policy, when set
  readonly bash?: BashTool;
  readonly recorder?: HarnessEventRecorder;
};

type HarnessResult =
  | { readonly kind: "plan"; readonly lwir: unknown }
  | { readonly kind: "orchestrate"; readonly output: unknown }
  | { readonly kind: "execute_step"; readonly output: unknown; readonly artifactRefs: readonly ArtifactRef[] }
  | { readonly kind: "fix_step"; readonly output: unknown; readonly fixedSource: string; readonly attempts: number }
  | { readonly kind: "delegate_to_default" };   // fall back to workflowHarness for this task kind

type OrchestratorManifest = {
  readonly harnessId: string;
  readonly orchestratorModelSlotId: string;
  readonly systemPromptHash: string;
  readonly skillsHash: string;
  readonly availableWorkflows: ReadonlyArray<{ readonly id: string; readonly definitionHash: string }>;
  readonly globalToolsHash: string;
  readonly memoryStoreIds: ReadonlyArray<string>;
  readonly bashCapabilitiesHash: string;
  readonly maxConcurrentSubRuns: number;
};

type PlannerManifest = {
  readonly harnessId: string;
  readonly plannerModelSlotId: string;
  readonly systemPromptHash: string;
  readonly skillsHash: string;
  readonly workflowDefinitionHash: string;
  readonly globalToolsHash: string;
  readonly memoryStoreIds: ReadonlyArray<string>;
  readonly bashCapabilitiesHash: string;
  readonly outerLoopContextHash?: string;
};

type WorkerManifest = {
  readonly harnessId: string;
  readonly workflowDefinitionHash: string;
  readonly workflowVersionId: string;
  readonly stepPath: string;
  readonly stepConfigHash: string;
  readonly modelSlotId?: string;
  readonly systemPromptHash?: string;
  readonly skillsHash: string;
  readonly allowedToolsHash: string;
  readonly memoryStoreIds: ReadonlyArray<string>;
  readonly bashCapabilitiesHash: string;
};

type FixerManifest = WorkerManifest & {
  readonly fixerModelSlotId: string;
  readonly fixerSystemHash: string;
  readonly fixerMaxAttempts: number;
};

type SuperviseOuterLoopState = {
  readonly goal: {
    readonly workflowDefinitionHash: string;
    readonly description: string;
  };
  readonly cycles: ReadonlyArray<{
    readonly cycleNumber: number;
    readonly workflowVersionId: string;
    readonly runId: string;
    readonly status: "completed" | "failed";
    readonly output: unknown;
    readonly summary?: string;
  }>;
};

type SuperviseDecision =
  | { readonly kind: "done"; readonly finalOutput: unknown }
  | { readonly kind: "continue"; readonly promptNote?: string };

class RunFailedError extends Error {
  readonly runId: string;
  readonly workflowVersionId: string;
  readonly failedStepPath?: string;
  readonly causeCode: RunFailedCauseCode;
  readonly result?: FailedRunResult;
  readonly outerLoopId?: string;
  readonly lastCycleOutput?: unknown;
}

type RunFailedCauseCode =
  | "input_schema_error"
  | "planner_validation_exhausted"
  | "capability_drift"
  | "runtime_config_error"
  | "step_schema_error"
  | "step_failed"
  | "max_visits_exceeded"
  | "timeout"
  | "cancelled"
  | "outer_loop_exhausted";

function isRunFailedError(value: unknown): value is RunFailedError;

import { isRunFailedError, runWorkflow } from "@little-stack/workflow";

try {
  await runWorkflow(workflow, input);
} catch (err) {
  if (!isRunFailedError(err)) throw err;
  console.error(err.runId, err.causeCode, err.failedStepPath);
}

type ToolSelectionPolicy = "planner_selected" | "all" | "explicit_only";