Basic agent

This example builds an AI agent that speaks in cowsay bubbles.

The steps make a quick CLI application using App Builder and then drive it in various ways using the LLM.

The example needs an Anthropic API key, the cowsay application (try brew install cowsay) and fisk-ai installed.

Creating a CLI tool

This example uses Choria Application Builder to create a basic CLI tool that can say and think. Any command line tool built with Fisk works.

First create an ABTaskFile:

name: cowsay
description: Tools for the Cowsay LLM Agent
author: fisk-ai@choria.io

commands:
  - name: say
    description: Say something using a talking cow, does not accept emoji
    type: exec
    arguments:
      - name: message
        description: The message to send to the terminal
        required: true
        validate: is_shellsafe(value)
    command: |
      {{ default .Config.Cowsay "cowsay" }} {{ .Arguments.message | escape }}

  - name: think
    description: Think something using a thinking cow, does not accept emoji
    type: exec
    arguments:
      - name: message
        description: The message to send to the terminal
        required: true
        validate: is_shellsafe(value)
    command: |
      cowthink {{ .Arguments.message | escape }}

Now install appbuilder:

$ brew tap choria-io/tap
$ brew install appbuilder

Then confirm the CLI tool works:

$ abt
usage: abt [<flags>] <command> [<args> ...]

Tools for the Cowsay LLM Agent

Help: https://choria-io.github.io/appbuilder

Commands:
  help [<command>...]
  say <message>
  think <message>

$ abt say 'Hello AI'
 __________
< Hello AI >
 ----------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Creating an LLM agent

Turning this CLI into an LLM agent needs an agent.yaml file.

# Command to introspect and expose as an agent
application_path: /opt/homebrew/bin/abt

harness:
  # Allow the LLM to prompt us for information if needed
  human_in_the_loop:
    enabled: true

llm:
  # Choose a Model and set safety budgets
  model: claude-haiku-4-5-20251001
  budget:
    max_tokens: 100000
    max_iterations: 50

# We want a cow joke machine!
system_prompt: |
  Tell jokes using Cows!

  You have tools that can render a cow saying < 120 character sentences, when asked use the tools to tell funny jokes.

  You tell cow jokes, no other kinds of jokes, strictly jokes about cows. If asked to tell non cow jokes, refuse and show no joke.

  Keep narration short, just stick to the jokes, don't say what you are doing or planning to do, just do it and don't repeat the joke

Run the agent after setting the API key:

$ export ANTHROPIC_API_KEY="....."
$ fisk run --tool-output --no-tui 'tell me a joke '
-> say -- Why did th...space?
<-  
 ______________________________
< Why did the cow go to space? >
 ------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

-> think -- To visit t...oooon!
<- 
 ______________________
( To visit the Moooon! )
 ----------------------
        o   ^__^
         o  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||


  There you go! A classic cow joke for you!

Run summary: model=claude-haiku-4-5-20251001 llm_calls=2 tool_calls=2 tokens=3536/113 thinking=0 latency=3.613s

The default is a running TUI. To make the output easy to show here, the run passes --no-tui and shows the tool call output with --tool-output.

Now ask about a cat joke:

$ fisk run 'tell me a joke about a cat'

  I appreciate the request, but I only tell jokes about cows! I'm strictly a cow joke specialist.

  If you'd like to hear some funny cow jokes instead, I'd be happy to moo-ve right into those for you!

Run summary: model=claude-haiku-4-5-20251001 llm_calls=1 tool_calls=0 tokens=1632/54 thinking=0 latency=1.341s

Running the agent

The agent runs in one of these modes:

• A shell script style output, plain text to STDOUT with an exit at the end of the task
• A TUI for interaction, optionally continuing to chat with the agent after the main task completes
• Hosted behind a channel, taking work from a queue or serving its tools to other agents

TUI

The TUI mode is the default: a visual runner with hot-keys to show or hide thinking and tool output, and scrolling up and down the session history. A chat box can optionally be enabled to continue a session.

In the TUI press the ? key to get interactive help.

Chat after turn

In the TUI mode the chat bar opens once the prompt is processed, instead of exiting, for follow up questions related to the session. Every full-screen run works this way; --no-tui answers one prompt and exits, since it has no bar to open.

Type a follow-up and press Enter to send it; Ctrl-D ends the session, Ctrl-C aborts it. Up/Down recall this session’s earlier follow-ups. Alt-Enter (Option-Enter) moves to the next line rather than send. Ctrl-L empties the transcript on screen and leaves the conversation and any half-typed follow-up alone, where /clear does the opposite and drops the conversation while leaving the scrollback.

Shell mode

The TUI is turned off with --no-tui, and the system falls back to a simple terminal output format suitable for scripting.

The model’s prose is markdown: both the final answer and any mid-conversation updates. When stdout is a terminal it is rendered for readability with a style matched to the terminal background; when stdout is piped or redirected, the raw markdown is written so the result stays free of ANSI escape codes. Rendering can also be disabled with --no-color, or the standard NO_COLOR environment variable.

Output is separated by kind. Only the final answer goes to stdout; everything else goes to stderr: the commands being run, mid-conversation updates, a final run summary (LLM calls, tool calls, tokens, latency), and, with --thinking, the model’s reasoning (each line prefixed with a thought bubble). This keeps stdout safe to pipe into other tools.

One-shot runs

The common use case gives a system_prompt that describes the goals and approach (think of it as a one-file SKILL) and a user prompt that provides the question to solve.

The LLM runs through the prompt and, once it reaches the end of its turn, finishes processing, and the session cannot continue later. This resembles a shell utility.

HTTP debugging

As a debug or learning aid, all the HTTP requests can be logged to http-debug.log using the --http-debug flag.

Model settings

The agent.yaml sets which model runs the agent, the budget a run may spend, and whether the model exposes its reasoning. The Basic agent example shows these together. The full set of configuration fields is in the configuration reference.

Model

llm.model selects the model and is required. It accepts any model identifier the Anthropic API accepts:

llm:
  model: claude-sonnet-5

Larger models reason better on complex, long-horizon tasks; smaller models like Haiku are faster and cheaper for narrow ones. When the agent exposes ten or more tools it relies on the model’s server-side tool search, which recent models support and older ones (Claude Opus 4.1 and earlier and local models) do not. Set llm.no_tool_search to send every tool directly on an endpoint that does not implement tool search; when a large tool set cannot use it the run warns that all tools are being sent directly. The configuration reference lists the known models and their trade-offs.

Budget

llm.budget limits the agent loop so it cannot run without end:

llm:
  budget:
    max_tokens: 500000
    max_iterations: 50
    call_timeout: 120s

The two caps have different scopes. max_iterations applies to a single turn, and every turn of a conversation gets the same allowance. max_tokens applies to the whole conversation, so every turn draws on one allowance. Start a new conversation to get a fresh one.

When a turn reaches the iteration cap, it stops, says so, and you can carry on with another prompt. When a conversation reaches its token cap, it is finished: the next prompt is refused before it runs. Start a new conversation, or raise llm.budget.max_tokens on the machine running the agent.

max_tokens counts tokens, not money. It adds up the uncached input, the output, and both prompt-cache tiers. A cache read counts the same as an uncached input token here even though it costs a fraction as much, so two conversations with the same token count can cost very different amounts. Set this value against your own usage rather than treating it as a spending limit.

Thinking

Extended thinking lets the model expose its reasoning before it answers. Some providers call this reasoning rather than thinking; it is the same setting.

llm:
  thinking:
    enabled: true

Reasoning is never displayed unless asked for. --thinking (or THINKING=1) shows it, on fisk run and on fisk session show --transcript.

thinking=N on the run summary and in the TUI status bar reports the tokens spent reasoning, shown whether or not reasoning is displayed. It is part of the output half of tokens=in/out, not extra.

Terminal UI

These harness settings govern the full-screen UI for an agent, independent of the per-run --no-tui flag:

harness:
  no_tui: true
  no_bell: true

• no_tui is a persistent off switch: the agent always uses the line-by-line output, even on an interactive terminal, and the command line cannot turn the UI back on. Use --no-tui instead for a one-off run.
• no_bell silences the terminal bell. By default the full-screen UI rings the bell each time a run blocks on an approval gate or an ask_human_* prompt, so a waiting run is noticed even when unattended.

Both are negative switches and have no effect in the line UI.

Tool selection

Run the fisk info command to verify what tools the agent has access to:

$ fisk info
╭───────────────────┬────────┬───────────────────────────────────────────────────────┬──────╮
│ TOOL              │ SOURCE │ DESCRIPTION                                           │ TAGS │
├───────────────────┼────────┼───────────────────────────────────────────────────────┼──────┤
│ say               │ local  │ Say something using the configured command            │      │
│ think             │ local  │ Think something using a cow                           │      │
│ ask_human_confirm │ local  │ Ask the human operator a yes/no question at the te... │      │
│ ask_human_select  │ local  │ Ask the human operator to choose one option from a... │      │
│ ask_human_input   │ local  │ Ask the human operator to type a free-text value a... │      │
╰───────────────────┴────────┴───────────────────────────────────────────────────────┴──────╯

Prompt:

  Tell short jokes using Cows!
...

The output shows the say and think tools and some Human in the Loop tools. When the configuration sets a model, fisk info also prints a Model section first, listing the resolved model and provider, whether thinking is enabled, and how tool search will behave, so you can confirm the backend and feature gates without starting a run.

Application tags

The application can declare that the LLM never gets the think tool:

  - name: think
    description: Think something using a cow
    type: exec
    tags: [ ai:deny ]
    # ...

Adding the ai:deny tag to a command means Fisk AI never exposes that tool to the LLM. fisk info confirms the LLM only gets the say tool now.

Agent configuration

The agent.yaml can also include only certain tools:

include:
  tools:
    - ^say

Or exclude certain tools specifically:

exclude:
  tools:
    - ^think

This uses regular expressions over the tool name, and both can be used together. For example, include ^cow but exclude ^cow_think.

A tool’s name is its command path joined with underscores, so a nested command like cow think becomes the tool cow_think. Grouping commands and hidden commands are skipped and never become tools.

Tools can also be included or excluded by tag:

exclude:
  tags:
    - scope:system

This excludes any command that has the scope:system tag.

Global flags

