Changelog

This page summarizes the changes that matter to Little Workflow users. The full, authoritative history for both little-workflow and little-harness, which share one version line, is the repository CHANGELOG.md. These docs keep the v0.1.0-alpha URL path for stable links, but they describe the current release.

Little Workflow is in its alpha phase: the LWIR wire format, public APIs, and persistence formats can change between alpha releases.

Unreleased (review preview)

These changes are in the current source only. No npm version includes them, and no version number has been assigned.

• Setup recovery reports its outcome. @little-stack/workflow/scaffold adds recoverSetup(), which returns nothing-to-recover, rolled-back, completed-cleanup or manual-recovery-required plus the preserved paths. rollbackSetup() is no longer exported; read retained from recoverSetup(). little setup --rollback needs a project directory or --here, prints a distinct message per outcome, and exits with an error when manual recovery is required. See Setup Recovery.
• One way to define and run a workflow. runWorkflow(workflow, input, options?) is the only run form; world is optional and defaults to localWorld(), and workflow.run(input, options?) takes the same options. The options-object form is removed: the deprecated orchestrator moves to runOrchestration({ workflows, orchestrator, input }). defineWorkflow now takes the full config (models, a PlannerConfig, toolSelection, workflowVersionReuseStrategy, a ToolRegistry or tool names under tools, suggestedInput) and a fixed plan that runs without a planner model; createLittleWorkflow moves to @little-stack/workflow/internals. See Define a Workflow and Run A Workflow.
• Explicit entry points. The root exports only the define, run, replay and Harness-composition API, plus isRunFailedError. LWIR validation moves to @little-stack/workflow/lwir, eval sets to @little-stack/workflow/eval, and runtime, world-storage, harness and pricing plumbing (listEvents, materializeRunState, workflowHarness, runReport, …) to @little-stack/workflow/internals, which has no semver guarantees. Use world.listEvents(runId) for events. Test helpers are no longer exported. See SDK API.
• One scaffolder vocabulary. In little setup, --here only means the current directory; add Little to an existing Next.js app with --template existing-next. little setup, little init and little-harness init default to the openai provider. little init and little add harness name a workflow with --workflow-name, and init rejects --yes/--no-install. The --workflow starter is a fixed-plan starter_echo workflow. See CLI.
• ai.generate prompts resolve expressions, and the step gets no tools. {{ ... }} expressions in with.prompt and with.system are resolved at run time with the same roots as input; before, they reached the model as literal braces. with.system now reaches the model after the worker's system prompt; before, it was dropped. The default worker harness no longer offers an ai.generate step the workflow's tools or bash in any output mode. Text-output steps used to be offered them, but a tool call only ended the step with empty output. Call tools from a tool.call step. See LWIR.
• Saved plans are kept without a planner call when nothing changed. With the default workflowVersionReuseStrategy: "planner_reviewed", a run whose definition, tools, model slots, output contract and input shape all match the newest successful WorkflowVersion keeps it without calling the planner; only the input values differ. Once the planner has reviewed a change and kept the plan, later runs keep it the same way. Anything the planner would read differently still sends the candidate to the planner for review. The planner prompt also asks the model to copy a policy in the workflow description word for word and add no rules of its own. See Run A Workflow.
• result.plan says which plan ran. Every completed runWorkflow result has plan: { kind, plannerCalled, workflowVersionId, previousWorkflowVersionId?, rationale? }, where kind is "drafted", "kept", "adapted" or "fixed". readWorkflowVersion(world, id) reads the steps a run executed, and little run prints plan. runOrchestration results have no plan. See Which Plan Ran.
• workflowVersionReuseStrategy: "planner_reviews_each_run" shows the planner the newest plan on every run, as "planner_reviewed" did before. Use it when input values change what the plan should be.
• defineWorkflow({ policy }). Rules every model step must follow. The runtime adds the policy, word for word, to the system prompt of every ai.generate step, whoever wrote the plan; the planner sees it and a change sends a saved plan back for review. See A policy.
• Graded runs. gradeRun(world, runId, { verdict, reason?, gradedBy? }) records whether a run did its job, and listRunGrades reads the grades back. A "fail" grade sends the plan that run executed back to the planner with the reason on the next run. See Grading Runs.
• Missing needs in a drafted plan are added. When a planner's draft reads an earlier step's output without listing it in needs, the compiler adds the entry instead of sending the draft back for a repair call. A reference to a missing step, from a parallel body to an outer step, or one that would close a cycle is still a validation error, and a fixed plan must still list its own needs. See Needs A Planner Left Out.
• Little Harness source changes that Workflow users may meet, such as typed parked turn results, broader reserved tool names and the mandatory durable append identity, are listed with their migrations on the Little Harness Alpha Migrations page. See Releases for the status of every product.

