# Strøm — LLM Reference

> Strøm is a workflow/task orchestration platform. Workflows are defined as YAML
> files in a `.workflows/` directory. This index lists documentation sections
> available at focused URLs so LLM agents can fetch only what they need.
>
> Site: https://fremvaerk.github.io/stroem

## Quick Reference — Validation Rules

When generating Strøm workflow YAML, these constraints are enforced at parse time:

**Action types:**
- `type: script` — requires `script` or `source`. Cannot have `image`. Supports `language` field: `shell` (default), `python`, `javascript`, `typescript`, `go`. Optional `dependencies` (package list) and `interpreter` (override auto-detected binary).
- `type: docker` — requires `image`. Runs container as-is (no workspace mount).
- `type: pod` — requires `image`. Runs as Kubernetes pod (no workspace mount).
- `type: script` + `runner: docker` — scripts inside a Docker container with workspace at `/workspace`.
- `type: script` + `runner: pod` — scripts inside a Kubernetes pod with workspace.
- `type: task` — requires `task` field. Cannot have `cmd`, `script`, `image`, `runner`, or `language`.
- `type: agent` — requires `provider` and `prompt`. Calls an LLM (19 providers: anthropic, azure, cohere, deepseek, galadriel, gemini, groq, huggingface, hyperbolic, llamafile, mira, mistral, moonshot, ollama, openai, openrouter, perplexity, together, xai). Optional `system_prompt`, `output` (structured JSON schema), `model`, `temperature`, `max_tokens`.
- `type: approval` — optional `message` (Tera template). Pauses job for human approval, reuses Phase 5d infrastructure.
- `type: script` + `image` is **rejected** — use `type: docker` or `runner: docker` instead.

**Task actions:**
- `task` field must reference an existing task — in the same workspace, or another workspace's task as `ws.task`.
- Self-referencing tasks (direct or via hooks) are rejected. With `ref`, the same task at another commit is allowed (bounded by the nesting depth).
- Maximum nesting depth: 10 levels.

**Git refs (`ref:`):**
- At parse time (`stroem validate`): `ref` is allowed only on a flow step (qualifies `action`), a `type: task` action (qualifies `task`), and scheduler / webhook triggers (qualifies `task`) — not on any other action type, hooks, event-source triggers or agent `tools: [{task: …}]` entries. The value must be a branch or tag name, `refs/heads/<name>`, `refs/tags/<name>`, or a full 40-hex commit SHA; other `refs/…` namespaces and templated values (`{{`, `{%`) are rejected.
- Not checked at parse time — rejected (400 / trigger MISSED) when the job is created or the trigger fires: a short SHA (it parses as a branch name, then fails as "ref … not found" with a hint to use the full 40-character SHA), a branch / tag / commit that does not exist, a library item (`lib.item`) with `ref`, a `ref` whose owner is a folder (non-git) workspace, an unknown workspace, a name missing at that ref, and a flow step whose ref'd action is `type: agent`.
- The referenced name is looked up at the ref (it need not exist on the default branch); `stroem validate` skips that check with a warning.

**Flow steps:**
- `action` must reference an existing action.
- `depends_on` must reference existing steps within the same flow.
- No cycles allowed in the dependency graph.
- Step names must not contain `[` or `]` (reserved for for_each instances).
- `for_each`: Tera template string (renders to JSON array) or literal array. Max 10,000 items.
- `sequential: true`: run loop instances one at a time (default: parallel).
- Inside loop instances: `each.item` = current element, `each.index` = zero-based index.
- `continue_on_failure` on a step: if this step fails, is cancelled, or is skipped because something above it failed, the steps that depend on it still run, and the failure does not fail the job. It never makes the step itself run. `continue_when_skipped` on a step: if this step is skipped by its own `when`, an empty `for_each`, or because a step above it was skipped the same way, the steps that depend on it still run. A step runs only when **every** dependency lets it through (completed, or not completed but carrying the matching flag) — there is no automatic convergence, so an if/else merge needs `continue_when_skipped` on each branch step. A failure fails the job unless a `continue_on_failure` catches it — on the failing step or on every path below it.

**Triggers:**
- `type: scheduler` — `cron` must be a valid 5-field or 6-field cron expression.
- `type: webhook` — `name` must match `^[a-zA-Z0-9_-]+$` (URL-safe).
- `mode` must be `"sync"` or `"async"` (default: `"async"`).
- `timeout_secs` must be 1–300 (default: 30). Only meaningful in sync mode.
- `type: event_source` — long-running queue consumer. Requires `task` (consumer task) and `target_task` (target for emitted jobs). Consumer's execution defined in referenced task. Emitted JSON on stdout creates jobs for target task. `env:` provides environment overrides. `restart_policy`: `always` (default), `on_failure`, `never`. `backoff_secs` for exponential backoff. `max_in_flight` for backpressure.
- `force_refresh: true` (scheduler, webhook) — reload workspace from source before creating the job.
- Scheduler / webhook `task` may name another workspace's task (`ws.task`), optionally with `ref`; the job is created in that workspace.

