Skip to main content
A Nika workflow is a list of tasks. Each task picks exactly one of four verbs (infer, exec, invoke, agent) and supplies its required fields. The set is closed: the parser’s verb dispatcher is exhaustive at compile time, so a fifth verb would be a change to the language specification, not a patch release.
All four verbs execute end-to-end on v. The snippets on this page are task fragments: put one under tasks: in a complete file with its permits: to run it. The verb set is part of the language specification and closed at four.

Why four?

A verb is a distinct native execution model the engine itself implements. Every workflow decomposes into one of these moves: Anything else we considered (“transform”, “map”, “branch”, “retry”) was a special case of one of these four, or workflow-level machinery (dependencies, for_each, when) that lives on the task envelope, not as a new verb. Uploads, forms and crawls stay on the same tool: uploads are multipart:, forms are form:, and a bounded site crawl is traverse: (crawl is an intention, fetch is the primitive):
The set is closed at four. Everything callable is a tool under invoke; everything about ordering is a DAG construct on the task envelope.
Where did fetch go? Fetching a URL is calling a tool, not a distinct execution model, so it is the nika:fetch builtin, reached through invoke: (the extract modes become its mode argument). Same reason a DB query (invoke: mcp:postgres/query) or a file write (invoke: nika:write) is not its own verb.

exec: run a local command

Spawns a subprocess, captures stdout/stderr, returns exit code + output. Required: exactly one of command (array · argv through execve, no shell) | shell (string · the explicit shell door: pipes · redirects · globs). A string command: is rejected at parse. Optional: cwd (path), env (map · OS env for this subprocess), stdin (string), capture (stdout default · stderr · combined · structured). Task-level timeout: applies (not a verb field). The portable argv example prints a literal message with the system printf. Save the canonical file as run.nika, then execute it. It needs no Cargo project or Rust toolchain:
Its command uses command: ["printf", "%s\n", "Hello from a confined program"] and declares permits.exec: ["printf"]. The complete file lives in the canonical argv example. To adapt it to a build, declare the workspace and toolchain access that build actually requires, then check and run the resulting workflow. For the shell door, structured exit status, conditional branches and cleanup, save the complete pipeline as exec-pipeline.nika and run nika run exec-pipeline.nika. That lesson uses explicit sample commands: its test exits 1, the simulated deploy skips, and cleanup runs. Change the sample’s exit 1 to exit 0 to exercise the other branch. It performs no real build or deployment. Invariants (from nika-kernel::process::ShellExecutor):
  • Command::new MUST set kill_on_drop(true): no leaked child processes (INV-011).
  • Concurrent pipe reading uses tokio::try_join! (INV-012).
  • Non-zero exit is a task failure (NIKA-EXEC-001) in the default capture modes, except capture: structured, where the exit code is data (output.exit_code · the task succeeds and the workflow branches on it). Untrusted values ride argv elements (each substituted independently, no shell to break out of) or stdin:, never a shell: string. Content from nika:fetch (or downstream of nika:notify) may not reach any exec: task at all, whatever the channel: NIKA-SEC-015, the order law (Security). Transform it with a builtin such as nika:jq instead.
Cross-link: ShellExecutor trait (L0.5 kernel contract).

HTTP fetch: invoke: nika:fetch (a builtin, not a verb)

