deep-research-brief

1nika: v12workflow:3  id: deep-research-brief4  description: "plan → budgeted research agent → thinking synthesis → brief on disk"5​6model: ollama/qwen3.5:4b   # local · zero key · `--model mock/echo` rehearses the whole file7​8inputs:9  topic:10    type: string11    default: "local-first AI runtimes"12    description: "What to research · free text (--var topic=…), and it never touches a path directly"13​14⛨permits:15  ⛨tools: ["nika:done", "nika:fetch", "nika:jq", "nika:write"]16  ⛨net:17    # There is no `*` here and there never will be: `net.http` entries are exact18    # host names. An agent told to « research the web » therefore cannot — the19    # corpus it may reach is a decision taken HERE, before the loop starts,20    # rather than discovered afterwards in a trace. Add the sources you actually21    # trust; the agent's fetch is judged against this list at RUN, and `check`22    # cannot see it coming because the agent chooses its own URLs.23    ⛨http:24      - "arxiv.org"25      - "export.arxiv.org"26      - "en.wikipedia.org"27      - "hn.algolia.com"28  ⛨fs:29    # One brief per topic, written DIRECTLY in ./research/. `*` matches a single30    # segment and never crosses `/`, so even a slug that somehow kept a slash is31    # refused rather than steered into a subtree — `./research/**` would let it32    # through. The slug task below makes that doubly hard; the wall makes it33    # impossible, and only one of the two is a guarantee.34    ⛨write: ["./research/*.md"]35​36tasks:37  # The topic is free text — « Local-First AI Runtimes: a survey/2026 » — and it38  # ends up in a filename. Deriving the slug in jq keeps that arithmetic out of39  # the model AND out of the path: the expression is total, so there is no input40  # for which it returns something containing a separator.41  slug:42    ◆invoke:43      tool: "nika:jq"44      args:45        input: "${{ inputs.topic }}"46        expression: 'ascii_downcase | gsub("[^a-z0-9]+"; "-") | gsub("^-|-
quot;; "")'47​48  plan:49    ◇infer:50      max_tokens: 400              # planning is short · cap it and the cost report is a ceiling51      prompt: "Break '${{ inputs.topic }}' into 4 sharp research queries · no overlap."52      schema:53        # `additionalProperties: false` on every object node — without it the54        # shape is a suggestion and each provider answers with a slightly55        # different object. `plan.output.queries` is read below, so it has to be56        # a promise, not a hope.57        type: object58        additionalProperties: false59        required: [queries]60        properties:61          queries:62            type: array63            items: { type: string }64​65  investigate:66    with:67      queries: ${{ tasks.plan.output.queries }}68    ✦agent:69      system: |70        You are a rigorous researcher. Work the queries one by one · fetch71        sources · keep verbatim quotes · note what each source actually72        supports, and what it does not. If a fetch is refused, record that the73        source was out of bounds rather than substituting another.74        Call nika:done when the plan is exhausted.75      prompt: "Research plan · ${{ with.queries }}"76      tools:77        # Every id here must also appear in `permits.tools` above — `check`78        # refuses the mismatch statically (NIKA-SEC-004 · agent tool … is79        # outside permits.tools). Note what is NOT granted: `nika:write`. The80        # agent's product is the typed object it returns, so it never needs a81        # file of its own, and the workflow keeps the only pen in the room.82        - "nika:fetch"                 # the corpus named in permits.net.http83        - "nika:done"                  # the loop-completion sentinel84      max_turns: 25                    # the leash · a loop that cannot end is a bill85      max_tokens_total: 150000         # and the second leash, in tokens86      schema:87        type: object88        additionalProperties: false89        required: [findings, sources]90        properties:91          findings:92            type: array93            items: { type: string }94          sources:95            type: array96            items: { type: string }97​98  brief:99    with:100      findings: ${{ tasks.investigate.output.findings }}101      sources: ${{ tasks.investigate.output.sources }}102    ◇infer:103      max_tokens: 2000104      prompt: |105        Findings · ${{ with.findings }}106        Sources · ${{ with.sources }}107        Write the executive brief · what's true · what's contested · what it108        means · what to do. Two pages max. Anything the sources do not support109        goes in « contested », never in « true ».110      thinking:111        # A reasoning budget, honoured by seats that support extended thinking112        # and ignored by the ones that do not — declaring it never fails a run.113        enabled: true114        budget_tokens: 8000115​116  save:117    with:118      slug: ${{ tasks.slug.output }}119      brief: ${{ tasks.brief.output }}120    ◆invoke:121      tool: "nika:write"122      args:123        path: "./research/${{ with.slug }}.md"124        content: "${{ with.brief }}"125        create_dirs: true126​127outputs:128  brief: ${{ tasks.brief.output }}129  sources:130    value: ${{ tasks.investigate.output.sources }}131    description: "Every source the agent actually used"132  slug:133    value: ${{ tasks.slug.output }}134    description: "The filename stem the brief landed under · ./research/<slug>.md"135​