@skarmy/research-agent

Skarmy's Research Lead — runs deep market, customer, and competitor research on demand. Joins the team when the team-selection judge matches its inclusion criterion: "There are real unknowns about the market, customers, competitors, or how this space works that are worth investigating before committing."

How it works

A prompt agent (SDK 0.4 contract): the hub's prompt engine runs onTurn, which drives a bounded JSON-action loop (src/turn.ts) — the model picks ONE action per step, the hub executes it, and a compact observation feeds the next step. All research I/O flows through hub-granted ctx capabilities; the definition never holds an API key or makes a raw network call:

| Capability | Manifest grant | Hub backend | Per-turn budget | |---|---|---|---| | ctx.search | web_search | Exa → Serper → Tavily → SearXNG chain | limits.searchCalls (10) | | ctx.extract | extract | Firecrawl scrape → markdown | pooled limits.toolCalls (10) | | ctx.trends | trends | SerpAPI google_trends | pooled limits.toolCalls | | ctx.domainCheck | domain_check | Domainr / keyless RDAP | pooled limits.toolCalls | | ctx.marketSnapshot | market_snapshot | US Census CBP + ACS (free, hub-built URLs) | pooled limits.toolCalls |

The hub appends TOOL_CALL / TOOL_RESULT events around every executed call, so the founder watches each search live in the session feed while the turn runs. Each step also carries a plain-language thought that the agent emits as a live NARRATION line (ctx.emitEvents) — the founder sees why the agent is about to do something, next to the raw what of the tool row. Every outcome is a degradable union (ok | unconfigured | blocked | error) — missing provider keys or exhausted budgets become graceful prose, never crashed turns.

A substantial researched reply (≥1 executed action, ≥600 chars) is auto-saved as a cited markdown report document to /research/<slug>.md and opened on the document pane (ctx.files + ctx.emitStage, granted by stage: ["document"] + tools: ["files"]). The slug is taken from the report's own H1 title so the founder's file library is cleanly named. Persisting never throws — a blob-store or stage hiccup degrades to a chat-only reply (src/report.ts).

Model: RESEARCH_MODEL env overrides this agent; falls back to OPENROUTER_MODEL, then openai/gpt-4.1-mini. The manifest is the one place the model is named.

What this package owns

• researchManifest (AgentManifest) — identity: key, model, tool grants, per-turn limits, protocol version. The hub imports this and pins it in its registry. Key, name, and roster fields must stay in lockstep with the hub's canonical team roster (skarmyv0 src/lib/discovery/team.ts).
• researchDefinition (AgentDefinition) — sessionIntro, systemPrompt, and the onTurn research loop.

Develop

Prereqs: Node 22+, @skarmy/agent-sdk ^0.4.0 (npm publish pending — until then, npm pack the workspace SDK from skarmyv0/packages/agent-sdk and npm install --no-save the tarball).

npm install
npm run typecheck
npm test           # SDK contract test + turn-loop tests

Publish & pin

1. Publish @skarmy/[email protected] from the hub monorepo first (pnpm, not npm — the publishConfig src→dist rewrite; see handoff.md).
2. npx pnpm@9 publish --access public --no-git-checks, then npm install to re-point the lockfile at the published SDK.
3. The hub adds/bumps @skarmy/research-agent and registers researchManifest / researchDefinition (src/lib/agents/registry.ts + PROMPT_DEFINITIONS in src/lib/agents/prompt-engine.ts — the legal entry shows the pattern).

License

MIT