Files
archie/docs/architecture/dashboard-agent-tools.md
T
sam 96314fb237 docs(news): state what a reader gets, and move the design where it is read
The v1.36.0 release note carried four things a reader cannot use. The dashboard's
seven in-browser tools and the installtype fix stay; the withheld judgement verbs,
the consequentialHint limitation and the two silent-failure notes are removed from
the release feed and moved to where an implementer looks.

  - The four verbs are withheld because an agent that can approve can approve its
    own work. That is settled design, so it now sits in docs/architecture/identity.md,
    beside the approval-path conflict it belongs with, stated as the constraint it is:
    attribution, not capability, is what releasing them depends on.
  - The browser-tool surface had no home in docs/architecture, so it has one now:
    docs/architecture/dashboard-agent-tools.md holds what a tool call can be
    attributed to, why confirmation is a signal rather than a control, and the two
    ways the surface fails silently.

Audited 1.35.0, 1.36.0 and 1.37.0 for the same class. 1.37.0 is clean. 1.35.0 carried
two build notes: a bullet recounting that a guard had never been written because it
failed, and a clause about a manager "finally" having a production writer. Both are
gone; the capabilities they were attached to remain.

RELEASING.md now carries the rule so the next release reads it: release notes state
what a reader gets, and design constraints, withheld capabilities and failure modes
belong in docs/architecture/, because a note about an absence reads as a feature to
someone who never had the thing.

docs/news/** is regenerated by task news, never hand-edited. task check passed before
this commit: the chain runs it, so a failing gate commits nothing.
2026-09-22 16:53:27 +10:00

40 lines
2.1 KiB
Markdown

# The dashboard's tools for an in-browser agent
The dashboard registers in-browser tools an agent can call through the page's model
context. Four are read-only — `list_tasks`, `get_task`, `recent_events`,
`daemon_health` — and three recover stuck work: `retry_task`, `stop_task`,
`cancel_task`. Each wraps the same `ui/src/lib/api.ts` client the dashboard itself
calls, so an agent and a person exercise one path rather than two.
The four judgement verbs are withheld for the reason `identity.md` gives: an agent
that can approve can approve its own work.
## What a tool call can be attributed to
A page can invoke its own tools, so an agent's call and a page script's call reach
the server identically — the difference does not exist on the wire, and no header
recovers it. A tool call is therefore attributed to the signed-in identity the
request presented, with its source recorded as a hint; it never records that an
agent acted, and it never records that a human approved. An agent's action is
attributable only on a surface where the agent presents its own credential.
## Confirmation is a signal, not a control
The three recovery tools require an explicit `confirm: true`, which makes a
consequential call deliberate rather than incidental. It is not a security control:
an agent can trivially satisfy it, and the browser cannot enforce
`consequentialHint` at all — Chrome accepts it at registration and omits it from
`getTools()`, so no client can see what the browser does not surface.
The boundary that holds is the session. These tools cannot exceed what the operator
signed in at the provider is already permitted to do.
## Two ways the surface fails silently
- **A secure context is required.** On a plain-HTTP origin `document.modelContext` is
absent even with the flag enabled, and nothing reports why. `mkcert` covers local
development.
- **The dashboard embeds `ui/dist` into its binary.** Rebuilding the distribution is
not deploying it: a running process can serve a bundle without tools while the
built one has them, or serve a bundle older than its own binary.