0.2.0-alpha.1

A little-workflow-only release; little-harness stays at 0.2.0-alpha.0. It adds little setup, which creates a Node or Next.js project with a Little Harness agent and, with --workflow, a sample workflow, or adds them to an existing Next.js app. Setup is keyless by default, disables dependency lifecycle scripts, previews with --plan without writing, and journals its writes so an interrupted run can be recovered with --rollback. little-workflow/scaffold exports planSetup(), applySetupPlan() and rollbackSetup().

0.2.0-alpha.0

The first npm release since 0.1.0-alpha.1, and the first Apache-2.0 release on npm. Install with pnpm add little-workflow@alpha ai@^7 zod @ai-sdk/<provider>.

Breaking changes

• AI SDK 7 and Node.js 22. ai is now a peer dependency (^7.0.0) instead of a bundled one, so install ai@^7 and an AI SDK 7 provider package. AI SDK 6 is no longer supported, and Node.js 22 or later is required.
• Tool context key. Code that reads callerRunIdentity, sequenceIndex, modelStepId, or a workflow signal inside a tool must read it from the AI SDK 7 context execute option instead of experimental_context.
• Workflow run storage under a harness. Runs started from a Little Harness agent are stored under the harness session's data directory (<dataDir>/sessions/<session>/workflows), not <cwd>/<sessionId>/workflows. Runs recorded under the old path are not found on resume.
• Orchestrator deprecated (LWF_DEP_ORCHESTRATOR). runWorkflow({ workflows: [...], orchestrator }), the plan_workflow / run_workflow / start_workflow tools, createOrchestratorTools, and workflowSnapshotsForOrchestrator still work but emit a one-time DeprecationWarning. Compose with defineWorkflow → asHarnessWorkflow → createHarness({ workflows }) instead; see Compose With Little Harness.
• Stricter LWIR. Declared-but-unimplemented fields are rejected with schema.unimplemented_field instead of being accepted and ignored. These are non-empty permissions.secrets / permissions.network, onFailure.repair.mode: "escalate", onFailure.repair.model, and step cache. Records keyed by a non-string schema (z.record(z.number(), V)) are rejected.
• Pinned scaffolds. little init / little add write the CLI's own version and AI SDK 7-compatible ranges instead of latest.

Added

• defineWorkflow with a typed runWorkflow(definition, input) and definition.run(input), plus folder workflows (little-workflow.json + workflows/<name>/workflow.ts) loaded with loadWorkflow.
• asHarnessWorkflow adapts a workflow into a Little Harness tool. It accepts a defineWorkflow result directly and requires definitionIdentity.
• Workflow tool results carry an outputSummary, a compact rendering of the output capped at 4,096 characters, so the calling model sees what the run produced.
• Bounded fan-out on the Harness surface. workflowBudgets.maxConcurrentWorkflowRuns / maxQueuedWorkflowRuns bound inline workflow-tool calls with a FIFO queue.
• Dynamic workflows. dynamicWorkflows() lets a Little Harness agent author and run a one-shot step-DAG plan.
• Real USD costs per step, session, and run (RunResult.usage.costUsd, runReport / formatRunReport, priceModelCall), from a bundled model registry with pricing provenance and a staleness gate.
• CLI: little init, little add workflow|harness, little test, and little report (JSON or --table). little init --help and little add --help print usage.
• Schemas: the annotation keywords description, title, and examples are accepted, so .describe() works. propertyNames is accepted for string- and enum-keyed z.record(...) and enforced at run time.
• lwir-input-cone@v1 (inputConeHash / inputConeSnapshot) and experimental eval-set bundles with a local content-addressed store.
• ai.generate steps repair malformed structured output themselves.

Changed and fixed

• The AI SDK adapter targets AI SDK 7: instructions instead of system, and usage as the all-steps total.
• Cached input and reasoning tokens are read from AI SDK 7's inputTokenDetails / outputTokenDetails. Before this fix, cached input was priced at the full rate.
• Registry prices were corrected and delisted models removed.
• little init writes pnpm.onlyBuiltDependencies: ["better-sqlite3"] so pnpm 10 builds the event store's native binding. little init / little add reject unknown options.
• Package exports use the default condition and expose ./package.json.

Earlier releases

• 0.1.0-alpha.2 (tagged, never published to npm) relicensed the project under Apache-2.0.
• 0.1.0-alpha.1 was the initial public alpha. It included workflow authoring, planner compilation, LWIR validation, durable Local World execution and replay, and the little CLI.

See the Roadmap for direction beyond the alpha.