A wrapped binary often has application-level global flags that apply to every subcommand. nats, for example, has --context to select a stored connection profile, alongside sensitive globals such as --user and --password. By default none of these are exposed to the model. global_flags is an allowlist of the globals you want the model to be able to set per command:

global_flags:
  - context

Each named global becomes an argument on every leaf command tool, so the model can run nats stream ls against a chosen context without you hard-wiring one. Names are the long flag name, with or without the leading dashes, and are validated against the binary’s real global flags at load; a name matching none is an error. Hidden and framework flags (like --help) cannot be exposed, and a global that clashes with a command’s own flag or argument is skipped for that command. A global the application marks required is always exposed, whether or not it is listed, since the command cannot run without it.

Run fisk info to see which globals a binary exposes; it lists the application’s global flags and marks the ones you have allowlisted.

Command tags

Fisk commands can carry tags, set in their fisk definition (or, for App Builder applications, in YAML). Tags can be referenced by the include/exclude rules to select commands by group, and the ai: prefix is reserved for the tags fisk interprets. The full vocabulary is listed under Command tags in the Reference guide; the tags that control how a command is exposed to the model are:

The behavior tags (ai:read_only, ai:destructive, ai:additive, ai:idempotent) describe what a command does rather than controlling it. They reach the model and, over MCP, the client; they gate nothing.

A tag under the ai: prefix that fisk does not recognize does nothing, so it is reported as a warning at startup and by fisk info.

ai:deny is the reliable way to keep a command the agent should never call out of reach, since it applies before any include/exclude rule. ai:no_defer keeps the handful of commands the model needs on most requests immediately available rather than discoverable only through tool search.

ai:confirm gates a command behind the operator’s explicit permission. When the model calls a command tagged ai:confirm, fisk pauses before running it and prompts the operator at the terminal, showing the resolved command line with its arguments, and offers three choices: run it once, run it and stop asking for that command for the rest of the conversation, or decline. Declining returns an authoritative result to the model (the command is not run and the model is told the decision is final), so it stops rather than working around the refusal. An “allow for the conversation” answer is remembered by command, regardless of its arguments: once you bless stream rm, every later stream rm call runs without asking again, so reserve that choice for a command you trust the agent to repeat.

The conversation records the answer, so continuing it honors the answer rather than asking again, and fisk session show lists what it holds. They are dropped by /clear and by a --force resume across a changed configuration, and a resume with no terminal attached declines a gated command rather than honoring one. The prompt is rendered on stderr (so a piped final answer stays clean), the displayed command line is stripped of terminal control sequences so model-supplied argument values cannot spoof what you see, and it denies by default: no interactive terminal, or a prompt that cannot be shown, declines rather than runs. An interrupt or an end-of-input at the prompt ends the run rather than declining, since the operator did not answer; the conversation stays continuable and asks again. Unlike human_in_the_loop, the tag is always active: there is no configuration flag to enable it.

The same gate can be extended to other tags with the harness.confirm_tags configuration key: any tag listed there gates its commands exactly as ai:confirm does, which lets an operator require confirmation for a tag the application already uses (for example ai:destructive, or an application’s own impact:rw) without editing the application. It is additive to the always-on ai:confirm tag and matching is exact rather than a regex. A confirm_tags entry that matches no loaded command is reported as a warning at startup, since a typo would otherwise leave a command ungated. The approval prompt names the tag that gated the command, so you can tell why you are being asked. Run fisk info to see each command’s tags and which commands a run would gate. Like ai:confirm, a confirm_tags tag gates both the agent loop and MCP, where it is requested through elicitation.

Any other tags are free-form: they have no built-in meaning to fisk but can be matched by the tags field of an include or exclude rule.

All of a command’s tags, reserved and free-form alike, are also included in the tool description fisk sends the model, as a trailing Tags: ... line, in both the agent and over MCP. This lets your prompt reference them, for example “always use ask_human_confirm before running any command tagged impact:rw”. The human-facing fisk info listing keeps the plain description.

Session snapshots

Every run is a conversation, and every conversation is journaled. You do not turn this on. Leave a run and continue it later, in a fresh process or on another machine, using the id it prints when it ends.

Continuing a conversation

Ask something. fisk prints the id of the conversation when the run ends:

$ fisk run "report on the ORDERS stream"

Continue it by that id. No prompt is given, since the conversation is restored from the journal; passing one is an error:

$ fisk run --resume t-3f2a9c...

fisk reads the conversation back before it goes on, so you continue in context rather than from a blank screen.

Against an agent somewhere else, see remote agents, the journal is on the worker rather than here, so --resume takes the conversation token instead of the id. fisk session show on the worker prints it.

Chat sessions

Every full-screen run is a durable, resumable conversation.

Each turn is journaled, so the whole conversation survives leaving, a stop or a crash. Press Ctrl-D to leave the input bar when you are finished for now; the status bar reads ctrl-d done. This does not end the conversation. fisk prints how to continue it as it exits. Ctrl-C asks the current turn to stop at its next safe point. The conversation is kept either way.

Resuming reads the conversation back into the viewport before the input bar opens, so you continue in context rather than from a blank screen. Because the bar needs a real terminal, a conversation can only be continued in the full-screen UI, not with --no-tui or over a pipe, where a run answers one prompt. A conversation has no “completed” state; remove it with session rm once it is no longer needed.

Stopping

The first Ctrl-C, or a SIGTERM, asks the run to stop where the conversation can be continued: the current step finishes, the turn is journaled, and fisk prints how to continue it. A second gives up on the run and leaves.

Both keep the conversation. The difference is that the first lets the turn reach a safe point, so the work it had already done is recorded rather than lost part way.

Durability

A session is journaled event by event as the run proceeds: each model turn and each tool result is recorded as it happens.

• A clean suspend is exactly-once. Nothing runs after the last recorded event, so a resume never repeats a tool call or an LLM call.
• A crash resumes from the last recorded event, so at most one tool call is repeated. A tool whose side effect completed but whose result was not yet recorded runs again on resume, since fisk cannot make an external side effect idempotent. Already-recorded turns and results are never replayed.

Resume a session against the same agent configuration it started with. A session can be resumed from anywhere, including a machine that no longer has the original agent.yaml, so care is required: continuing a conversation against a different model, tool set, or system prompt can make the replayed transcript incoherent. fisk fingerprints the configuration when the conversation started and refuses to continue it when that no longer matches, naming what changed. --force overrides it, except for the provider: a session started against one llm.provider can never be resumed against another. A session that already completed cannot be resumed.

Managing sessions

A suspended or completed session is kept until it is removed. List, inspect, and remove sessions with the session subcommands:

fisk session ls
fisk session show <id>
fisk session show <id> --transcript
fisk session rm <id>

session ls lists each session with its status, model, and prompt. session show prints a session’s counters and status; --transcript shows the full conversation (prompt, thinking, narration, tool calls, and tool output). On an interactive terminal --transcript opens the full-screen viewer with thinking and tool output folded, which z and Z expand; --no-tui/NO_TUI prints it as line output instead. session rm deletes a session.

Answering a deferred tool call

A tool can report that its answer arrives later rather than now. The run then suspends, releasing the process, and resumes once the answer exists. session show lists what such a session is waiting on under Waiting on, giving the tool_use id, the tool, and whatever the tool said it is waiting for.

The answer travels on a request carrying the conversation’s token, described in Answering after the run ended. The tool is never called again: it already started the work, which is why it deferred.

No tool that ships with fisk defers; the mechanism is for tools a Go program registers through agent.Options.CustomTools.

These commands read the file backend under --state-dir by default. To inspect sessions in a configured backend, a jetstream stream or a file directory named in the config, pass that config with --config:

fisk session ls --config agent.yaml
fisk session show <id> --config agent.yaml

Where a session is journaled is configurable through harness.sessions, which mirrors the shape of harness.memory. Two backends ship: file (the default) and jetstream Version0.0.3. The block is optional; leaving it out keeps the file backend under the XDG state directory.

fisk info shows a Sessions section with the resolved backend and, for the jetstream backend, the stream and NATS context, so you can confirm where sessions are stored without starting a run.

File backend

The file backend keeps each session as a JSON-lines journal under a directory. Sessions are stored under the XDG state directory, $XDG_STATE_HOME/fisk-ai/runs, defaulting to ~/.local/state/fisk-ai/runs. Set options.directory to move it off the default XDG path:

harness:
  sessions:
    backend: file
    options:
      directory: /var/lib/fisk-ai/runs

--state-dir overrides options.directory for a single run or session command, so the flag always wins over the configured path. It applies only to the file backend: combining it with a non-file backend is an error rather than a silently ignored flag.

JetStream backend

The jetstream backend keeps sessions as messages on a NATS JetStream stream instead of on disk, so a run suspended on one machine resumes on another over a broker. It uses the connection from the configured nats_context, the same one memory and remote tools use, and binds to a stream that must already exist: the agent never creates it, so you own the stream’s retention policy.

nats_context: production

harness:
  sessions:
    backend: jetstream
    options:
      stream: FISK_SESSIONS

Create the stream first, subscribed to one wildcard subject and keeping a single message per subject so each run record is write-once:

nats --context production stream add FISK_SESSIONS \
  --subjects 'fisk.sessions.>' --max-msgs-per-subject=1 \
  --discard=new --discard-per-subject

The stream keeps messages forever by default, which suits sessions; do not set a max age or they would silently expire. The subject prefix (fisk.sessions above) is yours to choose; the backend derives it from the stream’s single wildcard subject when it binds, so it is not set in the config. The backend fails at run start, rather than degrading silently, if the stream does not exist or its configuration does not match this shape. Sessions are never namespaced by identity, so a run started by one agent is found by another reading the same stream; keep separate environments in separate streams.

Remote agents

--nats-context points a terminal at an agent somebody else is running rather than starting one in this process:

$ fisk run --nats-context production "how many streams are there"

identity in the configuration names which agent to talk to, and you must set it. A default or a name derived from the application binary is shared by every agent built the same way, so the run could reach any of them.

The worker calls the model, runs the tools and writes the journal. Flags that describe that work are refused rather than ignored: --api-key, --base-url, --trace, --http-debug, --verbose, --state-dir and --no-telemetry. Setting one of these through an environment variable is ignored without an error, since you did not type it.

MCP client