**Hooks:**
- `on_success` / `on_error` hook action references must exist.
- Hook actions can be `type: task` (creates a child job).

**Templates:**
- Step names with hyphens (e.g., `say-hello`) become underscores in templates: `{{ say_hello.output.* }}`.
- Template context: `input.*`, `<step_name>.output.*`, `secret.*`, `state.*` (task state), `global_state.*` (workspace state), `job.revision`, `job.ref` (empty unless the job runs on a git ref).

**Pod manifest overrides:**
- `manifest` field is only valid on `type: pod` and `type: script` + `runner: pod`.
- Must be a JSON/YAML object (not array or scalar).

**Connections:**
- `connection_types` define property schemas (`string`, `integer`, `number`, `boolean`).
- `connections` are named instances referencing a type. Required fields must be present.
- Task input `type` can reference a connection type — the name is resolved to the full object at job creation.
- Connection values support Tera templates (e.g., `{{ 'ref+...' | vals }}`).

## Guides

- [Workflow Basics](https://fremvaerk.github.io/stroem/llms/workflow-basics.md): Fundamentals: workspaces, tasks, actions, flow steps
- [Action Types](https://fremvaerk.github.io/stroem/llms/action-types.md): script, docker, pod, task, agent, approval — fields and constraints
- [Input & Output](https://fremvaerk.github.io/stroem/llms/input-and-output.md): Task input schemas, step outputs, and OUTPUT: stdout protocol
- [Templating](https://fremvaerk.github.io/stroem/llms/templating.md): Tera expressions, template context, secrets, state variables
- [Conditional Flow Steps](https://fremvaerk.github.io/stroem/llms/conditionals.md): when expressions for conditional step execution
- [For-Each Loops](https://fremvaerk.github.io/stroem/llms/loops.md): for_each with parallel and sequential execution modes
- [Retry Mechanisms](https://fremvaerk.github.io/stroem/llms/retry.md): Step-level and task-level retry with backoff and jitter
- [Triggers](https://fremvaerk.github.io/stroem/llms/triggers.md): Scheduler (cron) and webhook triggers, including force_refresh
- [Event Source Triggers](https://fremvaerk.github.io/stroem/llms/event-sources.md): Long-running queue consumer triggers with OUTPUT: protocol
- [Hooks](https://fremvaerk.github.io/stroem/llms/hooks.md): on_success, on_error, on_cancel, on_suspended lifecycle hooks
- [Connections](https://fremvaerk.github.io/stroem/llms/connections.md): Typed external system configs (databases, APIs, credentials)
- [Secrets & Encryption](https://fremvaerk.github.io/stroem/llms/secrets.md): vals-based secret references (vault, AWS SSM, env vars)
- [Agent Actions](https://fremvaerk.github.io/stroem/llms/agent-actions.md): LLM calls as workflow steps (19 providers, structured output, tools)
- [Task State Snapshots](https://fremvaerk.github.io/stroem/llms/task-state.md): Cross-run state persistence: STATE:, GLOBAL_STATE:, /state mount
- [Git Refs](https://fremvaerk.github.io/stroem/llms/git-refs.md): ref: on actions, type: task and triggers — branch/tag/SHA, templated refs, pinned jobs, per-ref state
- [Artifacts](https://fremvaerk.github.io/stroem/llms/artifacts.md): Per-job files via /artifacts/: limits, MIME sniffing, UI/CLI/MCP download
- [File Inputs](https://fremvaerk.github.io/stroem/llms/file-inputs.md): type: file input fields: upload via UI/REST/CLI/MCP, paths in steps, limits
- [MCP Integration](https://fremvaerk.github.io/stroem/llms/mcp.md): Model Context Protocol server for exposing Strøm to AI agents

## Reference

- [Workflow YAML Reference](https://fremvaerk.github.io/stroem/llms/workflow-yaml.md): Complete YAML schema reference for all fields

## Examples

- [Hello World](https://fremvaerk.github.io/stroem/llms/hello-world.md): Minimal single-step workflow
- [Deploy Pipeline](https://fremvaerk.github.io/stroem/llms/deploy-pipeline.md): Multi-stage deploy with approval gate and rollback
- [CI Pipeline](https://fremvaerk.github.io/stroem/llms/ci-pipeline.md): Test → build → publish with matrix and conditionals

## Single-file reference

If your client cannot fetch individual sections, fetch [llms-full.txt](https://fremvaerk.github.io/stroem/llms-full.txt)
for everything inlined (~200 KB).