The 4 verbs

​

Why four?

crawl_site:
  invoke:
    tool: "nika:fetch"
    args:
      url: "${{ inputs.site_url }}"
      traverse: { max_pages: 5 }   # same-origin BFS · robots honored · page digests out

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

nika run run.nika

• 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.

​

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

secrets:
  github_token:
    source: env                        # a token is a governed reference, never a literal
    key: GITHUB_TOKEN
    egress:
      - to: "nika:fetch"               # the author declassifies THIS sink, in-file
        host: "api.github.com"         # and only this host

permits:
  net: { http: ["api.github.com"] }
  tools: ["nika:fetch"]

tasks:
  pull_readme:
    timeout: "30s"                     # task-level (applies to any verb)
    invoke:
      tool: nika:fetch
      args:
        url: https://api.github.com/repos/supernovae-st/nika/readme
        method: GET
        mode: text                     # extraction mode · see extract-modes
        headers:
          Accept: application/vnd.github.raw
          Authorization: "Bearer ${{ secrets.github_token }}"

• 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: they pass through SecretResolver + AuditSink::SecretRedacted.

​

invoke: call a builtin or MCP tool

search_vectordb:
  with:
    summary: ${{ tasks.summarize.output }}
  invoke:
    tool: "mcp:chroma/query"          # mcp:<server>/<tool> · one colon, then a slash
    args:
      query: "${{ with.summary }}"
      top_k: 5

​

infer: LLM inference

summarize:
  with:
    readme: ${{ tasks.pull_readme.output }}
  infer:
    model: openai/<model>           # <provider>/<name> · see /reference/providers-catalog
    system: "You are a technical writer."
    prompt: |
      Summarize this in one sentence:
      ${{ with.readme }}
    temperature: 0.3
    max_tokens: 500

• Unified InferRequest (INV-017): one DTO · per-provider wire dialects below (3 implemented today: anthropic · gemini · openai-compat, the dialect that carries most of the 16-provider catalog · plus mock).
• Capability rules ( rules) run before dispatch. Sending tools to a model whose capability rule says tool_calling = false fails with a typed validation error before the network round-trip.
• Every provider emits the same InferEvent stream: Delta, ToolUseStart, ToolUseDelta, Thinking, Usage, Done.

​

agent: multi-turn loop with tools

investigate:
  agent:
    model: openai/<model>           # <provider>/<name>
    system: |
      You are investigating a GitHub issue. Use tools to gather
      context before answering.
    tools:                               # default-deny · grant explicitly
      - nika:fetch
      - mcp:browser/*
    max_turns: 10
    max_tokens_total: 100000
    prompt: |
      Investigate issue #${{ inputs.issue_number }} and summarise
      the root cause in under 200 words.

• The loop is budget-bounded. The LANGUAGE contract (max_turns · max_tokens_total · spec 02-verbs) is what workflows declare; the engine’s AgentLoopConfig carries max_turns today plus its planning/reflection/compression knobs. max_tokens_total wires in with the runtime milestone. 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.

​

Verb selection is exhaustive

1. Extending RawAction + the Verb enum.
2. Wiring a new action builder arm.
3. Bumping SchemaVersion (currently v1).
4. Running all 12 admission gates on the consuming L2 verb crate.

​

Read next