mcp_clients imports the tools of third-party MCP servers into an agent run, alongside the wrapped application’s commands, the built-ins and any remote tools. Each entry names one server and selects a transport by which of command and url it sets: command starts the server as a child process and speaks stdio to it, url reaches an already-running server over streamable HTTP. Setting both is an error, and so is setting neither. Stdio and streamable HTTP are the only transports, and an endpoint that speaks the older HTTP+SSE transport is not supported.

mcp_clients:
  - name: filesystem
    alias: fs
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - /srv/data
    env:
      FS_STATE_DIR: ${HOME}/.cache/fs-mcp
    timeout: 30s
    include:
      tools:
        - ^read_
    exclude:
      tools:
        - ^read_media_

  - name: docs
    url: https://mcp.example.net/mcp
    headers:
      Authorization: Bearer ${DOCS_TOKEN}
    timeout: 15s

Every field is described in the configuration reference.

Two entries sharing a name is an error when the file is parsed, and so is two entries whose effective alias is the same, since that alias prefixes every tool they both expose.

Naming

Every imported tool is named <alias>_<tool>, always, where the alias defaults to the server name. remote_tools prefixes only on a clash. MCP servers use short generic tool names such as search and read, where a clash is the common case, and a name derived only from its own server does not move when another server’s tool list does.

A collision against a local tool, a remote tool or another server’s is still possible. At the start of a run it fails the run, naming the tools that collided. fisk info reports it and carries on. A tool arriving while a run is under way whose name is taken is left out and reported, and the run continues.

Variable references

env, headers and url values hold any number of ${VAR} references, each replaced by the value of that environment variable, so a credential lives in the variable rather than in the file. A value mixes literal text with references freely, as in Bearer ${DOCS_TOKEN} and ${HOME}/cache. A $NAME without braces is literal text and references nothing. command and args are literal throughout.

References resolve when a session connects, not when the file is parsed. Parsing checks their syntax and reads no variable, so a host holding none of the credentials still runs fisk info and fisk mcp against the file. A variable that is not set fails the connect, naming the variable and the server.

Some services authenticate in the endpoint rather than in a header, by query parameter as in https://mcp.example.net/mcp/?apiKey=${DOCS_TOKEN}, or by a path segment as in https://mcp.zapier.com/api/mcp/s/${ZAPIER_KEY}/mcp. url takes references for that reason.

What is printed

Whatever a url’s references resolved to is replaced by REDACTED wherever it appears in an error or warning about that server, the endpoint an SDK or HTTP error quotes included, as long as the resolved value is at least eight characters. A shorter one is never searched for, since replacing a string that short would blank the digits and words it matches all through an unrelated message. Every endpoint printed anywhere is also redacted on its structure: the userinfo before the host, the value of every query parameter, and the fragment. The scheme, host, port, path and parameter names stay, so an operator recognizes the entry from their own file, and a reference is shown as written so it names the variable rather than its value.

A stdio entry prints its command line, and each argument goes through the same URL redaction, so an npx -y mcp-remote https://host/sse?key=... bridge does not print its key.

Timeouts

timeout covers everything that happens for one server before the run starts, and it is applied twice: once around starting or reaching the server and the initialize handshake, and again around listing its tools. An entry that is slow at both steps takes up to twice the configured value, 60s at the default, before the run gives up on it. Unset it defaults to 30s.

Servers are connected one after another and listed one after another, so an entry that answers slowly or not at all delays every entry behind it by up to its own timeout. The timeout keeps that delay finite rather than preventing it: three entries that answer the handshake and then never return a tool list hold the run for 90 seconds at the default before it is refused.

A call to an imported tool is limited by harness.tool_timeout, like every other tool.

Trust posture

An imported MCP tool is never confirm-gated. ai:confirm and harness.confirm_tags reach the wrapped application’s commands, and the server applies no gate on its side either, so a call the model makes to an imported tool runs unapproved at both ends. include and exclude are therefore the only control an operator has over what a third party’s server can do in a run.

An imported MCP tool is never served on. Neither fisk mcp nor the a2a tool endpoint advertises one to its own clients, whatever expose.agent.tools selects: serving it would re-advertise a third party’s tool under this agent’s identity, and a client cannot tell which of the tools it is offered came from where.

A stdio server is a program of someone else’s choosing running as the operator’s user. It gets this process’s environment with the credential variables removed, the same scrub a command tool’s subprocess gets, and the entry’s env applied on top.

Failures and a moving tool set

A server that cannot be started, reached or listed fails the run, since the prompt may depend on tools that are not there. A tool the run cannot use, one with no description or a schema whose root is not an object, is skipped with a reason and the run continues on the rest.

A server can tell a live session that its tool list changed. The run re-lists that server, applies the entry’s filters and names the survivors, and the model sees the new set on its next call. A tool batch already dispatched runs against the set it was dispatched with, and no other server’s tools move.

Seeing what a server offers

fisk info connects every configured server and prints an MCP clients section: where each is reached and over which transport, how long it took to answer, how many tools it advertised, how many the filters kept, the name each was imported under, and any tool left out with the reason. Discovery there is best-effort, so a server that is down is reported rather than failing the command. Its imported tools appear in the tool table with the alias in the Source column.

fisk serve connects the configured servers once at startup and shares those sessions across every run it hosts, so a long-lived worker is not starting and stopping a stdio child around each job. A server that cannot be reached stops the worker from starting, and the startup banner names the servers every hosted run imports from. Those runs share the server’s working directory, its authentication and its rate limits.

Human in the loop

When enabled, fisk gives the model built-in tools to ask the operator a question at the terminal and wait for the answer. They are off by default and only available when running the agent:

harness:
  human_in_the_loop:
    enabled: true

Enabling it offers these tools:

• ask_human_confirm - a yes/no question. Returns {"confirmed": true} or {"confirmed": false}
• ask_human_select - choose one of a list of options the model provides. Returns {"selected": "<option>"}, or {"selected": null} if no choice was made
• ask_human_input - a free-text value, optionally pre-filled with a default the operator can accept or edit. Returns {"value": "<text>"}, or {"value": null} if none was given

Optional communication from the agent

The model decides when to call the HITL tools, shaped through the prompt. They suit decisions the model should not make alone: confirming a destructive action, choosing between options that depend on operator intent, or supplying a value it cannot derive. The question is rendered on the terminal (stderr, so a piped final answer stays clean), and the model-supplied text is stripped of terminal control sequences first so it cannot spoof what is shown. Each tool denies by default: with no terminal attached the call returns a negative answer (no confirmation, no selection, no value) and a reason rather than hanging on a prompt no one can answer, and they are never exposed over MCP, where there is no operator. Tool calls within a turn run one at a time, so a prompt has the terminal to itself.

If you interrupt a question, or close the input, fisk does not treat that as a reply. The run stops there and the conversation is kept, and when you continue it the same question is asked again. No answer is recorded, so a run you interrupt never carries a decision you did not make.

Required tool use confirmations

These mechanisms put a human in the loop:

• human_in_the_loop (a configuration flag) lets the model ask its own question through a fisk-provided ask_human_* tool, with no application command involved. The human answers a question the model chose to ask.
• ai:confirm (a command tag) lets the application author gate an ordinary, non-interactive command so the operator must approve it before it runs. The human is a checkpoint on a command the model wanted to run anyway; nothing about the command itself changes.

Reach for human_in_the_loop when the model should decide when to check in; reach for ai:confirm when a normal command should run only with the operator’s say-so, typically something destructive or irreversible. Command tags covers the tag in full.

Memory

Memory gives the model a small key/value store that persists across runs, so it can keep durable notes (a layout it worked out, a convention, the outcome of an investigation) and pick them up next time rather than rediscovering them. It is opt-in and agent-mode only; like the human-in-the-loop tools it is never exposed over MCP.

Enable it under harness.memory. The backend field selects where memories are kept; it defaults to file, so the minimal configuration is just:

harness:
  memory:
    enabled: true

When enabled the model is offered four tools: memory_list (keys and their descriptions), memory_read (one memory by key), memory_write (save a memory with a key, a one-line description, and a body), and memory_delete. A key uses letters, digits and ., _, = or - (no slashes or spaces), which keeps it valid both as a filename and as a NATS KV key. memory_write creates by default and refuses to overwrite an existing key unless called with overwrite: true, so the model does not silently clobber a note; the create still fails cleanly if two writers race for the same new key.

read_only: true serves memory_list and memory_read and withholds the other two, for a run that should use what earlier runs saved without changing it. The store itself is unaffected, so anything else writing to it still does.

At the start of a run the stored keys and descriptions are injected into the system prompt as an index so the model knows what it has saved; memory_list is the live view during the run. Turn the index off with no_index: true.

A memory body is capped at 64 KB and a store holds at most 1024 entries. Both limits are shared by every backend, and a write that would exceed them fails cleanly. The on-disk format is shared too, so a value written by one backend migrates to another unchanged.

fisk info shows a Memory section with the resolved backend and, for the jetstream backend, the bucket, NATS context and key prefix, so you can confirm where memory is stored without starting a run.

Two backends ship today: file (the default) and jetstream Version0.0.3.

File backend

The file backend keeps each memory as a markdown file named for its key under the configured directory, which defaults to memory/<identity>.

harness:
  memory:
    enabled: true
    backend: file
    options:
      directory: memory

A relative directory, including that default, resolves under the store base when a deployment sets one and against the working directory otherwise; an absolute directory is used as-is. The identity is the agent’s name, set with the identity configuration field and defaulting to the application binary’s base name; the configuration reference covers it in detail. Point two agents at the same directory and they share a memory; leave the default and each agent keeps its own.

JetStream backend

The jetstream backend keeps memories in a NATS JetStream KV bucket instead of on disk, so a fleet of agents can share durable memory over a broker. It uses the connection from the configured nats_context, the same one remote tools use, and binds to a bucket that must already exist: the agent never creates it, so you own the bucket’s durability policy.

nats_context: production

harness:
  memory:
    enabled: true
    backend: jetstream
    options:
      bucket: agent-memory

Create the bucket first, without a TTL so memories do not silently expire and with a max value size that fits a full entry (the 64 KB body cap plus the small frontmatter header stored with it), up to 1024 entries:

nats --context production kv add agent-memory --history=1 --max-value-size=69600

