agent-loop

1# SPDX-License-Identifier: Apache-2.02# yaml-language-server: $schema=https://nika.sh/spec/v1/workflow.schema.json3#4# TEMPLATE · agent-loop · plan fast → execute with a leashed agent → validate the typed result.5#6#   [plan]────▶[execute]─────▶[confirm]7#   infer       agent·leashed  nika:assert8#9# The open-ended job — research, review, triage — where the steps cannot be10# written in advance. A cheap `infer` drafts the plan, a LEASHED agent works11# it (bounded turns, bounded spend, a default-deny tool grant), and an assert12# refuses to pass an empty result downstream.13#14# Demonstrates ·15#   - `agent:` under the full leash · `max_turns` + `max_tokens_total` + an16#     explicit `tools:` list · nothing outside it is reachable17#   - `schema:` on the agent · the engine owns the final shape and RE-ASKS18#     until it conforms — you never hand-instruct it (see `execute`)19#   - `nika:assert` as a trust boundary · an empty run must not read as a20#     successful one21#22# Needs · nothing. Scaffolds and runs green in an empty directory.23#24# Run · nika run <file> --model mock/echo                    # offline rehearsal25#     · nika run <file> --var goal="triage the open bugs"    # a real seat26nika: v127workflow:28  id: agent-loop-template       # SLOT: kebab-case workflow id29  # SLOT: one honest sentence — `nika new` matches intents against these words30  description: "open-ended research / review / triage · plan → budgeted agent → typed result"31​32# SLOT: a TOOL-CALLING model · local by default. This seat is measured, not33# assumed: `ollama/qwen2.5:14b` completes the planning call in ~65s under the34# ceiling below. A reasoning seat (`ollama/qwen3.5:4b`) spends its whole35# budget thinking and never emits JSON here — the guaranteed offline path is36# `--model mock/echo`, which needs no seat at all.37model: ollama/qwen2.5:14b38​39inputs:40  goal:41    type: string42    required: true43    # A `required:` input still carries a `default:` here so the skeleton44    # RUNS the moment it is scaffolded. Replace the default with your job;45    # `--var goal=…` overrides it at any time.46    default: "list the risks of running an agent without a turn budget"   # SLOT47    description: "What the agent must accomplish"   # SLOT48​49⛨permits:                            # the blast radius · default-deny once present50  # Exactly what the body invokes: `nika:assert` (the confirm task) plus the51  # two the agent may call. No `fs:` — see the note on `tools:` below.52  ⛨tools: ["nika:assert", "nika:done", "nika:jq"]53​54tasks:55  plan:56    ◇infer:57      prompt: "Break '${{ inputs.goal }}' into at most 4 concrete steps."   # SLOT58      # SLOT: the spend ceiling for the planning call. Size it for the SEAT,59      # not for the answer: a reasoning model spends tokens thinking before60      # it emits the first brace, and a ceiling that cuts it off mid-thought61      # fails NIKA-INFER-002 ("no JSON value found · the reply was cut off at62      # the token limit"). Measured — 400 starves qwen3.5:4b on this prompt.63      max_tokens: 200064      schema:65        type: object66        additionalProperties: false67        required: [steps]68        properties:69          steps: { type: array, items: { type: string } }70​71  execute:72    with:73      steps: ${{ tasks.plan.output.steps }}74    ✦agent:75      # Say what the JOB is. Do NOT describe the output shape.76      #77      # The engine binds `schema:` to the FINAL answer: a free-text answer78      # that does not conform is RE-ASKED with the schema wired, bounded by a79      # retry budget. Measured on ollama/qwen3.5:4b — this task, with zero80      # shape instruction, returns a clean typed object.81      #82      # Hand-instructing "reply with the object, then call nika:done" is83      # actively harmful: a `nika:done` carrying `result:` is validated84      # DIRECTLY and is NEVER re-asked (nika-verb-agent/src/lib.rs · "a miss85      # is a verdict, never a re-ask"), so a model that hands its JSON back86      # as a *string* dies NIKA-INFER-002 with the budget already spent.87      # Measured twice on that exact instruction. Let the engine own shape.88      system: "You are a careful analyst. Work the plan step by step and report what you actually found."   # SLOT89      prompt: "Plan · ${{ with.steps }}"90      tools:                        # SLOT: the MINIMUM grant for the job91        # Pure compute — this pair needs no filesystem, so the skeleton runs92        # anywhere. Granting the agent a tool here is only HALF a grant: every93        # call still crosses the workflow boundary above. Adding `nika:read`94        # to this list WITHOUT adding `permits.fs.read` fails at run with95        # `NIKA-SEC-004 · agent tool "nika:read" refused by the security96        # boundary` — measured, mid-loop, after the turns are paid for.97        - "nika:jq"98        - "nika:done"               # the early-exit sentinel · loop-owned99      max_turns: 15                 # SLOT: the loop bound100      max_tokens_total: 80000       # SLOT: the spend bound101      schema:                       # SLOT: the typed final-message contract102        type: object103        additionalProperties: false104        required: [findings]105        properties:106          findings: { type: array, items: { type: string } }107​108  confirm:109    with:110      has_findings: ${{ size(tasks.execute.output.findings) > 0 }}   # the check crosses as ONE boundary expression111    ◆invoke:112      tool: "nika:assert"113      args:114        condition: "${{ with.has_findings }}"115        message: "Agent returned no findings, do not trust an empty run"   # SLOT116​117outputs:118  findings:119    value: ${{ tasks.execute.output.findings }}120    description: "The agent's typed findings"   # SLOT121​