129 lines
5.4 KiB
Markdown
129 lines
5.4 KiB
Markdown
# Progressive tool disclosure (bridge tools) — wiring
|
|
|
|
**Status:** Finalised
|
|
**Date:** 2026-08-15
|
|
**Compound:** the "keep the LLM tool schema small, give full access on demand" work (issue #167)
|
|
|
|
## Decision
|
|
|
|
The bridge-tool pattern is **implemented and tested** in
|
|
`internal/tools/disclosure.go` (`tool_search`, `tool_describe`, `tool_call`
|
|
|
|
- `ContextPressureGate` + `DisclosureMode`, section 17.14/17.15) — but it is
|
|
**never wired into the daemon**. `BridgeTools` and `ContextPressureGate` are
|
|
referenced only in `disclosure_test.go`. This task is therefore a **wiring**
|
|
task, not a feature build.
|
|
|
|
Wire the existing bridge into the per-chat-turn toolset:
|
|
|
|
1. **Compose a per-turn registry** seeded from the base registry plus the
|
|
per-turn extra tools, register the bridge tools into it, and hand it to both
|
|
the bridge handlers and the `ContextPressureGate`.
|
|
2. **Run the gate in `chatGenerateOptions`** (`internal/app/archied/main.go`)
|
|
so it decides full-vs-bridge disclosure per turn, and build the
|
|
`core.ToolSet` from the gate's filtered output.
|
|
3. **Thread the model's context window** into the preparation seam so the gate
|
|
has a real `ContextWindowSize` (it disables itself at 0, falling back to
|
|
full disclosure).
|
|
|
|
## Why the naive "register extras into the base registry" is wrong
|
|
|
|
`BuildToolSetFrom` (`internal/agentexec/toolset.go`) documents the invariant:
|
|
|
|
> the task tools carry the calling gateway's identity, so there is one set of
|
|
> them per gateway and they **cannot live in the process-wide registry**.
|
|
|
|
This is confirmed by wiring: gateways are per-channel
|
|
(`telegram_setup.go` build a `TurnRunner` per channel), and the extra
|
|
tools (`task_*`, `session_*`, `dashboard_*`) close over that channel's identity
|
|
via `TurnRunnerConfig` (`turn.go`). Registering them into `b.toolReg` would
|
|
let channel A's session/identity-bound tools be invoked by channel B — a real
|
|
cross-channel privilege bug. The bridge handlers iterate `reg.All()`
|
|
(`disclosure.go`), so the extras must be discoverable; the fix is a
|
|
**per-turn composed registry**, not a mutation of the process-wide one.
|
|
|
|
## Shape of the change
|
|
|
|
### 1. Per-turn composed registry + gate inside `chatGenerateOptions`
|
|
|
|
Replace the current base-set + extra-set merge (`main.go`) with a single
|
|
composed-registry pass:
|
|
|
|
```go
|
|
// new helper, in internal/tools/disclosure.go or the archied wiring package
|
|
func ComposeForTurn(reg *tools.Registry, extra []tools.ToolEntry) (*tools.Registry, error) {
|
|
composed := tools.NewRegistry()
|
|
for _, e := range reg.All() {
|
|
if err := composed.Register(e); err != nil { return nil, err }
|
|
}
|
|
for _, e := range extra {
|
|
if err := composed.Register(e); err != nil { return nil, err }
|
|
}
|
|
if _, err := composed.RegisterBatch(tools.BridgeTools(composed)); err != nil {
|
|
return nil, err
|
|
}
|
|
return composed, nil
|
|
}
|
|
```
|
|
|
|
`chatGenerateOptions` then:
|
|
|
|
```go
|
|
composed, err := ComposeForTurn(registry, extra)
|
|
// ...
|
|
gate := tools.NewContextPressureGate(contextWindow)
|
|
gate.SetAlwaysVisible(...) // e.g. session/session_resume, task/task_list
|
|
disclosed := gate.FilterTools(composed)
|
|
toolSet, err := agentexec.BuildToolSetFrom(disclosed, toolOpts)
|
|
```
|
|
|
|
`FilterTools` (`disclosure.go`) already returns `all` in full mode and
|
|
`bridge + always-visible` in bridge mode, and `BuildToolSetFrom` re-applies
|
|
availability/approval/schema rules, so the two layers compose cleanly.
|
|
|
|
### 2. Thread context window through the preparation seam
|
|
|
|
`ContextPressureGate` disables at `ContextWindowSize == 0`. The model context
|
|
window is resolved in `TurnRunner.prepareTurn` (`turn.go`) but is not
|
|
passed to `TurnModel.Prepare`. Extend the seam:
|
|
|
|
```go
|
|
type TurnPrepareContext struct {
|
|
Model string
|
|
Extra []tools.ToolEntry
|
|
ContextWindow int // model's context window in tokens; 0 = gate disabled
|
|
}
|
|
```
|
|
|
|
`TurnModel.Prepare(ctx, context TurnPrepareContext)`; `prepareTurn` fills
|
|
`ContextWindow` from `modelDetails.ContextWindow`. This touches one interface
|
|
(`turn.go`), one production impl (`chat_turn_model.go`), and the test
|
|
mock (`turn_test.go`).
|
|
|
|
### 3. Bridge-handler parity note
|
|
|
|
`bridgeCallHandler` calls `e.Handler` directly (`disclosure.go`), bypassing
|
|
`toolExecute` — so a `tool_call` invocation does **not** apply `CapPayload` /
|
|
`MaxResultSizeChars` spilling or `OnToolCall` reporting, and it pre-refuses
|
|
`RequiresApproval` tools (`disclosure.go`). This is acceptable for the
|
|
first wiring (the bridge is read-discover/describe plus a guarded call), but a
|
|
later hardening should route the invoked tool through the same
|
|
cap/approval path the model's direct call uses. Recorded as a follow-up, not a
|
|
blocker for this task.
|
|
|
|
## Files touched
|
|
|
|
- `internal/app/archied/main.go` — `chatGenerateOptions` composes + gates.
|
|
- `internal/app/archied/chat_turn_model.go` — `Prepare` accepts `TurnPrepareContext`.
|
|
- `internal/gateway/turn.go` — `TurnModel.Prepare` signature; `prepareTurn` fills context window.
|
|
- `internal/gateway/turn_test.go` — update the `turnTestModel.Prepare` mock.
|
|
- `internal/tools/disclosure.go` — add `ComposeForTurn` helper (or place in archied).
|
|
|
|
## Out of scope / follow-ups
|
|
|
|
- Delegate `tool_call` through `toolExecute` for cap/approval/observability parity.
|
|
- Cover the compose-and-gate path with tests (compressed footprint under a
|
|
small window; always-visible minus bridge margin).
|
|
- Reconcile any `ContextPressureGate` mode with the compression budget already
|
|
computed in `prepareTurn` (`turn.go`).
|