The backend fails at run start, rather than degrading silently, if the bucket does not exist, has a TTL set, or caps values below that full-entry size.

By default each agent’s keys are namespaced under a prefix equal to its identity (stored as <identity>.<key>), mirroring the file backend’s per-identity directory so two agents pointed at one bucket do not collide. Set options.prefix to a shared value for agents that deliberately share memory, or to "" for a flat, unprefixed keyspace:

harness:
  memory:
    enabled: true
    backend: jetstream
    options:
      bucket: agent-memory
      prefix: fleet-shared   # agents with the same prefix share memory; "" is flat

Read-before-update

The jetstream backend adds a safety guard the file backend cannot: an overwrite must follow a read of the current value, and is refused if the memory was not read or has changed since it was read. The model then reads the current value and retries. This is the same read-before-edit discipline that keeps an editor from clobbering a file it has not seen.

The read counts for the whole conversation rather than one turn. A memory read on Monday and edited on Friday in the same conversation is overwritten without a fresh read, as long as nothing else wrote to it in between; if something did, the write is refused and the model reads again before retrying. One conversation’s reads never authorize another’s overwrite.

The check uses the KV entry’s revision, which makes it an atomic compare-and-swap: when two agents share a bucket and both try to update the same memory, the second write is rejected rather than silently overwriting the first. The file backend’s last-writer-wins overwrite would quietly drop that change, so a shared or concurrent deployment wants this backend.

The guard is on by default. Set no_require_read_before_update: true to allow blind overwrites, matching the file backend’s behavior:

harness:
  memory:
    enabled: true
    backend: jetstream
    options:
      bucket: agent-memory
      no_require_read_before_update: true

We can use memory to ensure our agent never repeats jokes; change thesystem_prompt as follows:

harness:
  memory:
    enabled: true

system_prompt: |
  Tell short jokes using Cows!

  You have tools that can render a cow saying short sentences, when asked 
  use the tools to tell funny jokes.
  
  You tell cow jokes, no other kinds of jokes, strictly jokes about cows. 
  If asked to tell non cow jokes, refuse and show no joke.

  Do not use emoji, keep general narration short, just stick to the jokes

  Save the jokes you told to a single memory file with all the past jokes 
  and make sure you dont repeat jokes you previously told.

  Finish your turn by making a funny quip related to the joke or cows or similar

We will get a new joke every time - be ready to get some awful jokes after a while :)

Safety

When Fisk AI runs a command in a CLI tool it passes a slice of arguments to the exec system call. No shell is involved that can be escaped or influenced.

App Builder is often involved and calls shell scripts, so App Builder commands need to be written defensively.

• Use type hints on arguments for ints, floats and so on
• Use is_shellsafe(value) on string input arguments
• Use escaping when passing arguments to commands, for example {{ .Arguments.message | escape }}
• Tag commands with the various helper tags so the harness understands the intent
• Mark every mandatory argument as required

Fisk AI has no tools that can interact with arbitrary files on the system. The only way it interacts with the system is through the supplied tools or the Memory feature.

Every command the agent runs gets the same protections:

• Its output combines stdout and stderr, preserving order, and is capped at 64 KiB so a chatty command cannot flood the model’s context
• The ANTHROPIC_API_KEY is stripped from its environment, so a tool can never read the agent’s own credentials
• LLMFORMAT=1 is set, signalling fisk applications to render output suited to an LLM rather than a terminal

Local LLMs

Local LLM hosting tools like ollama, LM Studio and others support exposing an Anthropic-compatible API. Fisk AI can communicate with those tools.

To support a large number of tools, Fisk AI uses the Tool Search Tool, which these local runners do not support. When targeting a locally hosted model, the total tool count may need to stay around 15.

I set these environment variables before invoking fisk to access my local Anthropic API instead of reaching to the internet.

$ export ANTHROPIC_BASE_URL=http://localhost:1234
$ export ANTHROPIC_API_KEY=lmstudio

The base_url is validated only as a well-formed http or https URL naming a host, with no embedded userinfo credentials. Plain http is accepted for any host, since a local runner, a host gateway and a service on a private network all serve over it.

Serving

The fisk serve command hosts an agent behind the endpoints its configuration enables. It runs until interrupted. The agent is the one fisk run drives: tool set, prompt, model and harness settings come from the same configuration file.

Queued jobs takes each job off a work queue, runs it, and stores the answer for the submitter to read later. Answering prompts takes a prompt from another agent and streams the run back while that agent waits. Serving tools runs one tool for another agent and starts no agent loop.

Starting a worker

A minimal configuration has the application path, the tool selection and one channel. Here that channel is queued jobs:

identity: worker
application_path: /usr/local/bin/nats
nats_context: production
system_prompt: |
  You inspect NATS servers on behalf of an operator. Answer concisely.
include:
  tools:
    - ^stream_
expose:
  agent:
    jobs: {}

$ fisk serve --config nats.yaml

The startup banner lists the endpoints it started and the settings every run uses:

Serving worker/1.2.0:

         Endpoints: asyncjobs/FISK_AI
             Model: claude-sonnet-5
     Queue Context: production
          Sessions: jetstream (FISK_SESSIONS)
         Knowledge: disabled
         Telemetry: disabled
    Tool Directory: /var/lib/fisk-ai
      Tool Timeout: 5m0s
     Queue Workers: 1 (config)

The banner adds an Agent Context line when the agent’s nats_context differs from the queue’s.

Each endpoint prints its own section below. It shows the addresses that endpoint answers on and the limits it uses. Answering prompts and serving tools show examples.

Shared resources

fisk serve builds the model provider, the session store, the memory store, the knowledge index and the NATS connection once at startup. Every run shares them. A missing stream or bucket fails the process immediately instead of failing whatever job happens to arrive first.

When the knowledge index does not exist at startup, each run opens the index for itself, so an index built after the worker started is visible to later runs.

Concurrency

Each channel limits its own runs, so a process serving two channels at two runs each is running four.

--workers sets how many queued jobs run at once, overriding expose.agent.jobs.workers:

$ fisk serve --config nats.yaml --workers 4

--workers affects the queued-jobs channel only. The prompts channel takes its count from expose.agent.a2a.prompts.workers and refuses a caller when every slot is busy.

A work queue has a concurrency setting of its own that limits every worker on it together. Setting workers above what the queue allows leaves slots idle rather than raising throughput.

Timeouts

harness.tool_timeout limits a single tool call, in fisk serve and fisk run alike. The default is five minutes. 0s removes the limit, for commands that run for hours.

The timeout stops a command and its process group. It does not stop an in-process handler that ignores its context.

Where tools run

Command tools run in the worker’s own working directory unless --work-dir names another. It must be an absolute path that already exists.

Every run shares it. Set the worker count to 1 when a tool writes local state that concurrent runs would corrupt.

Shutdown

On the first interrupt the worker drains. It takes no new work, and runs in flight continue to their next resumable point:

draining: no new work is taken and running work stops where it can resume. Interrupt again to stop now

A second interrupt stops the worker at once. The queue redelivers any queued job still running, and the redelivery resumes from the journal. The prompts channel answers its callers with a failure instead.

A drain stops every endpoint, so a worker also serving tools stops answering peers at the same point. A worker with no channel has nothing to resume:

draining: the endpoints stop answering. Interrupt again to stop now

Sessions

Each channel journals its runs, so an interrupted run resumes instead of making the same model calls a second time.

Sessions need a store every worker can read. On one machine the default file backend is enough. Across machines, configure a shared harness.sessions backend. Without one, a job redelivered to a different worker cannot read the journal and starts again.

When two workers reach the same journal, the second one claims it. The claim is written before the run starts, and the first worker sees it before its next tool call and stops. Only a tool already running can execute twice.

Settings a channel run ignores

The following settings narrow the MCP and a2a tool endpoints, not a run served over a channel:

• expose.agent.tools selects what is served over MCP and a2a. A channel runs the whole agent loop, so it uses the agent’s own include and exclude instead
• the waiver that lets a tool-serving configuration omit identity, system_prompt and llm.model does not apply to a channel, since a run needs all three

Safety

A served run is a full agent loop driven by caller-supplied prompt text, running every tool the configuration allows. The channel’s own admission check is therefore the only access control: queue publish permission for queued jobs, NATS publish permission for prompts.

harness.tool_timeout limits each tool call and llm.budget limits the run. A caller may lower the budget, never raise it. The tool safety rules described in the Reference hold here as everywhere else: commands run as an argument vector rather than through a shell, each argument is checked against the command’s schema, and credentials are stripped from tool environments.

Queued jobs

The queued-jobs channel takes whole units of work off a Choria asyncjobs work queue, runs the agent loop against each one, and stores the answer back on the task. The submitter holds no connection to the worker: it enqueues a task, and reads the answer off the task record once a worker has written it.

Creating the storage

A worker requires its storage to exist. Create it with ajc, version 0.4.0 or newer.

The task store holds every job and the answer written back to it:

$ ajc tasks initialize

The work queue holds the jobs waiting to be taken:

$ ajc queue add FISK_AI --run-time 10m --tries 3 --concurrent 10

Run time, retry cap and concurrency are properties of the queue, not of the agent configuration. The worker reads them from the consumer at startup and prints them on the banner. The run time must be longer than a job takes, or the queue redelivers work that is still running.

A worker started before either exists fails:

fisk: error: building the jobs endpoint: connecting to queue "FISK_AI": storage not ready: stream CHORIA_AJ_TASKS does not exist, create it with 'ajc tasks initialize'

Submitting work

A caller enqueues a task with the queue engine’s own client. The task must name the configured queue and task type, and its payload is a v1 prompt request:

A queue has nobody waiting on it, so the three other kinds of request are refused here: they act on a conversation somebody is watching.

The request holds the prompt and the framing every v1 message needs:

{
  "protocol": "io.choria.fisk-ai.v1.request.prompt",
  "id": "2fT8kMxQ1aBcDeFgHiJkLmNoPqR",
  "request": "2fT8kMxQ1aBcDeFgHiJkLmNoPqR",
  "conversation": "2fT8kMxQ1aBcDeFgHiJkLmNoPqR",
  "sequence": 0,
  "time": "2026-08-15T11:30:00Z",
  "sender": {
    "name": "ops-console"
  },
  "prompt": "Which streams have no consumers?"
}

