98 lines
4.9 KiB
Markdown
98 lines
4.9 KiB
Markdown
# Bounded research delivery
|
||
|
||
New general research tasks should use `task_type: "research"` on
|
||
`delegate_task` or `spawn_agent`. The coordinator is instructed to select this
|
||
for search-and-guide requests. Omitted task types remain standard, including
|
||
old saved tasks. Existing research is not migrated or restarted.
|
||
|
||
## Delivery
|
||
|
||
The runtime stores research state with the task, including its start time,
|
||
source reservations, publications and source results.
|
||
|
||
- Initial collection stops at 120 seconds, two searches or six page reservations.
|
||
Limits are checked before starting a new source call and on each model round;
|
||
already running calls may finish.
|
||
- `publish_research` sends a first guide with summary, actionable steps, observed
|
||
source URLs and unknowns. It can declare zero to two material gaps.
|
||
- Each gap permits one additional search and two pages. Every supplement source
|
||
call needs its zero-based `gap` index. Supplement collection also stops after
|
||
120 seconds.
|
||
- A second publication contains only additions and remaining unknowns. It cannot
|
||
introduce new gaps. An empty gap list completes the task immediately.
|
||
- Opening acknowledgements and meaningful progress messages remain available.
|
||
They do not count as a first guide.
|
||
- Synthesis gets at most three model rounds after collection closes. Failure to
|
||
publish then ends the task with an explicit error and retains existing evidence
|
||
and publications, rather than resuming exploration.
|
||
- Other execution/delegation tools cannot bypass research limits. Browser
|
||
navigation counts as a page; browser snapshots and page reading are available
|
||
during collection for HTTP-blocked sources. Shell/MCP-based research requires a
|
||
standard task.
|
||
|
||
The 2–3 minute first-guide target is a goal, not a deadline for external model
|
||
responses. Network source calls have a 30 second timeout; model response and
|
||
queue delays are measured separately.
|
||
|
||
## Reuse and persistence
|
||
|
||
Within a research task, identical search queries and canonical URLs reuse the
|
||
saved result, including errors and timeouts. Different URLs can run concurrently;
|
||
concurrent requests for the same URL share one execution. URL fragments are
|
||
ignored; query parameters remain significant. Cached access does not spend a
|
||
new reservation. Failed source attempts spend their original reservation.
|
||
|
||
Large tool results include `output_id`. Use `read_tool_output` with that ID,
|
||
`offset` (default 0) and `limit` (default 6000, maximum 12000). Offsets count
|
||
Unicode characters. The reader is scoped to the current task/session and
|
||
rejects traversal or another task's output. It does not access the Docker
|
||
filesystem.
|
||
|
||
Publications are stored independently of foreground conversation checkpoints,
|
||
restored into chat history and made available to subsequent foreground turns.
|
||
Completed research does not enqueue a redundant coordinator summary.
|
||
|
||
## Diagnostics and validation
|
||
|
||
Persisted `timing` events carry task/agent association, timestamp and elapsed
|
||
milliseconds. Model queue and response records share a round identifier; source
|
||
and tool records carry the task's request number, with call IDs on tool records.
|
||
Stages include `worker_model_queue`, `foreground_model_queue`, `model_response`,
|
||
`model_retry_backoff`, `tool_execution`, `research_source`,
|
||
`research_first_delivery`, and `research_final_delivery`.
|
||
Retry-backoff values are scheduled wait durations. No prompts, arguments or
|
||
credentials are stored in timing events. `GROKBOY_TIMING=1` additionally prints
|
||
latency logs.
|
||
|
||
Offline checks:
|
||
|
||
```sh
|
||
cargo test -p grokboy-core --lib
|
||
cargo build -p grokboy
|
||
python3 tests/research_flow.py
|
||
```
|
||
|
||
The integration fixture makes no paid model calls and is not evidence of live
|
||
provider latency. After restarting the local backend, use new ordinary research
|
||
requests to measure actual first-guide latency from the recorded events.
|
||
|
||
## Accurate work indicators
|
||
|
||
`GET /api/agents/:id/activity` (daemon RPC `activity`) reports
|
||
`idle | queued | running | waiting_input`, active task IDs and a pending question.
|
||
Roster and agent detail use the same computation. A saved `running` task is
|
||
active only while the service owns a live worker. Completing one task does not
|
||
hide another active task; a human question by itself is not active computation.
|
||
|
||
The frontend reconciles on lifecycle events and every two seconds, independently
|
||
of streamed progress text. Only running activity animates; queued work has a
|
||
static label. The old OR of typing, stale detail, stale roster and status text is
|
||
removed. Status requests time out after eight seconds; connection failure shows
|
||
an unknown/reconnecting message instead of an endless working animation. Late
|
||
responses from another agent or before a newly sent message are discarded.
|
||
|
||
Browser regression (with the local Vite UI running):
|
||
`node tests/activity_ui.mjs`. This uses an isolated headless browser and mocked
|
||
API responses to verify running, idle, queued, waiting-input, disconnect and
|
||
reconnect, including stale progress events and roster data.
|