[{"k":"h","depth":1,"text":"02 · The 4 verbs","id":"02--the-4-verbs"},{"k":"quote","inline":[{"k":"text","text":"Every task in a Nika workflow binds to "},{"k":"strong","text":"exactly one"},{"k":"text","text":" of 4 verbs.\nA verb is a "},{"k":"strong","text":"distinct native execution model"},{"k":"text","text":" the engine itself\nimplements: call a model, run a process, dispatch a tool, drive an\nagentic loop. That is the whole operation space."},{"k":"text","text":"Everything "},{"k":"em","text":"callable"},{"k":"text","text":" (fetching a URL, a database query, a file\nwrite, cognitive recall) is a "},{"k":"strong","text":"tool"},{"k":"text","text":" reached through "},{"k":"code","text":"invoke:"},{"k":"text","text":".\nEverything about "},{"k":"em","text":"ordering"},{"k":"text","text":" (iteration, branching) is a "},{"k":"strong","text":"DAG"},{"k":"text","text":"\nconstruct ("},{"k":"code","text":"for_each"},{"k":"text","text":" · "},{"k":"code","text":"when"},{"k":"text","text":"). The 4 verbs never change; tools and\nthe stdlib grow freely."}]},{"k":"hr"},{"k":"h","depth":2,"text":"The 4 verbs · summary","id":"the-4-verbs--summary"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Verb · What it does · Stdlib it consumes"}],[{"k":"text","text":"`infer:` · Single LLM call · text · structured · vision · thinking · providers"}],[{"k":"text","text":"`exec:` · Shell command with sandboxing · (none · pure effect)"}],[{"k":"text","text":"`invoke:` · Call a builtin tool OR an MCP tool · builtins · MCP servers"}],[{"k":"text","text":"`agent:` · Multi-turn agentic loop with tool calls · providers · builtins · MCP"}]]},{"k":"p","inline":[{"k":"text","text":"A task "},{"k":"strong","text":"must"},{"k":"text","text":" specify exactly one of these. Multiple verbs on a single task is a validation error."}]},{"k":"quote","inline":[{"k":"strong","text":"Where did `fetch` go?"},{"k":"text","text":" Fetching a URL is "},{"k":"em","text":"calling a tool"},{"k":"text","text":", not a\ndistinct execution model, so it is the "},{"k":"code","text":"nika:fetch"},{"k":"text","text":" builtin, reached\nthrough "},{"k":"code","text":"invoke:"},{"k":"text","text":" (the extract modes become its "},{"k":"code","text":"mode"},{"k":"text","text":" argument). Same\nreason a DB query ("},{"k":"code","text":"invoke: mcp:postgres/query"},{"k":"text","text":") or a file write\n("},{"k":"code","text":"invoke: nika:write"},{"k":"text","text":") is not its own verb. See\n"},{"k":"link","text":"stdlib/builtins-v0.1.md","href":"../stdlib/builtins-v0.1.md"},{"k":"text","text":"."}]},{"k":"h","depth":3,"text":"What `\u0024{{ tasks.<id>.output }}` holds · per verb","id":"what--tasksidoutput--holds--per-verb"},{"k":"p","inline":[{"k":"text","text":"Every task also exposes the full result record ("},{"k":"code","text":".status"},{"k":"text","text":" · "},{"k":"code","text":".error"},{"k":"text","text":" ·\n"},{"k":"code","text":".started_at"},{"k":"text","text":" · "},{"k":"code","text":".ended_at"},{"k":"text","text":" · "},{"k":"code","text":".duration_ms"},{"k":"text","text":" · "},{"k":"link","text":"04 §task output reference","href":"./04-variables.md#-taskxoutput--task-output-reference"},{"k":"text","text":").\nThe "},{"k":"code","text":".output"},{"k":"text","text":" shape depends on the verb (know this before you bind downstream) ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Verb · `.output` is · Structured when"}],[{"k":"text","text":"`infer:` · the model's reply · **string** · `schema:` set → **object** matching it"}],[{"k":"text","text":"`exec:` · **stdout string** (default) · `capture: structured` → `{ stdout, stderr, exit_code }`"}],[{"k":"text","text":"`invoke:` · the **tool's response** (tool-defined · string · object · or bytes) · per builtin / MCP tool schema · bytes are tool-determined (MCP image content · binary read) · flow opaquely · see 04 §value rendering"}],[{"k":"text","text":"`agent:` · the loop's **final message** · string · `schema:` set → **object** matching it"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"`infer:` · LLM call","id":"infer--llm-call"},{"k":"p","inline":[{"k":"text","text":"A single LLM call. The result is the model's response."}]},{"k":"h","depth":3,"text":"Minimal","id":"minimal"},{"k":"code","lang":"yaml","text":"greet:\n    infer:\n      prompt: \"Say hello in French\""},{"k":"h","depth":3,"text":"Full","id":"full"},{"k":"code","lang":"yaml","text":"research:\n    infer:\n      prompt: \"Research Rust async runtimes 2026 in 5 paragraphs\"\n      system: \"You are a senior software architect.\"\n      model: mistral/mistral-large         # override default · <provider>/<name>\n      temperature: 0.3\n      max_tokens: 2000\n      schema:                            # optional · structured output\n        type: object\n        required: [summary, paragraphs]\n        properties:\n          summary: { type: string }\n          paragraphs: { type: array, items: { type: string } }\n      thinking:                          # optional · extended thinking\n        enabled: true\n        budget_tokens: 4000\n      vision:                            # optional · vision input\n        - source: file\n          path: \"./diagram.png\""},{"k":"h","depth":3,"text":"Fields","id":"fields"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Field · Required · Type · Notes"}],[{"k":"text","text":"`prompt` · yes · string · User prompt · may use `\u0024{{ ... }}` substitution"}],[{"k":"text","text":"`system` · no · string · System prompt"}],[{"k":"text","text":"`model` · no · string · Override workflow default · `<provider>/<name>` · see stdlib/providers-v0.1.md"}],[{"k":"text","text":"`temperature` · no · number 0-2 · Sampling temperature"}],[{"k":"text","text":"`max_tokens` · no · integer · Max output tokens · provider-dependent default"}],[{"k":"text","text":"`schema` · no · object · raw JSON Schema · structured output validation — the **out-of-core hatch**; the typed door is task-level `returns:` ([09](./09-types.md) · both on one task = `NIKA-TYPE-003`)"}],[{"k":"text","text":"`thinking` · no · object · Extended thinking · `{ enabled, budget_tokens }`"}],[{"k":"text","text":"`vision` · no · array · Image inputs · each `{ source: file"}]]},{"k":"h","depth":3,"text":"Conformance","id":"conformance"},{"k":"p","inline":[{"k":"text","text":"A v0.1-compliant engine MUST ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Call the configured provider with the given prompt + system + parameters"}],[{"k":"text","text":"Return the model's response as the task output"}],[{"k":"text","text":"Validate the response against "},{"k":"code","text":"schema"},{"k":"text","text":" if present · MAY auto-retry validation failures internally before surfacing "},{"k":"code","text":"NIKA-INFER-002"},{"k":"text","text":" (engine-configurable · the same rule as "},{"k":"link","text":"05 §structured output","href":"./05-errors.md#structured-output-validation"},{"k":"text","text":")"}],[{"k":"text","text":"Reject any unknown field with a clear error (forward-compat) · or accept + warn (engine choice)"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"`exec:` · shell command","id":"exec--shell-command"},{"k":"p","inline":[{"k":"text","text":"Run a shell command. The result is the command's stdout (default) or a structured output."}]},{"k":"h","depth":3,"text":"Minimal","id":"minimal-1"},{"k":"code","lang":"yaml","text":"build:\n    exec:\n      command: [\"cargo\", \"build\", \"--release\"]"},{"k":"h","depth":3,"text":"Full","id":"full-1"},{"k":"code","lang":"yaml","text":"test:\n    timeout: \"60s\"                   # task-level (applies to any verb · Go duration · see 03-dag)\n    exec:\n      command: [\"cargo\", \"test\", \"--workspace\", \"--lib\"]\n      cwd: \"./engine\"\n      env:\n        RUST_LOG: \"debug\"\n      stdin: \"\u0024{{ inputs.input_data }}\"\n      capture: structured            # stdout | stderr | structured | combined"},{"k":"h","depth":3,"text":"Fields","id":"fields-1"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Field · Required · Type · Notes"}],[{"k":"text","text":"`command` · one of · array · **argv** — `[\"prog\", \"arg\", …]` → direct `execve`, **NO shell** · each element substituted independently — an interpolated `\u0024{{ }}` value can never break out of its argument (see Security). Exactly one of `command` | `shell`."}],[{"k":"text","text":"`shell` · one of · string · **The explicit shell door** — one line run via `/bin/sh -c` · pipes · redirects · globs. The blocklist applies HERE; interpolating untrusted values here is the author's own risk, visibly. Exactly one of `command` | `shell`. *(D1 · #75: semantics never fork on a YAML type — the field name carries the meaning. The old string `command:` is rejected at parse.)*"}],[{"k":"text","text":"`cwd` · no · string · Working directory · default = engine's cwd"}],[{"k":"text","text":"`env` · no · object · OS environment variables for **this subprocess** · key→value map · applied over the COMPOSED environment ([01 §permits](./01-envelope.md#permits--optional--the-declared-capability-boundary) env · never inherited)"}],[{"k":"text","text":"`stdin` · no · string · Stdin data · may use `\u0024{{ ... }}`"}],[{"k":"text","text":"`capture` · no · enum · `stdout` (default) · `stderr` · `combined` · `structured` (= `{ stdout, stderr, exit_code }`) — the **source**"}],[{"k":"text","text":"`decode` · no · enum · `text` (default) · `json` · `jsonl` · `bytes` — how the captured **string** becomes a value ([09 §decode](./09-types.md#decode--how-exec-bytes-become-a-value-normative)) · illegal with `capture: structured` (`NIKA-PARSE-025` — that capture already IS an object) · a non-parsing stream settles the task `failure` inside `on_error:` scope"}]]},{"k":"quote","inline":[{"k":"strong","text":"`exec.env` ≠ the envelope `config:`"},{"k":"text","text":": different scopes, neighboring words\n(the one overlap to know · the pre-flip envelope "},{"k":"code","text":"env:"},{"k":"text","text":" block is dead —\n"},{"k":"code","text":"NIKA-VALUES-002"},{"k":"text","text":"). The envelope "},{"k":"code","text":"config:"},{"k":"text","text":" is "},{"k":"em","text":"workflow config"},{"k":"text","text":" read via\n"},{"k":"code","text":"\u0024{{ config.* }}"},{"k":"text","text":"; "},{"k":"code","text":"exec.env"},{"k":"text","text":" is the "},{"k":"em","text":"OS environment of this subprocess"},{"k":"text","text":". They\nare NOT auto-connected. To pass a workflow value into the process, do it\nexplicitly: "},{"k":"code","text":"env: { API_BASE: \"\u0024{{ config.API_BASE }}\" }"},{"k":"text","text":". The subprocess\nenvironment itself is COMPOSED, never inherited (NEP-0005 ·\n"},{"k":"link","text":"01 §permits","href":"./01-envelope.md#permits--optional--the-declared-capability-boundary"},{"k":"text","text":"):\nthe runner env floor ∪ the "},{"k":"code","text":"permits.env:"},{"k":"text","text":" passthrough ∪ this map, minus\nthe dangerous-name floor · an ambient engine variable reaches the child\nonly through a declared "},{"k":"code","text":"permits.env:"},{"k":"text","text":" name."}]},{"k":"quote","inline":[{"k":"code","text":"timeout"},{"k":"text","text":" and "},{"k":"code","text":"retry"},{"k":"text","text":" are "},{"k":"strong","text":"task-level"},{"k":"text","text":" fields (see "},{"k":"link","text":"03-dag.md","href":"./03-dag.md"},{"k":"text","text":"): they apply uniformly to every verb, so they are not repeated inside "},{"k":"code","text":"exec:"},{"k":"text","text":"."}]},{"k":"h","depth":3,"text":"Security","id":"security"},{"k":"p","inline":[{"k":"text","text":"A v0.1-compliant engine MUST ·"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Honor the two exec bodies"},{"k":"text","text":" · "},{"k":"code","text":"command:"},{"k":"text","text":" (array) runs through "},{"k":"code","text":"execve"},{"k":"text","text":" with NO shell: "},{"k":"code","text":"command[0]"},{"k":"text","text":" is the program, the rest are argv passed verbatim, each element substituted independently. "},{"k":"code","text":"shell:"},{"k":"text","text":" (string) runs through "},{"k":"code","text":"/bin/sh -c"},{"k":"text","text":" — the shell-feature path (pipes · redirects · globs). "},{"k":"strong","text":"Exactly one"},{"k":"text","text":" of the two; a string "},{"k":"code","text":"command:"},{"k":"text","text":" (the pre-0.103 implicit-shell form) is rejected at parse ("},{"k":"code","text":"NIKA-PARSE"},{"k":"text","text":" · "},{"k":"code","text":"validation_error"},{"k":"text","text":")."}],[{"k":"text","text":"Implement a shell "},{"k":"strong","text":"blocklist"},{"k":"text","text":" for dangerous commands on "},{"k":"code","text":"shell:"},{"k":"text","text":" (see reference impl "},{"k":"code","text":"nika-policy"},{"k":"text","text":" for canonical list · 100+ patterns including "},{"k":"code","text":"rm -rf /"},{"k":"text","text":" · "},{"k":"code","text":"chmod 777"},{"k":"text","text":" · "},{"k":"code","text":"curl … | sh"},{"k":"text","text":" · etc.)"}],[{"k":"text","text":"Reject blocklist matches with a clear error"}],[{"k":"text","text":"Honor "},{"k":"code","text":"timeout"},{"k":"text","text":" with a hard kill (Go-duration string · see 03-dag)"}],[{"k":"text","text":"Sandbox "},{"k":"code","text":"cwd"},{"k":"text","text":" if configured (engine-specific)"}]]},{"k":"quote","inline":[{"k":"strong","text":"The argv form is the STRUCTURAL fix for command injection: prefer it."},{"k":"text","text":"\nA "},{"k":"code","text":"\u0024{{ }}"},{"k":"text","text":"-interpolated value in the STRING form is shell-parsed:\n"},{"k":"code","text":"shell: \"process \u0024{{ item }}\""},{"k":"text","text":" with "},{"k":"code","text":"item == \"; rm -rf /\""},{"k":"text","text":" is a classic\ninjection, and the blocklist is a "},{"k":"em","text":"detector"},{"k":"text","text":" (best-effort), not a guarantee.\nThe ARRAY form removes the shell entirely: "},{"k":"code","text":"command: [\"process\", \"\u0024{{ item }}\"]"},{"k":"text","text":"\npasses "},{"k":"code","text":"item"},{"k":"text","text":" as ONE argv element no matter what it contains; there is no\nshell to parse it. "},{"k":"strong","text":"Rule of thumb · any command carrying a task output, a\n`var`, or any value not authored inline → use the array form."},{"k":"text","text":" "},{"k":"code","text":"nika check"},{"k":"text","text":"\nwarns ("},{"k":"code","text":"one-obvious-way"},{"k":"text","text":") when an interpolated value lands in a string\n"},{"k":"code","text":"command"},{"k":"text","text":". The string form stays first-class for genuine shell pipelines\n("},{"k":"code","text":"\"cat x | grep y > z\""},{"k":"text","text":"). That is what "},{"k":"code","text":"/bin/sh -c"},{"k":"text","text":" is for."}]},{"k":"h","depth":3,"text":"Conformance","id":"conformance-1"},{"k":"p","inline":[{"k":"text","text":"The engine MUST ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Run the STRING command via the OS shell ("},{"k":"code","text":"/bin/sh -c"},{"k":"text","text":" on Unix · "},{"k":"code","text":"cmd /c"},{"k":"text","text":" on Windows, OR a sandboxed equivalent) · run the ARRAY command via "},{"k":"code","text":"execve"},{"k":"text","text":" with no shell"}],[{"k":"text","text":"Capture stdout/stderr as configured"}],[{"k":"text","text":"Return exit code in "},{"k":"code","text":"structured"},{"k":"text","text":" capture mode"}],[{"k":"strong","text":"Fail the task on non-zero exit"},{"k":"text","text":" ("},{"k":"code","text":"NIKA-EXEC-001"},{"k":"text","text":" · "},{"k":"code","text":"process_error"},{"k":"text","text":") in\n"},{"k":"code","text":"stdout"},{"k":"text","text":" / "},{"k":"code","text":"stderr"},{"k":"text","text":" / "},{"k":"code","text":"combined"},{"k":"text","text":" capture modes (unless "},{"k":"code","text":"on_error:"},{"k":"text","text":" recovers ·\n"},{"k":"link","text":"05","href":"./05-errors.md"},{"k":"text","text":"), "},{"k":"strong","text":"EXCEPT `capture: structured`"},{"k":"text","text":", where a non-zero\nexit is "},{"k":"strong","text":"data, not failure"},{"k":"text","text":" · the task succeeds and "},{"k":"code","text":"exit_code"},{"k":"text","text":" is the\nworkflow's to branch on ("},{"k":"code","text":"when: \u0024{{ tasks.test.output.exit_code != 0 }}"},{"k":"text","text":") ·\nthe one-obvious-way split · default modes for « must succeed » · structured\nfor « inspect the outcome »"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"`invoke:` · builtin or MCP tool call","id":"invoke--builtin-or-mcp-tool-call"},{"k":"p","inline":[{"k":"text","text":"Call a builtin ("},{"k":"code","text":"nika:"},{"k":"text","text":" namespace) or an MCP tool ("},{"k":"code","text":"mcp:"},{"k":"text","text":" namespace). The result is the tool's response."}]},{"k":"h","depth":3,"text":"Tool reference grammar (canonical)","id":"tool-reference-grammar-canonical"},{"k":"code","lang":"text","text":"<namespace>:<path>          one colon introduces the namespace · `/` separates the path\n\nnika:fetch                  builtin · HTTP + extraction (used to be a verb)\nnika:write                  builtin · flat name\nnika:connectome/recall      builtin · grouped path\nmcp:browser/navigate        MCP · server `browser` · tool `navigate`\nmcp:postgres/query          MCP · server `postgres` · tool `query`\nmcp:my-server/do_thing      MCP · server names admit kebab-case · tools admit snake_case"},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"code","text":"mcp:"},{"k":"text","text":" form "},{"k":"strong","text":"requires the slash"},{"k":"text","text":": "},{"k":"code","text":"mcp:postgres"},{"k":"text","text":" alone (no tool) is a\nparse error ("},{"k":"code","text":"NIKA-PARSE"},{"k":"text","text":" · "},{"k":"code","text":"validation_error"},{"k":"text","text":") · server segment\n"},{"k":"code","text":"[a-z][a-z0-9-]*"},{"k":"text","text":" · tool segment "},{"k":"code","text":"[A-Za-z0-9_-]+"},{"k":"text","text":" (tool names are the MCP\nserver's to define)."}]},{"k":"p","inline":[{"k":"text","text":"One rule everywhere · the "},{"k":"strong","text":"colon"},{"k":"text","text":" marks the namespace boundary (exactly once),\nthe "},{"k":"strong","text":"slash"},{"k":"text","text":" separates the path within it. No "},{"k":"code","text":"::"},{"k":"text","text":", no mixed "},{"k":"code","text":"."},{"k":"text","text":"/"},{"k":"code","text":":"},{"k":"text","text":". Globs are\nclean · "},{"k":"code","text":"nika:*"},{"k":"text","text":" · "},{"k":"code","text":"nika:connectome/*"},{"k":"text","text":" · "},{"k":"code","text":"mcp:browser/*"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"strong","text":"The namespace set is CLOSED at v1"},{"k":"text","text":" · "},{"k":"code","text":"nika:"},{"k":"text","text":" and "},{"k":"code","text":"mcp:"},{"k":"text","text":" are the only two ·\nany other namespace ("},{"k":"code","text":"custom:thing"},{"k":"text","text":" · "},{"k":"code","text":"x:tool"},{"k":"text","text":") is rejected at parse time\n("},{"k":"code","text":"NIKA-PARSE"},{"k":"text","text":" · "},{"k":"code","text":"validation_error"},{"k":"text","text":"). A third namespace would be an additive\nspec minor. It never appears silently."}]},{"k":"h","depth":3,"text":"Builtin call","id":"builtin-call"},{"k":"code","lang":"yaml","text":"read_config:\n    invoke:\n      tool: \"nika:read\"\n      args:\n        path: \"./config.yaml\""},{"k":"p","inline":[{"k":"text","text":"See "},{"k":"link","text":"stdlib/builtins-v0.1.md","href":"../stdlib/builtins-v0.1.md"},{"k":"text","text":" for the canonical builtin list (28 builtins in v0.1)."}]},{"k":"quote","inline":[{"k":"strong","text":"Grouped paths are grammar-legal · v0.1 ships none."},{"k":"text","text":" The reference\ngrammar admits "},{"k":"code","text":"nika:<group>/<tool>"},{"k":"text","text":" (the "},{"k":"code","text":"nika:connectome/recall"},{"k":"text","text":"\nillustration above is the reserved FUTURE shape), but the v0.1 builtin\nset contains only flat names · a grouped "},{"k":"code","text":"nika:"},{"k":"text","text":" path is rejected against\nthe closed 23 set today ("},{"k":"code","text":"NIKA-INVOKE-001"},{"k":"text","text":"). The seam exists so the\nConnectome tools land additively · zero workflow-shape change."}]},{"k":"h","depth":3,"text":"MCP call","id":"mcp-call"},{"k":"code","lang":"yaml","text":"query_db:\n    invoke:\n      tool: \"mcp:postgres/query\"\n      args:\n        sql: \"SELECT * FROM users WHERE id = \u00241\"\n        params: [\"\u0024{{ inputs.user_id }}\"]"},{"k":"p","inline":[{"k":"text","text":"The MCP server "},{"k":"code","text":"postgres"},{"k":"text","text":" must be configured in the engine's MCP server registry."}]},{"k":"h","depth":3,"text":"Fields","id":"fields-2"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Field · Required · Type · Notes"}],[{"k":"text","text":"`tool` · yes · string · Tool identifier · `nika:<path>` OR `mcp:<server>/<tool>`"}],[{"k":"text","text":"`args` · no · object · Tool arguments · schema is tool-specific"}]]},{"k":"h","depth":3,"text":"Conformance","id":"conformance-2"},{"k":"p","inline":[{"k":"text","text":"The engine MUST ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Resolve the tool identifier to its implementation (builtin or MCP server)"}],[{"k":"text","text":"Reject unknown tools with a clear error"}],[{"k":"text","text":"Pass "},{"k":"code","text":"args"},{"k":"text","text":" to the tool · validate against tool's schema if known"}],[{"k":"text","text":"Return the tool's response as task output"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"`agent:` · multi-turn agentic loop","id":"agent--multi-turn-agentic-loop"},{"k":"p","inline":[{"k":"text","text":"Run an agentic loop · the model + a set of tools · iterating until completion or budget exhausted."}]},{"k":"h","depth":3,"text":"Minimal","id":"minimal-2"},{"k":"code","lang":"yaml","text":"research:\n    agent:\n      system: \"You are a research assistant.\"\n      prompt: \"Research the topic · \u0024{{ inputs.topic }}\"\n      tools: [\"nika:fetch\"]             # default-deny · grant explicitly"},{"k":"h","depth":3,"text":"Full","id":"full-2"},{"k":"code","lang":"yaml","text":"research:\n    agent:\n      system: \"You are a research assistant. Use tools to gather info.\"\n      prompt: \"Research the topic · \u0024{{ inputs.topic }} · and produce a markdown brief\"\n      model: mistral/mistral-large\n      tools:                            # whitelist · default-deny (no tools if omitted)\n        - \"nika:fetch\"\n        - \"nika:write\"\n        - \"mcp:browser/*\"               # all tools from browser MCP server\n      skills:                           # Agent Skills · SKILL.md paths (agentskills.io shape)\n        - \".agents/skills/nika-authoring/SKILL.md\"\n      max_turns: 20\n      max_tokens_total: 100000\n      temperature: 0.3\n      schema:                           # optional · validate the final message as structured output\n        type: object\n        required: [findings]\n        properties:\n          findings: { type: array, items: { type: string } }"},{"k":"h","depth":3,"text":"Fields","id":"fields-3"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Field · Required · Type · Notes"}],[{"k":"text","text":"`system` · no · string · System prompt"}],[{"k":"text","text":"`prompt` · yes · string · Initial user message (same field name as `infer:` · consistent)"}],[{"k":"text","text":"`model` · no · string · Override workflow default · `<provider>/<name>`"}],[{"k":"text","text":"`tools` · no · array · Tool whitelist · glob patterns · **default-deny** · if absent the agent gets NO tools (pure conversation · least-privilege). Grant explicitly."}],[{"k":"text","text":"`skills` · no · array · [Agent Skill](https://agentskills.io) file paths (each an agentskills.io-shape `SKILL.md`) · **explicit static paths only** — no globs, no `\u0024{{ }}` templates (the `permits:` explicitness law) · loaded at **compose time** and injected into the system context (§Agent Skills below)"}],[{"k":"text","text":"`max_turns` · no · integer · Loop limit · default 10"}],[{"k":"text","text":"`max_tokens_total` · no · integer · Cumulative token budget · default engine-configurable"}],[{"k":"text","text":"`temperature` · no · number 0-2 · Sampling temperature"}],[{"k":"text","text":"`schema` · no · object · raw JSON Schema · validates the agent's **final message** as structured output (same contract as `infer.schema:` · the out-of-core hatch — the typed door is `returns:` · [09](./09-types.md)) · `.output` becomes the matching object"}]]},{"k":"h","depth":3,"text":"Loop semantics","id":"loop-semantics"},{"k":"p","inline":[{"k":"text","text":"The agent loops · model response → if tool calls present, execute tools → feed results back to model → repeat. The loop terminates when ·"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"Model returns a final response with no tool calls, OR"}],[{"k":"code","text":"max_turns"},{"k":"text","text":" reached, OR"}],[{"k":"code","text":"max_tokens_total"},{"k":"text","text":" exhausted, OR"}],[{"k":"text","text":"A tool returns the canonical completion sentinel "},{"k":"code","text":"nika:done"},{"k":"text","text":" (the builtin tool · see "},{"k":"link","text":"stdlib/builtins-v0.1.md","href":"../stdlib/builtins-v0.1.md"},{"k":"text","text":")"}]]},{"k":"p","inline":[{"k":"code","text":"nika:done"},{"k":"text","text":" is "},{"k":"strong","text":"valid only inside an `agent:` loop's tool whitelist"},{"k":"text","text":": it is\nthe loop-completion sentinel. Calling "},{"k":"code","text":"nika:done"},{"k":"text","text":" from a standalone "},{"k":"code","text":"invoke:"},{"k":"text","text":"\ntask (outside any agent loop) is an error ("},{"k":"code","text":"NIKA-BUILTIN-DONE-001"},{"k":"text","text":"). The\nsentinel has no meaning without a loop to terminate. "},{"k":"code","text":"nika:done"},{"k":"text","text":" accepts an\noptional "},{"k":"strong","text":"`result:`"},{"k":"text","text":" arg (any JSON value) · when present the task's\n"},{"k":"code","text":".output"},{"k":"text","text":" is that value (and "},{"k":"code","text":"schema:"},{"k":"text","text":" validates IT) · when absent "},{"k":"code","text":".output"},{"k":"text","text":"\nis the final assistant message (string)."}]},{"k":"p","inline":[{"k":"text","text":"The agent may also grant itself "},{"k":"strong","text":"`nika:compose`"},{"k":"text","text":", a second loop-only\nbuiltin (also valid ONLY inside an "},{"k":"code","text":"agent:"},{"k":"text","text":" whitelist · standalone is\n"},{"k":"code","text":"NIKA-BUILTIN-COMPOSE-001"},{"k":"text","text":"). It lets the model "},{"k":"strong","text":"self-check a workflow it is\ndrafting"},{"k":"text","text":": pass a "},{"k":"code","text":"workflow_yaml"},{"k":"text","text":" string, get the full "},{"k":"code","text":"nika check"},{"k":"text","text":" verdict\nback (conformance + secret-flow + permits + the termination/cost certificate)\nas the tool result. It "},{"k":"strong","text":"never executes"},{"k":"text","text":" the draft: verification yields an\nartifact + its certificate, and running it stays a separate, gated decision.\nSee "},{"k":"link","text":"stdlib/builtins-v0.1.md","href":"../stdlib/builtins-v0.1.md"},{"k":"text","text":" §"},{"k":"code","text":"nika:compose"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"strong","text":"Termination outcomes (normative)"},{"k":"text","text":" ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Case 1 or 4 (natural completion · "},{"k":"code","text":"nika:done"},{"k":"text","text":") → "},{"k":"code","text":"status: success"},{"k":"text","text":"."}],[{"k":"text","text":"Case 2 ("},{"k":"code","text":"max_turns"},{"k":"text","text":" reached) → "},{"k":"strong","text":"`status: failure`"},{"k":"text","text":" · "},{"k":"code","text":"NIKA-AGENT-001"},{"k":"text","text":" ·\n"},{"k":"code","text":"budget_error"},{"k":"text","text":" · the last assistant message is preserved at\n"},{"k":"code","text":"error.details.partial_output"},{"k":"text","text":" (a budget that runs out did NOT produce the\nasked-for result: failing loudly beats returning an unfinished answer ·\nrecover the partial explicitly via "},{"k":"code","text":"on_error:"},{"k":"text","text":" if it is acceptable)."}],[{"k":"text","text":"Case 3 ("},{"k":"code","text":"max_tokens_total"},{"k":"text","text":" exhausted) → same shape · "},{"k":"code","text":"NIKA-AGENT-002"},{"k":"text","text":"."}]]},{"k":"p","inline":[{"k":"strong","text":"Tool-call errors inside the loop are fed back, not fatal"},{"k":"text","text":" · a failing tool\ncall returns its typed error to the MODEL as the tool result (the standard\nagentic convention: the model sees the failure and adapts) · the loop\ncontinues against its budgets. The ONE exception · a "},{"k":"code","text":"security_error"},{"k":"text","text":"\n(whitelist violation "},{"k":"code","text":"NIKA-SEC-002"},{"k":"text","text":" · blocklist) "},{"k":"strong","text":"fails the task\nimmediately"},{"k":"text","text":": security boundaries are not negotiation material for a model."}]},{"k":"h","depth":3,"text":"Tool whitelist · glob semantics","id":"tool-whitelist--glob-semantics"},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"code","text":"tools:"},{"k":"text","text":" whitelist uses "},{"k":"strong","text":"gitignore-style globs"},{"k":"text","text":" for matching ·"}]},{"k":"code","lang":"yaml","text":"tools:\n  - \"nika:read\"                  # exact match\n  - \"nika:*\"                     # any nika builtin\n  - \"mcp:browser/*\"              # any tool from the `browser` MCP server\n  - \"mcp:postgres/query\"         # exact match · postgres query only"},{"k":"p","inline":[{"k":"text","text":"Match rules (canonical) ·"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"*"},{"k":"text","text":" matches any sequence of characters EXCEPT the path separator "},{"k":"code","text":"/"},{"k":"text","text":" (so "},{"k":"code","text":"mcp:browser/*"},{"k":"text","text":" matches "},{"k":"code","text":"mcp:browser/navigate"},{"k":"text","text":" but not "},{"k":"code","text":"mcp:browser/tab/open"},{"k":"text","text":")"}],[{"k":"code","text":"**"},{"k":"text","text":" matches any sequence including "},{"k":"code","text":"/"},{"k":"text","text":" (rare · use sparingly)"}],[{"k":"text","text":"The namespace colon is never crossed by "},{"k":"code","text":"*"},{"k":"text","text":" (so "},{"k":"code","text":"nika:*"},{"k":"text","text":" never matches an "},{"k":"code","text":"mcp:"},{"k":"text","text":" tool)"}],[{"k":"text","text":"Order matters · later rules override earlier rules"}],[{"k":"text","text":"Negation via "},{"k":"code","text":"!"},{"k":"text","text":" prefix · "},{"k":"code","text":"tools: [\"mcp:browser/*\", \"!mcp:browser/navigate\"]"}]]},{"k":"p","inline":[{"k":"text","text":"A v0.1-compliant engine MUST implement these glob semantics canonically · NOT engine-specific. This is a portability invariant."}]},{"k":"p","inline":[{"k":"text","text":"The task output is the final model response."}]},{"k":"h","depth":3,"text":"Agent Skills · `skills:`","id":"agent-skills--skills"},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"code","text":"skills:"},{"k":"text","text":" field makes the agent a "},{"k":"strong","text":"consumer"},{"k":"text","text":" of the\n"},{"k":"link","text":"Agent Skills","href":"https://agentskills.io"},{"k":"text","text":" format — the same "},{"k":"code","text":"SKILL.md"},{"k":"text","text":" shape\n"},{"k":"code","text":"nika init"},{"k":"text","text":" already produces. Each entry is an "},{"k":"strong","text":"explicit file path"},{"k":"text","text":" to a\nskill file: a markdown document opening with a YAML frontmatter block\n("},{"k":"code","text":"---"},{"k":"text","text":" fences) that carries a non-empty "},{"k":"code","text":"name"},{"k":"text","text":" and "},{"k":"code","text":"description"},{"k":"text","text":"; the\nmarkdown body after the closing fence is the skill's instructions. Other\nfrontmatter keys ("},{"k":"code","text":"license"},{"k":"text","text":" · "},{"k":"code","text":"metadata"},{"k":"text","text":" · client-specific fields) are the\nskill author's surface — a consumer MUST tolerate them."}]},{"k":"code","lang":"yaml","text":"review:\n    agent:\n      system: \"You are a code reviewer.\"\n      prompt: \"Review the diff · \u0024{{ tasks.diff.output }}\"\n      skills:\n        - \".agents/skills/code-review/SKILL.md\"\n        - \"docs/skills/security-pass/SKILL.md\"\n      tools: [\"nika:read\"]"},{"k":"p","inline":[{"k":"strong","text":"Resolution (normative)"},{"k":"text","text":" · paths are "},{"k":"strong","text":"static"},{"k":"text","text":" — no globs, no\n"},{"k":"code","text":"\u0024{{ }}"},{"k":"text","text":" templates (the same explicitness law as "},{"k":"code","text":"permits:"},{"k":"text","text":"; a template\nin a skill path is a parse error). Relative paths resolve from the\nworking directory, like every other relative path in the language. The\nfiles are read at "},{"k":"strong","text":"compose time"},{"k":"text","text":" — before the run starts, by the\ncomposition layer, never mid-loop by the runtime — so skill reads are\n"},{"k":"strong","text":"outside `permits.fs`"},{"k":"text","text":" (exactly like the workflow file itself: what\nthe agent will carry is fixed and auditable before any effect)."}]},{"k":"p","inline":[{"k":"strong","text":"Injection (normative)"},{"k":"text","text":" · the resolved skills join the agent's system\ncontext as ONE deterministic section, appended after the authored\n"},{"k":"code","text":"system:"},{"k":"text","text":" (or standing alone when "},{"k":"code","text":"system:"},{"k":"text","text":" is absent) ·"}]},{"k":"code","lang":"text","text":"<authored system>\n\n## Skills\n\n### <frontmatter name>\n\n<frontmatter description>\n\n<markdown body · trimmed>"},{"k":"p","inline":[{"k":"text","text":"— one "},{"k":"code","text":"###"},{"k":"text","text":" block per skill, in "},{"k":"code","text":"skills:"},{"k":"text","text":" source order. Same inputs,\nsame bytes (provider-cache-friendly · reproducible transcripts)."}]},{"k":"p","inline":[{"k":"strong","text":"check≡run"},{"k":"text","text":" · "},{"k":"code","text":"skills:"},{"k":"text","text":" is fully validated statically. "},{"k":"code","text":"nika check"},{"k":"text","text":"\nfails a workflow whose skill paths do not resolve ("},{"k":"code","text":"NIKA-AGENT-003"},{"k":"text","text":" ·\nthe file is missing/unreadable) or whose files are not valid Agent\nSkills ("},{"k":"code","text":"NIKA-AGENT-004"},{"k":"text","text":" · no/unterminated/non-mapping frontmatter ·\nmissing/empty "},{"k":"code","text":"name"},{"k":"text","text":" or "},{"k":"code","text":"description"},{"k":"text","text":") — see\n"},{"k":"link","text":"05-errors.md","href":"./05-errors.md"},{"k":"text","text":". A run refuses on the same findings\nbefore any token is spent. The skill TEXT also joins the referencing\ntask's resume identity: editing a "},{"k":"code","text":"SKILL.md"},{"k":"text","text":" re-runs the task (the same\nlaw as an edited prompt — a resume never serves output produced under a\ndifferent skill)."}]},{"k":"h","depth":3,"text":"Conformance","id":"conformance-3"},{"k":"p","inline":[{"k":"text","text":"The engine MUST ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Honor the "},{"k":"code","text":"tools"},{"k":"text","text":" whitelist · reject tool calls not in the whitelist · "},{"k":"strong","text":"default-deny when `tools:` is absent"},{"k":"text","text":" (the agent gets no tools · least-privilege)"}],[{"k":"text","text":"Enforce "},{"k":"code","text":"max_turns"},{"k":"text","text":" and "},{"k":"code","text":"max_tokens_total"},{"k":"text","text":" budgets · terminate on exhaustion"}],[{"k":"text","text":"Detect the "},{"k":"code","text":"nika:done"},{"k":"text","text":" completion sentinel and exit gracefully"}],[{"k":"text","text":"Return the final model response as task output"}],[{"k":"text","text":"Resolve "},{"k":"code","text":"skills:"},{"k":"text","text":" at compose time · inject the "},{"k":"code","text":"## Skills"},{"k":"text","text":" section in source order exactly as specified above · fail statically ("},{"k":"code","text":"NIKA-AGENT-003"},{"k":"text","text":"/"},{"k":"code","text":"NIKA-AGENT-004"},{"k":"text","text":") on a missing or invalid skill file — never start a run with a half-composed context"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"Forward-compat","id":"forward-compat"},{"k":"p","inline":[{"k":"text","text":"The 4 verb names are "},{"k":"strong","text":"ratified by the [v1 constitution](../design/v1-constitution.md)"},{"k":"text","text":", and the count is "},{"k":"strong","text":"4, absolute"},{"k":"text","text":" — under the constitutional hierarchy of "},{"k":"strong","text":"three atomic calls and one bounded controller"},{"k":"text","text":": call a model once ("},{"k":"code","text":"infer"},{"k":"text","text":"), apply a typed callable once ("},{"k":"code","text":"invoke"},{"k":"text","text":"), run a host process once ("},{"k":"code","text":"exec"},{"k":"text","text":"), and orchestrate a bounded sequence of the atomic calls ("},{"k":"code","text":"agent"},{"k":"text","text":"). Every other capability is either an "},{"k":"strong","text":"invoke-able callable"},{"k":"text","text":" (an HTTP fetch → "},{"k":"code","text":"invoke: nika:fetch"},{"k":"text","text":" · a database query → "},{"k":"code","text":"invoke: mcp:postgres/query"},{"k":"text","text":" · a file write → "},{"k":"code","text":"invoke: nika:write"},{"k":"text","text":" · cognitive recall → "},{"k":"code","text":"invoke: nika:connectome/recall"},{"k":"text","text":") or a "},{"k":"strong","text":"DAG control-flow construct"},{"k":"text","text":" (iteration → "},{"k":"code","text":"for_each"},{"k":"text","text":" · branching → "},{"k":"code","text":"when"},{"k":"text","text":"). There is no "},{"k":"code","text":"nika: v2"},{"k":"text","text":" — ever: while the reference engine is pre-1.0 a verb change would be a break INSIDE "},{"k":"code","text":"v1"},{"k":"text","text":" (per the "},{"k":"link","text":"pre-1.0 stability contract","href":"./00-overview.md#pre-10-stability-contract"},{"k":"text","text":"), and after engine 1.0.0 the verb set is frozen with the rest of the grammar, so a fifth verb is effectively never."}]},{"k":"h","depth":3,"text":"The closure argument · why no case forces a 5th verb","id":"the-closure-argument--why-no-case-forces-a-5th-verb"},{"k":"p","inline":[{"k":"text","text":"Every candidate operation decomposes along "},{"k":"strong","text":"two orthogonal axes"},{"k":"text","text":" ·"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"WHO executes"},{"k":"text","text":": the execution model. There are exactly four · model\ninference ("},{"k":"code","text":"infer"},{"k":"text","text":") · OS process ("},{"k":"code","text":"exec"},{"k":"text","text":") · dispatch-a-call-and-await-its-\nresult ("},{"k":"code","text":"invoke"},{"k":"text","text":") · model-driven loop over tools ("},{"k":"code","text":"agent"},{"k":"text","text":"). Anything with a\nrequest/response shape (however exotic the backend) is by construction\nthe "},{"k":"code","text":"invoke"},{"k":"text","text":" model."}],[{"k":"strong","text":"WHEN it runs"},{"k":"text","text":": ordering. Edges ("},{"k":"code","text":"with:"},{"k":"text","text":" data · "},{"k":"code","text":"after:"},{"k":"text","text":" control) ·\nconditions ("},{"k":"code","text":"when"},{"k":"text","text":") · iteration ("},{"k":"code","text":"for_each"},{"k":"text","text":") · time-bounds ("},{"k":"code","text":"timeout"},{"k":"text","text":") ·\nrecovery ("},{"k":"code","text":"retry"},{"k":"text","text":" · "},{"k":"code","text":"on_error"},{"k":"text","text":" · "},{"k":"code","text":"on_finally"},{"k":"text","text":"). Ordering never executes\nanything: it is DAG-side, or host-side when it concerns "},{"k":"em","text":"starting"},{"k":"text","text":" a run\nat all."}]]},{"k":"p","inline":[{"k":"text","text":"The recurring « doesn't X need a verb? » cases, stress-tested ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Candidate · Axis · Resolution"}],[{"k":"text","text":"**wait-for-human** (approval gate) · WHO · a call that resolves when a human answers · a **tool** · request/response with a long latency · `invoke:` model · **already shipped** as `nika:prompt` (blocking confirm · [stdlib/builtins-v0.1.md](../stdlib/builtins-v0.1.md))"}],[{"k":"text","text":"**sleep / delay** inside a run · WHO · a call that resolves after a duration · a **tool** · **already shipped** as `nika:wait` (relative `duration:` XOR absolute `until:`) · NOT a verb · nothing is executed, a result (elapsed) is awaited"}],[{"k":"text","text":"**cron / schedule** (start a run at time T) · neither · it precedes the run · **host concern** · a workflow describes a run, not its triggering · explicitly out-of-scope ([08](./08-out-of-scope.md))"}],[{"k":"text","text":"**streaming between tasks** · WHEN · changes what an *edge* delivers · a **DAG-edge semantic**, not an execution model · out-of-scope v0.1 · an additive edge attribute later · never a verb"}],[{"k":"text","text":"**sub-workflow call** · WHO · dispatch-and-await a run · a **tool** (workflow-as-tool · see [08](./08-out-of-scope.md) §composition) · the `invoke` model again"}]]},{"k":"p","inline":[{"k":"text","text":"A 5th verb would have to name an execution model that is none of\ncall-with-result, process, inference, or loop, and every concrete candidate\ninspected since the 4-verb lock (D-2026-05-22-N18) has resolved to a tool\n(WHO · request/response) or an ordering construct (WHEN). That is the\nclosure: "},{"k":"strong","text":"the verb set is closed under decomposition into WHO × WHEN."}]},{"k":"p","inline":[{"k":"text","text":"Field additions to each verb are "},{"k":"strong","text":"additive"},{"k":"text","text":" within "},{"k":"code","text":"nika: v1"},{"k":"text","text":" (feature-detected · no minor version in the file). Field removal NEVER happens at v1."}]},{"k":"p","inline":[{"k":"text","text":"A v0.1-compliant engine that encounters an unknown field on a verb may ·"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Reject"},{"k":"text","text":" with a clear error (strict mode · default for tests)"}],[{"k":"strong","text":"Warn + ignore"},{"k":"text","text":" the field (lenient mode · default for production)"}]]},{"k":"p","inline":[{"k":"text","text":"Engine config picks which mode."}]},{"k":"hr"},{"k":"p","inline":[{"k":"text","text":"🦋 "},{"k":"em","text":"Next · [03 · DAG shape](./03-dag.md)"}]}]

the spec · 02

The 4 verbs

Every task in a Nika workflow binds to **exactly one** of 4 verbs.

02 · The 4 verbs #

Every task in a Nika workflow binds to exactly one of 4 verbs. A verb is a distinct native execution model the engine itself implements: call a model, run a process, dispatch a tool, drive an agentic loop. That is the whole operation space.Everything callable (fetching a URL, a database query, a file write, cognitive recall) is a tool reached through invoke:. Everything about ordering (iteration, branching) is a DAG construct (for_each · when). The 4 verbs never change; tools and the stdlib grow freely.

The 4 verbs · summary #

Verb · What it does · Stdlib it consumes
`infer:` · Single LLM call · text · structured · vision · thinking · providers
`exec:` · Shell command with sandboxing · (none · pure effect)
`invoke:` · Call a builtin tool OR an MCP tool · builtins · MCP servers
`agent:` · Multi-turn agentic loop with tool calls · providers · builtins · MCP

A task must specify exactly one of these. Multiple verbs on a single task is a validation error.

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. See stdlib/builtins-v0.1.md.

What `${{ tasks.<id>.output }}` holds · per verb #

Every task also exposes the full result record (.status · .error · .started_at · .ended_at · .duration_ms · 04 §task output reference). The .output shape depends on the verb (know this before you bind downstream) ·

Verb · `.output` is · Structured when
`infer:` · the model's reply · **string** · `schema:` set → **object** matching it
`exec:` · **stdout string** (default) · `capture: structured` → `{ stdout, stderr, exit_code }`
`invoke:` · the **tool's response** (tool-defined · string · object · or bytes) · per builtin / MCP tool schema · bytes are tool-determined (MCP image content · binary read) · flow opaquely · see 04 §value rendering
`agent:` · the loop's **final message** · string · `schema:` set → **object** matching it

`infer:` · LLM call #

A single LLM call. The result is the model's response.

Minimal #

yaml

1greet:2    ◇infer:3      prompt: "Say hello in French"

Full #

yaml

1research:2    ◇infer:3      prompt: "Research Rust async runtimes 2026 in 5 paragraphs"4      system: "You are a senior software architect."5      model: mistral/mistral-large         # override default · <provider>/<name>6      temperature: 0.37      max_tokens: 20008      schema:                            # optional · structured output9        type: object10        required: [summary, paragraphs]11        properties:12          summary: { type: string }13          paragraphs: { type: array, items: { type: string } }14      thinking:                          # optional · extended thinking15        enabled: true16        budget_tokens: 400017      vision:                            # optional · vision input18        - source: file19          path: "./diagram.png"

Fields #

Field · Required · Type · Notes
`prompt` · yes · string · User prompt · may use `${{ ... }}` substitution
`system` · no · string · System prompt
`model` · no · string · Override workflow default · `<provider>/<name>` · see stdlib/providers-v0.1.md
`temperature` · no · number 0-2 · Sampling temperature
`max_tokens` · no · integer · Max output tokens · provider-dependent default
`schema` · no · object · raw JSON Schema · structured output validation — the **out-of-core hatch**; the typed door is task-level `returns:` ([09](./09-types.md) · both on one task = `NIKA-TYPE-003`)
`thinking` · no · object · Extended thinking · `{ enabled, budget_tokens }`
`vision` · no · array · Image inputs · each `{ source: file

Conformance #

A v0.1-compliant engine MUST ·

Call the configured provider with the given prompt + system + parameters
Return the model's response as the task output
Validate the response against schema if present · MAY auto-retry validation failures internally before surfacing NIKA-INFER-002 (engine-configurable · the same rule as 05 §structured output)
Reject any unknown field with a clear error (forward-compat) · or accept + warn (engine choice)

`exec:` · shell command #

Run a shell command. The result is the command's stdout (default) or a structured output.

Minimal #

yaml

1build:2    ▷exec:3      command: ["cargo", "build", "--release"]

Full #

yaml

1test:2    timeout: "60s"                   # task-level (applies to any verb · Go duration · see 03-dag)3    ▷exec:4      command: ["cargo", "test", "--workspace", "--lib"]5      cwd: "./engine"6      env:7        RUST_LOG: "debug"8      stdin: "${{ inputs.input_data }}"9      capture: structured            # stdout | stderr | structured | combined

Fields #

Field · Required · Type · Notes
`command` · one of · array · **argv** — `["prog", "arg", …]` → direct `execve`, **NO shell** · each element substituted independently — an interpolated `${{ }}` value can never break out of its argument (see Security). Exactly one of `command` | `shell`.
`shell` · one of · string · **The explicit shell door** — one line run via `/bin/sh -c` · pipes · redirects · globs. The blocklist applies HERE; interpolating untrusted values here is the author's own risk, visibly. Exactly one of `command` | `shell`. *(D1 · #75: semantics never fork on a YAML type — the field name carries the meaning. The old string `command:` is rejected at parse.)*
`cwd` · no · string · Working directory · default = engine's cwd
`env` · no · object · OS environment variables for **this subprocess** · key→value map · applied over the COMPOSED environment ([01 §permits](./01-envelope.md#permits--optional--the-declared-capability-boundary) env · never inherited)
`stdin` · no · string · Stdin data · may use `${{ ... }}`
`capture` · no · enum · `stdout` (default) · `stderr` · `combined` · `structured` (= `{ stdout, stderr, exit_code }`) — the **source**
`decode` · no · enum · `text` (default) · `json` · `jsonl` · `bytes` — how the captured **string** becomes a value ([09 §decode](./09-types.md#decode--how-exec-bytes-become-a-value-normative)) · illegal with `capture: structured` (`NIKA-PARSE-025` — that capture already IS an object) · a non-parsing stream settles the task `failure` inside `on_error:` scope

`exec.env` ≠ the envelope `config:`: different scopes, neighboring words (the one overlap to know · the pre-flip envelope env: block is dead — NIKA-VALUES-002). The envelope config: is workflow config read via ${{ config.* }}; exec.env is the OS environment of this subprocess. They are NOT auto-connected. To pass a workflow value into the process, do it explicitly: env: { API_BASE: "${{ config.API_BASE }}" }. The subprocess environment itself is COMPOSED, never inherited (NEP-0005 · 01 §permits): the runner env floor ∪ the permits.env: passthrough ∪ this map, minus the dangerous-name floor · an ambient engine variable reaches the child only through a declared permits.env: name.

timeout and retry are task-level fields (see 03-dag.md): they apply uniformly to every verb, so they are not repeated inside exec:.

Security #

A v0.1-compliant engine MUST ·

Honor the two exec bodies · command: (array) runs through execve with NO shell: command[0] is the program, the rest are argv passed verbatim, each element substituted independently. shell: (string) runs through /bin/sh -c — the shell-feature path (pipes · redirects · globs). Exactly one of the two; a string command: (the pre-0.103 implicit-shell form) is rejected at parse (NIKA-PARSE · validation_error).
Implement a shell blocklist for dangerous commands on shell: (see reference impl nika-policy for canonical list · 100+ patterns including rm -rf / · chmod 777 · curl … | sh · etc.)
Reject blocklist matches with a clear error
Honor timeout with a hard kill (Go-duration string · see 03-dag)
Sandbox cwd if configured (engine-specific)

The argv form is the STRUCTURAL fix for command injection: prefer it. A ${{ }}-interpolated value in the STRING form is shell-parsed: shell: "process ${{ item }}" with item == "; rm -rf /" is a classic injection, and the blocklist is a detector (best-effort), not a guarantee. The ARRAY form removes the shell entirely: command: ["process", "${{ item }}"] passes item as ONE argv element no matter what it contains; there is no shell to parse it. Rule of thumb · any command carrying a task output, a `var`, or any value not authored inline → use the array form. nika check warns (one-obvious-way) when an interpolated value lands in a string command. The string form stays first-class for genuine shell pipelines ("cat x | grep y > z"). That is what /bin/sh -c is for.

Conformance #

The engine MUST ·

Run the STRING command via the OS shell (/bin/sh -c on Unix · cmd /c on Windows, OR a sandboxed equivalent) · run the ARRAY command via execve with no shell
Capture stdout/stderr as configured
Return exit code in structured capture mode
Fail the task on non-zero exit (NIKA-EXEC-001 · process_error) in stdout / stderr / combined capture modes (unless on_error: recovers · 05), EXCEPT `capture: structured`, where a non-zero exit is data, not failure · the task succeeds and exit_code is the workflow's to branch on (when: ${{ tasks.test.output.exit_code != 0 }}) · the one-obvious-way split · default modes for « must succeed » · structured for « inspect the outcome »

`invoke:` · builtin or MCP tool call #

Call a builtin (nika: namespace) or an MCP tool (mcp: namespace). The result is the tool's response.

Tool reference grammar (canonical) #

text

1<namespace>:<path>          one colon introduces the namespace · `/` separates the path23nika:fetch                  builtin · HTTP + extraction (used to be a verb)4nika:write                  builtin · flat name5nika:connectome/recall      builtin · grouped path6mcp:browser/navigate        MCP · server `browser` · tool `navigate`7mcp:postgres/query          MCP · server `postgres` · tool `query`8mcp:my-server/do_thing      MCP · server names admit kebab-case · tools admit snake_case

The mcp: form requires the slash: mcp:postgres alone (no tool) is a parse error (NIKA-PARSE · validation_error) · server segment [a-z][a-z0-9-]* · tool segment [A-Za-z0-9_-]+ (tool names are the MCP server's to define).

One rule everywhere · the colon marks the namespace boundary (exactly once), the slash separates the path within it. No ::, no mixed ./:. Globs are clean · nika:* · nika:connectome/* · mcp:browser/*.

The namespace set is CLOSED at v1 · nika: and mcp: are the only two · any other namespace (custom:thing · x:tool) is rejected at parse time (NIKA-PARSE · validation_error). A third namespace would be an additive spec minor. It never appears silently.

Builtin call #

yaml

1read_config:2    ◆invoke:3      tool: "nika:read"4      args:5        path: "./config.yaml"

See stdlib/builtins-v0.1.md for the canonical builtin list (28 builtins in v0.1).

Grouped paths are grammar-legal · v0.1 ships none. The reference grammar admits nika:<group>/<tool> (the nika:connectome/recall illustration above is the reserved FUTURE shape), but the v0.1 builtin set contains only flat names · a grouped nika: path is rejected against the closed 23 set today (NIKA-INVOKE-001). The seam exists so the Connectome tools land additively · zero workflow-shape change.

MCP call #

yaml

1query_db:2    ◆invoke:3      tool: "mcp:postgres/query"4      args:5        sql: "SELECT * FROM users WHERE id = $1"6        params: ["${{ inputs.user_id }}"]

The MCP server postgres must be configured in the engine's MCP server registry.

Fields #

Field · Required · Type · Notes
`tool` · yes · string · Tool identifier · `nika:<path>` OR `mcp:<server>/<tool>`
`args` · no · object · Tool arguments · schema is tool-specific

Conformance #

The engine MUST ·

Resolve the tool identifier to its implementation (builtin or MCP server)
Reject unknown tools with a clear error
Pass args to the tool · validate against tool's schema if known
Return the tool's response as task output

`agent:` · multi-turn agentic loop #

Run an agentic loop · the model + a set of tools · iterating until completion or budget exhausted.

Minimal #

yaml

1research:2    ✦agent:3      system: "You are a research assistant."4      prompt: "Research the topic · ${{ inputs.topic }}"5      tools: ["nika:fetch"]             # default-deny · grant explicitly

Full #

yaml

1research:2    ✦agent:3      system: "You are a research assistant. Use tools to gather info."4      prompt: "Research the topic · ${{ inputs.topic }} · and produce a markdown brief"5      model: mistral/mistral-large6      tools:                            # whitelist · default-deny (no tools if omitted)7        - "nika:fetch"8        - "nika:write"9        - "mcp:browser/*"               # all tools from browser MCP server10      skills:                           # Agent Skills · SKILL.md paths (agentskills.io shape)11        - ".agents/skills/nika-authoring/SKILL.md"12      max_turns: 2013      max_tokens_total: 10000014      temperature: 0.315      schema:                           # optional · validate the final message as structured output16        type: object17        required: [findings]18        properties:19          findings: { type: array, items: { type: string } }

Fields #

Field · Required · Type · Notes
`system` · no · string · System prompt
`prompt` · yes · string · Initial user message (same field name as `infer:` · consistent)
`model` · no · string · Override workflow default · `<provider>/<name>`
`tools` · no · array · Tool whitelist · glob patterns · **default-deny** · if absent the agent gets NO tools (pure conversation · least-privilege). Grant explicitly.
`skills` · no · array · [Agent Skill](https://agentskills.io) file paths (each an agentskills.io-shape `SKILL.md`) · **explicit static paths only** — no globs, no `${{ }}` templates (the `permits:` explicitness law) · loaded at **compose time** and injected into the system context (§Agent Skills below)
`max_turns` · no · integer · Loop limit · default 10
`max_tokens_total` · no · integer · Cumulative token budget · default engine-configurable
`temperature` · no · number 0-2 · Sampling temperature
`schema` · no · object · raw JSON Schema · validates the agent's **final message** as structured output (same contract as `infer.schema:` · the out-of-core hatch — the typed door is `returns:` · [09](./09-types.md)) · `.output` becomes the matching object

Loop semantics #

The agent loops · model response → if tool calls present, execute tools → feed results back to model → repeat. The loop terminates when ·

Model returns a final response with no tool calls, OR
max_turns reached, OR
max_tokens_total exhausted, OR
A tool returns the canonical completion sentinel nika:done (the builtin tool · see stdlib/builtins-v0.1.md)

nika:done is valid only inside an `agent:` loop's tool whitelist: it is the loop-completion sentinel. Calling nika:done from a standalone invoke: task (outside any agent loop) is an error (NIKA-BUILTIN-DONE-001). The sentinel has no meaning without a loop to terminate. nika:done accepts an optional `result:` arg (any JSON value) · when present the task's .output is that value (and schema: validates IT) · when absent .output is the final assistant message (string).

The agent may also grant itself `nika:compose`, a second loop-only builtin (also valid ONLY inside an agent: whitelist · standalone is NIKA-BUILTIN-COMPOSE-001). It lets the model self-check a workflow it is drafting: pass a workflow_yaml string, get the full nika check verdict back (conformance + secret-flow + permits + the termination/cost certificate) as the tool result. It never executes the draft: verification yields an artifact + its certificate, and running it stays a separate, gated decision. See stdlib/builtins-v0.1.md §nika:compose.

Termination outcomes (normative) ·

Case 1 or 4 (natural completion · nika:done) → status: success.
Case 2 (max_turns reached) → `status: failure` · NIKA-AGENT-001 · budget_error · the last assistant message is preserved at error.details.partial_output (a budget that runs out did NOT produce the asked-for result: failing loudly beats returning an unfinished answer · recover the partial explicitly via on_error: if it is acceptable).
Case 3 (max_tokens_total exhausted) → same shape · NIKA-AGENT-002.

Tool-call errors inside the loop are fed back, not fatal · a failing tool call returns its typed error to the MODEL as the tool result (the standard agentic convention: the model sees the failure and adapts) · the loop continues against its budgets. The ONE exception · a security_error (whitelist violation NIKA-SEC-002 · blocklist) fails the task immediately: security boundaries are not negotiation material for a model.

Tool whitelist · glob semantics #

The tools: whitelist uses gitignore-style globs for matching ·

yaml

1tools:2  - "nika:read"                  # exact match3  - "nika:*"                     # any nika builtin4  - "mcp:browser/*"              # any tool from the `browser` MCP server5  - "mcp:postgres/query"         # exact match · postgres query only

Match rules (canonical) ·

* matches any sequence of characters EXCEPT the path separator / (so mcp:browser/* matches mcp:browser/navigate but not mcp:browser/tab/open)
** matches any sequence including / (rare · use sparingly)
The namespace colon is never crossed by * (so nika:* never matches an mcp: tool)
Order matters · later rules override earlier rules
Negation via ! prefix · tools: ["mcp:browser/*", "!mcp:browser/navigate"]

A v0.1-compliant engine MUST implement these glob semantics canonically · NOT engine-specific. This is a portability invariant.

The task output is the final model response.

Agent Skills · `skills:` #

The skills: field makes the agent a consumer of the Agent Skills format — the same SKILL.md shape nika init already produces. Each entry is an explicit file path to a skill file: a markdown document opening with a YAML frontmatter block (--- fences) that carries a non-empty name and description; the markdown body after the closing fence is the skill's instructions. Other frontmatter keys (license · metadata · client-specific fields) are the skill author's surface — a consumer MUST tolerate them.

yaml

1review:2    ✦agent:3      system: "You are a code reviewer."4      prompt: "Review the diff · ${{ tasks.diff.output }}"5      skills:6        - ".agents/skills/code-review/SKILL.md"7        - "docs/skills/security-pass/SKILL.md"8      tools: ["nika:read"]

Resolution (normative) · paths are static — no globs, no ${{ }} templates (the same explicitness law as permits:; a template in a skill path is a parse error). Relative paths resolve from the working directory, like every other relative path in the language. The files are read at compose time — before the run starts, by the composition layer, never mid-loop by the runtime — so skill reads are outside `permits.fs` (exactly like the workflow file itself: what the agent will carry is fixed and auditable before any effect).

Injection (normative) · the resolved skills join the agent's system context as ONE deterministic section, appended after the authored system: (or standing alone when system: is absent) ·

text

1<authored system>23## Skills45### <frontmatter name>67<frontmatter description>89<markdown body · trimmed>

— one ### block per skill, in skills: source order. Same inputs, same bytes (provider-cache-friendly · reproducible transcripts).

check≡run · skills: is fully validated statically. nika check fails a workflow whose skill paths do not resolve (NIKA-AGENT-003 · the file is missing/unreadable) or whose files are not valid Agent Skills (NIKA-AGENT-004 · no/unterminated/non-mapping frontmatter · missing/empty name or description) — see 05-errors.md. A run refuses on the same findings before any token is spent. The skill TEXT also joins the referencing task's resume identity: editing a SKILL.md re-runs the task (the same law as an edited prompt — a resume never serves output produced under a different skill).

Conformance #

The engine MUST ·

Honor the tools whitelist · reject tool calls not in the whitelist · default-deny when `tools:` is absent (the agent gets no tools · least-privilege)
Enforce max_turns and max_tokens_total budgets · terminate on exhaustion
Detect the nika:done completion sentinel and exit gracefully
Return the final model response as task output
Resolve skills: at compose time · inject the ## Skills section in source order exactly as specified above · fail statically (NIKA-AGENT-003/NIKA-AGENT-004) on a missing or invalid skill file — never start a run with a half-composed context

Forward-compat #

The 4 verb names are ratified by the [v1 constitution](../design/v1-constitution.md), and the count is 4, absolute — under the constitutional hierarchy of three atomic calls and one bounded controller: call a model once (infer), apply a typed callable once (invoke), run a host process once (exec), and orchestrate a bounded sequence of the atomic calls (agent). Every other capability is either an invoke-able callable (an HTTP fetch → invoke: nika:fetch · a database query → invoke: mcp:postgres/query · a file write → invoke: nika:write · cognitive recall → invoke: nika:connectome/recall) or a DAG control-flow construct (iteration → for_each · branching → when). There is no nika: v2 — ever: while the reference engine is pre-1.0 a verb change would be a break INSIDE v1 (per the pre-1.0 stability contract), and after engine 1.0.0 the verb set is frozen with the rest of the grammar, so a fifth verb is effectively never.

The closure argument · why no case forces a 5th verb #

Every candidate operation decomposes along two orthogonal axes ·

WHO executes: the execution model. There are exactly four · model inference (infer) · OS process (exec) · dispatch-a-call-and-await-its- result (invoke) · model-driven loop over tools (agent). Anything with a request/response shape (however exotic the backend) is by construction the invoke model.
WHEN it runs: ordering. Edges (with: data · after: control) · conditions (when) · iteration (for_each) · time-bounds (timeout) · recovery (retry · on_error · on_finally). Ordering never executes anything: it is DAG-side, or host-side when it concerns starting a run at all.

The recurring « doesn't X need a verb? » cases, stress-tested ·

Candidate · Axis · Resolution
**wait-for-human** (approval gate) · WHO · a call that resolves when a human answers · a **tool** · request/response with a long latency · `invoke:` model · **already shipped** as `nika:prompt` (blocking confirm · [stdlib/builtins-v0.1.md](../stdlib/builtins-v0.1.md))
**sleep / delay** inside a run · WHO · a call that resolves after a duration · a **tool** · **already shipped** as `nika:wait` (relative `duration:` XOR absolute `until:`) · NOT a verb · nothing is executed, a result (elapsed) is awaited
**cron / schedule** (start a run at time T) · neither · it precedes the run · **host concern** · a workflow describes a run, not its triggering · explicitly out-of-scope ([08](./08-out-of-scope.md))
**streaming between tasks** · WHEN · changes what an *edge* delivers · a **DAG-edge semantic**, not an execution model · out-of-scope v0.1 · an additive edge attribute later · never a verb
**sub-workflow call** · WHO · dispatch-and-await a run · a **tool** (workflow-as-tool · see [08](./08-out-of-scope.md) §composition) · the `invoke` model again

A 5th verb would have to name an execution model that is none of call-with-result, process, inference, or loop, and every concrete candidate inspected since the 4-verb lock (D-2026-05-22-N18) has resolved to a tool (WHO · request/response) or an ordering construct (WHEN). That is the closure: the verb set is closed under decomposition into WHO × WHEN.

Field additions to each verb are additive within nika: v1 (feature-detected · no minor version in the file). Field removal NEVER happens at v1.

A v0.1-compliant engine that encounters an unknown field on a verb may ·

Reject with a clear error (strict mode · default for tests)
Warn + ignore the field (lenient mode · default for production)

Engine config picks which mode.

🦋 Next · [03 · DAG shape](./03-dag.md)

nika-spec@6ac29351a · 02-verbs.md · sha256 d2b0f6a768d75faf… · the pack upstream