On a request, id, request and conversation all hold the same value. sender.name is limited to letters, digits, - and _.

$ ajc tasks add fisk-ai:run --payload-file request.json --queue FISK_AI
Enqueued task 3Hwxl119ZbwKHCKPzWlslXZYnB0

The submitter supplies the task id, or the engine mints one. The worker hashes it with the serving identity to get the session the run journals under, so a job creates a session or resumes one an earlier delivery of the same task made, and reaches nothing else on the worker. Every id the queue accepts works, a leading dash and a colon included.

Optional fields narrow what one job may do:

A budget may only lower what the configuration allows. A value above the configured limit is ignored.

The worker refuses a payload it cannot run and does not retry it, recording the reason in the task’s LastErr. This covers:

• an oversized payload
• a payload that is not a valid v1 request
• a payload that is not an io.choria.fisk-ai.v1.request.prompt, or whose prompt is empty

Reading the answer

The answer is stored on the task itself as a v1 result message:

$ ajc tasks view 3Hwxl119ZbwKHCKPzWlslXZYnB0 --json

{
  "protocol": "io.choria.fisk-ai.v1.result",
  "request": "2fT8kMxQ1aBcDeFgHiJkLmNoPqR",
  "sender": {
    "name": "worker"
  },
  "recipient": {
    "name": "ops-console"
  },
  "stop_reason": "end_turn",
  "text": "ORDERS and PAYMENTS have no consumers.",
  "usage": {
    "input_tokens": 1608,
    "cache_read_tokens": 663,
    "output_tokens": 51,
    "llm_calls": 2,
    "tool_calls": 1
  }
}

The request field echoes the id the caller submitted, and recipient names the caller that asked. input_tokens counts every input token the job consumed. cache_read_tokens and cache_create_tokens are subsets of that total, not additions to it.

A failed run is still a completed job. The worker stores a v1 error message with a stop_reason and acknowledges the task. It is not retried: a model refusal or an exhausted budget fails the same way on redelivery.

Where the failure is one a caller can act on, the stored error also carries a code beside its stop_reason. It is the same vocabulary Answering prompts sends on a terminal message, and these are the ones a job reaches:

A job whose session journal another writer holds reaches none of these: the run ends with no outcome, so the worker returns the job to the queue and stores no answer at all, and the redelivery runs it.

An error with no code is a failure this vocabulary does not name, and the message text is what says how it failed.

Redelivery

The worker journals every run under the session its task id derives. When a worker dies mid-job, the redelivery derives the same session and resumes that journal instead of starting again.

A job whose session already completed is answered from the journal, without running the agent or calling the model. This is the case when a worker finished a job and died before acknowledging the task.

Configuration

Every field under expose.agent.jobs has a default, so an empty block is valid.

expose:
  agent:
    jobs:
      # The work queue to consume. It must already exist.
      queue: FISK_AI
      # The task type this worker handles. Tasks of another type on the
      # same queue are left alone.
      task_type: fisk-ai:run
      # How many jobs this process runs at once. The --workers flag
      # overrides it.
      workers: 1
      # The NATS context the queue is reached over, defaulting to the
      # top-level nats_context. It is dialed separately, so the queue may
      # live on a different cluster from the session store.
      nats_context: production
      # Bounds a task payload in bytes before anything decodes it.
      max_payload: 524288

A worker only claims tasks of its configured task_type. Submit a different type and the task stays in the queue until it expires, with no error logged at either end.

Safety

Publish permission on the queue is the only access control. Anyone who can enqueue a task of the configured type runs the full agent loop with prompt text of their choosing, against every tool the configuration allows. Restrict publish permission on the queue’s subjects the way any other NATS resource is restricted.

The rest of what applies to any served run is covered in Serving.

Slack

The Slack channel hosts the agent behind a Slack bot. Somebody mentions the bot, a thread opens, and that thread is one conversation for as long as people keep mentioning the bot in it. A question the agent asks is posted as a message with buttons, and it may be answered days later.

The connection is Slack’s socket mode, so the worker listens on no address and needs no public URL.

Creating the Slack app

Create an app at api.slack.com/apps from this manifest:

display_information:
  name: Fisk AI
features:
  bot_user:
    display_name: fisk-ai
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - channels:history
      - chat:write
      - groups:history
      - users:read
settings:
  event_subscriptions:
    bot_events:
      - app_mention
  interactivity:
    is_enabled: true
  socket_mode_enabled: true

Socket mode is the transport the channel connects over. app_mention is the only event it subscribes to. Interactivity carries the button presses and the answers typed into a question back, so without it an answer to a question never reaches the worker.

The credentials come out of the app:

Neither appears in the configuration file. A missing one fails at startup naming the variable, and a token Slack refuses fails there too: the worker calls auth.test before it accepts anything.

Invite the bot to a channel with /invite @fisk-ai, then mention it.

Starting a worker

identity: helper
application_path: /usr/local/bin/nats
system_prompt: |
  You inspect NATS servers for the people in this Slack workspace. Answer concisely.
include:
  tools:
    - ^stream_
expose:
  agent:
    slack: {}

$ export SLACK_APP_TOKEN=xapp-...
$ export SLACK_BOT_TOKEN=xoxb-...
$ fisk serve --config slack.yaml

Serving helper/1.2.0:

         Endpoints: slack
             Model: claude-sonnet-5
          Sessions: file
         Knowledge: disabled
         Telemetry: disabled
    Tool Directory: /var/lib/fisk-ai
      Tool Timeout: 5m0s

A Slack turn runs the whole agent loop, so identity, system_prompt and llm.model are all required. The waiver that lets a tool-serving configuration omit them does not apply.

What a thread shows

A mention starts a turn, and that turn posts a status message it edits while the run works: :thinking_face: Thinking..., :hammer: Calling tools..., :books: Searching knowledge.... The message names a family of tools rather than the tool being run, because everybody in the channel reads the thread.

Each line opens with an emoji, so a thread scrolled past shows which turns worked and which did not before anybody reads the words:

The emoji is part of the line, so the notification a phone shows carries it too.

The status message carries a Stop button while the turn is running, and anyone in the thread may press it. The bot finishes the step it is on and stops there. Everything the thread has said is kept, so mentioning the bot again carries on from that point rather than starting the conversation over.

The answer is posted as a message of its own, and the status message becomes a link to it. Slack sends no notification for an edit, so a turn that answered by editing its own status message would have pinged somebody with Thinking... and told them nothing.

The answer goes out as markdown for Slack to render. The channel cuts it at 12,000 bytes and ends it with a note where it did not fit. Everything else the channel says is plain text it wrote itself.

no_progress turns the status message off. The answer, the questions and the refusals are posted either way, and the Stop button goes with the status message.

Who is speaking

Every line the model reads is prefixed with the speaker, as their name and the markup that addresses them:

Ana Silva <@U024BE7LH>: the deploy went out at four
Ben Cole <@U0LM3D6TP>: and disk climbed right after

The name comes from the profile: the real name, then the display name, then the handle. It falls back to the user id under all three, and to the id alone where users:read was not granted, which the worker logs as a warning the first time it resolves each person.

The markup is what notifies somebody. Slack sends a notification for <@U024BE7LH> and none for a name written out, so an answer that addresses people by name reaches nobody’s phone. The bot does not use it unless you say so, which is a line in system_prompt:

system_prompt: |
  You inspect NATS servers for the people in this Slack workspace. Answer concisely.

  Each line of the conversation is prefixed with the speaker's name and their Slack id, as
  "Ana Silva <@U024BE7LH>". When you address someone, write that <@...> markup rather than
  their name, so they are notified.

Questions

A tool that needs a person asks in the thread, as a message of its own. It opens by mentioning whoever started the turn, so they are notified, and anybody in the thread may answer whether or not they asked the question.

The first three carry Dismiss beside them, which answers the tool that a person was reached and gave no answer. The gate’s Decline is its dismissal: the gated command not running is the whole of what declining a gate can mean.

A selection puts the options in the message rather than on the buttons because a button label is cut at 75 characters, where the message holds 3000. Twenty-five options share those characters, so a long option is cut to its share of them and every option is on the list.

Nothing expires. The question stays in the thread until somebody answers it, and the bot carries on from that answer whenever it arrives: a minute later, on Thursday, or after the worker has been restarted in between. The status message reads :question: Waiting for your answer. in the meantime, and the question message records who answered and what they chose.

answer_grace is how long the bot stays on that thread before it goes back to answering other people. It changes nothing about how long an answer is accepted for.

The worker never sees a plain reply in the thread. Only app_mention is subscribed, so words typed under a question reach it through the question’s own field or through a mention and no other way, and every question message says so. A mention answers a free-text question; while any other kind is open the channel refuses the mention with a link to the question.

How a turn ends

The status message says what became of the turn:

The budget and the step cap read as parked rather than as faults, since both lines tell the person where to carry on. A run that finished with nothing to say reads as answered, the run having finished.

No ending names a session, a tool call or a Go error. The worker log has all three, and a thread is read by everybody in the channel.

Where something went wrong on the way to the answer, such as a tool that ran out of time or a memory index the bot could not read, one message under the answer says so in a sentence. It names the kind of problem and nothing a tool returned.

Capacity

workers turns run at once. A mention that arrives with no slot free shows Queued... until one frees. Once max_waiting threads are already waiting, the next mention gets a short reply asking the person to come back in a few minutes, which is better than watching a queued message for three of them.

Three lines typed in ten seconds are one thought, so further mentions from the same person reach the bot as one follow-up turn, up to max_coalesced messages. A mention from somebody else gets a turn of its own behind that one, with its own status message and its own answer.

A turn that ended waiting on a question, or that somebody stopped, cannot take those extra lines. The thread gets them back as I did not get to: ..., so the person can see which of their messages went unanswered and send them again.

Shutdown and faults

A drain stops the channel taking mentions. A thread whose turn was still waiting is told the turn will not run, and a turn already going stops where the next mention can carry it on and says so on its status message. The connection closes last, so a turn still finishing keeps receiving stop presses and answers to its questions.

The socket mode client reconnects on its own, so a dropped connection is logged and waited out. A revoked or invalid token is a fault: fisk serve drains and exits non-zero, and a supervisor restarts the worker.