Fetching a URL is calling a tool, so it is the nika:fetch builtin reached through invoke:, not its own verb. Issues an HTTP request (GET/POST/etc.), returns bytes or parsed/extracted data; the old extract modes become the builtin’s mode argument.
A credential is a secrets: reference — never an inputs: default, never a literal. And a secret reaching any sink is a blocking leak by default (NIKA-SEC-006): the egress: entry is the author sanctioning one specific destination, statically checkable, and it never widens permits.net.http — it narrows inside it. Pick the mode for the content — the default is markdown, built for pages: fetching a JSON API without a mode markdown-escapes the body (\[, assets\_url) and every downstream jq/fromjson fails on byte 0. APIs take mode: raw (the exact bytes) or mode: jq + a jq: expression — the shape step rides the fetch itself, one task instead of two. Invariants (from nika-kernel::http::HttpClient):
  • Output is tainted by default (external input is untrusted, T3:A).
  • Transient statuses (429, 5xx) are retried per retry: on the task.
  • Authentication headers never appear in events: the runtime masks secret values before an event is written.
See nika:fetch for its full argument schema (mode, jq, selector, headers, body, form, multipart, traverse, response).

invoke: call a builtin or MCP tool

Calls a builtin (nika: namespace), a tool exposed by a connected Model Context Protocol server, or another workflow. MCP servers are declared in the project’s .nika/mcp_servers.json, never in a workflow file: an undeclared server is NIKA-INVOKE-001, and nika mcp approve <server> pins its tools before a run may call them. Required: exactly one of tool (nika:<name> for a builtin, or mcp:<server>/<tool>) or workflow (a filesystem child workflow, see Composition). Optional: args (object · tool-specific schema). Task-level timeout: applies (not a verb field).
The MCP server chroma is configured in the project’s MCP registry (.nika/mcp_servers.json), out of scope of the workflow file. Builtins use the nika: namespace, e.g. tool: "nika:read". Routing goes through ToolExecutor + ToolExecute::execute(ToolCall) at L0.5, the same trait the agent verb uses to dispatch in-loop tool calls (crates/nika-kernel/src/runtime/tool_executor.rs).

infer: LLM inference

Single-shot call to a language model. One InferRequest shape covers the providers this binary wires. Required: prompt (string). Optional: system (string), model (<provider>/<name> · overrides the workflow default), temperature (0.0–2.0), max_tokens (u32), schema (JSON Schema · structured output), thinking ({ enabled, budget_tokens }), vision (image inputs · a file is a read).
Model identifiers are catalog-validated at parse time. See the Providers catalog for live IDs. We never hard-code them in concept docs because model names drift faster than the docs refresh cycle.
Invariants (from nika-kernel::provider::Provider):
  • Unified InferRequest (INV-017): one DTO, three wire dialects (anthropic · gemini · openai-compat, the dialect that carries most of the wired providers) plus mock.
  • Capability rules are consulted before dispatch, first matching rule wins: the token-limit parameter a model takes, whether it reasons, its modalities and supported parameters. nika check reports a reasoning model whose max_tokens leaves no room for its answer, before the network round-trip.
  • Every provider emits the same InferEvent stream: Delta, ToolUseStart, ToolUseDelta, Thinking, Usage, Done.
Cross-link: Providers · Provider trait · ADR-035 (telemetry seams).

Vision files are reads

vision: lists the images sent with the prompt. Each entry is { source: file, path: <path> }, an image file Nika reads, or { source: url, url: <url> }, an image the provider fetches:
A source: file image is a read inside permits.fs.read, here permits: { fs: { read: ["./diagrams/**"] } }, wherever the workflow runs: nika run, nika serve, a child workflow (under the child’s grant met with its parent’s), nika test and a rehearsal, which reads its own copy.
  • At check, a literal path, or a whole bare const reference, is judged against the grant: NIKA-AUTH-006 under an absent permits: block, NIKA-SEC-004 outside a declared one. nika check --infer-permits prints the grant, and NIKA-DRIFT-001 counts it as used. A path the run computes is judged at run, except under a boundary whose fs.read grants no path at all (no block, permits: {}, an empty list), where every path is outside and nika check refuses it.
  • At run, Nika reads each file itself, through nika:read, before any provider call: judged on its resolved path (symlinks and .. resolved) and again when it is opened. Outside the grant the task fails NIKA-SEC-004 with no provider call, and the journal records the denied read. A granted file that cannot be read fails with the read’s own code: NIKA-BUILTIN-READ-001 when no file is there, NIKA-BUILTIN-READ-002 otherwise.
  • A vision entry is a sink. A secret in a vision URL or path is refused (NIKA-SEC-006) unless its egress: declares { to: "infer" }, and untrusted content that picks an entry reaches the task’s answer, so the lethal trifecta (NIKA-SEC-009) follows it.
A source: url entry is not an fs effect: Nika never fetches it, so it needs no fs or net.http grant. On an agent application’s seat over ACP, vision: files ride as image blocks under the same rule. A seat’s direct one-shot route carries no image, so a vision: task there is refused (NIKA-432: nika check blocks run ready, and the run refuses it before anything is sent), with a route that carries the files named (Harness access).

agent: multi-turn loop with tools

A model-driven loop: the agent calls tools, observes results, iterates until a completion signal fires or a budget exhausts. Required: prompt (string · initial user message). Optional: system (string), model (<provider>/<name>), tools (whitelist · glob patterns · default-deny), max_turns (u32 · default 10), max_tokens_total (u32 · cumulative token budget), temperature (0.0–2.0), schema (JSON Schema · validates the final message), images (an agent application’s images, on a harness seat only). On a harness seat (an agent application you are signed into), an agent: task can declare images:: its .output becomes { message, images }, and images: { save: <path> } writes each received image through nika:write, inside permits.fs.write. An API or local model refuses images:; there, nika:image_generate makes the images.
Invariants (from nika-kernel::runtime::agent):
  • The loop is budget-bounded by max_turns and max_tokens_total (spec 02-verbs); both are enforced. A ceiling hit is a typed failure (NIKA-AGENT-001 / NIKA-AGENT-002 · budget_error) with the last assistant message preserved in error.details.partial_output. Recover it explicitly via on_error: if a partial is acceptable. Natural completion (or nika:done, optionally with result:) is success.
  • A failing tool call feeds its typed error back to the model (the loop continues against its budgets), EXCEPT security_error, which fails the task immediately.
  • Every tool call is taint-checked: untrusted data cannot reach dangerous verbs without an explicit sanitizer.
  • The iteration trace (ToolCallRecord + CheckpointMessage) is emitted as events for audit and, optionally, checkpoint resume.
Cross-link: AgentLoopConfig · ADR-016 (cancellation model).

Verb selection is exhaustive

The nika-schema parser enforces “exactly one verb key per task” at compile time: RawAction in crates/nika-schema/src/raw/action.rs has four variants (Infer, Exec, Invoke, Agent), and the action builder has exactly four match arms. A fifth verb would require:
  1. A change to the language specification (spec 02-verbs).
  2. Extending RawAction and wiring a new action builder arm.
  3. A new L2 verb crate passing all 12 admission gates.
This is the single hardest number in the Nika grammar to change. We’d rather say no.
Implementation status. The four L2 verb crates (nika-verb-infer, nika-verb-exec, nika-verb-invoke, nika-verb-agent) are admitted and execute end-to-end (see Constellation). fetch is not a verb crate: it is the nika:fetch builtin reached through invoke. The verb grammar ships in nika-schema.

Workflows

How verbs compose into a DAG.

Bindings

How values flow between tasks.

Providers

The wired providers behind infer and agent.

Events

Every verb emits typed events.