@prata.ma/scout

Command-oriented research runtime for Anvil workspaces.

Overview

@prata.ma/scout owns the reusable runtime behind Anvil's governed search and research workflows. The package now centers on composable commands instead of the older stage-pipeline contract:

• plan expands a query with OpenCode
• discover retrieves hits from selected adapters
• curate ranks and filters hits against the query
• fetch retrieves full content from selected locations
• gather composes multi-angle discovery, curation, target selection, and fetch into one evidence payload
• synthesize turns fetched evidence into structured findings
• search and research compose the same commands for human end-to-end usage

Within the workspace and for external consumers, @catalog/blocks/scout owns authored skills, commands, and agents, while @prata.ma/scout owns executable behavior.

Installation

Install the package from npm when using the Scout runtime outside this monorepo.

{
  "dependencies": {
    "@prata.ma/scout": "^0.0.0"
  }
}

Usage

@prata.ma/scout supports both library-style usage and the standalone scout CLI.

Library

import {
  runScoutDiscover,
  runScoutFetch,
  runScoutGather,
  runScoutPlan,
  runScoutSearch,
  runScoutSynthesize,
} from '@prata.ma/scout'

const plan = await runScoutPlan({
  model: 'openai/gpt-5.5',
  query: 'state of browser-based AI agent architecture',
})

const discover = await runScoutDiscover({
  query: plan.result.queries[0]?.text ?? 'state of browser-based AI agent architecture',
  scope: plan.result.queries[0]?.scope ?? 'all',
  tools: plan.result.queries[0]?.tools ?? ['exa'],
})

const fetch = await runScoutFetch({
  targets: discover.result.hits.slice(0, 2).map(hit => ({
    adapter: hit.adapterId,
    location: hit.location,
  })),
})

const gather = await runScoutGather({
  angles: ['browser-based AI agent architecture examples', 'AI browser automation architecture'],
  discoverLimit: 10,
  fetchPercent: 75,
  query: 'state of browser-based AI agent architecture',
  scope: 'web',
  tools: ['exa', 'tavily'],
})

const synthesis = await runScoutSynthesize({
  model: 'openai/gpt-5.5',
  query: 'state of browser-based AI agent architecture',
  sources: fetch.result.sources,
})

console.log(plan.result.queries)
console.log(fetch.result.sources.length)
console.log(gather.result.sources.length)
console.log(synthesis.result.summary)

CLI

scout plan "state of browser-based AI agent architecture" --model openai/gpt-5.5
scout discover "state of browser-based AI agent architecture" --tools exa,tavily --scope web
scout fetch --input targets.json
scout gather "state of browser-based AI agent architecture" --angles '["browser AI agent architecture","AI browser automation patterns"]' --tools exa,tavily --scope web --discover-limit 10 --fetch-percent 75
scout synthesize --query "state of browser-based AI agent architecture" --model openai/gpt-5.5 --input sources.json

scout gather also saves per-run artifacts automatically under $XDG_STATE_HOME/scout/gather or ~/.local/state/scout/gather when XDG_STATE_HOME is unset. Each run writes a timestamped folder containing:

• manifest.json
• discover-0.json, discover-1.json, ...
• curate.json
• fetch.json
• result.json

Human-facing wrappers compose the same runtime:

scout search "state of browser-based AI agent architecture" --model openai/gpt-5.5
scout research "react hooks" --model openai/gpt-5 --tools context7

--tools on search and research is optional and acts as a preference layer over planner-selected tools rather than a hard override.

Governed Scout agent workflows use a narrower execution contract than the human wrappers: the agent collects parameters, plans query angles, synthesizes fetched evidence, and uses the CLI for gather or for lower-level discover, optional curate, and fetch debugging. plan, synthesize, search, and research remain package runtime commands, but they are not the preferred path inside governed agent workflows.

API

Exports

• adapter contract and adapter exports from src/adapters/*
• command helpers: runScoutPlan, runScoutDiscover, runScoutCurate, runScoutFetch, runScoutGather, runScoutSynthesize, runScoutSearch, runScoutResearch
• registry helpers: getAdapterById, getAdaptersByKind, getDeferredAdapterIds, getFirstSliceAdapterIds, SCOUT_ADAPTERS
• utility helpers: dedupeHits, selectDiverseHits, countDomains, getDomain
• shared command-oriented types exported from src/index.ts

Commands

The package ships one binary:

• scout

Available CLI subcommands:

• scout plan <query> --model <provider/model>
• scout discover <query> --tools <tool,...> [--scope all|web|code] [--limit N]
• scout curate --query <query> [--limit N] [--input file.json]
• scout fetch [--input file.json]
• scout gather <query> --angles '["query one","query two"]' --tools <tool,...> [--scope all|web|code] [--discover-limit N] [--curate-limit N] [--fetch-percent N] [--fetch-limit N]
• scout synthesize --query <query> --model <provider/model> [--input file.json]
• scout search <query> --model <provider/model> [--tools tool,...]
• scout research <query> --model <provider/model> [--tools tool,...]

All commands currently emit JSON. --input accepts a file path; otherwise commands that need structured input read JSON from stdin.

Supported Adapters

Curated ready adapters:

• exa - Exa web search, requires EXA_API_KEY
• tavily - Tavily web search, requires TAVILY_API_KEY
• firecrawl - Firecrawl web search plus scrape-backed snippets, requires FIRECRAWL_API_KEY
• context7 - Context7 documentation search, requires CONTEXT7_API_KEY

Additional active adapters not in the curated ready set:

• grep-app - public code search backed by an undocumented public API
• github-cli - GitHub code and repo search, requires gh auth login

Deferred adapters still present in the registry but intentionally skipped:

• browserbase
• gemini
• opensrc

Development

This package now participates in the repo's Changesets, npm publish, and GitHub Release automation as a package-scoped public surface. The package-local release:check script remains the focused validation contract for this package.

Layout

• src/adapters/ - adapter contract and per-tool implementations
• src/commands/ - command-oriented runtime entrypoints
• src/lib/ - shared helper logic used by commands, including stderr-safe CLI UX
• src/registry.ts - adapter registration and slice metadata
• src/types.ts - shared command and adapter types
• src/cli.ts - standalone scout CLI entry
• test/ - package tests

Commands

pnpm --filter @prata.ma/scout release:check
pnpm --filter @prata.ma/scout build
pnpm --filter @prata.ma/scout lint
pnpm --filter @prata.ma/scout test
pnpm --filter @prata.ma/scout test:type

Testing

The current Vitest coverage focuses on adapter behavior, dedupe/diversity helpers, command validation and normalization, OpenCode-backed plan and synthesize behavior, and the human wrapper composition for search and research.

Notes

• scout plan and scout synthesize require --model and call opencode run under the hood.
• Scout CLI UX writes intro, outro, and status text to stderr so JSON stdout remains scriptable.
• Governed Scout workflows prefer agent-owned planning and synthesis over the package plan and synthesize commands.
• discover is one query per invocation; use gather when multi-angle discovered, curated, and fetched evidence should stay in one JSON payload.
• fetch accepts only location plus adapter and handles GitHub raw URL rewriting internally for supported code-search cases.
• Real provider integrations can continue landing incrementally behind the existing adapter contract.
• @prata.ma/scout now ships a package CHANGELOG.md and participates in the repo's multi-package release workflow.