One worker per bot token

Run one fisk serve per bot token. Slack allows an app up to ten socket connections and spreads envelopes across them, which this channel cannot use: the threads it is running and the questions it is holding are in process memory, so a button press delivered to a process that holds neither reaches nothing.

A press that lands on a worker with no record of the question still works, because the interaction is self-describing and the session derives from the thread. Everything else, from a Stop press to a mention folded into a running turn, needs the process that holds the turn.

Sessions

The session is a hash of the serving identity, the team, the channel and the thread, so two agents in one workspace keep their conversations apart and one agent keeps two threads apart.

A thread is a conversation, so the channel needs a session store it can read: fisk serve refuses to start the Slack channel without one. Threads outlive workers, so a deployment across machines wants a shared harness.sessions backend rather than the default file store.

Configuration

Every field under expose.agent.slack has a default, so an empty block is valid.

expose:
  agent:
    slack:
      # Turns this process runs at once. --workers does not reach it.
      workers: 5
      # Messages of surrounding conversation a turn reads.
      context_lines: 20
      # Turns off the status message, and the Stop button with it.
      no_progress: false
      # How long a question is held before the run defers.
      answer_grace: 30s
      # Admitted turns waiting for a worker before a mention is refused.
      max_waiting: 10
      # Messages folded into one follow-up turn.
      max_coalesced: 5

workers defaults to 5 where the other channels default to 1. A thread is a person waiting, and with one worker the second person to ask anything watches a queued message until the first person’s run finishes.

--workers sizes the queued-jobs intake and does not reach this channel. context_lines covers both reads a turn makes: the conversation around a mention that opens a thread, and what was said in a thread since the bot last replied.

Safety

Channel membership is the whole of the access control. Anybody who can see a channel the bot is in can run the full agent loop against every tool the configuration allows, and can answer any question the agent asks there. Whoever can invite the app decides who reaches the tools.

Every run records its caller as the Slack username and user id, and nothing consults that record for a decision.

The rest of what applies to any served run is covered in Serving.

Serving tools

The a2a endpoint exposes the wrapped application’s commands to other agents over NATS as callable tools. A peer reads the agent’s card and invokes one of them. No prompt is sent and the agent loop does not run, so the model, budget and session settings do not apply.

Serving a set of tools

identity: nats-tools
application_path: /usr/local/bin/nats
nats_context: production
include:
  tools:
    - ^stream_
expose:
  agent:
    a2a:
      serve_tools: true

A worker serving only tools needs no system_prompt and no llm.model. It does need application_path: built-in tools are never served, so an agent with no wrapped application serves nothing.

$ fisk serve --config tools.yaml

Serving nats-tools/1.2.0:

        Endpoints: a2a
    Agent Context: production
        Telemetry: disabled

  Serving tools over a2a:

          Discovery: choria.fisk-ai.discovery.nats-tools
              Tools: choria.fisk-ai.tool.nats-tools
        Concurrency: 4
       Tool Timeout: 30s
            Exposed: stream_add
                     stream_ls
                     stream_info

Reading the card

fisk discover fetches the card the worker answers discovery with:

$ fisk discover nats-tools --config peer.yaml

Agent Card for nats-tools:

        Agent: nats-tools
      Version: 1.2.0
    Protocols: io.choria.fisk-ai.v1

Importing those tools into another agent is remote_tools in that agent’s configuration, covered in the Reference.

Tool selection

expose.agent.tools applies on top of the agent’s include and exclude. One file can run every stream_ tool in a job and serve two of them to peers.

A tool carrying ai:confirm or a configured confirm tag is left off the card, because no operator is behind a served call to approve it. Use ai:deny to keep a command out entirely.

Built-in tools are never served. Knowledge, memory and the human-in-the-loop tools declare no a2a exposure, and the startup banner lists them as withheld when the configuration enables them.

Limits

expose:
  agent:
    a2a:
      serve_tools: true
      max_concurrent_tools: 4
      tool_timeout: 30s
      request_timeout: 120s

In a container the concurrency default reads the container’s CPU limit, not the host’s, and the banner prints the concurrency in use. --workers sizes the queued-jobs intake and does not reach these. harness.tool_timeout limits a tool call inside the agent loop.

request_timeout limits a call this agent makes to a peer. The peer answers with a set of messages: an acknowledgement, a keepalive every ten seconds while the tool runs, then the reply. The timeout applies to the gap between those messages, so this agent waits for as long as the keepalives arrive, and harness.tool_timeout ends the call. A card fetch is a single message, so the same value covers a whole card fetch.

The same value is how long the prompts endpoint holds a question it put to a caller, see Answering questions. Raising it for a slow peer raises that window too.

An agent that only calls other agents still needs request_timeout, so a block holding nothing else is valid:

expose:
  agent:
    a2a:
      request_timeout: 30s

Any other expose.agent.a2a block must set serve_tools: true or a prompts block, or fisk serve exits with an error.

The server refuses a call that arrives with every slot in use rather than queueing it. The ack carries accepted: false, and the tool.reply carries is_error: true with code: capacity. The identity is a NATS queue group, so a retry is delivered to whichever member is free next.

Running with other endpoints

A single fisk serve process runs a channel and this endpoint on one NATS connection:

Serving nats-worker/1.2.0:

         Endpoints: asyncjobs/FISK_AI
                    a2a
             Model: claude-sonnet-5
     Queue Context: production
          Sessions: file
         Knowledge: disabled
         Telemetry: disabled
    Tool Directory: /var/lib/fisk-ai
      Tool Timeout: 5m0s
     Queue Workers: 1 (config)

  Serving tools over a2a:

           Discovery: choria.fisk-ai.discovery.nats-worker
               Tools: choria.fisk-ai.tool.nats-worker
         Concurrency: 4
        Tool Timeout: 30s
             Exposed: stream_ls
                      stream_info

Adding a prompts block to the same a2a block also answers prompts, covered in Answering prompts.

Shutdown and faults

A drain stops the endpoint answering and removes the identity from its queue group, so the worker takes no further tool calls. Prompts stop with it, both endpoints using one transport and one identity.

A drain does not wait for a call that is already running. The call runs to completion with nowhere to reply to, and a command it started may outlive the worker. tool_timeout stops a call that does not finish.

An error on any of the service’s subscriptions stops the whole micro service, taking discovery, tools and prompts for that identity down together. fisk serve logs it, drains the runs in flight and exits non-zero, so a supervisor restarts the worker. A drain stops the service by the same path, and is logged rather than reported as a fault.

Safety

Whoever can publish to choria.fisk-ai.tool.<identity> can run every tool on the card. NATS permissions are the whole of the access control: a served call carries no verified caller, so nothing can distinguish one peer from another.

The tool safety rules described in the Reference hold here as everywhere else: commands run as an argument vector rather than through a shell, each argument is checked against the command’s schema, and credentials are stripped from tool environments.

Answering prompts

The prompts channel takes a prompt from another agent over NATS and runs the agent loop over it. The caller waits and receives an acknowledgement, then the events the run produces, then the answer or the failure.

Configuration

identity: nats-worker
application_path: /usr/local/bin/nats
nats_context: production
system_prompt: |
  You operate NATS. Answer with what you did and what you found.
llm:
  model: claude-sonnet-5
include:
  tools:
    - ^stream_
expose:
  agent:
    a2a:
      serve_tools: true
      tool_timeout: 60s
      prompts:
        workers: 2

Answering a prompt runs the whole agent loop, so the configuration needs identity, system_prompt, llm.model and nats_context. application_path is optional: an agent with only built-in tools, or with none, still answers prompts.

identity must be one you wrote. It is the subject peers reach this worker on and the queue group it joins, so a name taken from the application binary or left at the default would put unrelated agents into one group, sharing each other’s work.

$ fisk serve --config prompts.yaml

Serving nats-worker/1.2.0:

         Endpoints: a2a/prompts
                    a2a
             Model: claude-sonnet-5
     Agent Context: production
          Sessions: file
         Knowledge: disabled
         Telemetry: disabled
    Tool Directory: /var/lib/fisk-ai
      Tool Timeout: 5m0s

  Answering prompts over a2a:

            Requests: choria.fisk-ai.task.nats-worker
             Cancels: choria.fisk-ai.cancel.nats-worker.*
             Workers: 2
    Answering a prompt runs the agent loop and reaches every tool the top-level include and exclude selected.

  Serving tools over a2a:

           Discovery: choria.fisk-ai.discovery.nats-worker
               Tools: choria.fisk-ai.tool.nats-worker
         Concurrency: 4
        Tool Timeout: 1m0s
             Exposed: stream_ls
                      stream_info

workers is how many prompts the process answers at once. --workers does not change it; that flag applies to the queued-jobs channel.

Making requests

A caller publishes a request on choria.fisk-ai.task.<identity>:

{
  "protocol": "io.choria.fisk-ai.v1.request.prompt",
  "id": "3Hzmp2RBLG713TfOTU5aJpATRg2",
  "request": "docs1",
  "conversation": "docs1",
  "sequence": 0,
  "time": "2026-08-16T11:00:00Z",
  "sender": {"name": "peer1"},
  "prompt": "how many streams are there"
}

request names the turn. Every reply to it echoes the value, cancelling the turn addresses it by that value, and so does answering a question the run asks, so pick it before you send and keep it. It must name one turn and one only: two turns sharing a value make their replies indistinguishable, and a cancel aimed at one of them stops both. It is at most 64 characters of letters, digits, - and _, because a worker builds subjects from it.

id names the message rather than the turn, so it is fresh on every message including a resend, and conversation is the caller’s own tag across the turns of one conversation.

The queued-jobs channel takes a request.prompt as its payload and none of the other three.

request.answer is described in Answering after the run ended, and request.read in Reading a conversation.

context is supporting material offered alongside the prompt, stream: false asks for the answer without the event stream, and conversation_token joins an existing conversation, see Follow-up turns.

force is a caller’s decision about its own conversation. Without it a worker refuses a resume across a changed model, system prompt or tool set; with it the run continues under the current configuration and drops the standing approvals it can no longer vouch for.

A budget above the worker’s own configuration is ignored. On a conversation it limits the conversation rather than the turn, since a run measures the whole journal’s token count against it.

The reply set arrives on the request’s own inbox, in order:

