# Build Step-by-step guides for building with Loopstack — getting started, workflow fundamentals, AI/LLM integration, workflow patterns, and third-party integrations. --- > Source: https://loopstack.ai/llms/build/add-to-existing-app.md --- title: Add to an Existing App description: Add Loopstack to an existing NestJS project by hand — install @loopstack/loopstack-module, register LoopstackModule.forRoot(), enable shutdown hooks, bundle YAML assets in nest-cli.json, provide PostgreSQL and Redis (Docker Compose or DATABASE_URL/REDIS_URL), and write your first workflow. Covers the Node.js 20.19+/22 baseline, the ESM-only requirement (type module, nodenext, .js extensions), and the zod v4 peer-dependency requirement. --- # Add to an Existing App Already have a NestJS backend? Wire Loopstack into it directly. Starting fresh instead? [`loopstack create`](./getting-started.md) scaffolds all of this — module, config, a hello workflow, Docker Compose, and a `.env` — in one command. ## Requirements - **Node.js 20.19+ (or 22 LTS).** Loopstack ships as native ESM, which needs the `require(esm)` support added in Node 20.19 / 22. - **An ESM app.** Loopstack is ESM-only (no CommonJS build), so your project must be ESM too — `"type": "module"` in `package.json`, `module`/`moduleResolution` set to `nodenext` in `tsconfig.json`, and `.js` extensions on relative imports. A CommonJS project has to migrate to ESM first. ## 1. Install the module ```shell npm install @loopstack/loopstack-module ``` ## 2. Register the module Add `LoopstackModule` to the imports in `src/app.module.ts`: ```typescript import { Module } from '@nestjs/common'; import { LoopstackModule } from '@loopstack/loopstack-module'; @Module({ imports: [LoopstackModule.forRoot()], }) export class AppModule {} ``` Enable shutdown hooks in `src/main.ts` so the workflow engine shuts down gracefully — on SIGTERM (a deploy, `docker stop`) running workflows finish their current transition, stop before the next one and queue their continuation, which the next process picks up: ```typescript async function bootstrap() { const app = await NestFactory.create(AppModule); app.enableShutdownHooks(); await app.listen(process.env.PORT ?? 3000); } ``` The drain waits at most `SHUTDOWN_DRAIN_TIMEOUT_MS` (30 seconds by default) for runs to yield, then closes by force; a second Ctrl+C does the same at once. See [Configuration](../reference/configuration.md#scheduler). Add YAML asset bundling to `nest-cli.json` so workflow UI configs are included in the build: ```json { "compilerOptions": { "assets": ["**/*.yaml"] } } ``` ## 3. Provide Postgres & Redis Loopstack needs a PostgreSQL and a Redis instance. There are two equally good ways to provide them: **Option A — Docker (quickest locally).** The module ships a Compose file for Postgres and Redis: ```shell docker compose -f node_modules/@loopstack/loopstack-module/docker-compose.yml up -d ``` Want the visual [Studio](../learn/studio.md) UI too? Start it alongside — it's a separate, optional compose file: ```shell docker compose -f node_modules/@loopstack/loopstack-module/docker-compose.studio.yml up -d ``` **Option B — Bring your own.** Point the app at any existing Postgres and Redis (managed, hosted, or already running) via `.env`: ```dotenv DATABASE_URL=postgres://user:password@host:5432/dbname REDIS_URL=redis://host:6379 ``` > CI and coding agents should use Option B (point the URLs at an available instance) and drive workflows from the [CLI](../reference/cli.md), not the browser-based Studio. ## 4. Write your first workflow Create `src/hello/hello.workflow.ts` — a single class with one transition: ```typescript import { z } from 'zod'; import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common'; import type { RunContext } from '@loopstack/common'; const InputSchema = z.object({ name: z.string().default('World'), }); type InputArgs = z.infer; @Workflow({ title: 'Hello World', description: 'Greets you by name — replace this with your first real workflow.', schema: InputSchema, }) export class HelloWorkflow extends BaseWorkflow { @Transition({ from: 'start', to: 'end' }) async greet(_state: unknown, ctx: RunContext) { const greeting = `Hello, ${ctx.args.name}! 👋`; await this.documentStore.save(MessageDocument, { role: 'assistant', text: greeting }); this.assignResult({ greeting }); } } ``` Create `src/hello/hello.module.ts` — `@StudioApp` groups workflows into an app: ```typescript import { Module } from '@nestjs/common'; import { StudioApp } from '@loopstack/common'; import { HelloWorkflow } from './hello.workflow'; @StudioApp({ title: 'My First App', workflows: [HelloWorkflow], }) @Module({ providers: [HelloWorkflow], }) export class HelloModule {} ``` Register it in `src/app.module.ts`: ```typescript import { Module } from '@nestjs/common'; import { LoopstackModule } from '@loopstack/loopstack-module'; import { HelloModule } from './hello/hello.module'; @Module({ imports: [LoopstackModule.forRoot(), HelloModule], }) export class AppModule {} ``` ## 5. Run ```shell npm run start:dev # http://localhost:3000 ``` Run the workflow from the terminal — the CLI talks to the local backend with no login: ```shell npx @loopstack/cli run hello --arg name=You ``` It streams each transition and the result live, and returns CI-friendly exit codes. Prefer a visual UI? Start Studio (step 3) and open [http://localhost:5173](http://localhost:5173). This first workflow is zero-config — no API keys needed. To make a workflow call an LLM, see [AI Text Generation](./ai/text-generation.md). ## Next steps - [Core Concepts](../learn/core-concepts.md) — workflows, tools, documents, and providers - [Creating Workflows](./fundamentals/workflows.md) — transitions, guards, state, and wait patterns - [AI Text Generation](./ai/text-generation.md) — add LLM calls to your workflows ## zod version (reference) Loopstack requires **zod v4** — it uses the v4-only `z.toJSONSchema()` API to turn workflow input schemas into JSON Schema. npm 7+ installs it automatically as a peer dependency when you run `npm install @loopstack/loopstack-module`, so you don't normally need to install it yourself. Older tutorials may show `zod@^3`; that won't resolve against Loopstack's peer constraint and `npm install` will fail with `ERESOLVE`. --- > Source: https://loopstack.ai/llms/build/best-practices.md --- title: Best Practices description: Design judgment for building with Loopstack's core building blocks — workflows (scripted vs agentic, where logic belongs, state vs result vs documents, error strategy), tools (single responsibility, schema/description as the LLM contract, idempotency), documents (a user-facing surface, not a data store), and modules / Studio apps (organize by feature, @StudioApp as a deliberate boundary). The principles every developer and agent should carry into the code. --- # Best Practices The other guides in this section show _how_ each mechanism works. This page is about _judgment_: which concept to reach for, why, and how to keep things clean as they grow. It is the knowledge every developer — and every agent — should carry into Loopstack before writing the first line. None of it is API detail; it is the professional shape of clean Loopstack code. The through-line for all four building blocks is the same: **optimize for legibility.** Someone reading your code should understand the system without running it. ## Workflows A workflow is a **state machine**, and its highest virtue is legibility. Someone scanning your transitions should understand the process without executing it. ### Think in narratives, not steps A workflow's places (states) and transitions are a story. Name them so the story reads top to bottom: ``` start → fetch_data → summarize → waiting_for_approval → publish → end ``` Good place names describe _where the workflow is_; good transition method names describe _the step being taken_ (`fetchData`, `summarize`, `publish`). When the state machine reads like prose, routing bugs become visible and onboarding is free. Avoid abstract names (`step1`, `process2`, `handlerA`) — name things for what they do, never for an invented taxonomy. ### Scripted by default; agentic only when the path is open-ended Loopstack gives you two modes for doing work: - **Scripted** — you write the transitions. The path is fixed and deterministic. - **Agentic** — an `AgentWorkflow` runs an LLM tool-calling loop and _decides_ the path at runtime. **Default to scripted.** Determinism is cheaper, faster, testable, and debuggable. Reach for an agent only when the sequence of steps genuinely cannot be known in advance — open-ended exploration, research, or tasks where the next action depends on what the previous one discovered. The best designs are usually **hybrid**: a deterministic workflow that scaffolds the run (validate input → prepare context → _contained agent step_ → validate output → publish). The agent gets autonomy only where autonomy is needed; everything around it stays predictable. An agent is a tool you place _inside_ a clear process, not a replacement for having one. ### Thin transitions, fat tools Logic has two homes, and putting it in the wrong one is the most common source of unmaintainable workflows. - **Transitions orchestrate.** They decide what happens next and move state. Keep their bodies short — read inputs, call a tool or a sub-workflow, write state, done. - **Tools do the work.** Domain logic belongs in a tool: one tool, one responsibility, a narrow Zod input schema, and a clear description. Why this split pays off: a tool is reusable across workflows, independently testable, and — because tools carry a description and schema — it doubles as an LLM function with zero extra work. Logic inlined in a transition is none of those things. ```typescript // Avoid: business logic living in the transition @Transition({ from: 'ready', to: 'done' }) async process(state: MyState) { const rows = await db.query(...); // domain logic const filtered = rows.filter(...); // domain logic this.assignState({ count: filtered.length }); } // Prefer: the transition orchestrates, the tool does the work @Transition({ from: 'ready', to: 'done' }) async process(state: MyState) { const result = await this.fetchActiveUsers.call({ since: state.since }); this.assignState({ count: result.data.length }); } ``` ### Know your three data surfaces: state, result, documents Workflows expose data in three places. Choosing the wrong one is the subtlest and most common smell. | Surface | What it is | Use it for | | ------------- | ------------------------------------------------ | ---------------------------------------------------- | | **State** | Internal working memory, persisted across pauses | Intermediate values the workflow needs to do its job | | **Result** | The workflow's _published output_ | The contract consumers and parent workflows read | | **Documents** | Typed objects rendered in Studio | Everything the _user_ should see | The rules of thumb: - **Keep state minimal.** It is scratch space, not an output channel. If a value only matters mid-run, it stays in state and never leaves. - **Design the result as a deliberate contract.** It is the public API of your workflow — what a parent receives in a callback, what a consumer depends on. Publish a clean, intentional shape with `setResult` / `assignResult`. Never dump raw internal state into the result. - **Documents are for humans.** If a value needs to be _seen_, save a document. If it needs to be _consumed by code_, it belongs in the result. They are not interchangeable. ### Extract a sub-workflow for a reason, not by reflex One readable workflow beats five fragmented ones. Split only when there is a concrete payoff: - **Reuse** — the same unit of work is needed in more than one place. - **Independent lifecycle or UI** — the unit pauses for its own input, or should render as its own panel/link in Studio. - **Fan-out** — you need to run the unit in parallel or in sequence over a list. If none of those apply, keep it inline. Premature decomposition trades one clear flow for orchestration overhead. And when you _do_ split, name the sub-workflow for what it accomplishes — never `sub-workflow-a` or `type-2-handler`. ### Pause only for genuinely external events A `wait` transition pauses the workflow until something outside it happens: a user clicks a button, a sub-workflow completes, an API calls back. That is the _only_ reason to wait. Never use waiting to poll or to "give something time." If you find yourself waiting and re-checking, the work should be a callback instead. Waiting is for handing control out and getting it back — not for busy-looping. ### Commit user input before slow work A transition's documents become visible when the transition **commits** — at the end of its body. If one transition stores the user's input _and_ does slow work (an LLM call, an external request), the input stays invisible until the whole turn finishes; in a chat, the assistant's streamed reply appears before the user's own message. Split them: the wait transition stores the input and completes (a fast commit — the message renders immediately), and the next automatic transition does the slow work. ```typescript @Transition({ from: 'waiting_for_user', to: 'generating_reply', wait: true, schema: z.string() }) async userMessage(state: ChatState, input: TransitionInput) { await this.documentStore.save(LlmMessageDocument, { role: 'user', text: input.data }); } @Transition({ from: 'generating_reply', to: 'waiting_for_user' }) async generateReply() { await this.llmGenerateText.call({}, { config: { ... } }); } ``` This is granularity working for you: every transition boundary is a UI update, so slicing transitions by "what should the user see, and when" gives responsive runs without any frontend tricks. ### Keep guards pure Guards decide routing when several transitions share a `from` place. Treat them as **pure predicates over state**: they read, they return a boolean, they do nothing else. A guard that mutates state, calls a tool, or has a side effect makes routing impossible to reason about and impossible to test in isolation. Compute the decision inputs in a transition, store them in state, and let the guard read them. The guard is the single, visible source of routing truth. ### Choose an error strategy by failure type Not all failures are equal. Match the recovery mode to the _kind_ of failure: | Failure kind | Strategy | | ------------------------------------------ | --------------------------------------------------------------------------- | | Transient (network blip, rate limit) | **Auto-retry** | | User-fixable (bad input, missing approval) | **Error place / manual retry** — surface it and let the user correct course | | Fatal (programmer error, impossible state) | **Fail loudly** — don't paper over a bug | Then internalize the rollback reality: **when a transition throws, its state mutations roll back — but external side effects do not.** A half-sent email or a half-written file stays half-done. So design transitions to be **safe to re-run**: make side effects idempotent, or structure them so a retry can't double-apply them. Surface failures the user should see as an `ErrorDocument` rather than letting them disappear into logs. ### Treat schemas as contracts Every boundary — workflow args, state, transition input — takes a Zod schema. Use them. A schema validates at runtime _and_ documents the shape for the next reader (human or LLM). Validated boundaries turn a class of silent, late failures into loud, early ones. The few lines a schema costs are repaid the first time bad data is rejected at the door instead of corrupting a run three steps later. ### Templates present; code decides Handlebars templates are for assembling text — prompts, markdown, user-facing copy. Keep _decisions_ out of them. Branching, lookups, and computed values belong in TypeScript where they can be read, typed, and tested; the template just renders the result. A template that contains business logic is logic hidden where no test will find it. ### Conventions that keep workflows clean These are project conventions; the reasons behind them are what matter: - **Transitions return nothing — mutate via setters** (`assignState` / `setState`, `assignResult` / `setResult`). Returning a value throws at runtime. This keeps state changes explicit and uniformly rollback-able. - **`async` only when the body awaits.** Don't decorate a synchronous transition with `async` — the linter strips unused `async`, and the intent stays honest. - **No abstract base classes for workflow patterns.** Compose with tools and sub-workflows instead of inheritance hierarchies; the framework is built for composition. - **Fix root causes, not symptoms.** When a workflow misbehaves, find the wrong assumption — don't add a guard or a retry to mask it. - **No compatibility shims.** When a contract changes, update every caller. Don't leave deprecated re-exports behind. ## Tools A tool is a reusable unit of logic with **two audiences**: your own code and the LLM that may call it as a function. Design for both. ### One tool, one responsibility A narrow tool is reusable, composable, and — crucially — easy for an LLM to call correctly. A tool that does five things is hard to reuse and hard for a model to use right, because the model has to guess which of its behaviors you want. If a tool's description needs the word "and" several times, it should probably be several tools. ### The description and schema are the LLM's instructions For a tool that an LLM can call, the description and Zod schema are not just documentation — they are the _only_ thing the model reads to decide **when** and **how** to call it. Write the description to state what the tool does and when to reach for it; give each field a clear, narrow type. Vague descriptions produce wrong calls. This is effort that pays back every time the model uses the tool. ### Keep tools stateless and self-contained Everything a tool needs arrives through its `args` and the `ctx` it is handed. A tool should never reach into a particular workflow's internal state — that couples it to one caller and breaks the reuse that justified making it a tool. Same inputs should mean same behavior. ### Make tools safe to re-run Tools get retried, and the rollback rules cover the calling transition's state — not a tool's external side effects. Design side effects to be idempotent so a retry can't double-apply them (don't charge the card twice, don't append the row twice). ### Return a clean result; fail with actionable errors A tool's result is a contract for both code and the LLM, so return a typed, intentional shape. And when a tool errors during agent use, the message is fed back to the model so it can self-correct — so an error should say _what_ went wrong and _how_ to fix it, not just "failed." ## Documents Documents are how a workflow talks to the **user**. They are a communication surface, not a data store. ### Documents are for humans, not for code If a value exists so that _code_ can use it, it belongs in state or result. Save a document only for what the _user_ should see in Studio. Using a document as a place to stash data your workflow will read back later is the most common misuse — it couples your logic to the UI and clutters the run. ### Reuse built-in document types before creating a custom one Markdown, chat messages, links, and errors already cover most needs. Create a custom document only when the _rendering_ genuinely differs — a form, a code editor, a structured display. A custom document is UI you have to maintain; don't add one just to hold plain data that a built-in type would render fine. ### Emit documents to keep a run legible A run a user can follow in Studio is one they can trust and debug. Save the meaningful intermediate outputs, not only the final one — but don't spam: a document the user doesn't need is noise that hides the ones they do. ## Modules & Studio Apps Modules are how you organize capability; `@StudioApp` is the user-facing boundary on top of that organization. ### Organize modules by feature, not by type Group the workflows, tools, and services of one capability into one module. Don't create a "tools module" and a "workflows module" — that scatters a single feature across the codebase. A module should read as one cohesive thing the system can do. ### Import only what you use A module's imports are its honest dependency list. Pull in a provider module (LLM, OAuth, sandbox, secrets) where the capability is actually needed and nowhere else. A lean, accurate import graph is one you can reason about; a kitchen-sink module hides what really depends on what. ### `@StudioApp` is a deliberate boundary, not a default `@StudioApp` marks a module as a launchable application in Studio. Apply it only to modules meant to be run by users — without it, workflows still exist as providers but stay out of the UI, which is often exactly right for internal building blocks. Keep each app focused: a coherent set of related workflows under one clear title, not a dumping ground. ### Register a shared tool once, at the right level Tools resolve through dependency injection at runtime, so a tool registered in a module is available to every workflow and agent in scope. Register a shared tool once where its consumers can reach it, rather than re-declaring it per workflow — that is what lets an agent and a scripted workflow use the same tool without duplication. ## Related - [Creating Workflows](./fundamentals/workflows.md) · [Tools](./fundamentals/tools.md) · [Documents](./fundamentals/documents.md) · [Modules](./fundamentals/modules.md) · [Studio App Config](./fundamentals/studio-config.md) - [State Management](./patterns/state-management.md) · [Error Handling](./patterns/error-handling.md) · [Sub-Workflows](./patterns/sub-workflows.md) · [Dynamic Routing](./patterns/dynamic-routing.md) - [Agent Workflows](./ai/agent-workflows.md) — when and how to go agentic --- > Source: https://loopstack.ai/llms/build/getting-started.md --- title: Getting Started description: Scaffold a new Loopstack app with `loopstack create` — it generates a NestJS backend, a zero-config hello workflow, a Docker Compose file for PostgreSQL and Redis (plus an optional one for Studio), a ready-to-edit .env, and a CLAUDE.md. Then run your first workflow from the terminal with `loopstack run`, or point DATABASE_URL / REDIS_URL at your own instances. --- # Getting Started The fastest way to start is `loopstack create` — it scaffolds a complete, runnable app so you can run your first AI workflow in a couple of minutes. Already have a NestJS project? See [Add to an Existing App](./add-to-existing-app.md) instead. ## Prerequisites - **Node.js 24 LTS** (recommended) - Node.js 20.19+ or 22 LTS with npm 11 (`npm i -g npm@11`) - Docker ## 1. Create your app ```shell npx @loopstack/cli create my-app cd my-app ``` `create` scaffolds a fresh NestJS backend with `LoopstackModule.forRoot()` wired in and a zero-config `hello` workflow under `src/hello/`. It also drops in: - `docker-compose.yml` — Postgres + Redis - `docker-compose.studio.yml` — the optional [Studio](../learn/studio.md) UI - `.env` — configuration; the defaults match the Docker services out of the box - `CLAUDE.md` — conventions and the CLI feedback loop for coding agents - an initialized git repository ## 2. Provide Postgres & Redis Loopstack needs a PostgreSQL and a Redis instance. There are two equally good ways to provide them — pick whichever fits your setup: **Option A — Docker (quickest locally).** From the project root: ```shell docker compose up -d ``` This starts Postgres and Redis with settings that match the scaffolded `.env`. Want the visual Studio UI too? Start it alongside — it's the separate, optional compose file: ```shell docker compose -f docker-compose.studio.yml up -d # Studio on http://localhost:5173 ``` **Option B — Bring your own.** Point the app at any existing Postgres and Redis (managed, hosted, or already running) in `.env`: ```dotenv DATABASE_URL=postgres://user:password@host:5432/dbname REDIS_URL=redis://host:6379 ``` > CI and coding agents should use Option B (point the URLs at an available instance) and drive workflows from the [CLI](../reference/cli.md), not the browser-based Studio. ## 3. Run Start the backend: ```shell npm run start:dev # http://localhost:3000 ``` Then run the scaffolded workflow from the terminal — the CLI talks to the local backend with no login: ```shell loopstack run hello --arg name=You ``` It streams each transition and the final result live, and returns CI-friendly exit codes — the fastest loop for iterating, scripting, and coding agents. Prefer a visual UI? Start Studio (step 2) and open [http://localhost:5173](http://localhost:5173). ## What you got The `hello` workflow lives in `src/hello/hello.workflow.ts` — one class with a single transition: ```typescript @Workflow({ title: 'Hello World', description: 'Greets you by name — replace this with your first real workflow.', schema: z.object({ name: z.string().default('World') }), }) export class HelloWorkflow extends BaseWorkflow { @Transition({ from: 'start', to: 'end' }) async greet(_state: unknown, ctx: RunContext) { const greeting = `Hello, ${ctx.args.name}! 👋`; await this.documentStore.save(MessageDocument, { role: 'assistant', text: greeting }); this.assignResult({ greeting }); } } ``` It's zero-config — no API keys needed for this first run. Edit it, add your own workflows beside it, and rerun with the CLI to see them live. To make a workflow call an LLM, see [AI Text Generation](./ai/text-generation.md). ## Next steps - [Core Concepts](../learn/core-concepts.md) — workflows, tools, documents, and providers - [Creating Workflows](./fundamentals/workflows.md) — transitions, guards, state, and wait patterns - [AI Text Generation](./ai/text-generation.md) — add LLM calls to your workflows - [Add to an Existing App](./add-to-existing-app.md) — wire Loopstack into a NestJS project you already have --- > Source: https://loopstack.ai/llms/build/testing-methodology.md --- title: Testing Methodology description: How to turn acceptance criteria into an executable workflow test suite — criterion-named scenarios as the human-reviewable contract, the criteria matrix as a test-report query, three run modes (hermetic replay, live, record) from one spec via the fixture option, choosing check types by determinism class (mechanical, semantic, effectful, interactive), and completeness via coverage() and parkView() assertions. Conventions over framework code — works with plain vitest and @loopstack/testing. --- # Testing Methodology [Testing](/docs/build/testing) documents the tools — `runWorkflow`, replay fixtures, scripted answers, `parkView()`. This page documents the **method**: how to organize those tools so a workflow's test suite is a faithful, checkable translation of its acceptance criteria. This matters doubly when the workflow author is an AI agent: for an agent, tests are perception — the suite is how it knows it is done, and how you know it understood the task. Everything here is convention over plain vitest; there is no scenario DSL to learn. ## Criteria become scenarios, scenarios become tests Start from the acceptance criteria — stated ones, plus the unstated ones every task carries (error paths, rejection paths, the branch nobody mentioned). Give each a short ID and expand it into scenarios: happy path, every branch, every park, every failure mode. Each scenario is one `it()` whose name starts with the criterion ID: ```ts describe('ExpenseApprovalWorkflow — acceptance', () => { it('C1: expenses under €100 auto-approve without human interaction', async () => { const run = await runWorkflow( ExpenseApprovalWorkflow, { amount: 40 }, { fixture: rec('small-expense.json'), }, ); expect(run.status).toBe('completed'); expect(run.path).not.toContain('managerDecision'); // never parked expect(run.result).toMatchObject({ approved: true, auto: true }); }); it('C2: expenses of €100+ park for the manager, amount visible', async () => { const run = await runWorkflow( ExpenseApprovalWorkflow, { amount: 250 }, { fixture: rec('large-expense.json'), }, ); expect(run.status).toBe('waiting'); const view = run.parkView(); expect(view?.widget).toBe('confirm-prompt'); expect(view?.content).toMatchObject({ question: expect.stringContaining('€250') }); }); it("C3: rejection records the manager's reason", async () => { const run = await runWorkflow( ExpenseApprovalWorkflow, { amount: 250 }, { fixture: rec('large-expense.json'), answers: { managerDecision: { approved: false, reason: 'no receipt' } }, }, ); expect(run.result).toMatchObject({ approved: false, reason: 'no receipt' }); }); }); ``` This file is the **contract**. A reviewer reads the `it()` names top to bottom and confirms the task was understood — before or after implementation, without deciphering test internals. Write the scenarios first, as failing tests, and let the workflow's design follow from what they need to script: every LLM call and external effect ends up behind a seam (`replayTools`, config) because the scenarios demand it. Assert **outcomes**, not mechanics: `result`, `documents`, where the run parked, what the user would see (`parkView()`). Avoid asserting internal call sequences — those tests break on refactors that change nothing observable. `run.trace` is for debugging a divergence, not for routine assertions. ## The criteria matrix is a test-report query With criterion IDs in test names, the criterion → scenario → result matrix needs no tooling: - The test report _is_ the matrix — every `C*:` line shows pass/fail, grouped by workflow. - "Is every criterion covered?" is a grep: a criterion ID that appears in the task but not in any test name is uncovered. - "Is every _path_ covered?" is a query: `coverage(runs, WorkflowClass)` reports declared transitions and parks no scenario exercised — criteria coverage and state-machine coverage are different questions; check both. ## One scenario, three run modes A scenario written against `fixture` runs in all three modes without changes: | Mode | How | When | | ------------ | ------------------------------------------------------------- | ----------------------------------------------------------- | | **Hermetic** | fixture exists → replayed, milliseconds, no keys | The default. CI gate, every local run | | **Record** | fixture missing (non-CI) → tools run live, responses captured | First run, and re-recording after intended behavior changes | | **Live** | separate spec without `fixture`, sampled, rubric-asserted | Rare, deliberate — semantic quality regression checks | Drift protection keeps the modes honest: replayed runs assert recorded args/config against the live call and validate envelopes against `resultSchema` — a stale fixture fails loudly instead of proving nothing. ## Pick the check type by determinism class A workflow's correctness decomposes into classes, each with a different right kind of check — blurring them into one integration test produces something flaky, slow, and vague at once: | Class | What | Check | | ----------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Mechanical | wiring, data flow, schemas, documents | Exact assertions on `result`/`path`/`document()` under replay | | Semantic | quality of LLM output | Structural assertions under replay; live sampled runs for quality | | Effectful | external writes (git push, email) | Replay inside the suite — tools marked `effects: 'external'` never run live in the inner loop; contract checks against the real service shape | | Interactive | HITL behavior | Scripted `answers` (+ `failure()` for failing children, `TestClock` for timeouts), `parkView()` for what the user sees | ## Checklist 1. Extract criteria (including failure modes); assign IDs. 2. Write criterion-named scenarios as failing tests; review them with a human — this is the cheap moment to resolve ambiguity. 3. Implement until the hermetic suite is green; unit-test tools with real logic via `testTool()`. 4. Run `coverage()` — close the gaps it names. 5. Record fixtures from good live runs; commit them. 6. Hand off with the test report: every criterion visibly green, park views asserted for every human touchpoint. --- > Source: https://loopstack.ai/llms/build/testing.md --- title: Testing Workflows and Tools description: How to test Loopstack workflows and tools — runWorkflow() in-process workflow tests with scripted HITL answers (queue() for cyclic workflows), provider overrides, contract-validated tool fakes (createContractFake) and tool mocks (createToolMock), state-machine coverage (coverage), trace diffing (diffTraces), park-view assertions (parkView — what the user would see at a park, shared rules with the CLI), and inline sub-workflows; testTool() unit tests; strict-sequence record/replay of tool responses (the fixture option with automatic record/replay and CI guard, record, the replayTools mock boundary, the --trace flag and LOOPSTACK_TRACE, loopstack runs --record --tools, replay()); live-LLM regression tests; and CI smoke runs with loopstack run --json. Covers @loopstack/testing, TestRun assertions (status, path, result, document, recordings, the run trace via trace and toolCalls), replay fixtures as ordered response scripts with metadata assertions, drift detection, resultSchema contract validation of replayed envelopes, replay boundaries (envelope-declared documents replay, pending envelopes, async tools always live), and the three strategies for scripting an async tool's answer. --- # Testing Workflows and Tools Loopstack workflows are state machines, and state machines are testable: given the same args and the same tool responses, a run takes the same path and produces the same result. `@loopstack/testing` builds on exactly that property. This page is the whole testing story on one page — unit tests for tools, in-process tests for workflows, recorded tool responses for deterministic regression tests, live runs for LLM regressions, and smoke runs for CI. The model has two layers: - **Inner loop** — ordinary vitest tests that run the real workflow engine in-process: no Postgres, no Redis, no backend. Tool responses can be replayed from recordings, so tests are fast and deterministic. This is where workflow logic, tool logic, and internal regressions are tested. - **Outer loop** — real runs against a running backend with real providers: the `loopstack` CLI for manual and CI smoke runs, and on-demand live-LLM tests after prompt or model changes. ## Testing tools with `testTool` A tool is a unit: given args and context, `handle()` returns an envelope. `testTool()` compiles a minimal module with the framework tokens mocked: ```ts import { testTool } from '@loopstack/testing'; import { ClassifyTicketTool } from '../classify-ticket.tool'; it('classifies an outage as high severity', async () => { const module = await testTool().forTool(ClassifyTicketTool).compile(); const tool = module.get(ClassifyTicketTool); const result = await tool.call({ text: 'Production is down!' }); expect(result.data).toMatchObject({ severity: 'high' }); }); ``` Dependencies are added with `.withProvider(MyService)`, mocked with `.withMock(MyService, { ... })`, and tool dependencies stubbed with `.withToolMock(OtherTool)` — stubbed calls reject until a response is scripted with `mockResolvedValue(...)`. ## Testing workflows with `runWorkflow` `runWorkflow()` executes the real state machine in-process and returns a rich, assertable run object: ```ts import { runWorkflow } from '@loopstack/testing'; import { ClassifyTicketTool } from '../classify-ticket.tool'; import { TriageTicketWorkflow } from '../triage-ticket.workflow'; it('triages a ticket and completes after approval', async () => { const run = await runWorkflow( TriageTicketWorkflow, { text: 'Production is down!' }, { providers: [ClassifyTicketTool], answers: { approve: { approved: true } }, // scripted HITL answer }, ); expect(run.status).toBe('completed'); expect(run.path).toEqual(['classify', 'report', 'approve']); // executed transitions, in order expect(run.result).toMatchObject({ severity: 'high', approved: true }); expect(run.document('triage_report')).toMatchObject({ role: 'assistant' }); }); ``` What the options do: - `providers` / `imports` — the workflow's dependencies (tools, sub-workflow classes, feature modules), exactly as in its real module. - `overrides` — replace providers that come from imported modules: `overrides: [[LlmGenerateTextTool, myMock]]`. A plain `providers` entry only shadows tokens the workflow itself injects; `overrides` reaches into imported modules. - `answers` — scripted HITL input, keyed by wait-transition method name. A plain value is submitted every time the run (or an inline sub-workflow, at any nesting depth — an agent flow's parent → agent → ask-user chain included) parks on the matching wait transition; `queue('first', 'second')` submits one value per park and then stops, which is how a cyclic workflow (a chat loop) is driven a known number of turns before parking. Without an applicable answer the parked run is returned, so you can also assert on the waiting state itself. A plain answer that keeps re-applying on a cyclic workflow trips the `maxSteps` guard (default 50) with an error pointing to `queue()`. - `fixture` / `replay` / `record` — scripted tool responses (next section). Omit them and tools run live. - `clock` — replace the framework clock with a `TestClock` for reproducible trace timestamps and testable transition timeouts: `await clock.waitForScheduled()` once the transition armed its timer, then `clock.advance(ms)` to fire it — no real waiting. - `replayTools` — the mock boundary: which tools consume the scripted responses. Omit it (or pass `'*'`) to mock every tool — right for simple workflows. Agent flows declare the LLM explicitly (`replayTools: [LlmGenerateTextTool]`) so the delegation and HITL machinery runs live. Tools outside the boundary always execute for real and are never captured. Tools can also be **mocked** instead of run live or replayed: pass `{ provide: MyTool, useValue: createToolMock('MyTool') }` in `providers` (or via `overrides` for tools from imported modules) and script responses with `mockResolvedValue({ data: ... })`. You hold the mock reference, so interaction assertions like `expect(mock.call).toHaveBeenCalledWith(...)` work directly. Unscripted mock calls fail the run loudly. Note that a mock bypasses the tool pipeline entirely — args validation, `resultSchema` result validation, interceptors, and replay never see a mocked tool. Prefer `createContractFake(MyTool)` over a plain mock: it scripts responses with `returns(...)` / `returnsOnce(...)` and validates every scripted envelope against the tool's declared `resultSchema` at scripting time, so a fake that drifts from the real contract fails the test instead of silently passing. Interaction assertions work the same (`expect(fake.call).toHaveBeenCalledWith(...)`); unscripted calls reject loudly. Sub-workflows started with `this.someWorkflow.run(...)` execute **inline**: children run to completion synchronously, their callbacks fire, and the whole composition finishes in one call. Child runs are available on `run.children` (status, result, documents per child). Fan-out children run sequentially in tests. Beyond `path`, the run object carries the full **run trace** — the ordered event journal of everything the run did: `run.trace` holds every `transition.started/completed/failed` (with duration and a per-key state diff), `tool.called/completed/failed` (with args and envelope), `document.emitted`, `child.queued/settled`, and one `run.settled` per park or terminal settle (parks include the transitions the run waited on). `run.toolCalls` is the tool-call view of the same trace. `path` derives from the trace's terminal transition events, so it lists transitions that actually executed — successes and failures alike, one entry per attempt; use `run.trace` when a test needs to distinguish outcomes or assert on timings, diffs, or the exact failure point. Two helpers turn traces into answers. `coverage(runs, WorkflowClass)` reports state-machine coverage — which declared transitions and parks a set of runs actually exercised (`missingTransitions` / `missingParks` / `complete`), so "did my tests cover every path?" is a query, not a feeling. `diffTraces(expected, actual)` compares two traces by behavioral identity (timings, sequence numbers, and generated keys are ignored) and returns the **first divergence** with both events and the differing field — or `null` when the runs did the same thing. ## Asserting the park view A workflow can park at the right place and still show the user nothing answerable — a document saved at the wrong place, a widget whose transition isn't available, a prompt hidden by `hideAtPlaces`. `run.status` and `run.place` cannot catch that class of bug; `run.parkView()` can. It answers "what would the human actually see?" using the **same canonical rules** Studio and the CLI use to pick the prompt (shared via `@loopstack/contracts/park-view`), walking the whole run tree — HITL prompts usually live on a sub-workflow: ```ts const run = await runWorkflow(AskUserTextExampleWorkflow, undefined, { imports: [LlmProviderModule, HitlModule, HitlExamplesModule], }); const view = run.parkView(); expect(view).toMatchObject({ workflowId: run.children[0].workflowId, // the ask_user sub-workflow asks, not the root widget: 'text-prompt', content: { question: 'What is your name?' }, transitions: ['userAnswered'], defaultTransition: 'userAnswered', // what an unqualified answer resolves to }); ``` The view carries the prompting workflow, the widget type, the prompt `content`, the answer-payload `schema`, widget `options`, the available `transitions`, the `defaultTransition`, and — for multi-action forms — the currently submittable action labels in `actions`. The rules honor visibility (`hideAtPlaces`, internal documents), place activity (`enableAtPlaces` included), and answered-ness (`answer: false` is an answer — presence counts, not truthiness). A run failed at an error place with recovery transitions is a prompt source too, so recovery screens are assertable like any other park. When a park offers several candidates, the view is the one the rules pick — in run-tree order, and within each workflow its document prompts before its workflow-level widgets; [Prompt Selection Rules](../reference/prompt-selection.md) describes the full order and the lone-transition rule for widgets that declare no transition. Two degenerate results are themselves meaningful assertions: a park with nothing renderable returns a view **without** `widget`/`documentName` (the user would see a bare waiting run — often the bug), and a terminal run returns `undefined`. To resolve a widget, `parkView()` needs the widget config, which is discovered from the app — so **import the workflow's `@StudioApp` module** in the test (`imports: [MyAppModule]`). Without it the widget can't be found and the view falls back to the bare-wait shape (transitions only, no `widget`). Display-only documents (messages, markdown, the transcript) are never reported as the prompt — only the interactive widget the user acts on. ## Record and replay tool responses Replay makes non-deterministic tools — above all LLM calls — deterministic: the recorded response envelope is returned instead of executing the tool. Your code, transitions, and assertions all run for real; only the tool boundary is replayed. A failing replay test means _your code_ changed behavior, not the model. The default flow is the `fixture` option — one file, automatic record/replay: ```ts const run = await runWorkflow( TriageTicketWorkflow, { text: 'Production is down!' }, { providers: [ClassifyTicketTool], answers: { approve: { approved: true } }, fixture: join(import.meta.dirname, '__recordings__/triage.json'), }, ); ``` When the file is missing, the run executes tools live and records it — captured at the exact interception point replay later uses, so the fixture is guaranteed to fit. When the file is present, the run replays it. Delete the file to re-record (for example after a drift failure), then commit the refreshed fixture. In CI (`CI` env set), a missing fixture is an **error** instead of a live run — recording is a deliberate local act, and an uncommitted fixture must never silently turn the PR gate into a live LLM call. Set `LOOPSTACK_RECORD=1` to explicitly allow recording in CI. For explicit control there are two lower-level options, mutually exclusive with `fixture` and with each other: `record` (a path, or `true` to only expose the capture on `run.recordings`) always records, and `replay` always replays a given source — a file path or an inline fixture object. **Recording from a real run** — when the fixture should reflect exactly what a deployed backend produced (a trust run, an agent-driven run): ```bash # 1. Run the workflow for real with trace persistence on (--trace covers the whole run tree) loopstack run triage_ticket --arg text="Production is down!" --trace # 2. Derive a replay fixture from the run's recorded tool calls loopstack runs --record src/triage/__tests__/__recordings__/triage.json ``` Trace persistence is off by default — `--trace` enables it per run. To record every run (e.g. on a dev backend), enable it globally with `LOOPSTACK_TRACE=true` or `LoopstackModule.forRoot({ trace: true })`. Replay the committed fixture in tests: ```ts import { replay, runWorkflow } from '@loopstack/testing'; const run = await runWorkflow( TriageTicketWorkflow, { text: 'Production is down!' }, { providers: [ClassifyTicketTool], answers: { approve: { approved: true } }, replay: replay(join(import.meta.dirname, '__recordings__/triage.json')), }, ); ``` The fixture is a **strict, ordered script**: each call inside the mock boundary consumes the next response — there is no matching or lookup, exactly like an ordinary mock's response queue. Each entry's metadata (`tool` always; `workflow`, `transition`, `args`, `config` when present) is **asserted** against the actual call, so a drifted call order, position, argument, or config fails loudly with the exact position named — a replayed run is deterministic, and any deviation from the recorded sequence means your code changed behavior. A completed run must consume the whole script; leftover responses fail too. Recording covers the **whole run tree** in call order: sub-workflow calls carry their own workflow's name, both in-process and when deriving from a backend run (`loopstack runs --record` fetches the root's and every descendant's calls; `--tools llm_generate_text` selects the mock boundary at derivation). When the outgoing args **or config** drift from the recording, the run **fails** with a drift error naming the tool, transition, and both values — and because LLM tools receive their system prompt, model, and tool list via `config`, a changed system prompt now fails the replayed test instead of silently passing against a stale fixture. A replayed response that no longer matches what your code sends proves nothing, so the fixture must be re-recorded before the test is trustworthy. Args and config are compared structurally (object key order does not matter); a hand-written fixture entry that omits `config` simply doesn't assert it. Fixtures are `version: 3` — older versions are rejected with a re-record message. Tools with no recordings for a transition run live; an exhausted recording list is an error. Replayed envelopes are also **contract-validated**: when a tool declares a `resultSchema`, the scripted response's `data` is parsed against it at the same pipeline point as a live result. A hand-written or stale fixture whose shape no longer matches what the tool really returns fails the run with an error naming the tool — a fixture that drifts from reality proves nothing, so fix the fixture, never loosen the schema. ### Replay boundaries - **Declared documents replay.** Tools produce documents by declaring them on the result envelope (`documents: [{ documentName, content, options }]`), and the pipeline applies declarations _after_ the replay boundary — so a replayed run materializes the same documents a live run would (the LLM message documents of `llm_generate_text` included) and you can assert on them directly. - **Pending envelopes cannot enter a fixture.** When an async tool (`ask_clarification`, `ask_for_approval`, `request_secrets_task`, `explore_task`) launches a sub-workflow, its `pending` envelope is a _reference_ to that live child, not a result — replaying it would hand the workflow a claim ticket for a child that was never launched, and the run would wait forever. So the guard is loud everywhere: in-process recording **fails** when a boundary tool returns a pending envelope (narrow `replayTools` to leave the async tool out), `loopstack runs --record` skips pending envelopes and reports how many, and `replay()` refuses to load a fixture containing one. The consequence: **async tools always execute for real in a replayed run.** How to control their answers is covered in the next section. - **Agent flows declare the LLM as the boundary.** The delegation machinery (`llm_delegate_tool_calls`, `llm_update_tool_result`) returns plain data envelopes that are entangled with live pending-tool state — its response is a _receipt for work performed_, and replaying a receipt doesn't perform the work: the agent parks forever. The LLM is the only genuine data source, so it is the boundary: ```ts const run = await runWorkflow(AgentClarificationExampleWorkflow, undefined, { fixture: join(import.meta.dirname, '__recordings__/agent-clarification.json'), // scripted LLM turns replayTools: [LlmGenerateTextTool], // everything else runs live answers: { userAnswered: { answer: 'Budget €2000, warm climate' } }, // nested HITL child }); ``` The replayed LLM turn returns the `ask_clarification` tool_use → delegation runs live → the ask-user child launches inline and parks → the scripted answer resumes it → the next replayed LLM turn completes the flow. Deterministic, no API key, and the real HITL and delegation machinery is exercised. ### Scripting an async tool's answer An async tool's answer is never replayed from the fixture — it always comes from one of three sources, and each one is scriptable. Pick the strategy by where the answer originates: 1. **A human answers** (`ask_clarification`, `ask_for_approval`, `request_secrets_task`) → script the human with `answers`. The tool runs live and launches its ask-user child inline; the child parks; your scripted answer resumes it; the tool's `complete()` transforms the child result into the tool result — the entire HITL machinery is exercised for real, and the answer is whatever the test scripts: ```ts answers: { userAnswered: { answer: 'Budget €2000, warm climate'; } } ``` 2. **An LLM answers** (`explore_task` — its result comes from a sub-agent) → replay reaches _inside_ the child instead. Recording covers the whole run tree in call order, so the sub-agent's own `llm_generate_text` turns are part of the script. With `replayTools: [LlmGenerateTextTool]` the tool runs live, launches the real sub-agent, and the sub-agent's inner LLM calls consume the script — the tool's answer reproduces deterministically from its actual source of nondeterminism. 3. **You want the tool gone entirely** → mock it wholesale via `providers` or `overrides`. The mock returns a plain _data_ envelope, so the tool never goes async and no child machinery is involved: ```ts const explore = createToolMock('explore_task'); explore.call.mockResolvedValue({ data: { summary: 'Three call sites, all in core.' } }); // providers: [{ provide: ExploreTaskTool, useValue: explore }] ``` What is deliberately not supported: replaying the pending envelope itself and fabricating the completion — that would require hand-reimplementing the callback delivery and `complete()` transformation the replay skipped. Strategy 3 expresses that intent in one line instead. ## Injecting failures Error paths are behavior worth asserting, and every failure mode has a scripting mechanism: - **A tool fails** — script a replay entry whose envelope carries an error: `{ tool: 'fetch_data', envelope: { error: 'upstream 503' } }`. The call throws, and the transition's error handling (retry, `errorPlace`, or manual-retry default) runs for real. - **A sub-workflow fails or is canceled** — script `failure()` as the answer: `answers: { onProvisioned: failure('Provisioning crashed') }` delivers a `status: 'failed'` callback (pass `'canceled'` as the second argument for cancellation) instead of answer data. A wait transition with `errorPlace`/`retryAttempts` routes accordingly; one without them runs its body with `input.status === 'failed'` for inline handling. Composes with `queue()`: `queue(answer, failure('then the child dies'))`. - **The user declines** — that is not a failure but an ordinary answer with negative content (`{ confirmed: false }`); script it like any other answer. ## Live-LLM regression tests Replay proves your code; it deliberately cannot prove the _model_ still behaves after you change a prompt or switch models. For that, run the same tests live — just omit `replay`: ```ts const run = await runWorkflow(TriageTicketWorkflow, { text: ticket }); // real providers expect(run.status).toBe('completed'); expect(['high', 'normal']).toContain(run.result.severity); // tolerant, structural assertions expect(run.document('triage_report')).toBeDefined(); ``` Live tests are non-deterministic and cost money: keep assertions structural (path taken, schema shape, allowed value sets, key facts present), run them **on demand** after prompt/model changes or nightly — never in the PR gate. The loop closes neatly: a replay **drift failure** in CI is your signal that fixtures are stale → run the live tests → when green, re-record the fixtures with `--record`. ## Smoke runs in CI End-to-end verification of a deployed backend needs no test framework — the CLI is the CI gate: ```bash loopstack run triage_ticket --arg text=@ticket.txt --json ``` One final JSON object on stdout, progress on stderr, and the exit-code contract: `0` completed, `1` failed, `2` connection/config error, `3` parked waiting for input. A handful of these smoke runs verifies the wiring; the dozens of behavior tests belong in the inner loop. ## Where to look next - How to organize these tools into an acceptance-criteria-driven suite: [Testing Methodology](/docs/build/testing-methodology). - Runnable versions of every pattern on this page: the [testing examples](/docs/examples/testing); every HITL and agent flavor tested side by side: the [HITL examples](/docs/examples/hitl). - Design guidance on what to test where: [Best Practices](/docs/build/best-practices). - CLI flags and exit codes: [CLI reference](/docs/reference/cli). --- > Source: https://loopstack.ai/llms/build/troubleshooting.md --- title: Troubleshooting description: Solutions to common Loopstack setup and runtime issues — YAML assets missing at runtime, Studio not connecting to the backend, and wait transitions that never fire. --- # Troubleshooting ## YAML widget file not found at runtime **Symptom:** Your workflow starts but throws an error like `ENOENT: no such file or directory` referencing a `.yaml` file, or Studio shows no UI widgets. **Cause:** NestJS's TypeScript compiler strips non-TS files during build. YAML files are not copied to `dist/` unless explicitly configured. **Fix:** Add a YAML assets rule to `nest-cli.json`: ```json { "compilerOptions": { "assets": ["**/*.yaml"] } } ``` Then restart the dev server (`npm run start:dev`) — NestJS watches and copies asset files on change. **Also check:** - `widget:` paths on `@Workflow` / `@Tool` / `@Document` are resolved relative to the file containing the decorator. Use a `./` or `../` prefix: ```typescript @Document({ widget: './my-document.yaml', }) ``` - `this.render(...)` takes an absolute path. Use `path.join(__dirname, ...)`: ```typescript this.render(join(__dirname, 'templates', 'prompt.md')); ``` Not a hardcoded path like `'src/my-feature/my-document.yaml'` — those resolve from the process's `cwd`, not the file's directory. --- ## Studio shows blank or can't reach the backend **Symptom:** Opening `http://localhost:5173` shows an empty screen, a connection error, or no workflows/runs appear. **Cause:** Studio is a static web app that connects to your NestJS backend via the `VITE_API_URL` environment variable. If it's not set, it defaults to `http://localhost:3000`. If your backend is on a different port or host, Studio can't find it. **Fix:** Set `VITE_API_URL` in your `.env` file before starting the Docker Compose stack: ```dotenv VITE_API_URL=http://localhost:3000 ``` If you changed the NestJS default port (e.g. via `app.listen(8080)`), update `VITE_API_URL` to match. After changing `.env`, restart the stack: ```shell docker compose -f node_modules/@loopstack/loopstack-module/docker-compose.yml down docker compose -f node_modules/@loopstack/loopstack-module/docker-compose.yml up -d ``` --- ## `wait: true` transition never fires when clicking a button **Symptom:** You click a button in Studio and nothing happens — the workflow stays paused and doesn't advance. **Cause:** The `transition:` value in your YAML widget config must exactly match the **method name** of the `wait: true` transition in your workflow class. If there's any mismatch (typo, different casing), Studio sends the trigger but the engine can't find the transition. **Fix:** Make sure the names match exactly. In your document YAML: ```yaml actions: - type: button transition: confirm # ← must match the method name label: Confirm ``` In your workflow: ```typescript @Transition({ from: 'reviewing', to: 'end', wait: true }) confirm(state: MyState, input: TransitionInput) { // ↑ must match the transition: value above } ``` The same applies to `prompt-input` widgets: ```yaml widget: prompt-input options: transition: userMessage # ← must match the method name ``` --- # Build / AI --- > Source: https://loopstack.ai/llms/build/ai/agent-workflows.md --- title: Agent Workflows description: Building autonomous LLM agents that call tools in a loop. Covers the built-in AgentWorkflow module, custom agent loops with @Guard routing, error recovery, and max-iterations limits. --- # Agent Workflows Build LLM agents that call tools, handle errors, and run as sub-workflows. Use the built-in `AgentWorkflow` for the common case, or build your own loop from scratch with the same decorators. ## Using the Built-In Agent Install the agent module: ```bash npm install @loopstack/agent ``` Register tools in your module so the agent can use them: ```typescript @Module({ imports: [LlmProviderModule, ClaudeModule, AgentModule], providers: [GlobTool, GrepTool, ReadTool, MyWorkflow], exports: [MyWorkflow], }) export class MyModule {} ``` `LlmProviderModule` must be imported alongside any LLM provider module (`ClaudeModule`, `OpenAiModule`) — it registers the global provider registry the adapter tools and provider implementations depend on. See [LLM Providers](./llm-providers.md). Launch the agent from any workflow: ```typescript @Transition({ from: 'planning', to: 'implementing' }) async runAgent(state: MyState) { await this.agent.run({ system: 'You are a code exploration agent. Summarize your findings.', tools: ['glob', 'grep', 'read'], userMessage: 'Find all API endpoints in the codebase.', }, { callback: { transition: 'agentDone' } }); } ``` The agent runs a full tool-calling loop automatically: LLM turn → tool execution → loop back → until the LLM responds without tool calls. ### Agent Args | Arg | Type | Required | Description | | ------------- | ---------- | -------- | --------------------------------------------- | | `system` | `string` | yes | System prompt | | `tools` | `string[]` | yes | Tool names available to the LLM | | `userMessage` | `string` | yes | Initial user message | | `context` | `string` | no | Hidden context message (e.g. pre-loaded docs) | ### Pre-Loading Context Pass documentation or environment data as a hidden context message. The LLM sees it but it's not shown in the UI: ```typescript const docs = await this.loadFiles.call({ files: ['docs/api-reference.md', 'docs/architecture.md'], basePath: './src/assets', }); const context = this.render(join(__dirname, 'templates', 'context.md'), { docs: docs.data, projectName: args.projectName, }); await this.agent.run({ system: 'You are a documentation agent.', tools: ['read', 'write', 'glob', 'grep'], userMessage: 'Generate API documentation.', context, }); ``` ## Tool Resolution When the LLM calls a tool, it's resolved from the NestJS dependency injection container by its `@Tool({ name })` value. The agent workflow only injects the three tools it always needs (`LlmGenerateTextTool`, `LlmDelegateToolCallsTool`, `LlmUpdateToolResultTool`). Domain-specific tools like `glob` or `read` are resolved from the module at runtime. This means you register tools once in the module and they're available to the agent and all other workflows. ## Error Handling Tool errors are handled automatically. When a tool call fails (schema validation, a runtime error, or a failed sub-workflow), the error is returned to the LLM as an `is_error` tool result. The LLM sees the error message and can self-correct on the next turn. The `LlmDelegateResult` includes error metadata: ```typescript interface LlmDelegateResult { allCompleted: boolean; toolResults: { type: 'tool_result'; toolCallId: string; content?: string; isError?: boolean }[]; pendingCount: number; hasErrors: boolean; errorCount: number; errors: { toolName: string; toolCallId: string; message: string }[]; } ``` ## Canceling Pending Tools If the agent is stuck at `awaiting_tools` (e.g. a sub-workflow hasn't returned), a "Cancel pending tools" button appears in the UI. This cancels all pending child workflows recursively and returns the agent to the LLM loop. ## Building a Custom Agent The built-in `AgentWorkflow` is a regular workflow. When you need custom behavior, copy it and modify directly. Here's the full loop: ```typescript import { BaseWorkflow, Guard, Transition, Workflow } from '@loopstack/common'; import type { RunContext, TransitionInput } from '@loopstack/common'; import type { LlmDelegateResult, LlmGenerateTextResult } from '@loopstack/llm-provider'; import { LlmDelegateToolCallsTool, LlmGenerateTextTool, LlmMessageDocument, LlmUpdateToolResultTool, } from '@loopstack/llm-provider'; interface AgentState { llmResult?: LlmGenerateTextResult; delegateResult?: LlmDelegateResult; } const MyAgentSchema = z.object({ instructions: z.string() }); type MyAgentArgs = z.infer; @Workflow({ widget: './my-agent.ui.yaml', schema: MyAgentSchema, }) export class MyAgentWorkflow extends BaseWorkflow { constructor( private readonly llmGenerateText: LlmGenerateTextTool, private readonly llmDelegateToolCalls: LlmDelegateToolCallsTool, private readonly llmUpdateToolResult: LlmUpdateToolResultTool, private readonly myCustomTool: MyCustomTool, ) { super(); } @Transition({ to: 'ready' }) async setup(state: AgentState, ctx: RunContext) { await this.documentStore.save(LlmMessageDocument, { role: 'user', text: ctx.args.instructions, }); } @Transition({ from: 'ready', to: 'prompt_executed' }) async llmTurn(state: AgentState) { const result = await this.llmGenerateText.call( {}, { config: { provider: 'claude', model: 'claude-sonnet-4-6', system: 'You are a custom agent.', tools: ['my_custom_tool'], }, }, ); this.assignState({ llmResult: result.data }); } @Transition({ from: 'prompt_executed', to: 'awaiting_tools', priority: 10 }) @Guard('hasToolCalls') async executeToolCalls(state: AgentState) { const result = await this.llmDelegateToolCalls.call({ message: state.llmResult!.message, tools: ['my_custom_tool'], callback: { transition: 'toolResultReceived' }, }); this.assignState({ delegateResult: result.data }); } @Transition({ from: 'awaiting_tools', to: 'awaiting_tools', wait: true }) async toolResultReceived(state: AgentState, input: TransitionInput) { const result = await this.llmUpdateToolResult.call({ delegateResult: state.delegateResult!, completedTool: input, }); this.assignState({ delegateResult: result.data }); } @Transition({ from: 'awaiting_tools', to: 'ready' }) @Guard('allToolsComplete') toolsComplete(state: AgentState) {} @Transition({ from: 'prompt_executed', to: 'end' }) @Guard('isDone') respond(_state: AgentState) {} private hasToolCalls(state: AgentState): boolean { return state.llmResult?.message.stopReason === 'tool_use'; } private allToolsComplete(state: AgentState): boolean { return state.delegateResult?.allCompleted ?? false; } private isDone(state: AgentState): boolean { return state.llmResult?.message.stopReason === 'end_turn'; } } ``` `LlmGenerateTextTool`, `LlmDelegateToolCallsTool`, and `LlmUpdateToolResultTool` all persist their messages automatically — the assistant turn after `llmGenerateText`, and the `tool_result` user turn when all delegated tools complete (sync or async). Pass `config: { save: false }` on any of them if you want to take over persistence. ### Adding User Interaction Pause for user input between LLM turns: ```typescript // Instead of final transition, go to waiting_for_user @Transition({ from: 'prompt_executed', to: 'waiting_for_user' }) @Guard('isDone') respondToUser(state: AgentState) {} @Transition({ from: 'waiting_for_user', to: 'ready', wait: true, schema: z.string() }) async userMessage(state: AgentState, input: TransitionInput) { await this.documentStore.save(LlmMessageDocument, { role: 'user', text: input.data, }); } ``` > **Tip:** The `@loopstack/agent` package ships `ChatAgentWorkflow` which implements this pattern out of the box. Use it when you need a multi-turn chat agent without customization. ### Wrapping an Agent as a Tool Make an agent callable by other agents via a task tool: ```typescript @Tool({ name: 'explore_codebase', description: 'Launch a sub-agent to explore the codebase.', schema: z.object({ instructions: z.string() }), }) export class ExploreTask extends BaseTool { constructor(private readonly agentWorkflow: AgentWorkflow) { super(); } protected async handle( args: { instructions: string }, ctx: RunContext, options?: ToolCallOptions, ): Promise { const result = await this.agentWorkflow.run( { system: 'You are a codebase exploration agent.', tools: ['glob', 'grep', 'read'], userMessage: args.instructions, }, { callback: options?.callback }, ); return { data: { workflowId: result.workflowId }, pending: { workflowId: result.workflowId }, }; } async complete(result: Record): Promise { const data = result as { data?: { response?: string } }; return { data: data.data?.response ?? result }; } } ``` This enables multi-agent architectures where an orchestrator agent delegates tasks to specialized sub-agents. ## Registry References - [@loopstack/agent](/docs/registry/agent) — Built-in agent workflow module - [@loopstack/code-agent](/docs/registry/code-agent) — Code exploration agent (ExploreTask) built on @loopstack/agent - [Tool Errors example](/docs/examples/agent#tool-errors) — Example demonstrating tool error handling and recovery --- > Source: https://loopstack.ai/llms/build/ai/chat-flows.md --- title: Chat Flows description: Building multi-turn conversational workflows with LLMs using LlmMessageDocument, messagesSearchTag pattern, and wait transitions for user input. --- # Chat Flows Build multi-turn conversational workflows where users exchange messages with an LLM. Messages are persisted as documents and accumulated across turns using the `messagesSearchTag` pattern. ## Example ```typescript import { z } from 'zod'; import { BaseWorkflow, Transition, type TransitionInput, Workflow } from '@loopstack/common'; import { LlmContextDocument, LlmGenerateTextTool, LlmMessageDocument } from '@loopstack/llm-provider'; @Workflow({ widget: './chat.ui.yaml' }) export class ChatWorkflow extends BaseWorkflow { constructor(private readonly llmGenerateText: LlmGenerateTextTool) { super(); } @Transition({ to: 'waiting_for_user' }) async setup(state: Record) { await this.documentStore.save(LlmContextDocument, { role: 'user', text: this.render(join(__dirname, 'templates', 'systemMessage.md')), }); } @Transition({ from: 'waiting_for_user', to: 'ready', wait: true, schema: z.string() }) async userMessage(state: Record, input: TransitionInput) { await this.documentStore.save(LlmMessageDocument, { role: 'user', text: input.data }); } @Transition({ from: 'ready', to: 'waiting_for_user' }) async llmTurn(state: Record) { await this.llmGenerateText.call({}, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }); } } ``` ## YAML Config ```yaml title: 'Chat Assistant' ui: widgets: - widget: prompt-input enabledWhen: - waiting_for_user options: transition: userMessage ``` ## How Message Accumulation Works 1. All messages are saved as `LlmMessageDocument` — automatically tagged with `message` 2. The LLM provider module collects all documents with the `message` tag as conversation history by default 3. Each new message adds to the conversation — the LLM sees the full history on every turn ## Message Resolution When `LlmGenerateTextTool.call()` runs, it resolves the conversation in this priority order: 1. **`args.prompt`** — if provided, used as a single user message. Documents are ignored. 2. **`args.messages`** — if provided (and no `prompt`), used as the full message array. Documents are ignored. 3. **Documents matching `config.messagesSearchTag`** — fallback when neither arg is set. Defaults to `'message'`. When falling back to documents, the tool: - Filters `DocumentEntity` records by `doc.tags.includes(messagesSearchTag)` - Excludes any document with `doc.isInvalidated === true` - Sorts by `doc.index` to preserve chronological order - Replays an assistant message's native response (`doc.meta.response`) when the same provider wrote it, and otherwise rebuilds the message from its normalized content — see [LLM Providers — Switching Provider Within a Conversation](./llm-providers.md#switching-provider-within-a-conversation) This means you can run parallel conversation threads in the same workflow by saving messages under different tags and switching `messagesSearchTag` per call: ```typescript // Save a summary-thread message await this.documentStore.save( LlmMessageDocument, { role: 'user', text: 'Summarize the discussion so far.' }, { tags: ['summary-chat'] }, ); // Call the LLM with only the summary thread as history await this.llmGenerateText.call( {}, { config: { provider: 'claude', model: 'claude-sonnet-4-6', messagesSearchTag: 'summary-chat' } }, ); ``` If a message isn't appearing in the LLM context, check that it has the expected tag and is not invalidated. ## Chat Loop Flow ``` setup → waiting_for_user → [user sends message] → ready → llmTurn → waiting_for_user (loop) ``` 1. **Initial transition** — Create system message (hidden from UI) 2. Workflow enters `waiting_for_user` — UI shows the prompt-input widget 3. User sends message → `userMessage` fires, saves user message as document 4. `llmTurn` fires — calls the LLM with full message history, saves response 5. Workflow returns to `waiting_for_user` — loop continues ## Combining with Tool Calling Add tool calling to a chat flow by combining the patterns from [AI Tool Calling](./tool-calling.md): ```typescript @Transition({ from: 'ready', to: 'prompt_executed' }) async llmTurn(state: ChatState) { const result = await this.llmGenerateText.call( {}, { config: { provider: 'claude', model: 'claude-sonnet-4-6', tools: ['get_weather', 'search_database'] } }, ); this.assignState({ llmResult: result.data }); } @Transition({ from: 'prompt_executed', to: 'awaiting_tools', priority: 10 }) @Guard('hasToolCalls') async executeToolCalls(state: ChatState) { ... } @Transition({ from: 'prompt_executed', to: 'waiting_for_user' }) respond(state: ChatState) {} ``` ## Registry References - [Prompt Input Chat example](/docs/examples/hitl#prompt-input-chat) — Multi-turn chat loop with the prompt-input widget, without an LLM - [Custom Agent example](/docs/examples/agent#custom-agent) — Tool calling loop built from the delegate primitives --- > Source: https://loopstack.ai/llms/build/ai/llm-providers.md --- title: LLM Providers description: Using multiple LLM providers (Claude, OpenAI) through the runtime provider registry. Covers LlmProviderModule setup, provider selection per-call, switching providers without code changes, and which message history (meta.response, meta.provider, content blocks) and server tools carry over when a conversation switches provider. --- # LLM Providers Loopstack supports multiple LLM providers through a runtime registry. Provider modules self-register at startup. Workflows and tools resolve providers by name — swap or use multiple providers in parallel without changing workflow code. ## Quick Start Import `LlmProviderModule` for the adapter tools and a provider module (e.g. `ClaudeModule`) to register the LLM backend: ```typescript import { ClaudeModule } from '@loopstack/claude'; import { LlmProviderModule } from '@loopstack/llm-provider'; @Module({ imports: [LoopstackModule.forRoot(), LlmProviderModule, ClaudeModule], }) export class AppModule {} ``` > **`LlmProviderModule` is required, and must be imported before any provider module.** > > `LlmProviderModule` registers `LlmProviderRegistry` — the runtime registry that provider modules (`ClaudeModule`, `OpenAiModule`) inject to self-register their backends. Importing a provider module without `LlmProviderModule` fails at boot with `UnknownDependenciesException` on `LlmProviderRegistry` (and on `ClaudeLlmProvider` / `OpenAiLlmProvider`, which depend on it). > > Any of these forms registers the registry: bare `LlmProviderModule`, `LlmProviderModule.forRoot(config)`, or `LlmProviderModule.forFeature(config)` (the feature form imports the global root transitively). Pick `forRoot` when setting app-wide defaults, `forFeature` for per-module overrides, and the bare import when no defaults are needed. ## Module-Level Defaults Use `LlmProviderModule.forRoot()` to set a default model for all LLM calls in your app. Use `forFeature()` to override per-module: ```typescript // app.module.ts — global default model @Module({ imports: [LoopstackModule.forRoot(), LlmProviderModule.forRoot({ model: 'claude-sonnet-4-5' }), ClaudeModule], }) export class AppModule {} ``` ```typescript // premium-feature.module.ts — this module uses a stronger model @Module({ imports: [LlmProviderModule.forFeature({ model: 'claude-opus-4-6' })], providers: [PremiumWorkflow], }) export class PremiumFeatureModule {} ``` ## Per-Call Configuration Override provider and model at individual call sites via `options.config`. Per-call config always takes priority over module defaults. ```typescript export class MyWorkflow extends BaseWorkflow { constructor( private readonly llmGenerateText: LlmGenerateTextTool, private readonly llmDelegateToolCalls: LlmDelegateToolCallsTool, ) { super(); } } ``` ```typescript const result = await this.llmGenerateText.call( { prompt: 'Hello!' }, { config: { provider: 'claude', model: 'claude-opus-4-6', system: 'You are a helpful assistant.', messagesSearchTag: 'message', tools: ['get_weather'], }, }, ); ``` ### Args vs Config LLM tools separate **args** (per-request data) from **config** (provider/model/behavior settings). For `LlmGenerateTextTool`, the input args are `prompt` and `messages`; `outputSchema` applies only to `LlmGenerateObjectTool`. See [Text Generation](./text-generation.md) for full call examples. | Parameter | Location | Description | | ------------------- | -------- | ------------------------------------------ | | `prompt` | args | Simple prompt string | | `messages` | args | Explicit message array | | `outputSchema` | args | JSON Schema (`LlmGenerateObjectTool` only) | | `provider` | config | LLM provider name (e.g. `'claude'`) | | `model` | config | Model name (e.g. `'claude-sonnet-4-6'`) | | `system` | config | System prompt | | `messagesSearchTag` | config | Load messages from documents by tag | | `tools` | config | Tool names the LLM can call | ## Using Multiple Providers Import both modules and configure each call with its provider: ```typescript @Module({ imports: [LoopstackModule.forRoot(), ClaudeModule, OpenAiModule], }) export class AppModule {} ``` ```typescript // Use Claude for complex tasks const smartResult = await this.llmGenerateText.call( { prompt: 'Analyze this code...' }, { config: { provider: 'claude', model: 'claude-opus-4-6' } }, ); // Use OpenAI for simple tasks const fastResult = await this.llmGenerateText.call( { prompt: 'Summarize in one line...' }, { config: { provider: 'openai', model: 'gpt-4o-mini' } }, ); ``` ### Switching Provider Within a Conversation A conversation saved as `LlmMessageDocument`s can start on one provider and continue on another. Each assistant message saved by `LlmGenerateTextTool` keeps the native API response in `meta.response` and the id of the provider that wrote it in `meta.provider`. A provider replays the native response only when `meta.provider` is its own id. Every other message is rebuilt from its normalized `text` and `blocks`. What carries over to the other provider: | Content | Carries over | | ------------------------------------------------- | --------------------------------------------------------------------------------- | | `text` blocks | Yes | | `tool_call` and `tool_result` blocks | Yes — tool call ids, names and arguments are kept | | `thinking` blocks | No — the OpenAI provider leaves them out | | `server_tool_use` and `server_tool_result` blocks | No — the OpenAI provider leaves them out. The answer text after a search is kept. | Server tools such as `claude_native_web_search` produce one provider's native tool spec, so they run only on that provider. The OpenAI provider rejects a call that lists a server tool with `Server tool '' is not supported by the openai provider` — remove the server tool from `config.tools` when you move that call to OpenAI. ## Provider-Specific Configuration `config.providerConfig` is an opaque pass-through to the active provider — its shape depends on which provider handles the call. Use it for tuning behavior beyond the cross-provider config fields (system prompt, tools, etc.). Provider-specific config is per-call only. The cross-provider fields `provider` and `model` can also be set at module level via `LlmProviderModule.forRoot()` / `forFeature()` (see [Module-Level Defaults](#module-level-defaults)) — per-call config always takes priority. ```typescript await this.llmGenerateText.call( { prompt: 'Write a haiku about coffee' }, { config: { provider: 'claude', model: 'claude-sonnet-4-6', providerConfig: { maxTokens: 1024, temperature: 0.7, cache: true, }, }, }, ); ``` ### `ClaudeProviderConfig` | Field | Type | Description | | --------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `maxTokens` | `number` | Maximum tokens to generate | | `temperature` | `number` | Sampling temperature (0–1) | | `stopSequences` | `string[]` | Stop generation when any of these strings is produced | | `cache` | `boolean` | Enable Anthropic prompt caching. Places cache breakpoints on the system prompt, tool definitions, and the last message automatically — useful for multi-turn workflows where the prefix is reused. | | `envApiKey` | `string` | Env var name holding the API key (defaults to `ANTHROPIC_API_KEY`) | ### `OpenAiProviderConfig` | Field | Type | Description | | ------------------ | ---------- | --------------------------------------------------------------- | | `maxTokens` | `number` | Maximum tokens to generate | | `temperature` | `number` | Sampling temperature (0–2) | | `stopSequences` | `string[]` | Stop generation when any of these strings is produced | | `frequencyPenalty` | `number` | -2.0 to 2.0; reduces token repetition | | `presencePenalty` | `number` | -2.0 to 2.0; encourages topic diversity | | `envApiKey` | `string` | Env var name holding the API key (defaults to `OPENAI_API_KEY`) | ## Adapter Tools All LLM interactions go through adapter tools from `@loopstack/llm-provider`. This ensures validation, interceptors, and logging apply to every LLM call. | Tool | Purpose | | -------------------------- | --------------------------------------------- | | `LlmGenerateTextTool` | Text generation with optional tool calling | | `LlmGenerateObjectTool` | Structured output conforming to a JSON Schema | | `LlmDelegateToolCallsTool` | Execute tool calls from an LLM response | | `LlmUpdateToolResultTool` | Handle async tool completion callbacks | ## Message Documents All providers share a single `LlmMessageDocument` with normalized content. Native API responses are stored in `entity.meta.response`, and the provider that wrote them in `entity.meta.provider`, for provider-specific round-trips — see [Switching Provider Within a Conversation](#switching-provider-within-a-conversation). See [Chat Flows — Message Resolution](./chat-flows.md#message-resolution) for how documents are collected from the document store and become the LLM's conversation history. | Document | Content Format | Widget | | -------------------- | --------------------------------------------------- | ------------- | | `LlmMessageDocument` | Normalized (`text`, `thinking`, `tool_call` blocks) | `llm-message` | ### Response shape `LlmGenerateTextResult.data.message` is an `LlmNormalizedMessage` — two views of the same response: | Field | Type | Description | | ------------ | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `role` | `'user' \| 'assistant'` | Message role | | `text` | `string` | Plain-text projection — concatenated `text`-type blocks. Always populated by providers. Use this when you just want a string. | | `blocks` | `LlmContentBlock[]` (optional) | Structured content blocks. Use this to inspect tool calls, thinking output, or render block-by-block. | | `stopReason` | `'end_turn' \| 'tool_use' \| 'max_tokens' \| 'stop_sequence'` | Why generation stopped | | `id` | `string` (optional) | Provider-assigned message ID | `text` is derived from `blocks` (text-type blocks joined with `\n`; `thinking` and tool blocks excluded). Both fields are populated by every provider, so you can pick whichever fits the call site without checking for `undefined`. Content blocks are one of: - `{ type: 'text', text: string }` — text output - `{ type: 'thinking', text: string }` — reasoning/thinking output - `{ type: 'tool_call', id: string, name: string, args: Record }` — tool call - `{ type: 'tool_result', toolCallId: string, content: string, isError: boolean }` — tool result (user-side, fed back to the LLM next turn) ### Writing messages — `text` vs `blocks` Assistant messages (and the user-side `tool_result` turn) are saved automatically by `LlmGenerateTextTool` / `LlmDelegateToolCallsTool`. When you save an `LlmMessageDocument` manually — for user input, seed messages, or system primers — the same two fields are available, both optional. Provide whichever fits: ```typescript // Plain text message — most common case await this.documentStore.save(LlmMessageDocument, { role: 'user', text: 'Hello!' }); // Structured message — multi-block content await this.documentStore.save(LlmMessageDocument, { role: 'user', blocks: [{ type: 'text', text: 'See attached.' }], }); ``` You don't need to fill both. The renderer and downstream providers fall back gracefully: if only `text` is set, it's rendered as a single text bubble; if only `blocks` is set, the text projection is derived from text-type blocks on demand. See [Creating LLM Providers](../../extend/llm-providers.md) for the full interface. ## Environment Variables | Variable | Provider | Description | | ------------------- | -------- | ---------------------- | | `ANTHROPIC_API_KEY` | Claude | API key | | `OPENAI_API_KEY` | OpenAI | API key | | `CLAUDE_MODEL` | Claude | Default model fallback | | `OPENAI_MODEL` | OpenAI | Default model fallback | ## Available Providers | Provider | Module | ID | | ---------------- | ------------------- | ---------- | | Anthropic Claude | `@loopstack/claude` | `'claude'` | | OpenAI | `@loopstack/openai` | `'openai'` | To create a custom provider, see [Creating LLM Providers](../../extend/llm-providers.md). --- > Source: https://loopstack.ai/llms/build/ai/structured-output.md --- title: AI Structured Output description: Forcing LLMs to return structured JSON data using LlmGenerateObjectTool with Zod schemas. Provider-agnostic — works with Claude, OpenAI, and other providers. --- # AI Structured Output Use `LlmGenerateObjectTool` from `@loopstack/llm-provider` to generate structured data conforming to a JSON Schema. Provider-agnostic — works with Claude, OpenAI, and other providers. ## Define a Document ```typescript import { z } from 'zod'; import { Document } from '@loopstack/common'; export const FileDocumentSchema = z .object({ filename: z.string(), description: z.string(), code: z.string(), }) .strict(); export type FileDocumentType = z.infer; @Document({ schema: FileDocumentSchema, widget: './file-document.yaml', }) export class FileDocument { filename: string; description: string; code: string; } ``` ## Workflow Example ```typescript import { toJSONSchema, z } from 'zod'; import { BaseWorkflow, DocumentEntity, Transition, Workflow } from '@loopstack/common'; import type { RunContext } from '@loopstack/common'; import type { LlmGenerateObjectResult } from '@loopstack/llm-provider'; import { LlmGenerateObjectTool, LlmMessageDocument } from '@loopstack/llm-provider'; import { FileDocument, FileDocumentSchema, FileDocumentType } from './documents/file-document'; interface StructuredOutputState { language?: string; llmResult?: DocumentEntity; } const StructuredOutputSchema = z.object({ language: z.enum(['python', 'javascript', 'java', 'cpp', 'ruby', 'go', 'php']).default('python'), }); type StructuredOutputArgs = z.infer; @Workflow({ schema: StructuredOutputSchema, }) export class PromptStructuredOutputWorkflow extends BaseWorkflow { constructor(private readonly llmGenerateObject: LlmGenerateObjectTool) { super(); } @Transition({ to: 'ready' }) async greeting(state: StructuredOutputState, ctx: RunContext) { await this.documentStore.save( LlmMessageDocument, { role: 'assistant', text: `Creating a Hello World script in ${ctx.args.language}...` }, { key: 'status' }, ); this.assignState({ language: ctx.args.language }); } @Transition({ from: 'ready', to: 'prompt_executed' }) async prompt(state: StructuredOutputState) { const result = await this.llmGenerateObject.call( { outputSchema: toJSONSchema(FileDocumentSchema) as Record, prompt: this.render(join(__dirname, 'templates', 'prompt.md'), { language: state.language }), }, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }, ); const objectResult = result.data as LlmGenerateObjectResult; const llmResult = await this.documentStore.save(FileDocument, objectResult.data as FileDocumentType, { validate: 'skip', }); this.assignState({ llmResult }); } @Transition({ from: 'prompt_executed', to: 'end' }) async respond(state: StructuredOutputState) { await this.documentStore.save( LlmMessageDocument, { role: 'assistant', text: `Generated: ${state.llmResult?.content?.description ?? ''}` }, { key: 'status' }, ); } } ``` ## How It Works 1. Convert your Zod schema to JSON Schema using `toJSONSchema()` 2. Pass the JSON Schema as `outputSchema` to `llmGenerateObject.call()` 3. The provider forces the LLM to return data matching the schema 4. Save the result as a typed document using `this.documentStore.save()` ## Key Parameters ```typescript await this.llmGenerateObject.call( { outputSchema: toJSONSchema(MyDocumentSchema) as Record, prompt: 'Generate structured data.', }, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }, ); ``` ## Registry References - [Structured Output example](/docs/examples/llm#structured-output) — Generates structured code files using the LLM provider --- > Source: https://loopstack.ai/llms/build/ai/text-generation.md --- title: AI Text Generation description: Calling LLMs for text generation using LlmGenerateTextTool. Covers setup, system prompts, message history, provider selection, prompt caching, and streaming. --- # AI Text Generation Generate text from any configured LLM provider using `LlmGenerateTextTool`. Pass prompts, system instructions, and message history — the tool handles provider routing, token counting, and optional streaming. ## Setup ```typescript import { Module } from '@nestjs/common'; import { ClaudeModule } from '@loopstack/claude'; import { LlmProviderModule } from '@loopstack/llm-provider'; @Module({ imports: [LlmProviderModule, ClaudeModule], providers: [PromptWorkflow], exports: [PromptWorkflow], }) export class PromptModule {} ``` `LlmProviderModule` registers the global provider registry that adapter tools (`LlmGenerateTextTool`, `LlmGenerateObjectTool`) and provider implementations (`ClaudeLlmProvider`) depend on. Without it, NestJS throws `UnknownDependenciesException` for `LlmProviderRegistry` at boot. See [LLM Providers](./llm-providers.md) for details and module-level defaults. ## Example Workflow ```typescript import { z } from 'zod'; import { BaseWorkflow, Transition, Workflow } from '@loopstack/common'; import type { RunContext } from '@loopstack/common'; import { LlmGenerateTextTool } from '@loopstack/llm-provider'; const PromptSchema = z.object({ subject: z.string().default('coffee'), }); type PromptArgs = z.infer; @Workflow({ schema: PromptSchema, }) export class PromptWorkflow extends BaseWorkflow { constructor(private readonly llmGenerateText: LlmGenerateTextTool) { super(); } @Transition({ to: 'end' }) async prompt(state: Record, ctx: RunContext) { await this.llmGenerateText.call( { prompt: this.render(join(__dirname, 'templates', 'prompt.md'), { subject: ctx.args.subject }), }, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }, ); } } ``` ## Reading the Response A normalized result has two views of the assistant's reply: - `result.data.message.text` — the plain-text projection (always populated). This is what you want in 95% of cases. - `result.data.message.blocks` — the structured content blocks (`text`, `thinking`, `tool_call`, etc.). Use these when you need to inspect tool calls, thinking output, or render block-by-block. ```typescript const result = await this.llmGenerateText.call({ prompt: 'Write a haiku about coffee' }); const text = result.data.message.text; ``` Both views are derived from the same underlying response — `text` is the concatenation of all `text`-type blocks, with `thinking` and tool blocks filtered out. ## Call Options ```typescript await this.llmGenerateText.call( { // Option 1: Simple prompt prompt: 'Write a haiku about coffee', // Option 2: Explicit messages — `text` for plain content, `blocks` for structured messages: [{ role: 'user', text: 'Write a haiku about coffee' }], }, { config: { provider: 'claude', model: 'claude-sonnet-4-6', system: 'You are a helpful assistant.', // Option 3: Collect documents by tag as conversation history messagesSearchTag: 'message', }, }, ); ``` ## Persisting the Response The tool saves the assistant message as an `LlmMessageDocument` automatically — no manual `documentStore.save()` is required. Two config knobs control this: - `config: { save: false }` — opt out entirely. Use this when you want to inspect, transform, or persist the response yourself (see [Multi-Provider example](/docs/examples/llm#multi-provider) for a worked case). - `config: { meta: {...} }` — merge extra metadata into the auto-saved document. Free-form payload that downstream readers can pick up off `document.meta`. To run a "silent" turn the LLM remembers but the user doesn't see, opt out of auto-save and persist the result as `LlmContextDocument` (declared `internal: true`, so Studio never sees it): ```typescript const result = await this.llmGenerateText.call( { prompt: 'Summarize the previous turn in one sentence for internal reasoning.' }, { config: { provider: 'claude', save: false } }, ); await this.documentStore.save(LlmContextDocument, { role: 'assistant', text: result.data.message.text ?? '', }); ``` Other documents (user inputs, seed system messages, structured outputs) stay manual — see [Chat Flows](./chat-flows.md) for the two halves side by side. ## Using Templates Render Handlebars templates for complex prompts (`this.render()` is available from `BaseWorkflow`): ```typescript const rendered = this.render(join(__dirname, 'templates', 'prompt.md'), { subject: ctx.args.subject, }); const result = await this.llmGenerateText.call( { prompt: rendered }, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }, ); ``` ## Streaming LLM responses stream to Studio automatically — no opt-in, no code changes. Whenever a workflow runs in a context that has a connected Studio client (`ctx.workflowId`, `ctx.userId`, and an active `ClientMessageService`), `LlmGenerateTextTool` assigns a `streamMessageId`, passes an `onStream` callback to the provider, and forwards each event to Studio as it arrives. The workflow itself still receives the complete `LlmGenerateTextResult` after the stream finishes — streaming is a side-effect for the UI, not a change to the return value. ### Lifecycle in Studio 1. Tool dispatches `llm.response.start` with a fresh `streamMessageId`. 2. Provider emits `text_delta`, `thinking_delta`, and `tool_call` events as content arrives. Studio renders an in-flight message keyed by `streamMessageId`. 3. Tool dispatches `llm.response.done` with the final normalized message; the result is returned to the workflow. 4. The tool persists an `LlmMessageDocument` for the assistant turn automatically. The saved document inherits `streamMessageId` as its `id`, so Studio **replaces** the in-flight streamed message with the final document — same ID, same slot. No duplicate bubble. Pass `config: { save: false }` if you want to handle persistence yourself. This is why you don't need to do anything special to "finalize" the stream: the document save naturally takes over from the stream because they share the same `id`. ### Custom providers If you're implementing a custom `LlmProviderInterface`, honor the `onStream` callback in `LlmGenerateTextArgs` — call it with `LlmStreamEvent`s (`start`, `text_delta`, `thinking_delta`, `tool_call`, `done`, `error`) as content arrives. Providers that don't stream can ignore it; the framework still returns the final result correctly. See [Creating LLM Providers](../../extend/llm-providers.md) for the full event union. ## Environment Variables | Variable | Description | | ------------------- | ----------------- | | `ANTHROPIC_API_KEY` | Anthropic API key | ## Registry References - [Prompt example](/docs/examples/llm#prompt) — Single-turn prompt with subject parameter and Handlebars template --- > Source: https://loopstack.ai/llms/build/ai/tool-calling.md --- title: AI Tool Calling description: Enabling LLMs to invoke workflow tools via function calling. Covers LlmDelegateToolCallsTool, tool descriptions, passing tools to LLM calls, and handling tool results. --- # AI Tool Calling Enable the LLM to call workflow tools (function calling). The LLM decides which tools to invoke, and `LlmDelegateToolCallsTool` executes them. ## Create a Tool for the LLM Tools exposed to the LLM need a `description` so the LLM knows when to use them: ```typescript import { z } from 'zod'; import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common'; import type { RunContext } from '@loopstack/common'; @Tool({ name: 'get_weather', description: 'Retrieve weather information.', schema: z.object({ location: z.string().describe('City or location name'), }), }) export class GetWeather extends BaseTool<{ location: string }, object, string> { protected async handle(): Promise> { return Promise.resolve({ type: 'text', data: 'Mostly sunny, 14C, rain in the afternoon.' }); } } ``` ## Tool Calling Workflow `LlmDelegateToolCallsTool` always dispatches tools with a callback so sub-workflow / HITL / async tools work safely. A `wait: true` self-loop on `awaiting_tools` catches each completion via `LlmUpdateToolResultTool`. Synchronous tools complete immediately and the loop falls through to `toolsComplete`. ```typescript import { BaseWorkflow, Guard, Transition, Workflow } from '@loopstack/common'; import type { LlmDelegateResult, LlmGenerateTextResult } from '@loopstack/llm-provider'; import { LlmDelegateToolCallsTool, LlmGenerateTextTool, LlmMessageDocument, LlmUpdateToolResultTool, } from '@loopstack/llm-provider'; import { GetWeather } from './tools/get-weather.tool'; interface ToolCallState { llmResult?: LlmGenerateTextResult; delegateResult?: LlmDelegateResult; } @Workflow({}) export class ToolCallWorkflow extends BaseWorkflow { constructor( private readonly llmGenerateText: LlmGenerateTextTool, private readonly llmDelegateToolCalls: LlmDelegateToolCallsTool, private readonly llmUpdateToolResult: LlmUpdateToolResultTool, private readonly getWeather: GetWeather, ) { super(); } @Transition({ to: 'ready' }) async setup(state: ToolCallState) { await this.documentStore.save(LlmMessageDocument, { role: 'user', text: 'How is the weather in Berlin?', }); } @Transition({ from: 'ready', to: 'prompt_executed' }) async llmTurn(state: ToolCallState) { const result = await this.llmGenerateText.call( {}, { config: { provider: 'claude', model: 'claude-sonnet-4-6', tools: ['get_weather'] } }, ); this.assignState({ llmResult: result.data }); } @Transition({ from: 'prompt_executed', to: 'awaiting_tools', priority: 10 }) @Guard('hasToolCalls') async executeToolCalls(state: ToolCallState) { const result = await this.llmDelegateToolCalls.call({ message: state.llmResult!.message, tools: ['get_weather'], callback: { transition: 'toolResultReceived' }, }); this.assignState({ delegateResult: result.data }); } hasToolCalls(state: ToolCallState): boolean { return state.llmResult?.message.stopReason === 'tool_use'; } @Transition({ from: 'awaiting_tools', to: 'awaiting_tools', wait: true }) async toolResultReceived(state: ToolCallState, payload: unknown) { const result = await this.llmUpdateToolResult.call({ delegateResult: state.delegateResult!, completedTool: payload, }); this.assignState({ delegateResult: result.data }); } @Transition({ from: 'awaiting_tools', to: 'ready' }) @Guard('allToolsComplete') toolsComplete(state: ToolCallState) {} allToolsComplete(state: ToolCallState): boolean { return state.delegateResult?.allCompleted ?? false; } @Transition({ from: 'prompt_executed', to: 'end' }) respond(_state: ToolCallState) {} } ``` Both `LlmGenerateTextTool` and `LlmDelegateToolCallsTool` persist their messages automatically — the assistant turn and the `tool_result` user turn appear in the document store and conversation history without any explicit `documentStore.save()` call. Pass `config: { save: false }` on either tool if you need to handle persistence yourself. ## How the Loop Works ``` setup → llmTurn → [hasToolCalls?] ├─ yes → executeToolCalls → awaiting_tools │ ├─ toolResultReceived (wait, self-loop on async completions) │ └─ toolsComplete (@Guard allToolsComplete) → llmTurn (loop) └─ no → respond (done) ``` 1. `llmGenerateText` is called — the `tools` array in config lists available tools 2. If the LLM returns `stopReason: 'tool_use'`, the guard routes to `executeToolCalls` 3. `llmDelegateToolCalls` dispatches each tool with a callback. Synchronous tools complete immediately; async tools (sub-workflows, HITL) return `pending: true` and fire `toolResultReceived` once each 4. When `delegateResult.allCompleted` is true, the unguarded fall-through (`toolsComplete`) loops back to the LLM 5. When the LLM is done (no more tool calls), the fallback transition to `end` fires ## Key Concepts - **`tools` array in config** — Lists tool names the LLM can call. Names must match `@Tool({ name })` values. At startup, Loopstack auto-discovers every `@Tool()`-decorated provider in the module graph and indexes them by name. If a name doesn't match, you'll get an error listing all registered tools — useful for catching typos and missing module imports. - **`llmDelegateToolCalls`** — Dispatches tool calls from the LLM response message with a callback transition. Pass it the same `tools` list you gave `llmGenerateText`: only those tools are executed. Required for safety: sub-workflow / HITL / any tool that returns `pending: true` only completes once its callback fires - **`llmUpdateToolResult`** — Merges each async tool completion into the running `delegateResult`. The `wait: true` self-loop on `awaiting_tools` calls it once per completion - **`message.stopReason === 'tool_use'`** — The LLM wants to call a tool - **`allCompleted`** — All delegated tool calls have finished - **`@Guard` + `priority`** — Routes between tool calling and final response ## Under the Hood: How `llmDelegateToolCalls` Works `LlmDelegateToolCallsTool` is what makes a tool-calling workflow actually do work. Without it, the LLM's `tool_call` blocks would just sit in the message — nothing would be executed. The tool reads the most recent assistant message, runs every tool the LLM requested, and stores the outputs back as `tool_result` entries that the next LLM turn can read. Internally it delegates to `LlmDelegateService`, which: 1. **Refuses tools the LLM was not offered** — a tool call whose name is not in the `tools` arg is never executed; it becomes a `tool_result` with `isError: true` (`Tool "x" is not available to this agent`), so the LLM sees it and can correct itself. 2. **Resolves each allowed tool by name** from the global tool registry (the same one built by `@Tool()` auto-discovery). 3. **Dispatches all tool calls in parallel** with `Promise.all` — the LLM is free to request multiple tools in one turn, and they run concurrently. 4. **Catches errors per tool** so one failing tool doesn't crash the others. Failures show up as `tool_result` entries with `isError: true` and are also collected on `result.errors` for inspection. 5. **Tracks pending async tools** — tools that return `{ pending: true }` (typically [HITL](./agent-workflows.md#adding-user-interaction) or sub-workflow tools) don't produce a result immediately. The result includes a `pendingCount`, and `allCompleted` stays `false` until those tools fire their completion callbacks. `LlmUpdateToolResultTool` is the companion that processes those callbacks and updates the delegate result. The `callback` arg is required — it's how async tool completions find their way back to the workflow. For all-synchronous tool sets, `allCompleted` is already true when `executeToolCalls` returns and the `wait` transition is never entered; the callback is harmless overhead. For mixed or async-only sets, the `wait` transition is what keeps the workflow from silently hanging on pending tools. ## Registry References - [Agent example](/docs/examples/agent#agent) — Parent workflow that delegates to `AgentWorkflow` for tool-calling with weather and calculator tools - [Custom Agent example](/docs/examples/agent#custom-agent) — Reference for hand-rolling the tool loop when you need custom error policy or per-turn logic --- > Source: https://loopstack.ai/llms/build/ai/usage-tracking.md --- title: AI Token Usage Tracking description: Reading LlmUsage from LLM tool results. Every LLM tool (LlmGenerateTextTool, LlmGenerateObjectTool, document generation) returns LlmResultMeta with provider, model, and a usage breakdown — inputTokens, outputTokens, cacheCreationInputTokens, cacheReadInputTokens, reasoningTokens. --- # AI Token Usage Tracking Every LLM tool call returns token usage on `result.metadata`. The shape is the same regardless of which tool produced the result — `LlmGenerateTextTool`, `LlmGenerateObjectTool`, and any other LLM-backed tool all return `LlmResultMeta` with a `usage?: LlmUsage`. Read it to log costs, enforce budgets, or report consumption back to users. ## Result metadata shape ```typescript type LlmResultMeta = { provider: string; // e.g. 'claude', 'openai' model: string; // e.g. 'claude-sonnet-4-6' usage?: LlmUsage; }; interface LlmUsage { inputTokens: number; outputTokens: number; cacheCreationInputTokens?: number; cacheReadInputTokens?: number; reasoningTokens?: number; } ``` | Field | Description | | -------------------------- | ----------------------------------------------------------------- | | `inputTokens` | Prompt tokens sent to the model | | `outputTokens` | Completion tokens produced | | `cacheCreationInputTokens` | Tokens written to the prompt cache (provider-dependent) | | `cacheReadInputTokens` | Tokens served from the prompt cache | | `reasoningTokens` | Internal reasoning tokens (e.g. Claude thinking, OpenAI o-series) | `usage` is optional — providers that don't report token counts will omit it. ## Reading usage from a tool call ```typescript const result = await this.llmGenerateText.call( { prompt: 'Write a haiku about coffee' }, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }, ); const { provider, model, usage } = result.metadata; if (usage) { console.log( `${provider}/${model}:`, `in=${usage.inputTokens}`, `out=${usage.outputTokens}`, `cacheRead=${usage.cacheReadInputTokens ?? 0}`, ); } ``` The same access pattern works for `LlmGenerateObjectTool` and any other LLM-backed tool that returns `LlmResultMeta`. ## Persisting usage in workflow state If you need usage downstream (for billing, reporting, or aggregation across multiple calls), store `result.metadata` in the workflow state alongside the result: ```typescript interface PromptState { llmResult?: LlmGenerateTextResult; llmMeta?: LlmResultMeta; } @Transition({ to: 'prompt_executed' }) async prompt(state: PromptState, ctx: RunContext) { const result = await this.llmGenerateText.call( { prompt: 'Write a haiku' }, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }, ); this.assignState({ llmResult: result.data, llmMeta: result.metadata, }); } ``` ## See also - [Text Generation](./text-generation.md) — `LlmGenerateTextTool` call signature - [Structured Output](./structured-output.md) — `LlmGenerateObjectTool` call signature --- # Build / Fundamentals --- > Source: https://loopstack.ai/llms/build/fundamentals/documents.md --- title: Creating Documents description: How to define typed document classes with @Document() decorator, Zod validation schemas, and YAML widget configs for rendering in Loopstack Studio. --- # Creating Documents Documents are typed data objects displayed in the Loopstack Studio UI. They have a Zod schema for validation and a YAML config for rendering. ## Basic Document ```typescript import { z } from 'zod'; import { Document } from '@loopstack/common'; export const NotesSchema = z.object({ text: z.string(), }); @Document({ schema: NotesSchema, widget: './notes.ui.yaml', }) export class NotesDocument { text: string; } ``` ```yaml # notes.ui.yaml type: document ui: widgets: - widget: form options: properties: text: title: Notes widget: textarea rows: 8 ``` ## The `@Document` Decorator ```typescript @Document({ schema: NotesSchema, widget: './notes.ui.yaml', }) ``` All options are optional. | Option | Type | Default | Description | | ------------- | -------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | class name with `Document` suffix stripped, snake_cased | Explicit snake_case identifier. E.g. `AskUserDocument` → `ask_user`, `LlmMessageDocument` → `llm_message`. | | `title` | `string` | — | Human-readable display title shown in Studio UI. | | `description` | `string` | — | Human-readable description shown in Studio UI. | | `widget` | `WidgetRef \| WidgetRef[]` | — | Path(s) to YAML file(s) — or inline widget object(s) — defining how the document renders in Studio. | | `schema` | `z.ZodType` | — | Zod schema validating document content on `documentStore.save()`. | | `tags` | `string[]` | — | Default tags assigned to every instance of this document. Useful for filtering and querying. | | `meta` | `StaticDocumentMeta` | — | Static document metadata — served via the config endpoint, not persisted per instance. | | `internal` | `boolean` | `false` | When `true`, instances are persisted server-side (still readable by LLM providers) but excluded from API responses and live updates — Studio never sees them. Use for framework plumbing like LLM context. | > **Documents are plain DTOs, not NestJS providers.** Unlike `@Tool` and `@Workflow`, `@Document` does **not** apply `@Injectable()`. Don't add document classes to a module's `providers` array and don't try to inject them — reference the class directly when calling `documentStore.save(MyDocument, ...)`. ## Saving Documents Use `this.documentStore.save()` inside workflow transition methods. Reference document classes directly — no injection needed. `documentStore` is auto-injected on `BaseWorkflow` and `BaseTool`. ```typescript // Create a new document await this.documentStore.save(NotesDocument, { text: 'Hello!' }); // A new revision under a key — invalidates the previous version, placed at the end await this.documentStore.save(NotesDocument, { text: 'Revised content' }, { key: 'notes-1' }); // Update in place — the new revision takes the place of the previous one await this.documentStore.save(NotesDocument, { text: 'Updated content' }, { key: 'notes-1', position: 'keep' }); // With meta options (free-form extension data on the document row) await this.documentStore.save(NotesDocument, { text: 'Tagged note' }, { meta: { source: 'import' } }); ``` ### Saving an Instance `save()` is overloaded — instead of passing class + data, you can `create()` an instance, mutate it, then save it. Useful when you need to build up a document across several steps before persisting. ```typescript const draft = this.documentStore.create(NotesDocument, { text: 'Initial draft' }); draft.text += '\n\nAddendum.'; await this.documentStore.save(draft); // With save options await this.documentStore.save(draft, { key: 'notes-1' }); ``` `create()` returns a class instance (typed as `NotesDocument`) populated with the data; it does not persist anything. Persistence only happens on `save()`. ### Save Options | Option | Type | Description | | ----------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` | `string` | Stable revision key — saving again with the same `key` writes a new revision and invalidates the previous ones. | | `position` | `'keep' \| 'end'` | Where a keyed save puts the new revision. Default `'end'` — appended, below everything saved since. `'keep'` — in the place of the revision it supersedes; use for documents that update over time (status tickers, form state, transcripts). | | `validate` | `'strict' \| 'safe' \| 'skip'` | Validation mode. Default `'strict'` — throws on invalid content. `'safe'` stores partial data + error. `'skip'` bypasses validation. See [Validation](../../learn/document-store.md#validation). | | `meta` | `Record` | Free-form extension data persisted on the document row. Use for ad-hoc payload that downstream readers need. For framework concerns (hide from UI, etc.), use decorator options instead. | | `meta.invalidate` | `boolean` | When `false`, prevents the previous version with the same `key` from being invalidated. Default behavior replaces the old version. | ## Querying Documents `documentStore` exposes three read methods. All of them return only **non-invalidated** documents for the current workflow run — invalidated revisions are filtered out automatically. | Method | Returns | When to use | | --------------------- | ------------------ | -------------------------------------------------------------------- | | `findAll(MyDocument)` | `MyDocument[]` | All documents of one type, **hydrated as typed instances**. | | `findByTag('tag')` | `DocumentEntity[]` | Documents tagged with that tag (across types). Returns raw entities. | | `findAllDocuments()` | `DocumentEntity[]` | Everything in the run — useful for LLM tools, history scans. | ```typescript // Typed, type-safe — preferred const notes = this.documentStore.findAll(NotesDocument); notes.forEach((n) => console.log(n.text)); // By tag — across document types const messages = this.documentStore.findByTag('message'); // All documents in this run (raw entities) const all = this.documentStore.findAllDocuments(); ``` `findAll` re-validates and hydrates entities back into class instances (via `plainToInstance`). `findByTag` and `findAllDocuments` return raw `DocumentEntity` objects — use `entity.content` for the persisted data and `entity.documentName` to discriminate types. > Need a typed instance without persisting? Use [`documentStore.create(MyDocument, data)`](#saving-an-instance) — it validates against the Zod schema and returns a class instance with no DB write. ## Built-in Document Types These are available without creating custom documents: | Document | Source | Key Fields | | -------------------- | ------------------------- | ------------------------------------------ | | `LlmMessageDocument` | `@loopstack/llm-provider` | `role`, `text`, `blocks` | | `LlmContextDocument` | `@loopstack/llm-provider` | `role`, `text` | | `LinkDocument` | `@loopstack/common` | `label`, `workflowId`, `embed`, `expanded` | | `MessageDocument` | `@loopstack/common` | `role`, `text` | | `MarkdownDocument` | `@loopstack/common` | `markdown` | | `PlainDocument` | `@loopstack/common` | `text` | | `ErrorDocument` | `@loopstack/common` | `error` | ### Choosing the right built-in type - **`LlmMessageDocument`** — visible assistant/user conversation turns. Extends `MessageDocument` with structured `blocks` (tool calls, thinking, tool results) and an LLM `stopReason`. Tagged `'message'`, so it's automatically collected into LLM conversation history. The LLM provider tools save these for you in normal use. - **`LlmContextDocument`** — hidden conversation context. Declared `@Document({ internal: true, tags: ['message'] })`. The LLM provider picks these up as conversation history just like `LlmMessageDocument`, but Studio doesn't show them. Use to seed system prompts, prior steps, or background info without polluting the user-facing chat. - **`MessageDocument`** — plain `{ role, text }` UI bubbles for non-LLM flows (status updates, narrative output, logging a `system` note). Tagged `'ui-message'` — **not** collected into LLM history. Use this when you want a chat-style message in Studio without polluting the LLM's context. - **`MarkdownDocument`** — formatted prose, headings, lists, links. Use when you want Studio to render rich text. - **`PlainDocument`** — unformatted text output: raw command output, log dumps, plain blob. Use when Markdown rendering would interpret characters you want shown literally. - **`LinkDocument`** — links to other workflow runs (sub-workflows, related runs). Studio renders these as cards with a live status indicator derived from the linked workflow's state. The orchestrator saves one automatically when you call `subWorkflow.run()` (see [Sub-Workflows](../patterns/sub-workflows.md)); save manually only if you need a link card outside the standard sub-workflow flow. - **`ErrorDocument`** — engine-managed; do not construct manually. Written automatically when a transition fails (see [Workflow Engine — ErrorDocument](../../learn/workflow-engine.md#errordocument)). ```typescript import { LinkDocument, MarkdownDocument, PlainDocument } from '@loopstack/common'; import { LlmMessageDocument } from '@loopstack/llm-provider'; await this.documentStore.save(LlmMessageDocument, { role: 'assistant', text: 'Hello! How can I help?', }); await this.documentStore.save(MarkdownDocument, { markdown: '# Report\n- Item 1\n- Item 2', }); // Raw command output — keep characters literal await this.documentStore.save(PlainDocument, { text: shellOutput }); ``` ## YAML UI Configuration ### Form Widget The `form` widget renders document fields as an editable form: ```yaml type: document ui: widgets: - widget: form options: order: [name, description, items] properties: name: title: Name description: title: Description widget: textarea items: title: Items collapsed: true items: title: Item actions: - type: button transition: submit label: 'Submit' ``` ### Available Widget Types Use these in `options.properties..widget`: | Widget | Description | | ----------- | ------------------------------------ | | `text` | Single-line text input (default) | | `textarea` | Multi-line text area | | `select` | Dropdown select | | `radio` | Radio button group | | `checkbox` | Checkbox | | `switch` | Toggle switch | | `slider` | Numeric slider | | `code-view` | Code editor with syntax highlighting | ### Property Options | Option | Type | Description | | ------------- | --------- | ---------------------------------- | | `title` | `string` | Display label | | `widget` | `string` | Widget type | | `placeholder` | `string` | Placeholder text | | `rows` | `number` | Visible rows (textarea) | | `readonly` | `boolean` | Read-only field | | `hidden` | `boolean` | Hide the field | | `disabled` | `boolean` | Disable interaction | | `collapsed` | `boolean` | Collapse arrays/objects by default | | `items` | `object` | UI config for array items | ### Document Actions Buttons that trigger `wait: true` transitions in the workflow: ```yaml actions: - type: button transition: confirm # Must match the method name label: 'Confirm' ``` ### Tags Tags categorize documents for filtering and searching. There are two ways to set them: **Decorator default tags** — written to every instance, persisted on each row, queryable via `findByTag()`: ```typescript @Document({ schema: NotesSchema, widget: './notes.ui.yaml', tags: ['message', 'important'], }) export class NotesDocument { /* ... */ } ``` **YAML config tags** — static metadata served via the config endpoint, used by Studio and LLM tools for grouping/filtering, not persisted on individual rows: ```yaml type: document tags: - message - important ``` Decorator tags are the right choice for runtime querying — every saved instance carries them, and `this.documentStore.findByTag('message')` returns them. YAML tags are for static document-type metadata. Tags from both sources are also used by LLM tools with `messagesSearchTag` config to collect documents as conversation history. ## Structured Output Example Documents work with `LlmGenerateObjectTool` for AI-generated structured data: ```typescript export const FileDocumentSchema = z .object({ filename: z.string(), description: z.string(), code: z.string(), }) .strict(); @Document({ schema: FileDocumentSchema, widget: './file-document.yaml', }) export class FileDocument { filename: string; description: string; code: string; } ``` ```yaml # file-document.yaml type: document ui: widgets: - widget: form options: order: [filename, description, code] properties: filename: title: File Name readonly: true description: title: Description readonly: true code: title: Code widget: code-view ``` Used in a workflow: ```typescript const result = await this.llmGenerateObject.call( { outputSchema: toJSONSchema(FileDocumentSchema) as Record, prompt: 'Generate a Hello World script in Python', }, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }, ); ``` ## Registry References - [Structured Output example](/docs/examples/llm#structured-output) — FileDocument with code-view widget for AI-generated code - [Meeting Notes example](/docs/examples/hitl#meeting-notes) — MeetingNotesDocument and OptimizedNotesDocument with form widgets and action buttons - [UI Documents example](/docs/examples/advanced-workflows#ui-documents) — Demonstrates all core UI document types: MessageDocument, ErrorDocument, MarkdownDocument, PlainDocument --- > **Using an AI coding agent?** See [Skill: Create a Custom Document](../../skills/create-custom-document.md) for a dense checklist and syntax reference optimized for code generation. --- > Source: https://loopstack.ai/llms/build/fundamentals/modules.md --- title: Modules & Workspaces description: How to organize workflows, tools, and services into NestJS modules. Covers @StudioApp decorator for app identity, module structure, app modules vs feature modules, workspace configuration, forRoot/forFeature patterns, and provider registration. --- # Modules & Workspaces Loopstack uses NestJS modules to organize your application. Workflows and tools are registered as standard NestJS providers. ## App Modules (`@StudioApp`) Every module whose workflows should be **visible and launchable in Loopstack Studio** must be decorated with `@StudioApp`. Without it, workflows are registered as NestJS providers but do not appear in the Studio UI. ```typescript import { Module } from '@nestjs/common'; import { ClaudeModule } from '@loopstack/claude'; import { StudioApp } from '@loopstack/common'; import { MyTool } from './tools/my.tool'; import { MyWorkflow } from './workflows/my.workflow'; @StudioApp({ title: 'My App', workflows: [MyWorkflow], }) @Module({ imports: [ClaudeModule], providers: [MyWorkflow, MyTool], }) export class MyAppModule {} ``` `@StudioApp` options: - **`title`** (required) — display name shown in Studio - **`workflows`** — array of workflow classes launchable from Studio - **`app`** — explicit snake_case identifier (defaults to module class name with `Module` → `App`, e.g. `HelloModule` → `hello_app`, `CodeAgentModule` → `code_agent_app`) - **`description`** — human-readable description - **`ui`** — Studio UI options for this app. See [Studio Configuration](./studio-config.md). > **Important:** `@StudioApp` is a metadata decorator — it does not replace `@Module`. Both decorators are required on the same class. ### Recommended File Layout A typical app module groups workflows, tools, services, documents, and tests like this: ``` my-app/ └── src/ ├── my-app.module.ts # @StudioApp + @Module ├── index.ts # public exports ├── workflows/ │ ├── index.ts │ ├── my.workflow.ts │ ├── my.ui.yaml # widget config for Studio │ └── __tests__/ │ └── my.workflow.spec.ts ├── tools/ │ ├── index.ts │ ├── my.tool.ts │ └── __tests__/ │ └── my.tool.spec.ts ├── documents/ │ ├── my-document.ts # @Document class │ └── my-document.yaml # UI/widget metadata ├── services/ │ └── my.service.ts └── templates/ └── prompt.md # Handlebars templates ``` Conventions: - **`__tests__/`** folder next to source for `*.spec.ts` files - **`workflows/`, `tools/`, `documents/`, `services/`, `templates/`** as sibling folders under `src/` - **`index.ts`** re-exports public symbols (used when this module is consumed as a package) - Document classes (`*.ts`) and their widget config (`*.yaml`) sit side by side Smaller modules can collapse this — a one-workflow module often keeps everything flat under `src/`. Use this layout as the upper bound, not a requirement. See the [Custom Tool example](/docs/examples/advanced-workflows#custom-tool) and the [Meeting Notes example](/docs/examples/hitl#meeting-notes) for concrete references. ### App Modules vs Feature Modules There are two kinds of modules in a Loopstack project: - **App modules** — decorated with `@StudioApp`, define a launchable application in Studio. They list workflows in the `workflows` array. - **Feature modules** — plain `@Module` classes that provide reusable tools, services, or workflows. They are imported by app modules but don't appear in Studio on their own. Registry packages (like `ClaudeModule`, `SandboxToolModule`, or example workflows) are feature modules. When you import them, you still need a `@StudioApp` module to surface their workflows in Studio. > Feature modules are auto-discovered when reachable from a `@StudioApp` module's import graph. Some modules also opt into a Studio UI surface (panel, widget) via `forFeature()` — see [Studio Features](../../extend/features.md) for details. > **`@StudioApp` modules must not be nested.** An app module cannot import another app module — Loopstack throws at bootstrap if it detects this. Always import each app module independently from your root `AppModule`. Shared logic belongs in plain feature modules. ## Feature Modules A feature module groups related workflows, tools, and services together for reuse across app modules. ```typescript import { Module } from '@nestjs/common'; import { ClaudeModule } from '@loopstack/claude'; import { MyTool } from './tools/my.tool'; import { MyWorkflow } from './workflows/my.workflow'; @Module({ imports: [ClaudeModule], providers: [MyWorkflow, MyTool], exports: [MyWorkflow, MyTool], }) export class MyFeatureModule {} ``` ### Key Rules - **`LoopCoreModule` is global** — registered once by `LoopstackModule.forRoot()`, do not import it in feature modules - **Import feature modules** like `ClaudeModule` for AI, `SandboxToolModule` for Docker sandboxes, etc. - **Documents are NOT providers** — they are plain DTOs and don't need registration - **Export workflows and tools** that other modules might need ### Registering in AppModule Add your module to the main `AppModule`: ```typescript import { Module } from '@nestjs/common'; import { LoopstackModule } from '@loopstack/loopstack-module'; import { MyFeatureModule } from './my-feature/my-feature.module'; @Module({ imports: [LoopstackModule.forRoot(), MyFeatureModule], }) export class AppModule {} ``` ### Multi-Module Example For larger applications, split functionality across app modules and shared feature modules: ```typescript // analytics.module.ts — app module (visible in Studio) @StudioApp({ title: 'Analytics', workflows: [AnalyticsWorkflow], }) @Module({ imports: [ClaudeModule], providers: [AnalyticsWorkflow, DataFetchTool], }) export class AnalyticsModule {} // shared-tools.module.ts — feature module (not visible in Studio) @Module({ providers: [EmailTool, SlackTool], exports: [EmailTool, SlackTool], }) export class SharedToolsModule {} // notifications.module.ts — app module (visible in Studio) @StudioApp({ title: 'Notifications', workflows: [NotificationWorkflow], }) @Module({ imports: [SharedToolsModule], providers: [NotificationWorkflow], }) export class NotificationsModule {} // app.module.ts @Module({ imports: [LoopstackModule.forRoot(), AnalyticsModule, NotificationsModule], }) export class AppModule {} ``` ## Module Configuration (`forRoot` / `forFeature`) Many Loopstack modules support `forRoot()` and `forFeature()` for configuring defaults. This follows the standard NestJS dynamic module pattern. - **`forRoot(config)`** — sets **global defaults** for the module. Call once in your root `AppModule`. - **`forFeature(config)`** — **overrides defaults** for a specific feature module. Tools in that module use the override instead of the global. ```typescript // app.module.ts — global default: all LLM calls use claude-sonnet-4-6 @Module({ imports: [ LoopstackModule.forRoot(), LlmProviderModule.forRoot({ model: 'claude-sonnet-4-6' }), ClaudeModule, MyFeatureModule, ], }) export class AppModule {} // my-feature.module.ts — this module's LLM calls use claude-opus-4-6 instead @Module({ imports: [LlmProviderModule.forFeature({ model: 'claude-opus-4-6' })], providers: [MyWorkflow], }) export class MyFeatureModule {} ``` Each `forFeature()` import creates an isolated scope — tools in `MyFeatureModule` see the override, while tools in any other module continue to see the global `forRoot()` default. Multiple `forFeature()` calls in different modules coexist without interfering, each with its own resolved config. Modules that support this pattern include `LlmProviderModule`, `RemoteClientModule`, `SecretsModule`, and others. Per-call config (via `options.config`) always takes priority over module defaults. ### Creating Your Own Configurable Module Authoring a module that supports `forRoot()` / `forFeature()` requires three pieces: 1. A **config injection token** (a `Symbol`) and a `Config` interface — so providers can `@Inject()` the resolved config. 2. A **separate `@Global()` root module** that provides the default config and exports the tools. Keeping it as its own class prevents NestJS from deduplicating it with `forFeature()` imports. 3. A **wrapper module** exposing the static `forRoot()` and `forFeature()` factories that return `DynamicModule`s with the overridden config. ```typescript // my-feature.constants.ts export const MY_FEATURE_CONFIG = Symbol('MY_FEATURE_CONFIG'); export interface MyFeatureConfig { apiKey?: string; region?: string; } ``` ```typescript // my-feature.module.ts import { DynamicModule, Global, Module } from '@nestjs/common'; import { MY_FEATURE_CONFIG, MyFeatureConfig } from './my-feature.constants.js'; import { MyTool } from './my.tool.js'; const DEFAULT_CONFIG: MyFeatureConfig = {}; const TOOLS = [MyTool]; @Global() @Module({ providers: [{ provide: MY_FEATURE_CONFIG, useValue: DEFAULT_CONFIG }, ...TOOLS], exports: [MY_FEATURE_CONFIG, ...TOOLS], }) class MyFeatureRootModule {} @Module({}) export class MyFeatureModule { static forRoot(config: MyFeatureConfig): DynamicModule { return { module: MyFeatureRootModule, global: true, providers: [{ provide: MY_FEATURE_CONFIG, useValue: config }, ...TOOLS], exports: [MY_FEATURE_CONFIG, ...TOOLS], }; } static forFeature(config: MyFeatureConfig): DynamicModule { return { module: MyFeatureModule, imports: [MyFeatureRootModule], providers: [{ provide: MY_FEATURE_CONFIG, useValue: config }, ...TOOLS], exports: [...TOOLS], }; } } ``` Providers then inject the resolved config via the token: ```typescript @Tool({ name: 'my_tool' }) export class MyTool extends BaseTool { constructor(@Inject(MY_FEATURE_CONFIG) private readonly config: MyFeatureConfig) { super(); } } ``` The `forFeature()` import of `MyFeatureRootModule` ensures the global default is always available — bare `import MyFeatureModule` works even if `forRoot()` was never called. **Why `@Global()`?** The `@Global()` decorator is a [standard NestJS feature](https://docs.nestjs.com/modules#global-modules) that makes a module's exports available to every other module in the application without an explicit `imports: [...]` entry. The root module uses it so that `MY_FEATURE_CONFIG` and the tools are injectable anywhere — including in modules that never call `forRoot()` or `forFeature()`. This is also why `LoopCoreModule` is marked global by `LoopstackModule.forRoot()`. Use `@Global()` sparingly for app-wide singletons; prefer per-module imports for scoped behavior. See [Module Config example](/docs/examples/advanced-workflows#module-config) for a complete runnable example, including a nested wrapper module that passes config through to the underlying configurable module. ## Dependency Injection Workflows and tools use standard NestJS constructor injection: ```typescript @Workflow({ widget: './chat.ui.yaml', }) export class ChatWorkflow extends BaseWorkflow { constructor( private readonly llmGenerateText: LlmGenerateTextTool, private readonly myTool: MyCustomTool, ) { super(); } } ``` Sub-workflows are also injected via constructor: ```typescript export class ParentWorkflow extends BaseWorkflow { constructor(private readonly subWorkflow: SubWorkflow) { super(); } } ``` ## Using in Loopstack Studio Once registered: 1. Open Loopstack Studio at `http://localhost:5173` 2. Your workspace appears in the sidebar 3. Click a workflow to create a new run 4. Fill in the input form and start the workflow ## Registry References - [Prompt Input Chat example](/docs/examples/hitl#prompt-input-chat) — Part of `HitlExamplesModule`, which imports `ClaudeModule` beside `HitlModule` and `AgentModule` - [Custom Tool example](/docs/examples/advanced-workflows#custom-tool) — Module with custom tools, services, and workflow providers - [Sub-Workflow example](/docs/examples/advanced-workflows#sub-workflow) — Module registering both parent and sub-workflow providers --- > Source: https://loopstack.ai/llms/build/fundamentals/studio-config.md --- title: Studio Configuration description: Reference for the `ui` option on @StudioApp. Documents StudioUiConfig, the StudioWidgetConfig widget array, and the app-level start-form widget (options workflow, title, subtitle, label) that adds launch cards with a workflow's args form to the workspace home page. --- # Studio Configuration The `ui` option on `@StudioApp` controls how an app is rendered in Loopstack Studio. This page is the single reference for those options. More options will be added over time. ## `ui.widgets` `widgets` is an array of widget descriptors. Each entry names a widget and may pass widget-specific options. ```typescript @StudioApp({ title: 'My App', workflows: [ReportWorkflow], ui: { widgets: [{ widget: 'start-form', options: { workflow: 'report', title: 'Create a report' } }], }, }) @Module({ /* ... */ }) export class MyAppModule {} ``` Each entry has: - **`widget`** — the widget identifier - **`options`** — optional, widget-specific configuration At app level, Studio renders one widget: [`start-form`](#start-form). Document and workflow YAML configs use the same `{ widget, options }` format under `ui.widgets[]`, with their own widgets (for example `prompt-input`, `button` and `form`). ### `start-form` A `start-form` entry adds a launch card to the workspace home page — the page Studio opens when you open a workspace of the app, for example after creating it from the app launcher. Each card starts one workflow. Several entries stack as several cards, in array order. An app without `start-form` entries has no home page content. | Option | Required | Default | Description | | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `workflow` | yes | — | Name of the workflow to start — `@Workflow({ name })`, or the class name without `Workflow`, snake_cased (`ReportWorkflow` → `report`) | | `title` | no | — | Heading of the card | | `subtitle` | no | — | Short text under the heading | | `label` | no | `Run` | Text of the submit button | Studio looks the workflow up among the app's `workflows`. When the workflow declares an args `schema`, the card renders it as a form and the submitted values become the run's args. Without a `schema` the card shows only the button, and the run starts without args. On submit, Studio creates a run of the workflow in the current workspace, starts it, and opens it. ```typescript @StudioApp({ title: 'Maintenance', workflows: [StateReportWorkflow, CleanupWorkflow], ui: { widgets: [ { widget: 'start-form', options: { workflow: 'state_report', title: 'What is on disk?', subtitle: 'Read-only.', label: 'Report' }, }, { widget: 'start-form', options: { workflow: 'cleanup', title: 'Reclaim orphaned state', label: 'Clean Up' }, }, ], }, }) ``` ## Available Features Some registry modules light up additional Studio surfaces when imported by your app — sidebars, panels, or richer document widgets. Importing a module through its `forFeature()` (or `forRoot()`) registers its feature at bootstrap, and the feature then appears under `StudioAppConfig.features`, which Studio reads to decide what UI to expose. A bare import of the module class does not register the feature. | Feature | Registered by | What it adds to Studio | | -------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `git` | `@loopstack/git` (`GitModule.forFeature(config)`) | Git status panel and version-control affordances | | `localFileExplorer` | `@loopstack/local-file-explorer` (`LocalFileExplorerModule.forFeature(config)`) | "Files" sidebar panel for browsing the local workspace filesystem | | `remoteFileExplorer` | `@loopstack/remote-file-explorer` (`RemoteFileExplorerModule.forFeature(config)`) | "Remote Files" sidebar panel for browsing a remote workspace (requires `RemoteClientModule`) | | `secrets` | `@loopstack/secrets` (`SecretsModule.forFeature(config)`) | Workspace secrets management UI | | `handoff` | `@loopstack/handoff` (`HandoffModule.forFeature(config)`) | Handoff panel and the `handoff` / `changed-files` document widgets | To enable a feature, import the corresponding module's `forFeature()` (or `forRoot()`) in your app's module graph. Features that aren't imported simply don't appear — Studio degrades gracefully and never assumes a feature is present. > Feature registration is an internal mechanism — module authors call `registerFeature()` to declare a feature exists. Most users only need to know which features are available and how to enable them, both shown above. --- > Source: https://loopstack.ai/llms/build/fundamentals/tools.md --- title: Creating Tools description: How to define custom tools with BaseTool, Zod argument schemas, @Tool() decorator, handle() method signature, resultSchema result contracts, tool configuration, and dependency injection into workflows. --- # Creating Tools Tools are reusable TypeScript classes that encapsulate a single action — calling an API, querying a database, transforming data, or any other side effect. Define a tool once with a Zod schema for its arguments, then inject it into any workflow or expose it to LLMs for autonomous tool calling. ## Basic Tool ```typescript import { z } from 'zod'; import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common'; import type { RunContext } from '@loopstack/common'; @Tool({ name: 'search', description: 'Short description of what this tool does.', schema: z .object({ query: z.string().describe('Search query'), limit: z.number().default(10).describe('Max results'), }) .strict(), }) export class SearchTool extends BaseTool<{ query: string; limit: number }, object, string> { protected async handle(args: { query: string; limit: number }, ctx: RunContext): Promise> { return { data: `Found results for: ${args.query}` }; } } ``` ## The `@Tool` Decorator ```typescript @Tool({ name: 'my_tool', description: 'User-facing description.', schema: InputSchema, }) ``` All options are optional. | Option | Type | Default | Description | | -------------- | -------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | class name (as-is) | Unique identifier used in the LLM tool-calling wire format. Always set this to a snake_case identifier (e.g. `git_status`, `math_sum`) — the class name is a fallback. | | `description` | `string` | — | Human-readable description shown to LLMs for tool-use. Critical for autonomous tool calling. | | `widget` | `WidgetRef \| WidgetRef[]` | — | Custom Studio widget(s) for rendering tool calls/results — YAML file path(s) or inline widget object(s). | | `schema` | `z.ZodType` | — | Zod schema validating tool arguments before `handle()` is invoked. | | `configSchema` | `z.ZodType` | — | Zod schema validating tool config (provided via `options.config` on `call()`). | | `resultSchema` | `z.ZodType` | — | Zod schema validating the tool's result (`envelope.data` on success). Optional — without it, results are not validated. | | `effects` | `'none' \| 'external'` | — | Effect classification: `'none'` = reads/computes only, safe to repeat; `'external'` = writes outside the run (sends mail, pushes commits). Unset = treated as external by cautious consumers. | ## The `handle()` Method The abstract method you implement. It receives validated arguments, the execution context, and optional config: ```typescript protected async handle( args: TArgs, ctx: RunContext, options?: ToolCallOptions, ): Promise> { // Your logic here return { data: result }; } ``` The public `call()` method is the entry point — it routes through validation before calling `handle()`, then narrows the envelope: throws on `error`, throws on `pending`, returns a `ToolResult` with `data` and `metadata` non-optional. ## ToolEnvelope vs ToolResult Two related types — pick the right one for the right side of the boundary: ```typescript // What handle() returns — internal/dispatcher shape. type ToolEnvelope = { type?: 'text' | 'image' | 'file'; data?: TData; error?: string; metadata?: Record; pending?: { workflowId: string }; documents?: ToolDocumentDeclaration[]; }; // What tool.call() returns — the narrowed success path workflow authors see. interface ToolResult { data: TData; metadata: Record; type?: 'text' | 'image' | 'file'; } ``` Return patterns inside `handle()`: ```typescript return { data: 42 }; // Simple value return { data: { name: 'result', items: [...] } }; // Typed data return { error: 'Something went wrong' }; // Recoverable failure (LLM tool loop reads this) return { type: 'text', data: 'Mostly sunny, 14C.' }; // Typed output return { data: result, metadata: { tokensUsed: 150 } }; // With metadata return { pending: { workflowId } }; // Async sub-workflow launched ``` ## Result Contract Declare what your tool returns with `resultSchema`. On every successful call, the framework parses `envelope.data` against it — a result that doesn't match fails loudly with an error naming the tool. Error and pending envelopes are exempt; they carry no data contract. ```typescript const SearchResultSchema = z.strictObject({ results: z.array(z.strictObject({ title: z.string(), url: z.string() })), totalCount: z.number(), }); @Tool({ name: 'search', description: 'Searches the index.', schema: z.object({ query: z.string() }).strict(), resultSchema: SearchResultSchema, }) export class SearchTool extends BaseTool<{ query: string }, object, z.infer> { // ... } ``` Conventions: - Use `z.strictObject({...})` — unknown keys in a result are a contract violation and should fail, in both live runs and test fixtures. - Raw third-party payloads passed through verbatim (a provider response, an API blob) are declared as `z.unknown()` **fields**, never as the whole schema. Note that a `z.unknown()` field must still be present — mark it `.optional()` if your code sometimes omits it. - Derive the `TResult` generic from the schema (`z.infer`) so the compile-time type and the runtime contract cannot drift. - Parsing applies schema defaults, so a declared `.default(...)` reaches consumers even when `handle()` omits the field. Because validation happens in the tool pipeline, replayed test fixtures are checked against the same contract as live results — a fixture that drifts from what the tool really returns fails the test instead of silently passing. ## Producing Documents A tool that produces documents **declares** them on its result envelope instead of writing them inside `handle()`. The tool pipeline applies each declaration through the document store after the call completes — the tool decides _whether_ and _what_, the framework does the writing: ```typescript return { data: result, documents: [ { documentName: 'llm_message', // registered @Document name (or the kebab-derived class name) content: result.message, options: { meta: { provider: 'claude' } }, // key / meta / validate — same options as documentStore.save() }, ], }; ``` Declarations are applied on success envelopes only (error and pending envelopes carry none), validated against the document's schema, and a failing save fails the tool call. Because application happens in the pipeline — after any interceptor or replay substitution — a replayed test fixture materializes the same documents a live call would. _Reading_ documents is different: use `this.documentStore` (`findAll`, `findAllDocuments`, `findByTag`) inside `handle()` as usual — the declaration pattern covers writes. ## Dependency Injection Use standard NestJS `@Inject()` or constructor injection: ```typescript import { Inject } from '@nestjs/common'; @Tool({ name: 'math_sum', description: 'Calculates the sum of two numbers.', schema: z.object({ a: z.number(), b: z.number() }).strict(), }) export class MathSumTool extends BaseTool<{ a: number; b: number }, object, number> { constructor(private readonly mathService: MathService) { super(); } protected async handle(args: { a: number; b: number }, ctx: RunContext): Promise> { return { data: this.mathService.sum(args.a, args.b) }; } } ``` ## Tools for LLM Function Calling When a tool is exposed to the LLM, the `description` and `schema` tell the LLM what the tool does and what arguments it accepts: ```typescript @Tool({ name: 'get_weather', description: 'Retrieve weather information for a location.', schema: z.object({ location: z.string().describe('City or location name'), }), }) export class GetWeather extends BaseTool<{ location: string }, object, string> { protected async handle(args: { location: string }, ctx: RunContext): Promise> { return Promise.resolve({ type: 'text', data: 'Mostly sunny, 14C.' }); } } ``` In the workflow, list the tool name in the `tools` config: ```typescript constructor( private readonly llmGenerateText: LlmGenerateTextTool, private readonly getWeather: GetWeather, ) { super(); } const result = await this.llmGenerateText.call( {}, { config: { provider: 'claude', model: 'claude-sonnet-4-6', tools: ['get_weather'] } }, ); ``` ## Async Tools (sub-workflow callbacks) A tool can launch a sub-workflow from `handle()` and finish asynchronously when that sub-workflow completes. The lifecycle has two halves: 1. **`handle()`** returns `{ data, pending: { workflowId } }`. The `pending` field tells the framework "I started run `workflowId`, don't return to the LLM yet — wait for that run to finish, then call me back." 2. **`complete(result)`** runs when the sub-workflow finishes **successfully**. The argument is the sub-workflow's output. The return value is the `ToolEnvelope` that's actually delivered to the LLM (or the caller). Failed or canceled sub-workflows never reach `complete()` — the framework delivers an error envelope directly. Every async tool must implement `complete()` — it defines what the sub-workflow's completion means as the tool's result. The `BaseTool` implementation throws, so a tool that returns `pending` without implementing `complete()` fails loudly on its first completion. The result it returns is validated against the tool's `resultSchema` like any other success envelope. The HITL pattern shows the shape — `AskForApprovalTool.handle()` launches the sub-workflow with `show: 'inline'` so its UI appears in the parent's run view, and returns `pending`; `complete()` returns the user's decision as the typed answer. ```typescript @Tool({ name: 'ask_for_approval', description: 'Ask the user to approve.', /* … */ }) export class AskForApprovalTool extends BaseTool { protected async handle(/* … */) { const { workflowId } = await this.confirmWorkflow.run( args, { callback: { transition: 'onConfirm' }, show: 'inline', label: 'Waiting for approval...' }, ); return { data: { workflowId }, pending: { workflowId } }; } async complete(result: Record): Promise> { const { workflowId, data } = result as { workflowId: string; data: { confirmed: boolean } }; return { data: { approved: data.confirmed, workflowId } }; } } ``` Use this when a tool genuinely depends on an async outcome (HITL, long-running provisioning, external job completion). Tools that finish synchronously inside `handle()` never go pending, so `complete()` is not involved. ## Server Tools Some LLM providers ship built-in tools that **run on the provider's side**, not in your app — examples are Anthropic's `web_search` and `code_execution`. Loopstack exposes these via the `ServerTool` base class instead of `BaseTool`. Key differences from `BaseTool`: | Aspect | `BaseTool` | `ServerTool` | | --------------- | -------------------------------------------- | ----------------------------------------- | | Execution | runs locally in your app | runs on the LLM provider's infrastructure | | Abstract method | `handle(args, ctx, options)` | `toServerToolConfig(config?)` | | Has `call()` | yes — entry point for workflow code | no — the provider invokes it | | Use it for | your own logic, API calls, internal services | provider-native built-in tools | A server tool's job is to translate the workflow author's config into the provider-native shape. The framework detects `instanceof ServerTool` when assembling the LLM request and sends the result of `toServerToolConfig()` to the provider instead of registering a callable local tool. ```typescript import { z } from 'zod'; import { ServerTool, Tool } from '@loopstack/common'; const ConfigSchema = z.object({ maxUses: z.number().int().positive().default(8), allowedDomains: z.array(z.string()).optional(), }); type Config = z.infer; @Tool({ name: 'claude_native_web_search', description: "Claude's provider-native web search. Attach it to an LLM call by listing it in `tools`.", configSchema: ConfigSchema, }) export class ClaudeNativeWebSearchTool extends ServerTool { toServerToolConfig(config?: Config): unknown { return { type: 'web_search_20260209', name: 'web_search', max_uses: config?.maxUses ?? 8, ...(config?.allowedDomains?.length ? { allowed_domains: config.allowedDomains } : {}), }; } } ``` List the server tool in the LLM `tools` config the same way as a regular tool — the framework picks the right code path based on the class. A server tool runs only on the provider whose native spec it returns; a provider that cannot run it rejects the call. ```typescript await this.llmGenerateText.call( {}, { config: { provider: 'claude', model: 'claude-sonnet-4-6', tools: ['claude_native_web_search'], }, }, ); ``` A server tool and a regular tool can wrap the same provider feature, and they are used differently. `@loopstack/claude` ships `claude_native_web_search`, the server tool above: list it in an agent's or LLM call's `tools`, and Claude searches inside that call. `@loopstack/claude-tools` ships `claude_web_search_step`, a `BaseTool` you call from workflow code: it makes its own Claude request with `claude_native_web_search` and returns the hits. To give an agent web search, list `claude_native_web_search` — listing `claude_web_search_step` works too, but every search then costs a second LLM call. ## Using Tools in Workflows ```typescript constructor(private readonly myTool: SearchTool) { super(); } @Transition({ from: 'ready', to: 'done' }) async process(state: MyState) { const result = await this.myTool.call({ query: 'hello', limit: 5 }); this.assignState({ searchResults: result.data }); } ``` ## Module Registration ```typescript @Module({ providers: [SearchTool, MathService], exports: [SearchTool], }) export class MyToolModule {} ``` Then import the module in the workflow's parent module. ## File Structure ``` src/ ├── tools/ │ ├── search.tool.ts │ ├── math-sum.tool.ts │ └── index.ts # Re-exports all tools ├── services/ │ └── math.service.ts ├── my-feature.module.ts └── index.ts ``` ## Registry References - [Custom Tool example](/docs/examples/advanced-workflows#custom-tool) — MathSumTool with injected service, stateful CounterTool, and workflow demonstrating tool usage - [Server Tool example](/docs/examples/advanced-workflows#server-tool) — a code-execution `ServerTool` listed in an `llm_generate_text` call, with the code and its output read from the reply blocks - [Custom Agent example](/docs/examples/agent#custom-agent) — `weather_lookup` and `calculator` tools exposed to the LLM for function calling --- > **Using an AI coding agent?** See [Skill: Create a Custom Tool](../../skills/create-custom-tool.md) for a dense checklist and syntax reference optimized for code generation. --- > Source: https://loopstack.ai/llms/build/fundamentals/workflows.md --- title: Creating Workflows description: How to define workflow state machines using BaseWorkflow, @Workflow() decorator, @Transition() decorator, state typing, wait transitions, and guards. Covers the run trace — the per-run event journal (transitions, tool calls, documents, run.settled) with opt-in persistence via --trace. Includes full chat workflow example. --- # Creating Workflows A workflow is a state machine defined as a TypeScript class. Define transitions between named states, add guards for conditional routing, and use wait transitions to pause for user input or external events. > **Before you build much:** read [Best Practices](../best-practices.md) — when to choose scripted vs agentic flows, where logic belongs, the difference between state, result, and documents, and the conventions that keep workflows clean. ## Chat Example A simple chat workflow: wait for a user message, call LLM, display the response, and loop back. ```typescript import { z } from 'zod'; import { BaseWorkflow, Transition, type TransitionInput, Workflow } from '@loopstack/common'; import { LlmGenerateTextTool, LlmMessageDocument } from '@loopstack/llm-provider'; @Workflow({ widget: './chat.ui.yaml', // UI config }) export class ChatWorkflow extends BaseWorkflow { constructor(private readonly llmGenerateText: LlmGenerateTextTool) { super(); } // 1. Entry point @Transition({ to: 'waiting_for_user' }) setup(state: Record) {} // 2. Wait for user message @Transition({ from: 'waiting_for_user', to: 'ready', wait: true, schema: z.string(), }) async userMessage(state: Record, input: TransitionInput) { await this.documentStore.save(LlmMessageDocument, { role: 'user', text: input.data }); } // 3. Call LLM and loop back @Transition({ from: 'ready', to: 'waiting_for_user', }) async llmTurn(state: Record) { await this.llmGenerateText.call({}, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }); } } ``` That's a complete workflow. The state flow is: ``` start → waiting_for_user → [user sends message] → ready → llmTurn → waiting_for_user (loop) ``` ## The `@Workflow` Decorator ```typescript @Workflow({ widget: './chat.ui.yaml', }) ``` All options are optional. | Option | Type | Default | Description | | -------------- | -------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `name` | `string` | class name with `Workflow` suffix stripped, snake_cased | Explicit snake_case identifier. E.g. `ChatWorkflow` → `chat`, `AgentExampleWorkflow` → `agent_example`. | | `title` | `string` | — | Human-readable display title shown in Studio UI. | | `description` | `string` | — | Human-readable description shown in Studio UI. | | `widget` | `WidgetRef \| WidgetRef[]` | — | Path(s) to YAML file(s) — or inline widget object(s) — defining the Studio UI surface for this workflow. | | `schema` | `z.ZodType` | — | Zod schema validating workflow input arguments. Surfaces as `ctx.args` in transitions. | | `configSchema` | `z.ZodType` | — | Zod schema validating workflow config (provided via `options.config` at start time / sub-workflow `run()`). | | `stateSchema` | `z.ZodType` | — | Zod schema validating the resulting state after every transition (see [Validating State](#validating-state-with-stateschema)). | ```typescript @Workflow({ widget: './prompt.ui.yaml', schema: z.object({ subject: z.string().default('coffee'), }), }) ``` ## `BaseWorkflow` All workflows extend `BaseWorkflow`, which provides: | Property / Method | Description | | -------------------- | ----------------------------------------------------------------------------------- | | `this.documentStore` | Save and query documents via `this.documentStore.save(DocClass, content, options?)` | | `this.render` | Render Handlebars templates via `this.render(templatePath, data?)` | Context is passed as a parameter to transition methods via `ctx: RunContext`. The generic parameter types `ctx.args` — prefer it over casting: | Context Property | Description | | --------------------------- | ------------------------------------------------------------------------------------------ | | `ctx.userId` | User ID | | `ctx.workspaceId` | Workspace ID | | `ctx.workflowId` | Current workflow run ID | | `ctx.args` | Validated input arguments (typed via `RunContext`) | | `ctx.execution?.place` | Current state name. Present in workflow transitions, absent when `ctx` is passed to tools. | | `ctx.execution?.retryCount` | Retry attempt counter for the current transition (0 on first run). | ```typescript @Transition({ to: 'ready', schema: z.object({ subject: z.string() }) }) setup(state: MyState, ctx: RunContext<{ subject: string }>) { this.assignState({ subject: ctx.args.subject }); } ``` ## Transition Types ### Initial Transition — Entry Point Runs once when the workflow starts. Uses `@Transition` with no `from` (defaults to `'start'`): ```typescript @Transition({ to: 'ready' }) setup(state: MyState, ctx: RunContext<{ subject: string }>) { this.assignState({ subject: ctx.args.subject }); } ``` The `state` parameter starts as an empty object `{}` — the initial transition is the place to populate it. ### Standard Transition — State Change Moves between states. Fires automatically unless `wait: true` is set. ```typescript @Transition({ from: 'ready', to: 'processed' }) async doWork(state: MyState) { const result = await this.myTool.call({ query: 'hello' }); this.assignState({ data: result.data }); } ``` A method can listen on **multiple source states**: ```typescript @Transition({ from: 'ready', to: 'prompt_executed' }) @Transition({ from: 'tools_done', to: 'prompt_executed' }) async llmTurn(state: MyState) { ... } ``` ### Wait Transition — Pause for Input Add `wait: true` to pause the workflow until externally triggered — by user input, a button click, or a sub-workflow callback. Use `schema` to validate and type the incoming `data`; the transition method receives a `TransitionInput` envelope with `data` plus failure info (`hasError`, `errorMessage`, `status`). ```typescript @Transition({ from: 'waiting_for_user', to: 'ready', wait: true, schema: z.object({ message: z.string() }), }) async userMessage(state: MyState, input: TransitionInput<{ message: string }>) { await this.documentStore.save(LlmMessageDocument, { role: 'user', text: input.data.message, }); } ``` For approval gates, confirmation dialogs, and other interactive pauses built on top of `wait: true`, see [Human-in-the-Loop](../patterns/human-in-the-loop.md). ### Final Transition — Completion Uses `@Transition` with `to: 'end'`. The workflow's output is published via `this.assignResult(...)` or `this.setResult(...)` — that value is what parent workflow callbacks and `WorkflowRunner` callers receive. ```typescript @Transition({ from: 'done', to: 'end' }) finish(state: MyState) { this.setResult({ concept: state.confirmedConcept! }); } ``` ## Guarding Transitions When multiple transitions share the same `from` state, attach `@Guard('methodName')` to pick which one fires: - Higher `priority` is checked first. Transitions without `priority` are evaluated last, in declaration order. - A guard is a boolean method on the workflow that receives the current `state` and returns `true` to allow the transition. - A transition without a guard always passes — use it as the fallback. ```typescript @Transition({ from: 'prompt_executed', to: 'awaiting_tools', priority: 10 }) @Guard('hasToolCalls') async executeToolCalls(state: MyState) { const result = await this.llmDelegateToolCalls.call({ message: state.llmResult!.message, tools: TOOLS, // the tool names given to llmGenerateText callback: { transition: 'toolResultReceived' }, }); this.assignState({ delegateResult: result.data }); } @Transition({ from: 'prompt_executed', to: 'end' }) respond(_state: MyState) {} hasToolCalls(state: MyState): boolean { return state.llmResult?.message.stopReason === 'tool_use'; } ``` From `prompt_executed`, `executeToolCalls` fires whenever the LLM requested tools; otherwise `respond` (unguarded) ends the workflow. ## State Transitions return nothing — mutate state via `this.assignState(...)`. Use `async` when the body awaits. State is read from the `state` parameter and written through setters on `BaseWorkflow`: | Setter | Effect | | ---------------------------- | --------------------------------------------------------------------------------------------------------- | | `this.assignState(partial)` | Shallow-merge `partial` into the current state. The most common form. | | `this.setState(full)` | Replace the state object outright. | | `this.assignResult(partial)` | Shallow-merge `partial` into the workflow's published `result` (visible to callers and parent callbacks). | | `this.setResult(full)` | Replace the workflow's published `result` outright. | ```typescript interface MyState { counter: number; llmResult?: LlmGenerateTextResult; } export class MyWorkflow extends BaseWorkflow { @Transition({ from: 'ready', to: 'processed' }) process(state: MyState) { this.assignState({ counter: (state.counter ?? 0) + 1 }); } } ``` Values persist even when the workflow pauses and resumes. Returning a value from a transition is a runtime error — every write must go through the setters. ### Validating State with `stateSchema` Add a Zod schema via `@Workflow({ stateSchema })` to enforce the state shape at runtime. The processor validates the resulting state after every transition (before persistence). If validation fails the transition errors out — bugs that corrupt state are caught at the point they occur instead of leaking into later transitions or checkpoints. ```typescript const MyStateSchema = z.object({ counter: z.number().int().nonnegative(), llmResult: z.unknown().optional(), }); @Workflow({ stateSchema: MyStateSchema, }) export class MyWorkflow extends BaseWorkflow { @Transition({ from: 'ready', to: 'processed' }) process(state: z.infer) { this.assignState({ counter: (state.counter ?? 0) + 1 }); } } ``` Use this when the state shape is critical and you want fail-fast diagnostics. Skip it for prototyping or when the state is loose by design. ## Injecting Tools Tools are injected via standard NestJS constructor injection: ```typescript constructor( private readonly llmGenerateText: LlmGenerateTextTool, ) { super(); } @Transition({ from: 'ready', to: 'done' }) async process(state: MyState) { const result = await this.llmGenerateText.call( { prompt: 'Write a haiku' }, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }, ); this.assignState({ llmResult: result.data }); } ``` Any provider can be injected the same way. For time-dependent logic, inject the framework clock (`@Inject(CLOCK) private readonly clock: Clock`) instead of calling `Date.now()` or `setTimeout` directly — under a test clock the workflow stays deterministic. ## Documents Use `this.documentStore.save()` to create or update documents. Reference document classes directly — no injection needed. ```typescript // Create a document await this.documentStore.save(LlmMessageDocument, { role: 'user', text: 'Hello!', }); // Update an existing document by key, in place await this.documentStore.save( LlmMessageDocument, { role: 'assistant', text: 'Updated response' }, { key: 'response-1', position: 'keep' }, ); // Hidden context (not shown in UI — LLM still sees it as conversation history) await this.documentStore.save(LlmContextDocument, { role: 'user', text: 'System prompt' }); ``` ## Templates `render` is available directly on `BaseWorkflow` (like `documentStore`). Use `this.render()` to render Handlebars template files: ```typescript const rendered = this.render(join(__dirname, 'templates', 'prompt.md'), { subject: args.subject, }); ``` ## Places (States) Places are implicit — defined by `from`/`to` values in your decorators. Two special places: - **`start`** — Implicit initial place (the initial transition moves from here when `from` is omitted) - **`end`** — When reached, the workflow completes All other place names are arbitrary strings you choose. ## The Run Trace Every run produces a **trace**: an ordered, append-only journal of everything the run did. The engine never reads it — it exists for you: debugging a failed run, asserting on behavior in tests, deriving replay fixtures, and auditing what an automation actually executed. | Event | Emitted when | Carries | | ------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------ | | `transition.started` | A transition begins | transition id, `from`/`to`, the wait payload | | `transition.completed` | It succeeds | duration, a per-key **state diff**, whether the result was touched | | `transition.failed` | It throws or a sub-workflow callback fails | error, retry count, whether a retry is scheduled | | `tool.called` / `tool.completed` / `tool.failed` | Each tool call | tool name, per-transition order, validated args, the result envelope, duration | | `document.emitted` | A document is saved | document name/key, the invalidated predecessor key | | `child.queued` / `child.settled` | A sub-workflow launches / finishes | child workflow id, name, status | | `run.settled` | Every park and terminal settle | status, place — parks include the transitions the run is waiting on | Events are ordered by a per-run monotonic `seq` (continuous across pause/resume) and carry a wall-clock `ts`. Failing tool calls and failing transitions are first-class events — a trace always shows _where_ a run died, with the exact call and error. **In memory, the trace is always on.** A run's processing result carries it (`meta.trace`), stateless runs carry it across park/resume, and workflow tests assert on it via [`run.trace` and `run.toolCalls`](/docs/build/testing). **Persistence is opt-in per run.** Start a run with `loopstack run --trace` (or `trace: true` on the start payload) and its whole run tree — sub-workflows inherit the flag — persists its events as queryable rows. Read them back with `loopstack runs --record ` (derives a [replay fixture](/docs/build/testing)), `GET /workflows/:id/tool-calls`, or `client.workflows.toolCalls(id)`. To record every run, e.g. on a dev backend, enable it globally with the [`trace` option / `LOOPSTACK_TRACE=true`](/docs/reference/configuration#trace). ## YAML Configuration YAML files define **UI layout only** — no transitions, conditions, or tool calls. They configure what widgets appear in the Studio interface. ```yaml title: 'My Workflow' description: 'What this workflow does' ui: widgets: - widget: form enabledWhen: [waiting] options: properties: name: title: Name actions: - type: button transition: userResponse label: Submit - widget: prompt-input enabledWhen: [waiting_for_user] options: transition: userMessage ``` The `transition` values must match **method names** of `wait: true` transitions. ### `enabledWhen` Controls when a widget is interactive based on the current workflow place. Outside the listed places the widget stays on screen but is disabled: ```yaml - widget: prompt-input enabledWhen: - waiting_for_user # Only enabled at this place options: transition: userMessage ``` ### `showWhen` Controls when a widget is visible. Outside the listed places the widget is not rendered at all — use it for widgets that only make sense at one step, such as a cancel or recover button: ```yaml - widget: button showWhen: - awaiting_tools # Only rendered at this place options: transition: cancelPendingTools label: Cancel pending tools ``` When a widget sets both, `showWhen` decides whether it is rendered and `enabledWhen` whether it is enabled. See [Workflow YAML Schema — `showWhen`](/docs/reference/workflow-yaml#showwhen). ### Form Actions Buttons that trigger `wait: true` transitions when clicked: ```yaml actions: - type: button transition: confirm # Must match the method name label: 'Confirm' ``` ## Module Registration ```typescript @Module({ imports: [ClaudeModule], providers: [ChatWorkflow], exports: [ChatWorkflow], }) export class ChatModule {} ``` ## File Structure ``` src/ ├── workflows/ │ ├── chat.workflow.ts │ ├── chat.ui.yaml │ └── templates/ │ └── systemMessage.md ├── chat.module.ts └── index.ts ``` ## Registry References - [Prompt Input Chat example](/docs/examples/hitl#prompt-input-chat) — Multi-turn chat loop with the prompt-input widget, without an LLM - [Prompt example](/docs/examples/llm#prompt) — Simple single-turn prompt workflow - [Custom Agent example](/docs/examples/agent#custom-agent) — Tool calling loop with guards and conditional routing - [Dynamic Routing example](/docs/examples/advanced-workflows#dynamic-routing) — Multi-level guard-based routing - [Workflow State example](/docs/examples/advanced-workflows#workflow-state) — State management with typed state interface - [Sub-Workflow example](/docs/examples/advanced-workflows#sub-workflow) — Sub-workflow execution with callbacks --- > **Using an AI coding agent?** See [Skill: Create a Custom Workflow](../../skills/create-custom-workflow.md) for a dense checklist and syntax reference optimized for code generation. --- # Build / Integrations --- > Source: https://loopstack.ai/llms/build/integrations/lifecycle-events.md --- title: Lifecycle Events description: In-process lifecycle events a host app listens to with @OnEvent from @nestjs/event-emitter — workflow.settled (WORKFLOW_SETTLED, WorkflowSettledEvent from @loopstack/core) when a run completes, fails or is canceled, and workflow.deleted / workspace.deleted when a run or workspace is deleted. Payload fields, when each event is emitted, the cascade rule for workspace and sub-workflow deletes, error handling, and why listeners must be idempotent. --- # Lifecycle Events An app often holds something for a run or a workspace that Loopstack does not know about: a checkout on disk, a container, a reserved slot, a row in its own tables. Loopstack emits in-process events when a run ends and when a run or workspace is deleted, so the app can release those resources without polling. ## The events | Event | Emitted when | Payload | | ------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `workflow.settled` | A run reaches `completed`, `failed` or `canceled` | `WorkflowSettledEvent` — `id`, `workspaceId`, `workflowName`, `parentId?`, `status`, `user` | | `workflow.deleted` | A run is deleted through the API | `{ id, workspaceId, user }` | | `workspace.deleted` | A workspace is deleted through the API | `{ id, appName, user }` | `user` is the ID of the user the run or workspace belongs to. ### `workflow.settled` `@loopstack/core` exports the event name as `WORKFLOW_SETTLED` and the payload type as `WorkflowSettledEvent`. The event fires once a run reaches a state it does not leave by itself: `completed`, `failed` or `canceled`. Every path that ends a run emits it — a processing pass that reaches a terminal state, a job the queue gave up on, and a cancellation. - It is emitted after the run's own persistence has committed. - It is emitted for sub-workflows as well as root runs. `parentId` is set only for a sub-workflow, so a listener that cares only about root runs checks that `parentId` is absent. ### `workflow.deleted` and `workspace.deleted` `@loopstack/api` emits these after the delete has committed — once per deleted run or workspace, from the single delete and from the batch delete endpoint. In a batch delete, only the items that were actually deleted emit an event; IDs that were not found or not deleted emit nothing. The database removes dependent rows by cascade, and a **cascaded delete emits no event of its own**: - Deleting a workspace deletes all its runs, but emits only `workspace.deleted`. A `workspace.deleted` listener must release everything the workspace owned, including what it holds per run. - Deleting a run deletes its sub-workflows, but emits `workflow.deleted` only for the run that was deleted. Rows deleted directly in the database, outside the API, emit nothing. ## Listening to an event The events go through the NestJS event emitter that `LoopstackModule` registers. They do not leave the process: a listener is an `@Injectable()` provider with an `@OnEvent()` method, registered in a module of your app. `OnEvent` comes from `@nestjs/event-emitter`; add it to your app's dependencies. ```typescript import { Injectable, Logger } from '@nestjs/common'; import { OnEvent } from '@nestjs/event-emitter'; import { WORKFLOW_SETTLED, type WorkflowSettledEvent } from '@loopstack/core'; @Injectable() export class PreviewCleanupListener { private readonly logger = new Logger(PreviewCleanupListener.name); constructor(private readonly previews: PreviewService) {} @OnEvent(WORKFLOW_SETTLED) async onSettled(event: WorkflowSettledEvent) { if (event.parentId) return; // only root runs hold a preview await this.previews.stopForRun(event.id); } @OnEvent('workflow.deleted') async onWorkflowDeleted(payload: { id: string; workspaceId: string; user: string }) { await this.previews.removeForRun(payload.id); } @OnEvent('workspace.deleted') async onWorkspaceDeleted(payload: { id: string; appName: string; user: string }) { // Runs deleted with the workspace emit no workflow.deleted — release them here. await this.previews.removeForWorkspace(payload.id); } } ``` ```typescript @Module({ providers: [PreviewService, PreviewCleanupListener], }) export class MyAppModule {} ``` ### Rules for listeners - **Make them idempotent.** There is no guarantee that an event arrives exactly once, and a process that stops before the listener ran never sees it. Release operations must tolerate a second call. When correctness depends on the release, also reconcile against the stored state (for example, sweep for resources whose run or workspace no longer exists) and treat the event as the prompt to do it early. - **Do not depend on the caller waiting.** The emitter does not await an async listener. The delete request returns and the run continues while your listener is still working, so a slow cleanup does not block anything. - **Errors do not reach the caller.** `@OnEvent` catches and logs an error thrown by its listener by default, so a failing listener does not fail the delete or the run. A failed `workflow.settled` listener also does not stop the parent run's callback. Log what you could not release, so the next sweep can find it. ## Real listeners Two registry packages release their resources this way: - [`@loopstack/claims`](/docs/registry/claims#a-claim-cannot-be-left-behind) releases resource claims on `workflow.settled`, `workflow.deleted` and `workspace.deleted`. - [`@loopstack/code-workspace`](/docs/registry/code-workspace#reclamation) removes checkouts, containers and volumes on `workflow.deleted` and `workspace.deleted`, and runs an orphan sweep for anything a listener missed. For events that describe what happens _inside_ a run — workflow and document updates as they stream to Studio — see the `client.message` listener in the [Audit Log example](/docs/examples/observability#audit-log). --- > Source: https://loopstack.ai/llms/build/integrations/oauth.md --- title: OAuth Authentication description: Integrating OAuth 2.0 authentication using @loopstack/oauth. Covers setup with Google Workspace provider, token management, and accessing OAuth-protected APIs from workflows. --- # OAuth Authentication Add OAuth 2.0 authentication to your workflows using the provider-agnostic `@loopstack/oauth`. Register providers like Google Workspace or GitHub, and access OAuth-protected APIs from any workflow or tool. ## How It Works The module is split into three layers: 1. **Provider registry** — provider modules (Google, GitHub, etc.) implement `OAuthProviderInterface` and self-register at module init. The registry resolves a provider by name at call time. 2. **OAuth workflow** — a generic `OAuthWorkflow` that builds the auth URL, surfaces a sign-in prompt via `OAuthPromptDocument`, waits for the browser callback, and exchanges the auth code for tokens. Run it as a sub-workflow from any parent workflow. 3. **Token store** — `OAuthTokenStore` persists access/refresh tokens per user per provider in Redis (falls back to in-memory when Redis is unavailable). `getValidAccessToken()` automatically refreshes expired tokens via the provider's `refreshToken()` method. ``` start ──► initiateOAuth ──► awaiting_auth ──► exchangeToken ──► end │ │ │ Builds auth URL, │ Validates CSRF state, │ saves OAuthPromptDocument │ exchanges code, │ with sign-in prompt │ stores tokens ▼ ▼ (waits for user to (callback resumes complete OAuth in browser) parent workflow) ``` Tools that need an access token call `OAuthTokenStore.getValidAccessToken(userId, provider)` and return `{ error: 'unauthorized' }` if no valid token exists, which lets the parent workflow guard branch into running `OAuthWorkflow`. ## Setup ```typescript import { Module } from '@nestjs/common'; import { GoogleWorkspaceModule } from '@loopstack/google-workspace'; @Module({ imports: [GoogleWorkspaceModule], providers: [MyWorkflow], exports: [MyWorkflow], }) export class MyModule {} ``` `GoogleWorkspaceModule` and `GitHubModule` import `OAuthModule` internally — you don't need to add it explicitly. For a custom provider, import `OAuthModule` directly alongside your provider module: ```typescript import { OAuthModule } from '@loopstack/oauth'; import { MyCustomOAuthModule } from './my-custom-oauth.module'; @Module({ imports: [OAuthModule, MyCustomOAuthModule], providers: [MyWorkflow], }) export class MyModule {} ``` `OAuthModule` is decorated with `@Global()`, so a single import makes the registry, token store, and OAuth tools available throughout your app. ## OAuth as Sub-Workflow The simplest approach: launch the built-in `OAuthWorkflow` when authentication is needed. ```typescript import { BaseWorkflow, Guard, Transition, Workflow } from '@loopstack/common'; import type { RunContext, TransitionInput } from '@loopstack/common'; import { MarkdownDocument } from '@loopstack/common'; import { OAuthWorkflow } from '@loopstack/oauth'; interface CalendarState { events?: CalendarEvent[]; requiresAuthentication?: boolean; } type CalendarArgs = { calendarId: string }; @Workflow({ widget: './calendar.ui.yaml' }) export class CalendarWorkflow extends BaseWorkflow { constructor( private readonly calendarFetchEvents: CalendarFetchEventsTool, private readonly oAuth: OAuthWorkflow, ) { super(); } @Transition({ to: 'calendar_fetched' }) async fetchEvents(state: CalendarState, ctx: RunContext) { const result = await this.calendarFetchEvents.call({ calendarId: ctx.args.calendarId, }); this.assignState({ requiresAuthentication: result.data.error === 'unauthorized', events: result.data.events, }); } // If unauthorized -> launch OAuth sub-workflow @Transition({ from: 'calendar_fetched', to: 'awaiting_auth', priority: 10 }) @Guard('needsAuth') async authRequired(state: CalendarState) { await this.oAuth.run( { provider: 'google', scopes: ['https://www.googleapis.com/auth/calendar.readonly'] }, { callback: { transition: 'authCompleted' }, show: 'inline', label: 'Google authentication required' }, ); } needsAuth(state: CalendarState): boolean { return !!state.requiresAuthentication; } // After auth -> retry from start @Transition({ from: 'awaiting_auth', to: 'start', wait: true }) authCompleted(state: CalendarState, _input: TransitionInput) {} // Success -> display results @Transition({ from: 'calendar_fetched', to: 'end' }) async displayResults(state: CalendarState) { await this.documentStore.save(MarkdownDocument, { markdown: this.render(join(__dirname, 'templates', 'summary.md'), { events: state.events }), }); } } ``` ## Using Tokens in Custom Tools ```typescript import { z } from 'zod'; import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common'; import type { RunContext } from '@loopstack/common'; import { OAuthTokenStore } from '@loopstack/oauth'; @Tool({ name: 'calendar_fetch_events', description: 'Fetches Google Calendar events.', schema: z.object({ calendarId: z.string().default('primary') }).strict(), }) export class CalendarFetchEventsTool extends BaseTool { constructor(private readonly tokenStore: OAuthTokenStore) { super(); } protected async handle(args: { calendarId: string }, ctx: RunContext): Promise { const accessToken = await this.tokenStore.getValidAccessToken(ctx.userId, 'google'); if (!accessToken) { return { data: { error: 'unauthorized' } }; } const response = await fetch(`https://www.googleapis.com/calendar/v3/calendars/${args.calendarId}/events`, { headers: { Authorization: `Bearer ${accessToken}` }, }); return { data: await response.json() }; } } ``` ## Creating a Custom OAuth Provider See [Creating OAuth Providers](../../extend/oauth-providers.md) for how to implement `OAuthProviderInterface` and register a custom provider. ## Environment Variables Each OAuth provider reads its own credentials from env, conventionally named `_CLIENT_ID`, `_CLIENT_SECRET`, and `_OAUTH_REDIRECT_URI`: ``` # Google Workspace GOOGLE_CLIENT_ID=... GOOGLE_CLIENT_SECRET=... GOOGLE_OAUTH_REDIRECT_URI=... # GitHub GITHUB_CLIENT_ID=... GITHUB_CLIENT_SECRET=... GITHUB_OAUTH_REDIRECT_URI=... ``` The token store also reads `REDIS_HOST`, `REDIS_PORT`, and `REDIS_PASSWORD` — see [Configuration Reference](../../reference/configuration.md) for defaults. Redis is optional; an in-memory fallback is used when unavailable. ## Token Lifecycle 1. `OAuthWorkflow` generates auth URL and shows it to the user 2. User completes OAuth in browser 3. Token is exchanged and stored per user per provider 4. `OAuthTokenStore.getValidAccessToken()` auto-refreshes expired tokens 5. Tools return `{ error: 'unauthorized' }` if no token exists 6. Workflow guard detects the error and launches OAuth sub-workflow ## Registry References - [Google Workspace examples](/docs/examples/google-workspace) — Google Calendar fetch with OAuth sub-workflow and Google Workspace agent with tool calling - [GitHub examples](/docs/examples/github) — GitHub OAuth integration with repos overview and GitHub agent with 25 tools --- > Source: https://loopstack.ai/llms/build/integrations/programmatic-execution.md --- title: Scheduling & Programmatic Execution description: Scheduling and programmatic workflow execution with WorkflowRunner — cron (@Cron), webhook endpoints, delayed runs (SchedulerRegistry), batch fan-out, and triggering from API requests or internal events. run vs runSync, appName/userId context. --- # Scheduling & Programmatic Execution Start and manage workflows programmatically from your NestJS application — in response to API requests, webhook events, cron jobs, or internal application logic — without going through the Studio UI. ## Overview Use the `WorkflowRunner` to execute workflows in response to: - External API requests - Webhook events - Scheduled cron jobs - Internal application events - Batch processing tasks For a runnable version of every pattern below — cron, webhook, delayed run, and batch — see the [scheduling examples](/docs/examples/scheduling). Each fundamental ships as a small workflow plus the real trigger that fires it, and you can drive the HTTP-triggered ones straight from Studio. ## Basic Example ### Create a Controller ```typescript import { Body, Controller, Post } from '@nestjs/common'; import { WorkflowRunner } from '@loopstack/core'; import { MyWorkflow } from './workflows/my.workflow'; @Controller() export class AppController { constructor(private readonly workflowRunner: WorkflowRunner) {} @Post('run-my-workflow') async runMyWorkflow(@Body() payload: any) { const userId = '...'; // define a user id to run the workflow const result = await this.workflowRunner.run(MyWorkflow, payload, { appName: 'default', userId, }); return { message: 'Workflow run is queued.', workflowId: result.workflowId }; } } ``` ### WorkflowRunner Methods ```typescript // Async (queued via BullMQ) await this.workflowRunner.run( workflow, // Workflow class reference args, // Data passed as workflow args (type-safe) { appName, // App name for workspace resolution userId, // User ID for execution context }, ); // Sync (inline execution, awaits result) await this.workflowRunner.runSync( workflow, // Workflow class reference args, // Data passed as workflow args (type-safe) { appName, // App name for workspace resolution userId, // User ID for execution context stateless, // Optional: skip persistence (default: false) }, ); ``` ## Advanced Examples ### Webhook Handler Trigger a workflow when receiving a webhook: ```typescript import { Body, Controller, Headers, Post } from '@nestjs/common'; import { WorkflowRunner } from '@loopstack/core'; @Controller('webhooks') export class WebhookController { constructor(private readonly workflowRunner: WorkflowRunner) {} @Post('stripe') async handleStripeWebhook(@Body() webhookData: any, @Headers('stripe-signature') signature: string) { await this.workflowRunner.run( ProcessWebhookWorkflow, { source: 'stripe', event: webhookData, receivedAt: new Date().toISOString(), }, { appName: 'main', userId: webhookData.userId, }, ); return { received: true }; } } ``` ### Scheduled Task Execute a workflow on a schedule using NestJS's `@Cron` decorator: ```typescript import { Injectable } from '@nestjs/common'; import { Cron, CronExpression } from '@nestjs/schedule'; import { WorkflowRunner } from '@loopstack/core'; @Injectable() export class TaskScheduler { constructor(private readonly workflowRunner: WorkflowRunner) {} @Cron(CronExpression.EVERY_DAY_AT_9AM) async generateDailyReports() { const users = await this.getUsersWithReportsEnabled(); for (const user of users) { await this.workflowRunner.run( DailyReportWorkflow, { reportDate: new Date().toISOString(), reportType: 'daily', }, { appName: 'reports', userId: user.id, }, ); } } } ``` ### Delayed Run Run a workflow once after a delay — e.g. "follow up 24h after signup". Register a one-off timeout with NestJS's `SchedulerRegistry`, then trigger the workflow when it fires: ```typescript import { Injectable } from '@nestjs/common'; import { SchedulerRegistry } from '@nestjs/schedule'; import { randomUUID } from 'node:crypto'; import { WorkflowRunner } from '@loopstack/core'; @Injectable() export class SignupFollowupService { constructor( private readonly workflowRunner: WorkflowRunner, private readonly scheduler: SchedulerRegistry, ) {} scheduleFollowup(email: string, userId: string, delayMs = 24 * 60 * 60 * 1000) { const name = `signup-followup-${randomUUID()}`; const timeout = setTimeout(() => { this.scheduler.deleteTimeout(name); void this.workflowRunner.run(SignupFollowupWorkflow, { email }, { appName: 'onboarding', userId }); }, delayMs); this.scheduler.addTimeout(name, timeout); } } ``` `SchedulerRegistry` timeouts live in memory, so a server restart loses any pending run. For delays that must survive restarts, enqueue a [BullMQ delayed job](https://docs.bullmq.io/guide/jobs/delayed) instead. ### Batch Processing Process multiple items by triggering workflows in parallel: ```typescript import { Injectable } from '@nestjs/common'; import { WorkflowRunner } from '@loopstack/core'; @Injectable() export class OrderProcessingService { constructor(private readonly workflowRunner: WorkflowRunner) {} async processPendingOrders() { const pendingOrders = await this.getPendingOrders(); const promises = pendingOrders.map((order) => this.workflowRunner.run( ProcessOrderWorkflow, { orderId: order.id, orderData: order, }, { appName: 'orders', userId: order.userId, }, ), ); await Promise.all(promises); return { processed: pendingOrders.length }; } } ``` ## Registry References - [Scheduling examples](/docs/examples/scheduling) — Runnable examples of every scheduling fundamental: cron (`@Cron` + `WorkflowRunner.run`), webhook (`@Public @Post` controller), delayed run (`SchedulerRegistry` timeout), and batch (`Promise.all` fan-out). Includes Studio-launchable workflows that make the real HTTP call to each trigger endpoint. --- > Source: https://loopstack.ai/llms/build/integrations/sandbox.md --- title: Sandbox Execution description: Executing untrusted code in Docker containers using @loopstack/docker-sandbox and @loopstack/docker-sandbox-filesystem. Setup, file I/O inside sandboxes, and cleanup. --- # Sandbox Execution Run untrusted or AI-generated code safely in isolated Docker containers. The sandbox packages provide tools for creating disposable execution environments with filesystem access, letting workflows execute arbitrary code without risking the host system. ## Prerequisites Docker must be installed and running on the host system before any sandbox tool is invoked. The sandbox tools shell out to the local Docker daemon to create, start, exec into, and remove containers — `sandbox_init` will fail at runtime if Docker isn't available. Any Docker image works — `imageName` is passed straight through to Docker, so anything you'd put after `docker pull` (`node:18`, `python:3.11-slim`, your own private image) is valid. Images are pulled automatically on first use, so the first init for an unfamiliar image may be slow. ## Host ↔ Container Filesystem `sandbox_init` takes two related paths: - `projectOutPath` — an absolute path on the **host** machine. - `rootPath` — a path **inside** the container (defaults to `workspace`). The host directory at `projectOutPath` is bind-mounted into the container at `/`. Anything the container writes under `/` shows up at `projectOutPath` on the host, and vice versa — it's the same set of files viewed from two sides. Use this to feed inputs into the sandbox, read outputs back out, and persist artifacts across container destroys. ## Setup ```typescript import { Module } from '@nestjs/common'; import { SandboxFilesystemModule } from '@loopstack/docker-sandbox-filesystem'; @Module({ imports: [SandboxFilesystemModule], providers: [SandboxWorkflow], exports: [SandboxWorkflow], }) export class SandboxModule {} ``` ## Example Workflow ```typescript import { z } from 'zod'; import { BaseWorkflow, Transition, Workflow } from '@loopstack/common'; import type { RunContext } from '@loopstack/common'; import { SandboxDestroy, SandboxInit } from '@loopstack/docker-sandbox'; import { SandboxCreateDirectory, SandboxDelete, SandboxReadFile, SandboxWriteFile, } from '@loopstack/docker-sandbox-filesystem'; interface SandboxState { containerId?: string; } const SandboxArgsSchema = z.object({ outputDir: z.string().default(process.cwd() + '/out') }); type SandboxArgs = z.infer; @Workflow({ widget: './sandbox.ui.yaml', schema: SandboxArgsSchema, }) export class SandboxWorkflow extends BaseWorkflow { constructor( private readonly sandboxInit: SandboxInit, private readonly sandboxDestroy: SandboxDestroy, private readonly sandboxWriteFile: SandboxWriteFile, private readonly sandboxReadFile: SandboxReadFile, private readonly sandboxCreateDirectory: SandboxCreateDirectory, ) { super(); } @Transition({ to: 'sandbox_ready' }) async initSandbox(state: SandboxState, ctx: RunContext) { const result = await this.sandboxInit.call({ containerId: 'my-sandbox', imageName: 'node:18', containerName: 'sandbox-container', projectOutPath: ctx.args.outputDir, rootPath: 'workspace', }); this.assignState({ containerId: result.data.containerId }); } @Transition({ from: 'sandbox_ready', to: 'file_written' }) async writeFile(state: SandboxState) { await this.sandboxCreateDirectory.call({ containerId: state.containerId!, path: '/workspace/src', recursive: true, }); await this.sandboxWriteFile.call({ containerId: state.containerId!, path: '/workspace/src/hello.js', content: "console.log('Hello from sandbox!');", encoding: 'utf8', createParentDirs: true, }); } @Transition({ from: 'file_written', to: 'file_read' }) async readFile(state: SandboxState) { await this.sandboxReadFile.call({ containerId: state.containerId!, path: '/workspace/src/hello.js', encoding: 'utf8', }); } @Transition({ from: 'file_read', to: 'end' }) async destroySandbox(state: SandboxState) { await this.sandboxDestroy.call({ containerId: state.containerId!, removeContainer: true, }); } } ``` ## Available Tools ### Container Lifecycle | Tool | Args | Description | | ---------------- | ----------------------------------------------------------------- | -------------------------- | | `sandboxInit` | `containerId, imageName, containerName, projectOutPath, rootPath` | Create and start container | | `sandboxDestroy` | `containerId, removeContainer` | Stop/remove container | ### Filesystem Operations | Tool | Args | Description | | ------------------------ | ---------------------------------------------------------- | ---------------------- | | `sandboxWriteFile` | `containerId, path, content, encoding?, createParentDirs?` | Write file | | `sandboxReadFile` | `containerId, path, encoding?` | Read file content | | `sandboxListDirectory` | `containerId, path, recursive?` | List directory entries | | `sandboxCreateDirectory` | `containerId, path, recursive?` | Create directory | | `sandboxDelete` | `containerId, path, recursive?, force?` | Delete file/directory | | `sandboxExists` | `containerId, path` | Check if path exists | | `sandboxFileInfo` | `containerId, path` | Get file metadata | ### Command Execution | Tool | Args | Description | | ---------------- | ----------------------------------------------------------------------- | ------------------------ | | `sandboxCommand` | `containerId, executable, args?, workingDirectory?, envVars?, timeout?` | Run command in container | ## Security - Path traversal detection and prevention - Shell argument escaping - Isolated Docker containers with volume mounting - Configurable timeouts on command execution ## Registry References - [Sandbox example](/docs/examples/sandbox#sandbox) — Full sandbox lifecycle: init, create directory, write/read files, list directory, check existence, get file info, delete, and destroy --- > Source: https://loopstack.ai/llms/build/integrations/secrets.md --- title: Secrets Management description: Requesting, storing, and retrieving secrets (API keys, tokens) at runtime using SecretRequestDocument, RequestSecretsTask, and GetSecretKeysTool from @loopstack/secrets. --- # Secrets Management Loopstack provides built-in tools for requesting and retrieving secrets (API keys, tokens, etc.) from users at runtime. ## Overview Secrets are requested from the user via a `SecretRequestDocument` form (or `RequestSecretsTask` in agent loops) and persisted in the database via `SecretEntity`, scoped per workspace. Values are never exposed to the LLM — only key names and availability flags (`GetSecretKeysTool`) are returned to workflow code. ### Providing Secrets to Remote Environments When a workflow runs commands on a remote sandbox or Fly.io machine via `@loopstack/remote-client-module`, secrets must reach that environment to be useful. The `SyncSecretsTool` (`sync_secrets`) reads all workspace secrets, ships them to the remote agent over its authenticated control channel, and writes them as `.env` variables before restarting the app. Values stay on the server side of the control channel and are not surfaced to the LLM. Call `sync_secrets` before launching long-running commands or whenever a secret changes: ```typescript constructor(private readonly syncSecrets: SyncSecretsTool) { super(); } @Transition({ from: 'secrets_received', to: 'ready' }) async pushSecrets(state: SecretsState) { await this.syncSecrets.call({}); } ``` ## Available Tools | Tool | Source | Description | | ----------------------- | -------------------- | -------------------------------------------------------- | | `RequestSecretsTask` | `@loopstack/secrets` | Agent-friendly task that launches a secrets sub-workflow | | `GetSecretKeysTool` | `@loopstack/secrets` | List stored secret keys and their availability | | `SecretRequestDocument` | `@loopstack/secrets` | Document displaying the secret input form | ## Example Workflow ```typescript import { BaseWorkflow, Transition, Workflow } from '@loopstack/common'; import { MarkdownDocument } from '@loopstack/common'; import { GetSecretKeysTool, SecretRequestDocument } from '@loopstack/secrets'; interface SecretsState { secretKeys?: Array<{ key: string; hasValue: boolean }>; } @Workflow({ widget: './secrets-example.ui.yaml' }) export class SecretsExampleWorkflow extends BaseWorkflow { constructor(private readonly getSecretKeys: GetSecretKeysTool) { super(); } @Transition({ to: 'requesting_secrets' }) async requestSecretsFromUser(state: SecretsState) { await this.documentStore.save(SecretRequestDocument, { variables: [{ key: 'EXAMPLE_API_KEY' }, { key: 'EXAMPLE_SECRET' }], }); } @Transition({ from: 'requesting_secrets', to: 'verifying', wait: true }) async secretsSubmitted(state: SecretsState) { const result = await this.getSecretKeys.call({}); this.assignState({ secretKeys: result.data }); } @Transition({ from: 'verifying', to: 'end' }) async showResult(state: SecretsState) { await this.documentStore.save(MarkdownDocument, { markdown: this.render(join(__dirname, 'templates', 'secretsVerified.md'), { secretKeys: state.secretKeys, }), }); } } ``` ## How It Works 1. **Request** — saving a `SecretRequestDocument` with the needed keys shows a secure input form in the UI 2. **Wait** — The workflow pauses on a `wait: true` transition named `secretsSubmitted` (the transition the form fires) until the user submits the secrets 3. **Verify** — `GetSecretKeysTool` checks which secrets are now stored 4. **Use** — Secrets are available as environment variables in subsequent tool calls ## Template Example ```markdown # Secrets Verification {{#each secretKeys}} - **{{this.key}}**: {{#if this.hasValue}}Stored{{else}}Missing{{/if}} {{/each}} ``` ## Registry References - [Secrets examples](/docs/examples/secrets) — Request secrets from user, verify storage, and display results with both direct workflow and agent-based approaches --- # Build / Patterns --- > Source: https://loopstack.ai/llms/build/patterns/dynamic-routing.md --- title: Dynamic Routing description: Conditional workflow routing using @Guard decorators and priority-based transition selection when multiple transitions share the same source state. --- # Dynamic Routing Route workflows conditionally using `@Guard` decorators and `priority` to control which transition fires when multiple transitions share the same source state. ## Basic Guard ```typescript @Transition({ from: 'check', to: 'high', priority: 10 }) @Guard('isHigh') routeHigh(state: MyState) {} @Transition({ from: 'check', to: 'low' }) routeLow(state: MyState) {} // Fallback — no guard isHigh(state: MyState): boolean { return state.value > 100; } ``` **How it works:** 1. Transitions with higher `priority` are checked first 2. The `@Guard` references a method that returns a boolean 3. First transition whose guard returns `true` fires 4. A transition without `@Guard` acts as the fallback ## Multi-Level Routing Chain routing decisions with cascading forks: ```typescript import { z } from 'zod'; import { BaseWorkflow, Guard, Transition, Workflow } from '@loopstack/common'; import type { RunContext } from '@loopstack/common'; import { MessageDocument } from '@loopstack/common'; interface RoutingState { value?: number; } const RoutingSchema = z.object({ value: z.number().default(150) }).strict(); type RoutingArgs = z.infer; @Workflow({ schema: RoutingSchema, }) export class DynamicRoutingExampleWorkflow extends BaseWorkflow { @Transition({ to: 'prepared' }) async createMockData(state: RoutingState, ctx: RunContext) { await this.documentStore.save(MessageDocument, { role: 'assistant', text: `Analyzing value = ${ctx.args.value}`, }); this.assignState({ value: ctx.args.value }); } // First fork: value > 100? @Transition({ from: 'prepared', to: 'placeA', priority: 10 }) @Guard('isAbove100') routeToPlaceA(state: RoutingState) {} @Transition({ from: 'prepared', to: 'placeB' }) routeToPlaceB(state: RoutingState) {} // Fallback: value <= 100 isAbove100(state: RoutingState): boolean { return (state.value ?? 0) > 100; } // Second fork: value > 200? @Transition({ from: 'placeA', to: 'placeC', priority: 10 }) @Guard('isAbove200') routeToPlaceC(state: RoutingState) {} @Transition({ from: 'placeA', to: 'placeD' }) routeToPlaceD(state: RoutingState) {} // Fallback: 100 < value <= 200 isAbove200(state: RoutingState): boolean { return (state.value ?? 0) > 200; } // Terminal transitions @Transition({ from: 'placeB', to: 'end' }) async showMessagePlaceB(state: RoutingState) { await this.documentStore.save(MessageDocument, { role: 'assistant', text: 'Value is less or equal 100' }); } @Transition({ from: 'placeC', to: 'end' }) async showMessagePlaceC(state: RoutingState) { await this.documentStore.save(MessageDocument, { role: 'assistant', text: 'Value is greater than 200' }); } @Transition({ from: 'placeD', to: 'end' }) async showMessagePlaceD(state: RoutingState) { await this.documentStore.save(MessageDocument, { role: 'assistant', text: 'Value is less or equal 200, but greater than 100', }); } } ``` ## Routing Flow ``` prepared → [value > 100?] ├─ yes → placeA → [value > 200?] │ ├─ yes → placeC (done) │ └─ no → placeD (done) └─ no → placeB (done) ``` ## Common Patterns ### Tool Call Routing Route based on LLM response (see [AI Tool Calling](../ai/tool-calling.md)): ```typescript @Transition({ from: 'prompt_executed', to: 'ready', priority: 10 }) @Guard('hasToolCalls') async executeToolCalls(state: MyState) { ... } // Run tools, loop back @Transition({ from: 'prompt_executed', to: 'end' }) async respond(state: MyState) { ... } // Fallback: no tool calls hasToolCalls(state: MyState): boolean { return state.llmResult?.message.stopReason === 'tool_use'; } ``` For async tools that complete via callback (sub-workflows, HITL), insert an `awaiting_tools` intermediate state with a `wait: true` re-entry transition — see [Agent Workflows](../ai/agent-workflows.md). ### Error-Based Routing Route based on a tool's error response: ```typescript @Transition({ from: 'fetched', to: 'auth_needed', priority: 10 }) @Guard('needsAuth') async startAuth(state: MyState) { ... } @Transition({ from: 'fetched', to: 'end' }) async displayResults(state: MyState) { ... } needsAuth(state: MyState): boolean { return state.fetchResult?.error === 'unauthorized'; } ``` ## Guard Method Rules - Guard methods must return a **boolean** (or truthy/falsy value) - They receive `state` as their first parameter - They should be **synchronous** — no async guards - Use descriptive names: `hasToolCalls`, `isAbove100`, `needsAuth` ## Registry References - [Dynamic Routing example](/docs/examples/advanced-workflows#dynamic-routing) — Multi-level guard-based routing with cascading forks - [Custom Agent example](/docs/examples/agent#custom-agent) — Guard-based routing for LLM tool call detection --- > Source: https://loopstack.ai/llms/build/patterns/error-handling.md --- title: Error Handling, Retry & Timeout description: Recovering from transition errors with auto-retry and exponential backoff, retryTarget for retry-via-another-place, errorPlace routing for sync throws and sub-workflow failure callbacks, manual retry via Studio UI, and transition timeouts. --- # Error Handling, Retry & Timeout When a transition fails — by throwing, timing out, or receiving a `failed` / `canceled` callback from a sub-workflow — the framework rolls back local changes and then runs a single decision tree: 1. **Auto-retry** if `retryAttempts` has budget left. 2. **Route to `errorPlace`** if declared (retries exhausted, or no retries configured). 3. **Manual retry (default)** — stay at the current place and surface a Retry button in the UI. The same rule applies to sync throws, timeouts, and sub-workflow failure callbacks — there's one mental model. ## Retry Modes ### Auto-Retry Automatically re-run a failed transition with exponential backoff: ```typescript @Transition({ from: 'fetching', to: 'done', retryAttempts: 3 }) async fetchData() { await this.httpClient.call({ url: 'https://api.example.com/data' }); } ``` If `fetchData` throws, the framework retries up to 3 times with exponential delays (1s, 2s, 4s). The workflow stays at the `fetching` place during retries. ### Retry via a Different Place (`retryTarget`) Some retries need preparation work between attempts — refresh a token, invalidate a cache, log out and back in. `retryTarget` moves the workflow to a different place on each auto-retry, instead of re-running the failing transition directly: ```typescript @Transition({ from: 'fetching', to: 'done', retryAttempts: 3, retryTarget: 'refresh_credentials', }) async callApi() { await this.api.call({ ... }); } @Transition({ from: 'refresh_credentials', to: 'fetching' }) async refreshCredentials() { await this.auth.refreshToken(); } ``` On failure, `callApi`'s retry budget is decremented, the workflow jumps to `refresh_credentials`, the refresh transition runs, and the workflow loops back to `fetching` to re-attempt `callApi`. Transitions inside the retry target have their own independent retry budget — a failure in `refreshCredentials` doesn't consume `callApi`'s attempts. ### Custom Error Place (`errorPlace`) Route to a dedicated error state when a transition fails: ```typescript @Transition({ from: 'processing', to: 'done', errorPlace: 'error_processing' }) async processData() { await this.processor.call({ data: this.rawData }); } @Transition({ from: 'error_processing', to: 'done', wait: true }) async handleProcessingError() { // Recovery logic — user clicks a "Recover" button to trigger this await this.documentStore.save(MessageDocument, { role: 'assistant', text: 'Processing failed. Retrying with fallback strategy.', }); } ``` The workflow transitions to `error_processing` where you define recovery logic via `wait: true` transitions (buttons in the UI). When `errorPlace` is set without `retryAttempts`, attempts default to `0` — failures route straight to the error place on the first try. ### Manual Retry (Default) When no failure handling is specified, the workflow stays at the current place and shows a "Retry" button: ```typescript @Transition({ from: 'sending', to: 'sent' }) async sendEmail() { await this.email.call({ to: 'user@example.com', body: this.content }); } ``` If it fails, the user sees the error message and can retry manually. No auto-retry, no error place — just pause and let the user decide. ### Hybrid: Auto-Retry + Error Place Combine auto-retry with a fallback error state: ```typescript @Transition({ from: 'deploying', to: 'deployed', retryAttempts: 2, errorPlace: 'deploy_failed', }) async deploy() { await this.deployer.call({ target: 'production' }); } @Transition({ from: 'deploy_failed', to: 'deployed', wait: true }) async retryDeploy() { // Manual recovery after auto-retries exhausted } ``` Retries twice automatically. If both fail, transitions to `deploy_failed` for manual intervention. ## Sub-Workflow Failure Callbacks A wait transition that resumes from a sub-workflow callback can fail just like a synchronous transition — when the child finishes with `status: failed` or `canceled`. The same `retryAttempts` / `retryTarget` / `errorPlace` rules apply: ```typescript @Transition({ from: 'awaiting_child', to: 'done', wait: true, errorPlace: 'sub_failed' }) async childCompleted(_state, _input) { // Happy path only — the child succeeded. } @Transition({ from: 'sub_failed', to: 'done', wait: true }) async handleSubFailed() { // Recovery when the child failed — surfaces a Recover button. } ``` Without `errorPlace` (or `retryAttempts`), a sub-workflow failure callback still fires the body — for accumulator patterns where the body itself handles error results (e.g. LLM tool delegation). With either declared, the framework treats the failure as the wait transition failing and skips the body entirely. That protects schema-validated bodies from receiving `null` / malformed data when the child never reached `setResult(...)`. ## Failure-Handling Configuration ```typescript retryAttempts?: number // -1 = unlimited manual retry (default). // 0 = no auto-retry (default when errorPlace is set). // N>0 = up to N auto-retries. retryDelay?: number // Base delay in ms (default: 1000). retryBackoff?: 'fixed' | 'exponential' // (default: 'exponential') retryMaxDelay?: number // Backoff cap in ms (default: 30000). retryTarget?: string // Re-enter this place on each auto-retry, instead of re-running this transition. errorPlace?: string // Where to route when retries are exhausted (or no retry is configured). ``` **Backoff calculation (exponential):** `retryDelay * 2^(attempt - 1)`, capped at `retryMaxDelay`. | Attempt | Delay (default config) | | ------- | ---------------------- | | 1 | 1,000ms | | 2 | 2,000ms | | 3 | 4,000ms | | 4 | 8,000ms | | 5 | 16,000ms | | 6+ | 30,000ms (capped) | ### Reading the retry count Transitions can access the current retry count through `ctx.execution.retryCount`. It is 0-indexed: `0` on the first attempt, `1` after the first retry, and so on. Add `1` for a human-friendly attempt number when logging or branching on retries. ```typescript @Transition({ from: 'fetching', to: 'done', retryAttempts: 3 }) async fetchData(state: MyState, ctx: RunContext) { const attempt = (ctx.execution?.retryCount ?? 0) + 1; this.logger.log(`Fetch attempt ${attempt}`); // ... } ``` `ctx.execution` is optional in the type — guard with `?.` or `!` depending on your call site. `ctx.execution.place` is also available for the current place name. ## Timeout Every transition has a default timeout of **5 minutes** (300,000ms). If a transition takes longer, it's interrupted with `Error: Transition '...' timed out after ...ms` and flows through the normal retry logic. You can override the default globally with the `DEFAULT_TRANSITION_TIMEOUT` environment variable (in ms), or per-transition: ```typescript @Transition({ from: 'analyzing', to: 'analyzed', timeout: 5000 }) async analyzeData() { await this.analyzer.call({ dataset: this.data }); } ``` To disable the timeout for a specific transition, set `timeout: 0`: ```typescript @Transition({ from: 'processing', to: 'done', timeout: 0 }) async longRunningTask() { // No timeout — runs until completion } ``` You can combine timeout with retry: ```typescript @Transition({ from: 'analyzing', to: 'analyzed', timeout: 5000, retryAttempts: 2, }) async analyzeData() { await this.analyzer.call({ dataset: this.data }); } ``` Times out after 5s, retries up to 2 times, then falls to manual retry. ## What Gets Rolled Back When a transition fails, the framework rolls back: - **Documents** created during the transition (restored from snapshot) - **Database changes** within the transition's transaction - **Workflow state** stays at the pre-transition place What is **not** rolled back: - An `ErrorDocument` is saved after rollback as an audit trail - The error message is stored in workflow metadata - Workflow instance variables (`this.someField`) persist across retries — useful for attempt counters ## ErrorDocument Every failed transition creates an `ErrorDocument` with the error message: ```typescript // Automatically created by the framework: { className: 'ErrorDocument', content: { error: 'Connection refused: api.example.com' } } ``` Multiple `ErrorDocument`s accumulate if retries fail repeatedly — giving a full audit trail of each attempt. ## Registry References - [Auto Retry example](/docs/examples/error-handling#auto-retry) — `retryAttempts` re-runs a failing service call with exponential backoff until the third attempt succeeds. - [Retry Target example](/docs/examples/error-handling#retry-target) — `retryTarget` routes each retry through a credential-refresh place before the call runs again. - [Error Place example](/docs/examples/error-handling#error-place) — `errorPlace` moves a failed workflow to a recovery place with a Recover button. - [Manual Retry example](/docs/examples/error-handling#manual-retry) — The default: the failed workflow stays at its place and offers a Retry button. - [Transition Timeout example](/docs/examples/error-handling#transition-timeout) — `timeout` fails a transition that runs too long; the tool stops its work via `ctx.signal`. - [Sub-Workflow Error Place example](/docs/examples/error-handling#sub-workflow-error-place) — A failed child workflow callback is routed to a recovery place via `errorPlace`. --- > Source: https://loopstack.ai/llms/build/patterns/human-in-the-loop.md --- title: Human-in-the-Loop description: Pausing workflows for user input, review, or confirmation. Covers wait:true transitions on custom documents, AskUserWorkflow / ConfirmUserWorkflow sub-workflow shortcuts, and LLM-agent HITL via the ask_clarification and ask_for_approval tools. --- # Human-in-the-Loop Pause workflows for user input, review, or confirmation. Loopstack offers three distinct patterns — pick the one that matches who decides what to ask. ## Choosing a HITL Pattern | You are building... | Use | Where it lives | | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | A predefined workflow with known user-input steps — form fields, structured records | **Custom document with a widget** — your workflow owns the document + `wait: true` | This page → [Wait Transition Pattern](#wait-transition-pattern) | | A predefined workflow that just needs a quick generic ask (free text, yes/no, pick one) | **`AskUserWorkflow` / `ConfirmUserWorkflow`** as a sub-workflow shortcut | This page → [Using HITL as a Sub-Workflow](#using-hitl-as-a-sub-workflow) | | An LLM agent loop where the agent dynamically decides when to ask | **Agent tools** `ask_clarification` / `ask_for_approval` | This page → [Agent-Driven HITL](#agent-driven-hitl) | The custom-document pattern is the **default for predefined workflows**: the form _is_ the structured data, the wait-transition payload schema _is_ the document schema, and types line up end-to-end. Sub-workflow shortcuts are for when designing a form would be overkill. Agent tools are for LLM-driven flows where the next question isn't known in advance. ## Wait Transition Pattern A transition with `wait: true` pauses the workflow until externally triggered by user interaction: ```typescript import type { TransitionInput } from '@loopstack/common'; @Transition({ from: 'waiting_for_user', to: 'ready', wait: true, schema: z.object({ message: z.string() }), }) async userMessage(state: Record, input: TransitionInput<{ message: string }>) { await this.documentStore.save(LlmMessageDocument, { role: 'user', text: input.data.message, }); } ``` ## Document Action Buttons Documents can include buttons that trigger `wait: true` transitions: ```yaml # Document YAML type: document ui: widgets: - widget: form options: properties: text: title: Text widget: textarea actions: - type: button transition: userResponse # Must match the method name label: 'Submit' ``` When the user clicks **Submit**, the workflow's `userResponse` method fires with the document's current content as the payload. ## Chat Input Widget For conversational UIs, use the `prompt-input` widget: ```yaml ui: widgets: - widget: prompt-input enabledWhen: - waiting_for_user options: transition: userMessage ``` ```typescript @Transition({ from: 'waiting_for_user', to: 'ready', wait: true, schema: z.string(), }) async userMessage(state: Record, input: TransitionInput) { await this.documentStore.save(LlmMessageDocument, { role: 'user', text: input.data, }); } ``` ## Confirmation Pattern Show AI-generated content for user review before proceeding: ```typescript import { z } from 'zod'; import { toJSONSchema } from 'zod'; import { BaseWorkflow, Transition, Workflow } from '@loopstack/common'; import type { RunContext } from '@loopstack/common'; import { LlmGenerateObjectTool } from '@loopstack/llm-provider'; interface MeetingNotesState { meetingNotes?: z.infer; } const MeetingNotesArgsSchema = z.object({ inputText: z.string().default('...') }); type MeetingNotesArgs = z.infer; @Workflow({ widget: './meeting-notes.ui.yaml', schema: MeetingNotesArgsSchema, }) export class MeetingNotesWorkflow extends BaseWorkflow { constructor(private readonly llmGenerateObject: LlmGenerateObjectTool) { super(); } @Transition({ to: 'waiting_for_response' }) async createForm(state: MeetingNotesState, ctx: RunContext) { await this.documentStore.save(MeetingNotesDocument, { text: ctx.args.inputText }, { key: 'input' }); } // Wait for user to edit and submit @Transition({ from: 'waiting_for_response', to: 'response_received', wait: true, schema: MeetingNotesDocumentSchema }) async userResponse(state: MeetingNotesState, input: TransitionInput>) { const result = await this.documentStore.save(MeetingNotesDocument, input.data, { key: 'input' }); this.assignState({ meetingNotes: result.content as z.infer }); } // AI generates structured output @Transition({ from: 'response_received', to: 'notes_optimized' }) async optimizeNotes(state: MeetingNotesState) { const result = await this.llmGenerateObject.call( { outputSchema: toJSONSchema(OptimizedMeetingNotesDocumentSchema) as Record, prompt: `Structure these notes: ${state.meetingNotes?.text}`, }, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }, ); const objectResult = result.data as LlmGenerateObjectResult; await this.documentStore.save( OptimizedNotesDocument, objectResult.data as z.infer, { key: 'final', validate: 'skip' }, ); } // Wait for user to confirm @Transition({ from: 'notes_optimized', to: 'end', wait: true, schema: OptimizedMeetingNotesDocumentSchema }) async confirm(state: MeetingNotesState, input: TransitionInput>) { await this.documentStore.save(OptimizedNotesDocument, input.data, { key: 'final' }); } } ``` ## `enabledWhen` and `showWhen` — Conditional Widgets Two widget keys gate a widget on the current workflow place. `enabledWhen` keeps the widget on screen but disables it outside the listed places: ```yaml ui: widgets: - widget: form enabledWhen: - review - editing options: properties: summary: title: Summary widget: textarea actions: - type: button transition: confirm label: 'Confirm' ``` The form is visible at every place, but it can only be edited and submitted while the workflow is at the `review` or `editing` place. `showWhen` hides the widget entirely outside the listed places — use it for a widget that should only exist at one step: ```yaml ui: widgets: - widget: prompt-input enabledWhen: - waiting_for_user options: transition: userMessage - widget: button showWhen: - awaiting_tools options: transition: cancelPendingTools label: Cancel pending tools ``` The prompt input is always on screen and disabled while the agent works; the cancel button is only rendered while the workflow is at `awaiting_tools`. When a widget sets both keys, `showWhen` decides whether it is rendered and `enabledWhen` whether it is enabled. See [Workflow YAML Schema — `showWhen`](../../reference/workflow-yaml.md#showwhen). When a park has more than one enabled widget — a confirmation document from a sub-workflow and the parent's chat input, say — Studio, the CLI and `parkView()` all pick the same one as the prompt: in run-tree order, and within each workflow its document prompts before its workflow-level widgets. [Prompt Selection Rules](../../reference/prompt-selection.md) describes the full order. ## Using HITL as a Sub-Workflow The `wait: true` pattern above is for workflows that own their own UI. For generic prompts you don't want to design a form for, run `AskUserWorkflow` or `ConfirmUserWorkflow` from `@loopstack/hitl` as a sub-workflow and receive the answer through a callback. The callback delivers the standard `TransitionInput` envelope — the `schema` on the transition describes only `data`, and `input.data` is fully typed. See [Sub-Workflows → Typing the Callback Envelope](./sub-workflows.md#typing-the-callback-envelope) for the full reference. ### `AskUserWorkflow` — free text ```typescript import { z } from 'zod'; import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common'; import { AskUserWorkflow } from '@loopstack/hitl'; const AnswerSchema = z.object({ answer: z.string() }); @Workflow({ title: 'Ask Then Continue' }) export class AskThenContinueWorkflow extends BaseWorkflow { constructor(private readonly askUser: AskUserWorkflow) { super(); } @Transition({ to: 'waiting' }) async ask(state: Record) { await this.askUser.run({ question: 'What is your name?' }, { callback: { transition: 'onAnswer' } }); } @Transition({ from: 'waiting', to: 'end', wait: true, schema: AnswerSchema }) onAnswer(state: Record, input: TransitionInput<{ answer: string }>) { this.setResult({ name: input.data.answer }); } } ``` ### `AskUserWorkflow` — pick from options Pass `mode: 'options'` with a list of choices. `allowCustomAnswer: true` adds a free-text field alongside the choices for "other". ```typescript await this.askUser.run( { question: 'Which environment should we deploy to?', mode: 'options', options: ['staging', 'production'], allowCustomAnswer: true, }, { callback: { transition: 'choiceReceived' } }, ); ``` The envelope shape is the same as the free-text case (`input.data: { answer: string }`). ### `AskUserWorkflow` — yes / no Pass `mode: 'confirm'`. The answer comes back as the literal string `'yes'` or `'no'` in `input.data.answer` — compare directly. ```typescript await this.askUser.run( { question: 'Send the email now?', mode: 'confirm' }, { callback: { transition: 'decisionReceived' } }, ); ``` ### `ConfirmUserWorkflow` — markdown review For showing a pre-rendered markdown blob (a release plan, a summary, a code diff) and receiving an explicit approve/deny, use `ConfirmUserWorkflow`. The callback `input.data` carries both the user's decision and the original markdown: ```typescript import { ConfirmUserWorkflow } from '@loopstack/hitl'; const ConfirmSchema = z.object({ confirmed: z.boolean(), markdown: z.string() }); @Transition({ to: 'awaiting' }) async showSummary(state: Record) { await this.confirmUser.run( { markdown: '## Ready to deploy v1.2.3?\n\n- 3 commits since last release\n- Smoke tests passing' }, { callback: { transition: 'decisionReceived' } }, ); } @Transition({ from: 'awaiting', to: 'end', wait: true, schema: ConfirmSchema }) decisionReceived( state: Record, input: TransitionInput>, ) { this.setResult({ confirmed: input.data.confirmed }); } ``` ## Agent-Driven HITL When the asking party is an LLM agent rather than your workflow, use the `ask_clarification` and `ask_for_approval` tools from `@loopstack/hitl`. The agent decides at runtime to call the tool; the agent loop pauses, the user answers, and the answer flows back as the tool result — no extra wait-transition wiring at your level. ### `ask_clarification` — agent asks the user a question Register the tool in your module and add it to the agent's tool list. A system prompt that tells the agent to use the tool when info is missing is enough: ```typescript import { z } from 'zod'; import { AgentWorkflow } from '@loopstack/agent'; import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common'; const AgentResponseSchema = z.object({ response: z.string() }); const SYSTEM_PROMPT = `You are a trip-planning assistant. - Before recommending a destination, you MUST know BOTH the user's budget AND climate preference. - If either is missing, your response MUST be exactly ONE tool call to "ask_clarification".`; @Workflow({ title: 'Trip Planner' }) export class TripPlannerWorkflow extends BaseWorkflow { constructor(private readonly agent: AgentWorkflow) { super(); } @Transition({ to: 'running' }) async start(state: Record) { await this.agent.run( { system: SYSTEM_PROMPT, tools: ['ask_clarification'], userMessage: 'Where should I go on holiday next month?', }, { callback: { transition: 'onComplete' } }, ); } @Transition({ from: 'running', to: 'end', wait: true, schema: AgentResponseSchema }) async onComplete(state: Record, input: TransitionInput<{ response: string }>) { await this.documentStore.save(MessageDocument, { role: 'assistant', text: input.data.response }); this.setResult({ response: input.data.response }); } } ``` `ask_clarification` supports the same `mode` arg as `AskUserWorkflow` (`'text'` / `'options'` / `'confirm'`) — the LLM can pick the right mode per call. ### `ask_for_approval` — agent asks the user to approve content Same shape, with `tools: ['ask_for_approval']`. The agent drafts content and passes it as the `concept` argument; the user sees the markdown and confirms or denies. The agent loop only resumes after the decision. ```typescript const SYSTEM_PROMPT = `You are a release-notes drafting assistant. - Your response MUST be exactly ONE tool call to "ask_for_approval". - The "concept" argument IS the markdown draft.`; await this.agent.run( { system: SYSTEM_PROMPT, tools: ['ask_for_approval'], userMessage: 'Draft release notes for v1.2.3.', }, { callback: { transition: 'onComplete' } }, ); ``` See [`@loopstack/hitl`](/docs/registry/hitl) for the full tool args reference. ## Registry References - [HITL examples](/docs/examples/hitl) — Side-by-side examples of every HITL pattern: custom document with widget, all `AskUserWorkflow` modes, `ConfirmUserWorkflow`, and both agent tools - [@loopstack/hitl](/docs/registry/hitl) — The underlying HITL module: `AskUserWorkflow`, `ConfirmUserWorkflow`, `ask_clarification`, `ask_for_approval` - [Meeting Notes example](/docs/examples/hitl#meeting-notes) — Full human-in-the-loop workflow with editable form, AI optimization, and user confirmation - [Prompt Input Chat example](/docs/examples/hitl#prompt-input-chat) — Chat input pattern with prompt-input widget --- > Source: https://loopstack.ai/llms/build/patterns/state-management.md --- title: State Management description: Defining, reading, and updating typed workflow state. Covers state interfaces, per-transition state typing, state persistence across transitions, and state access patterns. --- # State Management Workflow state is managed through a typed state interface passed as the first parameter to transition methods. Transitions return nothing — they write through setter methods on `BaseWorkflow`, and the engine persists the updated state automatically across transitions. Use `async` when the body awaits. ## Defining State Define a state interface and reference it on each transition's `state` parameter: ```typescript interface MyState { counter?: number; llmResult?: LlmGenerateTextResult; items?: string[]; } export class MyWorkflow extends BaseWorkflow { // State is typed per-transition via the `state` parameter — see below. } ``` State begins as an empty object `{}` — the initial transition is responsible for populating it. For this reason, **all properties on a state schema should be optional**. If a property is required, the empty starting state will fail validation immediately. Treat missing fields as the absence of data and read them defensively (`state.counter ?? 0`). ## Writing State `BaseWorkflow` exposes four setters. Pick the one that matches the write you want: | Setter | Effect | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `this.assignState(partial)` | Shallow-merge `partial` into the current state. The most common form — leaves any field you don't mention untouched. | | `this.setState(full)` | Replace the state object outright. Use when you want to reset state or know you're writing every field. | | `this.assignResult(partial)` | Shallow-merge `partial` into the workflow's published `result` (the value parent callbacks and `WorkflowRunner` callers see). | | `this.setResult(full)` | Replace the published `result` outright. | Transitions return nothing — mutate state via setters. Returning a value is a runtime error. ```typescript @Transition({ from: 'ready', to: 'processed' }) async process(state: MyState) { const result = await this.llmGenerateText.call( {}, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } }, ); this.assignState({ llmResult: result.data, counter: (state.counter ?? 0) + 1, items: [...(state.items ?? []), 'new item'], }); } ``` A transition that doesn't write state simply omits the setter call: ```typescript @Transition({ from: 'ready', to: 'logged' }) log(state: MyState) { this.logger.log(`counter = ${state.counter}`); } ``` If `stateSchema` is defined on the workflow, the merged state is validated after every write. ## Reading State Access state in any transition or guard method: ```typescript @Transition({ from: 'processed', to: 'end' }) async display(state: MyState) { await this.documentStore.save(MessageDocument, { role: 'assistant', text: `Processed ${state.counter} items. Result: ${state.llmResult?.text}`, }); } hasToolCalls(state: MyState): boolean { return state.llmResult?.message.stopReason === 'tool_use'; } ``` ## Publishing a Result The workflow's `result` field is what `WorkflowRunner.runSync()` returns and what parent callbacks receive as `input.data`. Write to it on the final transition (or any earlier transition that wants to surface partial output): ```typescript @Transition({ from: 'done', to: 'end' }) finish(state: MyState) { this.setResult({ concept: state.confirmedConcept! }); } ``` Use `this.assignResult(partial)` to build the result up across multiple transitions, and `this.setResult(full)` to replace it. Publish what callers need and keep working data in state. The [workflow result example](/docs/examples/advanced-workflows#workflow-result) builds its result across two transitions while its working data stays private. ## Persistence Across Pauses State survives when a workflow pauses at a `wait: true` transition and resumes later: ```typescript @Transition({ to: 'waiting' }) setup(state: MyState) { this.assignState({ counter: 42 }); // Set before pause } @Transition({ from: 'waiting', to: 'end', wait: true }) onResume(state: MyState) { // state.counter is still 42 } ``` ## Accessing Workflow Args Input arguments are available via `ctx.args`: ```typescript const MyArgsSchema = z.object({ value: z.number().default(150) }); type MyArgs = z.infer; @Workflow({ schema: MyArgsSchema, }) export class MyWorkflow extends BaseWorkflow { @Transition({ to: 'ready' }) setup(state: MyState, ctx: RunContext) { console.log(ctx.args.value); // 150 } } ``` ## Helper Methods Use regular private methods for reusable logic — no special decorator needed: ```typescript export class MyWorkflow extends BaseWorkflow { @Transition({ from: 'data_created', to: 'end' }) async showResults(state: MyState) { await this.documentStore.save(MessageDocument, { role: 'assistant', text: this.formatMessage(state.message!), }); } private formatMessage(text: string): string { return text.toUpperCase(); } } ``` ## Registry References - [WorkflowStateWorkflow](/docs/examples/advanced-workflows#workflow-state) — Stores state in a typed state interface, reads it in the next transition, uses a helper method - [WorkflowResultWorkflow](/docs/examples/advanced-workflows#workflow-result) — Builds the published result across two transitions with `assignResult()`, keeping working data in private state --- > Source: https://loopstack.ai/llms/build/patterns/sub-workflows.md --- title: Sub-Workflows description: Running workflows inside other workflows via .run(), the show option ('inline' | 'link' | 'hidden') for parent-view rendering, callback transitions, typing the callback envelope via TransitionInput, handling sub-workflow failures via input.hasError / input.errorMessage without try/catch, passing arguments to child workflows, receiving sub-workflow results, and coordinating multiple sub-workflows via FanOutWorkflow (parallel) and SequenceWorkflow (sequential) with 'all' / 'allSettled' failure modes. --- # Sub-Workflows Sub-workflows let you compose complex automations from smaller, reusable workflow building blocks. A parent workflow can launch one or more child workflows via `.run()`, pause until they complete, and receive results through a callback transition. ## Injecting a Sub-Workflow ```typescript import { QueueResult } from '@loopstack/common'; constructor(private readonly subWorkflow: SubWorkflow) { super(); } ``` ## Running a Sub-Workflow ```typescript @Transition({ to: 'sub_started' }) async start(state: MyState) { await this.subWorkflow.run( { prompt: 'Hello' }, // Args passed to the sub-workflow { callback: { transition: 'onSubComplete' } }, // Method to call when done ); } ``` The parent's run view automatically renders the child sub-workflow inline by default — there is no extra `documentStore.save(LinkDocument, …)` step. ## Controlling How the Child Appears: `show` The `show` option on `RunOptions` controls how the child sub-workflow is rendered inside the parent's run view: | `show` | What the parent sees | Use for | | ---------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `'inline'` _(default)_ | The child is embedded as an inline iframe; the user can interact with it in place. | HITL prompts, OAuth flows, agents whose progress you want visible. | | `'link'` | A status link card with the child's label and live status — opens the child in a separate window when clicked. | Long-running autonomous children the parent just tracks. | | `'hidden'` | Nothing is shown. | Background fan-out where surfacing each child would be noise. | ```typescript await this.askUser.run(args, { callback: { transition: 'answered' }, show: 'inline', // (default) embed the child UI in the parent's view label: 'Waiting for user answer', // optional — defaults to the child workflow's name }); await this.longJob.run(args, { callback: { transition: 'done' }, show: 'link', // status card, opens child in a separate window }); await this.background.run(args, { show: 'hidden', // no card at all }); ``` The link card's status is read live from the child workflow's actual state — it transitions from pending to success or failure automatically as the child runs. ## Receiving the Callback The sub-workflow's published `result` (built via `assignResult` / `setResult`) is passed as `input.data`: ```typescript import type { TransitionInput } from '@loopstack/common'; @Transition({ from: 'sub_started', to: 'sub_done', wait: true, schema: z.object({ message: z.string() }), }) async onSubComplete( state: MyState, input: TransitionInput<{ message: string }>, ) { await this.documentStore.save(MessageDocument, { role: 'assistant', text: `Sub-workflow said: ${input.data.message}`, }); } ``` ## Typing the Callback Envelope Every `wait: true` transition receives a `TransitionInput` envelope — the same shape whether the resume came from a sub-workflow completion or a frontend / API trigger: ```typescript interface TransitionInput { workflowId: string; status: 'completed' | 'failed' | 'canceled'; hasError: boolean; errorMessage: string | null; data: TData; meta?: TMeta; } ``` | Field | Type | What it is | | -------------- | ---------------- | ---------------------------------------------------------------------------------------------------------- | | `workflowId` | `string` | ID of the run that produced this resume (the child for sub-workflow callbacks, the parent for user input). | | `status` | enum | `'completed'` / `'failed'` / `'canceled'`. | | `hasError` | `boolean` | `true` if the trigger source ended in failure — branch on this, not on `status`. | | `errorMessage` | `string \| null` | Error message if `hasError`, otherwise `null`. | | `data` | `TData` | The validated payload (the child's published `result`, or the user's form data). | | `meta` | `TMeta?` | Optional correlation metadata passed via `callback.metadata`. Undefined for user-driven resumes. | The `schema` on `@Transition({ wait: true })` describes **only `data`** — the framework constructs the surrounding envelope. Type the parameter via `TransitionInput`: ```typescript import type { TransitionInput } from '@loopstack/common'; import { z } from 'zod'; const AnswerSchema = z.object({ answer: z.string() }); @Transition({ from: 'awaiting', to: 'end', wait: true, schema: AnswerSchema, }) onAnswer(state: MyState, input: TransitionInput<{ answer: string }>) { // input.workflowId, input.status, input.hasError available at the top level // input.data.answer is fully typed against AnswerSchema this.setResult({ answer: input.data.answer }); } ``` ## Error Handling When a sub-workflow throws, the failure does **not** bubble up through `run()` — `run()` only schedules the child. Instead, the parent's callback transition still fires, with `hasError: true` and `errorMessage` populated. The parent branches on `input.hasError`: ```typescript import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common'; @Workflow({ title: 'Recovers from a Failing Child' }) export class RecoveringParentWorkflow extends BaseWorkflow { constructor(private readonly failingSub: FailingSubWorkflow) { super(); } @Transition({ to: 'awaiting' }) async launch(state: Record) { await this.failingSub.run({}, { callback: { transition: 'onFinished' }, show: 'link', label: 'Failing child' }); } @Transition({ from: 'awaiting', to: 'end', wait: true }) async onFinished(state: Record, input: TransitionInput) { if (input.hasError) { await this.documentStore.save(MessageDocument, { role: 'assistant', text: `Child failed: ${input.errorMessage ?? 'unknown error'} — continuing with a fallback.`, }); this.setResult({ recovered: true }); return; } this.setResult({ recovered: false }); } } ``` Two things to note: - **No try/catch at the parent.** The child's exception is captured by the framework, persisted on the child run, and surfaced through the envelope. The parent only sees `hasError`. - **The link card / inline iframe turns red automatically.** No extra UI wiring is needed to reflect the failure in the parent's run view. For `FanOutWorkflow` and `SequenceWorkflow` the same idea applies one level deeper: each item's per-result entry carries its own `hasError`, and the aggregate `input.data` exposes `hasErrors` and `errorCount`. ## Sub-Workflow Output The sub-workflow defines its output by writing to the run's `result` field via `this.assignResult(...)` or `this.setResult(...)`: ```typescript @Workflow({ widget: './sub.ui.yaml' }) export class SubWorkflow extends BaseWorkflow { @Transition({ to: 'end' }) start() { this.setResult({ message: 'Hi mom!' }); } } ``` ## Complete Example ```typescript @Workflow({ widget: './parent.ui.yaml' }) export class ParentWorkflow extends BaseWorkflow { constructor(private readonly subWorkflow: SubWorkflow) { super(); } @Transition({ to: 'sub_started' }) async runWorkflow(state: Record) { await this.subWorkflow.run( {}, { callback: { transition: 'subWorkflowCallback' }, show: 'link', label: 'Sub-Workflow' }, ); } @Transition({ from: 'sub_started', to: 'end', wait: true, schema: z.object({ message: z.string() }), }) async subWorkflowCallback(state: Record, input: TransitionInput<{ message: string }>) { await this.documentStore.save(MessageDocument, { role: 'assistant', text: `Message from sub-workflow: ${input.data.message}`, }); } } ``` ## Running Sub-Workflows in Parallel To launch multiple sub-workflows at the same time and receive a single aggregated callback when they all complete, use the built-in `FanOutWorkflow` from `@loopstack/core`. Inject it like any other sub-workflow. ```typescript import { z } from 'zod'; import { type TransitionInput } from '@loopstack/common'; import { FanOutResultSchema, FanOutWorkflow } from '@loopstack/core'; type FanOutResultData = z.infer; @Workflow({ title: 'Parallel Fan-Out' }) export class ParallelWorkflow extends BaseWorkflow { constructor(private readonly fanOut: FanOutWorkflow) { super(); } @Transition({ to: 'awaiting' }) async launch(state: Record) { await this.fanOut.run( { items: { user: { workflow: 'fetch_user', args: { id: 1 } }, orders: { workflow: 'fetch_orders', args: { id: 1 } }, }, }, { callback: { transition: 'onAllDone' } }, ); } @Transition({ from: 'awaiting', to: 'end', wait: true, schema: FanOutResultSchema }) onAllDone(state: Record, input: TransitionInput) { const user = (input.data.results as Record).user.data; const orders = (input.data.results as Record).orders.data; this.setResult({ user, orders }); } } ``` `items` accepts either a **keyed record** (results addressable by name) or an **array** of `{ workflow, args, label?, show? }` (results returned in input order with each entry's `key`). The `workflow` field is the canonical name string — either the explicit `@Workflow({ name })` value or the auto-derived snake_case form (e.g. `FetchUserWorkflow` → `'fetch_user'`). ### Failure modes | `mode` | Behavior | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `'all'` _(default)_ | First failure triggers `cancelChildren` on the parent; the callback fires once every in-flight child has settled (canceled siblings also send callbacks). `input.data.hasErrors` is `true`. | | `'allSettled'` | Every child runs to completion regardless of siblings; the callback aggregates `completed` / `failed` results for every item. | ## Running Sub-Workflows in Sequence To run sub-workflows one after another with a single aggregated callback at the end, use `SequenceWorkflow`. Same call shape as `FanOutWorkflow`, same `'all'` / `'allSettled'` modes. ```typescript import { type TransitionInput } from '@loopstack/common'; import { SequenceResultSchema, SequenceWorkflow } from '@loopstack/core'; import { z } from 'zod'; type SequenceResultData = z.infer; @Workflow({ title: 'Sequential' }) export class SequentialWorkflow extends BaseWorkflow { constructor(private readonly sequence: SequenceWorkflow) { super(); } @Transition({ to: 'awaiting' }) async launch(state: Record) { await this.sequence.run( { items: [ { workflow: 'step_a', args: { ... }, label: 'step-1' }, { workflow: 'step_b', args: { ... }, label: 'step-2' }, { workflow: 'step_c', args: { ... }, label: 'step-3' }, ], }, { callback: { transition: 'onComplete' } }, ); } @Transition({ from: 'awaiting', to: 'end', wait: true, schema: SequenceResultSchema }) onComplete(state: Record, input: TransitionInput) { this.setResult({ results: input.data.results }); } } ``` In `mode: 'all'`, a failure aborts the sequence and remaining items are marked `'skipped'` in the result. In `mode: 'allSettled'`, the sequence continues past failures. `FanOutWorkflow` and `SequenceWorkflow` are auto-registered by `LoopstackModule.forRoot()` — there is no manual `providers: [...]` entry needed for them. You still register your own sub-workflows normally. ## Registering Sub-Workflows Both workflows must be registered in the module: ```typescript @Module({ providers: [ParentWorkflow, SubWorkflow], exports: [ParentWorkflow, SubWorkflow], }) export class MyModule {} ``` ## Wrapping as a Task Tool A task tool is a `BaseTool` that launches a sub-workflow and returns `pending`. The framework calls `complete()` when the sub-workflow finishes. This lets agents decide when to run sub-workflows. ```typescript @Tool({ name: 'run_tests', description: 'Run tests in the specified directory.', schema: z.object({ testDirectory: z.string().describe('Directory containing the test files to run.'), }), }) export class RunTestsTask extends BaseTool { constructor(private readonly testRunner: TestRunnerWorkflow) { super(); } protected async handle( args: { testDirectory: string }, ctx: RunContext, options?: ToolCallOptions, ): Promise { const result = await this.testRunner.run( { testDirectory: args.testDirectory }, { callback: options?.callback, show: 'inline', label: 'Running tests...' }, ); return { data: { workflowId: result.workflowId }, pending: { workflowId: result.workflowId }, }; } async complete(result: Record): Promise { const data = result as { data?: { passed: boolean; output: string } }; return { data: data.data ?? result }; } } ``` Key parts: - **`pending: { workflowId }`** tells the framework this tool is async — the parent workflow waits for a callback - **`callback: options?.callback`** passes the parent's callback config to the sub-workflow - **`show`** decides how the child appears in the parent's run view (`'inline'` by default) - **`complete()`** is called when the sub-workflow finishes — transform results and return the tool's final value here ## Nested Agents The sub-workflow can be an `AgentWorkflow` itself, enabling multi-agent architectures. See [Agent Workflows](../ai/agent-workflows.md) for the full pattern. ## Registry References - [Sub-Workflow example](/docs/examples/advanced-workflows#sub-workflow) — Parent calling sub-workflows with callbacks and typed output, all three `show` modes chained, `FanOutWorkflow` / `SequenceWorkflow` coordination, and a failing-child workflow paired with a parent that branches on `input.hasError` - [@loopstack/code-agent](/docs/registry/code-agent) — ExploreTask wrapping AgentWorkflow as a task tool --- > Source: https://loopstack.ai/llms/build/patterns/templates.md --- title: Template Expressions description: Rendering dynamic text content with Handlebars templates via this.render(). Covers template syntax, variable interpolation, helpers, and use in prompts. --- # Template Expressions Use Handlebars templates to render dynamic text content in workflows. Call `this.render()` from any `BaseWorkflow` to interpolate state values, format prompts, and generate dynamic output. ## Setup ```typescript import { BaseWorkflow, Transition, Workflow } from '@loopstack/common'; @Workflow({}) export class MyWorkflow extends BaseWorkflow { // this.render() is available from BaseWorkflow — no injection needed } ``` ## Usage ```typescript import { join } from 'node:path'; const rendered = this.render(join(__dirname, 'templates', 'prompt.md'), { subject: args.subject, items: state.items, }); ``` `this.render()` expects an absolute path. Build it with `path.join(__dirname, ...)` so templates resolve relative to the workflow's compiled `.js` file at runtime (where the `templates/` folder is copied during build). Template file (`templates/prompt.md`): ```markdown Write a haiku about {{subject}}. {{#each items}} - {{this.name}} {{/each}} ``` ## Passing Data Pass any data as the second argument to `this.render()`: ```typescript // Workflow args (from ctx parameter — typed via RunContext<{ subject: string }>) this.render(templatePath, { subject: ctx.args.subject }); // Workflow state (from state parameter) this.render(templatePath, { items: state.items, count: state.counter }); // Mixed data this.render(templatePath, { prompt: ctx.args.prompt, history: state.conversationHistory, timestamp: new Date().toISOString(), }); ``` ## Handlebars Syntax ### Variables ```markdown Hello {{name}} Nested: {{user.profile.email}} Array element: {{items.[0]}} ``` ### Conditionals ```markdown {{#if isActive}}Welcome back!{{else}}Please log in{{/if}} {{#unless isBlocked}}Access granted{{/unless}} ``` ### Iteration ```markdown {{#each items}} - {{this.name}}: {{this.value}} {{else}} No items found. {{/each}} ``` ### Context Scoping ```markdown {{#with user}}{{name}} ({{email}}){{/with}} ``` ## Multi-line Template Example ```markdown # Events This Week {{#each events}} - **{{this.summary}}**: {{this.start}} – {{this.end}} {{/each}} {{#unless events}} No events found. {{/unless}} ``` ## When to Use Templates | Scenario | Approach | | ----------------------------------- | --------------------------------- | | LLM prompts with variables | `this.render(templatePath, data)` | | Simple string interpolation | Template literals in TypeScript | | Complex multi-line content | Handlebars template file | | Prompts with iteration/conditionals | Handlebars with `#each`, `#if` | ## YAML UI Config YAML widget configuration uses `transition` values that reference method names and `enabledWhen` / `showWhen` to enable or show widgets only at certain places. These are not template expressions — they are static configuration: ```yaml ui: widgets: - widget: prompt-input enabledWhen: [waiting_for_user] options: transition: userMessage ``` ## Registry References - [Prompt example](/docs/examples/llm#prompt) — Uses `this.render()` for Handlebars prompt templates - [Meeting Notes example](/docs/examples/hitl#meeting-notes) — Renders the LLM prompt that extracts structured notes from a template ---