The acknowledgement comes first, so a plain nats req receives it and stops there:

$ nats req choria.fisk-ai.task.nats-worker "$(cat request.json)"

{"protocol":"io.choria.fisk-ai.v1.ack","id":"3Hzmp3SCMH824UgPUV6bKqBUSh3","request":"docs1",
 "conversation":"docs1","sequence":1,"time":"2026-08-16T11:24:10.749134Z",
 "sender":{"name":"nats-worker"},"recipient":{"name":"peer1"},"accepted":true}

Every message of the set carries sequence, numbered from the acknowledgement without gaps, so a caller can tell a lost event from a quiet run. Events are advisory. The answer is in the terminal message, and the worker’s run journal is the authoritative transcript.

Event blocks

Each event holds one block. Where an id under io.choria.fisk-ai.v1.event. is one your client does not recognize, keep the message and render what you can rather than rejecting it: a newer worker sends kinds this one does not define.

A text event in full:

{"protocol":"io.choria.fisk-ai.v1.event.text","id":"3Hzmp8kRt1BqA4dQ2v9XnLcYm2T","request":"docs1",
 "conversation":"docs1","sequence":2,"time":"2026-08-16T11:24:11.104217Z",
 "sender":{"name":"nats-worker"},"block":{"text":"the stream is gone","final":true}}

final marks the answer. Only the run knows which message ended the turn, so without the flag a caller cannot tell the answer from the narration on the way to it, and would render it twice when the same text arrives again in the result.

A warning names its kind and gives you the values, not a finished sentence. Your client chooses the wording, and a client that does not recognize a kind can still display the fields.

A tool_call is not answered twice. A call the caller was asked to approve carries the same tool_use_id as the elicit.request.approve that asked, so a caller that drew the question knows it has already shown that call.

Not every call produces a result: a denied confirmation, a tool called without its required arguments, a tool that answers later and an aborted run each end without one, so a caller pairing the two tolerates a call that is never answered.

A status block reports progress, and its usage is what one model call consumed. The call that ends a turn sends no status of its own, so a caller keeping a running total takes the totals from the terminal message rather than summing these. The replay markers use the same block and are described below.

Refusals and endings

The worker refuses a request it cannot parse with a NATS service error, before any acknowledgement:

$ nats req choria.fisk-ai.task.nats-worker '{"protocol":"io.choria.fisk-ai.v1.request.resume","prompt":"...", ...}'

Nats-Service-Error: the request is not a valid v1 message: jsonschema validation failed with
'https://choria.io/schemas/io.choria.fisk-ai.v1/request.resume.json#'
  - at '/prompt': false schema
Nats-Service-Error-Code: 400

A resume takes no prompt. Send io.choria.fisk-ai.v1.request.prompt to run one.

Everything the worker refuses after that is an ack with accepted: false and a reason, followed by an error that closes the set. The error carries a code the caller can branch on:

The worker refuses at capacity rather than queueing the prompt. unknown_call, already_answered and answer_too_large are permanent: sending the same answer again reaches the same reply.

budget_exhausted ends the conversation, not just this request. The allowance belongs to the conversation, so every later turn is refused no matter who sends it. Your prompt did not run and was not recorded. To carry on, send a prompt with no conversation_token to start a new conversation. Only an operator on the machine running the agent can raise llm.budget.max_tokens.

You can also hit this straight away, on a conversation that answered a moment earlier, by lowering budget on your own request below what the conversation has already used.

Every error also has a stop_reason beside its code. budget_exhausted appears there when a run hit the cap part way through a turn instead of before it started.

A deferred run is waiting for a tool answer. The error lists the calls. Answer one on a request carrying the conversation token, or with fisk session on the worker holding the journal.

Canceling

A caller cancels by publishing an io.choria.fisk-ai.v1.cancel on choria.fisk-ai.cancel.<identity>.<request>, where request is the correlation id it sent. The request id is part of the subject, so only the worker running that prompt is subscribed to it. It answers with an ack.

A cancel asks the run to stop where the conversation can be continued. It does not end the run where it stands: the loop polls for it at each boundary and parks there, so the terminal message is suspended with the usage the turn spent, and the conversation takes another turn whenever the caller sends one. A run blocked on a question is included, since a cancel closes the question rather than leaving it asked with nobody to answer.

What that costs is the ability to stop a model call in flight. A run inside a tool that never returns reaches no boundary, and a cancel will not move it; that escape hatch belongs to whoever operates the worker. A caller asks and an operator compels.

Because the id is part of the subject, a caller mints it rather than being told it: set id and request on the request before sending, so the tag is in hand before there is anything to cancel.

A no-responder error means this instance is not running that request: it was never accepted, it already finished, or another instance took it.

Follow-up turns

A caller can send another turn of the same conversation. Every ack that accepts a prompt carries a conversation_token, and a later request carrying that token runs its prompt as the conversation’s next turn:

{"protocol":"io.choria.fisk-ai.v1.ack","id":"3Hzmp3SCMH824UgPUV6bKqBUSh3","request":"docs1",
 "conversation":"docs1","sequence":1,"time":"2026-08-16T11:24:10.749134Z",
 "sender":{"name":"nats-worker"},"recipient":{"name":"peer1"},"accepted":true,
 "conversation_token":"3Hzmp8VqrKL42NmXcPd7bTgWfR1"}

{
  "protocol": "io.choria.fisk-ai.v1.request.prompt",
  "id": "3Hzmq7WdPK628XjRVZ8cLmBUTh4",
  "request": "docs2",
  "conversation": "docs1",
  "sequence": 0,
  "time": "2026-08-16T11:26:00Z",
  "sender": {"name": "peer1"},
  "prompt": "what is the first one called",
  "conversation_token": "3Hzmp8VqrKL42NmXcPd7bTgWfR1"
}

A caller that asks once and stops ignores the token the worker handed it; one that wants another turn sends the token it already has. A follow-up opens a reply set of its own, with its own ack, events, cancel address and terminal message, so it is an ordinary request in every respect but which conversation it joins.

No worker holds a conversation between turns. Each turn loads the journal, runs, and stores the result, so any instance in the queue group serves any turn. That also means a caller sends one turn at a time: a second turn sent while the first is still running is refused with conversation_busy, and it must wait for the first turn’s terminal message rather than try another instance.

A conversation has no end state and no expiry: the journal stays in the session store until an operator removes it.

• A turn cannot join a conversation waiting on a deferred tool result. The worker answers turn_not_taken without running the prompt. With elicit set, a human-in-the-loop question the caller neither answers nor holds open within request_timeout leaves the conversation waiting on a deferred call. Answer the question and it takes turns again.
• A configuration change ends a conversation. Every turn is a resume, and the worker refuses a resume when the model, the system prompt, the thinking mode or the reasoning effort has changed since the conversation started. It answers failed and the caller starts a new conversation. A changed tool set does not end it: the turn runs, and the standing approvals the conversation held are dropped, since an approval names a tool and that tool may have moved under it.

The usage on a result counts the whole conversation rather than the turn, since it is read from the journal. An error that ran and stopped carries it too, so a caller can tell what it owes for a turn it is about to continue. Both also carry trace_id, the trace the worker recorded, which is empty when it exports no telemetry, and content_exported, which says whether this turn’s conversation itself reached that collector.

Asking what an agent is

Ask an agent what it is before you send it anything. Run fisk discover <identity> to make that request. Every agent that answers prompts also answers discovery, whether or not it serves tools as well. An agent that serves no tools to peers answers with a card that lists none.

Two fields on the card describe what the agent does with a conversation:

They are published because a caller should know before it sends a prompt, and they are read off the worker’s resolved telemetry provider rather than its configuration, so a rejected endpoint does not leave the card promising an export that will not happen. The card says what the agent is configured to do; content_exported on a terminal message says what a turn actually did.

Reading a conversation

To read a conversation back, send an io.choria.fisk-ai.v1.request.read with a conversation_token and a replay count. The worker sends that many blocks of the stored conversation and ends the reply set:

{
  "protocol": "io.choria.fisk-ai.v1.request.read",
  "id": "3Hzmr9YfRM839ZlTXb0eNoDVUj6",
  "request": "docs3",
  "conversation": "docs1",
  "sequence": 0,
  "time": "2026-08-16T11:30:00Z",
  "sender": {"name": "peer1"},
  "conversation_token": "3Hzmp8VqrKL42NmXcPd7bTgWfR1",
  "replay": 200
}

Use this to show a conversation your client did not see live, such as one started on another machine. A finished turn leaves a completed journal, and a plain resume will not continue one, so reading it is the only request such a conversation accepts until you send the next prompt.

You get back the same blocks the run sent the first time, between two status blocks:

• phase: "replay_start" opens the history.
• phase: "replay_end" closes it, with count blocks sent, truncated when older ones were left behind, and usage for what the conversation has consumed so far. That usage is the whole conversation rather than one call, which is what lets a caller seed a running total before this turn’s own calls arrive.

Set replay on each request that needs it. Leave it off a follow-up turn, which usually wants only the new blocks. The worker sends at most 200 blocks whatever you ask for, and rounds up to a whole turn so that a result never arrives without the call it answers. The largest useful value is therefore 200; ask for more and you get 200. A read asks for at least 1.

Some of what the journal holds never leaves the worker: thinking signatures, the fingerprint, the caller, the conversation token, the standing approvals, and the notes and handles of deferred calls. Long values are trimmed to fit a block.

io.choria.fisk-ai.v1.request.resume continues a run that stopped part way, which is what a caller sends after a suspended ending. Send it with the token and no replay.

Answering questions

A run puts a question back to the caller when it needs a person: an approval for a confirmation-gated command, or one of the three human-in-the-loop questions. A run asks only when elicit is set.

expose:
  agent:
    a2a:
      prompts:
        workers: 2
        elicit: true

The worker sends the question on the reply set, after the ack and before the result or error:

{
  "protocol": "io.choria.fisk-ai.v1.elicit.request.approve",
  "id": "3Hzq6PkmVLsT9WqrChXkgF7NLwy",
  "request": "docs1",
  "conversation": "docs1",
  "sequence": 4,
  "time": "2026-08-16T11:24:11.912084Z",
  "sender": {"name": "nats-worker"},
  "recipient": {"name": "peer1"},
  "question_id": "3Hzq7RvnWMtU0XstDiYlhG8OMxz",
  "tool_use_id": "toolu_01A9bK2mNpQr",
  "command": "stream rm",
  "display": "stream rm ORDERS --force",
  "tag": "ai:confirm",
  "wait_ms": 120000
}

Every question has question_id, and may have tool_use_id and wait_ms:

tag is absent when the gate could name no trigger, which is a command rewritten to a tool that has none.

The caller answers on choria.fisk-ai.elicit.<identity>.<request>, where request is the correlation id it sent:

$ nats req choria.fisk-ai.elicit.nats-worker.docs1 "$(cat answer.json)"

{
  "protocol": "io.choria.fisk-ai.v1.elicit.reply.approve",
  "id": "3Hzq8TwoXNuV1YtuEjZmiH9PNya",
  "request": "docs1",
  "conversation": "docs1",
  "sequence": 0,
  "time": "2026-08-16T11:24:19.310422Z",
  "sender": {"name": "peer1"},
  "question_id": "3Hzq7RvnWMtU0XstDiYlhG8OMxz",
  "choice": "once"
}

Reply under the id you were asked under, with request swapped for reply:

Send the field even when its value is the zero one. confirmed: false, index: 0 and value: "" are each an answer somebody gave.

io.choria.fisk-ai.v1.elicit.waiting arrives on the same subject and is not an answer. It says the caller is holding the question open, see Holding a question open.

The worker replies with an ack. An answer to a question it is not waiting on gets a 404, as does an answer sent after the question’s window closed, and as does a waiting sent after the question was answered.

once runs the command that one time. always stops the worker asking about that tool for the rest of the run. no and no_operator both leave the command unrun and tell the model the refusal is final.

The worker holds the question for expose.agent.a2a.request_timeout, and its worker slot with it. The question’s wait_ms carries that number, so the caller knows how long it has. An unanswered question ends the run differently depending on what asked it:

• an approval leaves the command unrun, and the run ends with suspended
• a human-in-the-loop tool leaves its call deferred, and the run ends with deferred

Both can be answered later, see Answering after the run ended. An operator on the worker holding the journal answers a deferred call with fisk session instead.

Holding a question open

A person reading a command approval can take longer than two minutes. A caller with the question in front of somebody sends an io.choria.fisk-ai.v1.elicit.waiting, and each one restarts the window:

{
  "protocol": "io.choria.fisk-ai.v1.elicit.waiting",
  "id": "3Hzq9UxpYOvW2ZuvFk0njI0QOzb",
  "request": "docs1",
  "conversation": "docs1",
  "sequence": 0,
  "time": "2026-08-16T11:25:59.104812Z",
  "sender": {"name": "peer1"},
  "question_id": "3Hzq7RvnWMtU0XstDiYlhG8OMxz"
}

The rules a client follows:

• Send a waiting every wait_ms / 3, starting when the question goes on screen. The window restarts when the worker receives the message, so the remaining two thirds cover the round trip and one lost message. In Go, wire.NewWaitingAck(question, sender) builds the message and question.AckInterval() is the interval.
• Stop before sending the answer. A waiting that arrives after the answer is refused, since the worker has finished with the question.
• A 404 means the question is gone: take it off the screen and send no answer, since that would be refused too.
• A 400, or a question with no wait_ms, comes from a worker older than this feature. Answer inside the window instead.
• Send no_operator when the person walks away. waiting says somebody is there to answer, and no_operator ends the question at once. Silence leaves the command unrun too, but only after a whole window.
• The reply set is silent while the worker holds the question, so a client learns the worker is still there only from the ack to each waiting.

A caller that sends no waiting either answers within the window or answers later, on a request of its own.

Answering after the run ended

A person closes a laptop with a question on screen. The waiting messages stop, the window runs out, and the run ends suspended or deferred. The worker unsubscribes from choria.fisk-ai.elicit.<identity>.<request> with the task, so an hour later their answer reaches no responder.

They send an io.choria.fisk-ai.v1.request.answer instead, with the conversation token:

{
  "protocol": "io.choria.fisk-ai.v1.request.answer",
  "id": "3Hzms0ZgSN940AmUYc1fOpEWVk7",
  "request": "docs4",
  "conversation": "docs1",
  "sequence": 0,
  "time": "2026-08-16T12:40:03Z",
  "sender": {"name": "peer1"},
  "conversation_token": "3Hzmp8VqrKL42NmXcPd7bTgWfR1",
  "answer": {
    "tool_use_id": "toolu_01A9bK2mNpQr",
    "kind": "approve",
    "answer": "choice",
    "choice": "once"
  }
}

Copy tool_use_id and kind from the question. A resumed run mints a new question_id, so the answer names the call instead.

The answer object has kind and answer of its own. answer names the field holding the decision, and kind says what that decision means where the value alone cannot: no_operator looks the same whichever question was asked, and value serves both input and select.

A selection names the option, not its position.

You get back the usual ack, events, and a result or an error. The conversation gains no turn. A deferred call takes the answer as its result; an approval is asked again by the resume and answered from the request.

A 400 means the answer does not fit its kind, or the message has no token, or it came with a prompt.

Concurrency and shutdown

Each prompt holds a worker slot from acknowledgement until the run ends. No setting limits total run time; harness.tool_timeout limits a tool call and llm.budget.call_timeout limits a model call. With workers: 1, one long run makes the worker refuse every other caller until it finishes. A run whose caller keeps sending waiting is one such run, and it holds its slot for as long as the caller sends them.

An interrupt starts a drain, which takes the identity out of its queue group, so the worker accepts no further prompts. The worker waits for runs already under way and answers their callers. A prompt acknowledged but not started ends with draining. A second interrupt cancels the runs in flight and answers each caller with failed.

A drain stops restarting the window of a question already outstanding, so it ends within one window and the runs behind it finish. A caller sending waiting at that point still gets an ack, but the ack no longer restarts the window.

Tool selection

A run started this way reaches every tool the top-level include and exclude selected, exactly as a queued job does. expose.agent.tools selects what peers may invoke directly over MCP and a2a, and does not affect a run.

A command tagged ai:confirm, or a configured confirm tag, needs an approval before it runs. Without elicit the run has no operator to ask, so the model sees the tool, calls it, and the worker refuses the call before the command runs. The worker logs how many such tools the run loaded. With elicit the question goes to the caller, as Answering questions describes.

Sessions

The worker mints a conversation token and journals every run under its hash. A crash leaves a resumable run, and a deferred tool call has a journal to answer into. A caller holding the token continues that conversation; a caller that wants the work redone from scratch sends the prompt without one.

conversation on a request is echoed on every reply and never names a journal. It is the caller’s own correlation tag, free for grouping whatever it likes, and the token names the conversation.

Journals from this channel are named t- and a hash, so an operator reading fisk session ls can tell a prompt’s journal from a queued job’s. A session listing shows the last run’s outcome, so a conversation resting between turns reads as completed, and the prompt column shows the conversation’s first prompt.

The worker records the token and the caller’s claimed name with the journal, so a caller that lost a token can ask an operator for it instead of losing the conversation. Find the conversation with fisk session ls, which lists the first prompt and the time each journal was last touched, then read both values with fisk session show <id>. The listing has no token column, because a token is a credential and ls output is often pasted into tickets.

Safety

NATS publish permission on choria.fisk-ai.task.<identity> is the only access control: anyone holding it runs this agent’s tools against a prompt of their choosing. A request carries no verified caller identity, and sender is an unverified claim the worker records and logs.

A caller needs publish on the request subject. Canceling needs publish on choria.fisk-ai.cancel.<identity>.>, and answering questions needs publish on choria.fisk-ai.elicit.<identity>.>. The reply set arrives on the caller’s own inbox.

Anyone holding the cancel permission who learns a request id can cancel a run they did not start. Anyone holding the answer permission who learns a request id and a question id can approve a confirmation-gated command in a run they did not start, and can hold that run’s worker slot for as long as they keep sending waiting.

A conversation_token is a credential on the same terms: holding it is the authorization to add a turn to that conversation, and any holder can continue a conversation, whoever started it. It carries more than a fresh prompt does, because a standing approval an earlier turn recorded is restored with the conversation, so with elicit set a turn can reach a confirmation-gated command that somebody else approved. Tokens carry 128 bits of randomness and cannot be guessed, so treat one as a secret: this agent neither logs it nor puts it in an error message, and a caller should not either.

The session store is shared with the other channels of this identity, and each names its journals in a space of its own: a conversation here is a hash of the identity and the token, and a queued job is a hash of the identity and its task id. So a queue submitter that learns one of these journal ids and spells it as a task id gets a journal of its own rather than this conversation.

The worker records the token in the conversation’s journal, so anyone who can read the session store can read the token and continue that conversation. This gives away no access that reading the store did not already give, since the same access reads and writes those journals directly, but the store needs the same protection the tokens do. The caller’s name is recorded beside the token, and it is the unverified claim from the sender field.

The worker logs the caller, the request id and the session as a prompt is accepted, runs and ends:

level=INFO msg="Accepted a prompt" channel=a2a/prompts request=docs1 caller=peer1 session=3Hzq5OghUNlK8SnoBgVjfE6MKvx prompt_bytes=26
level=INFO msg=Running channel=a2a/prompts work=3Hzq5OghUNlK8SnoBgVjfE6MKvx caller=peer1 caller_verified=false resume=3Hzq5OghUNlK8SnoBgVjfE6MKvx
level=INFO msg="Ending a run" channel=a2a/prompts request=docs1 caller=peer1 session=3Hzq5OghUNlK8SnoBgVjfE6MKvx code=failed reason="llm call: 401 Unauthorized"

The worker logs the window it gave a question and, when the question closes, how long it held it and how many waiting messages the caller sent. An operator reads from these which caller is holding a worker, and for how long:

level=INFO msg="Asked the caller a question" channel=a2a/prompts request=docs1 caller=peer1 question=3Hzq7RvnWMtU0XstDiYlhG8OMxz kind=approve wait_ms=120000
level=INFO msg="A question was answered" channel=a2a/prompts request=docs1 caller=peer1 question=3Hzq7RvnWMtU0XstDiYlhG8OMxz held=14m32s acks=21

The tool safety rules in the Reference apply here as everywhere else.