235 lines
16 KiB
Markdown
235 lines
16 KiB
Markdown
# PR4 Recon — Slice 5: Agent-Search / Agent-Pick
|
||
|
||
**Screen 09 Marketplace · Variation A "agent-suggestion box"**
|
||
"Describe what you want to do…" → agent recommends a **connector + skill + tool**, each with a **"why"** reason and an **install** button.
|
||
|
||
Branch: `feature/warm-hive-pr4` · READ-ONLY recon · cited file:line as of 2026-06-16.
|
||
|
||
---
|
||
|
||
## TL;DR
|
||
|
||
The agent-pick engine **already exists and is good**: `searchCapabilities()` in
|
||
`packages/agent/src/capability-acquisition.ts:179` takes a natural-language `need` and returns a
|
||
ranked, deduped `AcquisitionProposal` of native tools / installed skills / starter-pack skills /
|
||
marketplace packages — **each candidate already carries a `matchReason` ("why") and an
|
||
`installAction`** plus a trust assessment. It fuses **keyword scoring** (no embeddings) across local
|
||
sources with **pre-fetched marketplace FTS5 candidates**.
|
||
|
||
**The gap is entirely the surface, not the brain.** This engine is reachable **only as an agent tool**
|
||
(`acquire_capability`, `packages/agent/src/skill-tools.ts:406`) invoked inside the chat loop — there is
|
||
**no HTTP route** that the Screen-09 agent-search bar could `POST` a need to and render the
|
||
three-up suggestion box. PR4 must add a thin REST endpoint over the existing `searchCapabilities()`
|
||
(plus its deps assembly that today lives inline in `local/index.ts:620`) and a new
|
||
`MarketplaceApp` agent-search UI. The matching scoring is single-recommendation today
|
||
(`proposal.recommendation` is ONE candidate); the design wants **one-of-each-kind** (connector+skill+tool),
|
||
which is a selection/grouping change on top of the existing ranked `candidates[]`, not new matching.
|
||
|
||
---
|
||
|
||
## What exists today (verified)
|
||
|
||
### 1. The matching brain — `searchCapabilities()` (the agent-pick core)
|
||
`packages/agent/src/capability-acquisition.ts`
|
||
|
||
- **Input** (`SearchCapabilitiesInput`, :170): `{ need, installedSkills[], starterSkillsDir,
|
||
nativeToolNames[], marketplaceCandidates[] }`. Marketplace candidates are **pre-fetched and passed
|
||
in** — `searchCapabilities` itself does no IO except reading starter-skill `.md` files from disk
|
||
(`loadStarterSkillsMeta`, :142).
|
||
- **Algorithm** (no embeddings — pure keyword): `extractKeywords()` (:64, stop-word filtered) →
|
||
`scoreMatch()` (:74, name-hit ×2 / content-hit ×1, normalized 0–1) across four source lanes:
|
||
1. native tools (scored vs `NATIVE_TOOL_HINTS` map, :113);
|
||
2. installed/active skills (:218);
|
||
3. starter-pack skills not yet installed (:241);
|
||
4. marketplace candidates, merging the FTS score when present via `Math.max(keywordScore, mkt.score)` (:270).
|
||
- **Output** (`AcquisitionProposal`, :39): `{ need, gapDetected, summary, candidates[]≤8,
|
||
recommendation, alreadyHandled }`. Each `CapabilityCandidate` (:27) already has the exact fields
|
||
Screen-09 needs: `name`, `type` ('native'|'skill'|'plugin'|'mcp'|'connector'|'marketplace'),
|
||
`availability`, `description`, `matchReason` (**the "why"**, built by `buildMatchReason` :99),
|
||
`installAction` (string|null), and `trust`.
|
||
- **Recommendation is SINGLE** (:307–314): picks the best installable (or best active if
|
||
already-handled). It does **not** group into connector+skill+tool. The full ranked `candidates[]`
|
||
is there to do that, but the grouping logic does not exist yet.
|
||
- **`summary`** is a markdown string built for the **chat** surface (`buildProposalSummary`, :330): it
|
||
even **emits the inline-install marker** (`<!--waggle:capability_request {...}-->`, :385) verbatim for
|
||
the chat card. This is debug/chat-grade prose — a UI agent-suggestion box would consume the
|
||
**structured `candidates`/`recommendation`, not `summary`**.
|
||
|
||
### 2. How it's invoked today — the agent tool `acquire_capability`
|
||
`packages/agent/src/skill-tools.ts:404–478`
|
||
|
||
- Tool `acquire_capability` (param: `need`) gathers deps: `getInstalledSkills()`, `starterSkillsDir`,
|
||
`nativeToolNames`, and calls `deps.searchMarketplace(need)` (graceful try/catch) to pre-fetch
|
||
marketplace candidates, then calls `searchCapabilities(...)` and **returns `proposal.summary`** (the
|
||
markdown string) to the model. Audit event recorded on gap (:461).
|
||
- Companion tool `install_capability` (:482) installs **starter-pack skills only** (validated by
|
||
`validateInstallCandidate`, capability-acquisition.ts:424 — rejects any source ≠ `starter-pack`).
|
||
- The deps are wired in `packages/server/src/local/index.ts:620` (`createSkillTools({...})`):
|
||
- `nativeToolNames` = union of mind/system/plan/git/document tool names (:624);
|
||
- `getInstalledSkills` = live `server.agentState.skills` (:631, hot-reloadable);
|
||
- `searchMarketplace` = `marketplaceDb.search({ query, limit: 10 })` mapped to `MarketplaceCandidate[]`
|
||
(:641–656) — note `score` is hardcoded `undefined` (FTS rank not surfaced through the API).
|
||
|
||
### 3. The marketplace search it sits on
|
||
`packages/server/src/local/routes/marketplace.ts:57` — `GET /api/marketplace/search`
|
||
→ `MarketplaceDB.search()` (`packages/marketplace/src/db.ts:86`).
|
||
|
||
- FTS5 over the `packages` table. **Critically, `db.search` already tolerates a verbose NL `need`**:
|
||
`toFtsMatchQuery()` (db.ts:91–99) relaxes the raw string into an OR-of-prefixes and falls back to an
|
||
unfiltered listing rather than throwing — so the agent's natural-language need works as-is.
|
||
- `SearchResult` (`types.ts:233`): `{ packages[], total, facets{types,categories,sources},
|
||
installedCount }`. Each `MarketplacePackage` carries `waggle_install_type` ('skill'|'connector'|'mcp')
|
||
→ **the kind badge**, `package_type`, `description`, `downloads` (install count), and (route-annotated
|
||
at marketplace.ts:105) `installed`, `scanStatus`. **`installedCount`** is the natural source for the
|
||
"N in this workspace" count bar (currently catalog-wide, not workspace-scoped — see Gaps).
|
||
|
||
### 4. The parallel, narrower "recommend" path (skills-only) — DO NOT confuse with agent-pick
|
||
`packages/agent/src/skill-recommender.ts` (`SkillRecommender.recommend(context, topN)`, class at :118).
|
||
- Multi-signal keyword + bigram + synonym-cluster matcher over **installed skills only** (no
|
||
marketplace, no connectors, no MCP). Returns `SkillRecommendation[] = {skillName, reason,
|
||
relevanceScore}` — also a "why" (`reason`), but skills-only.
|
||
- Exposed over HTTP at `GET /api/skills/suggestions?context=&topN=`
|
||
(`packages/server/src/local/routes/skills.ts:393–406`). This is the **only** existing HTTP surface
|
||
that returns "what should I use" with a reason — but it's the wrong shelf (skills only, already
|
||
installed) for Screen-09's connector+skill+tool suggestion box. Useful as a *prior-art pattern* for
|
||
shaping the new route.
|
||
|
||
### 5. The router (a third matcher) — for completeness
|
||
`packages/agent/src/capability-router.ts` (`CapabilityRouter.resolve(query)`, :58). Maps a query to
|
||
ranked routes across native/connector/skill/plugin/mcp/subagent with confidences. **Resolution, not
|
||
recommendation** — returns "where could this be handled" not "install this". Connector lane (:85)
|
||
knows `connected` status and emits a suggestion when not connected. Not currently HTTP-exposed; a
|
||
secondary input if PR4 wants live-connector awareness in the suggestion box.
|
||
|
||
### 6. The inline-card render path (the "sync" downstream, shared with the grid)
|
||
- Parser: `apps/web/src/components/os/apps/chat-blocks/capability-request-parser.ts` — `segmentText()`
|
||
splits agent text on the `<!--waggle:capability_request {name,source,reason}-->` marker (and a legacy
|
||
phrasing) into install-card segments, deduped by `source::name`.
|
||
- Card: `apps/web/src/components/os/apps/chat-blocks/CapabilityRequestCard.tsx` — renders the
|
||
**pending→installing→installed/failed** micro-states (:17,:107–149) with a "why" line from
|
||
`request.reason` (:103). Install routing already branches by source: marketplace →
|
||
`adapter.searchMarketplace` then `adapter.installMarketplacePackage(pkg.id)` (:48–54, tier-gated, 403
|
||
→ UpgradeModal); starter-pack → `adapter.installPack` (:69). **This is exactly the type-aware
|
||
one-click flow §09 asks for, already built for the inline-chat variation (Variation B).**
|
||
|
||
### 7. Adapter methods already present (the install actions)
|
||
`apps/web/src/lib/adapter.ts`: `searchMarketplace(query,limit)` (:1334), `installMarketplacePackage(id)`
|
||
(:1338), `installPack(skillId)` (:1292), `connectConnector(id,creds)` (:1971), `installMcp(mcpId)`
|
||
(:2017). All three install kinds in the §09 sync spec (skill Add / connector Connect / MCP Enable)
|
||
have adapter coverage.
|
||
|
||
---
|
||
|
||
## Gaps vs the Screen-09 contract
|
||
|
||
1. **No HTTP route for agent-pick.** `searchCapabilities()` is reachable ONLY inside the chat agent
|
||
loop via the `acquire_capability` tool. The Screen-09 centered agent-search bar ("Ask the agent")
|
||
needs a `POST /api/marketplace/agent-search` (or similar) that runs `searchCapabilities` and returns
|
||
**structured candidates** (not the chat `summary` markdown). Must be built on top of the existing
|
||
engine.
|
||
|
||
2. **Returns chat-grade `summary`, not a structured suggestion box.** The tool returns
|
||
`proposal.summary` (markdown for the model). The UI needs the raw `candidates[]`/`recommendation`
|
||
JSON. The data is computed (proposal object) but **discarded** at skill-tools.ts:476 — a route would
|
||
return the object directly.
|
||
|
||
3. **Single recommendation, not one-of-each-kind.** `proposal.recommendation` is ONE candidate
|
||
(capability-acquisition.ts:307). §09 wants **connector + skill + tool** (three, one per kind) each
|
||
with its own why + install. Needs a small grouping pass over the ranked `candidates[]` (top per
|
||
`type`/`availability`) — new logic, but trivial given candidates already carry `type`.
|
||
|
||
4. **Marketplace deps assembly lives inline in `local/index.ts`, not reusable.** The
|
||
`getInstalledSkills` / `nativeToolNames` / `searchMarketplace` closure that feeds the tool is
|
||
constructed once at server boot (index.ts:620). A new route needs the same deps — either lift this
|
||
into a shared helper or have the route reconstruct it. (Native tool names, in particular, are only
|
||
assembled in that closure.)
|
||
|
||
5. **"N in this workspace" count bar is catalog-wide, not workspace-scoped.** `installedCount`
|
||
(db.search → types.ts:242) counts all installed packages globally; the marketplace DB is not
|
||
workspace-partitioned. §09's per-workspace chip count has **no backing field** today.
|
||
|
||
6. **No "example chips" / suggested-need seeding.** Pure UI; no backend. Can be static or derived
|
||
from persona `suggestedCommands` — out of agent-pick scope.
|
||
|
||
7. **No shared install-state store on the frontend.** §09's CRITICAL "sync" (one store powers grid +
|
||
agent-pick + inline card, installing in any view reflects in all) — the current `MarketplaceApp.tsx`
|
||
(no agent-search at all, install state local to each card) and `CapabilityRequestCard` (local
|
||
`useState` phase) have **independent** state. This is the headline PR4 frontend build; agent-pick is
|
||
one of the three consumers of that store. (Owned by the "shared install store" slice — flagged here
|
||
as the integration boundary.)
|
||
|
||
8. **`MarketplaceApp.tsx` has no agent-search UI.** Verified: the 417-line component
|
||
(`apps/web/src/components/os/apps/MarketplaceApp.tsx`) contains no "Ask the agent" / suggestion /
|
||
`acquire`-style references — only grid install/uninstall via `installMarketplacePackage` (:228).
|
||
Variation A's centered bar + suggestion box must be built net-new.
|
||
|
||
9. **Marketplace FTS rank not surfaced.** `searchMarketplace` hardcodes `score: undefined`
|
||
(index.ts:651), so marketplace candidates rank purely by keyword re-scoring inside
|
||
`searchCapabilities`. Acceptable, but means FTS relevance is currently dropped on the floor for the
|
||
agent-pick path.
|
||
|
||
---
|
||
|
||
## Exact integration points a PR4 build would touch
|
||
|
||
- **Reuse (engine):** `searchCapabilities(input): AcquisitionProposal`
|
||
— `packages/agent/src/capability-acquisition.ts:179`. Exported from `@waggle/agent`
|
||
(`packages/agent/src/index.ts:326`). Types `CapabilityCandidate` / `AcquisitionProposal` /
|
||
`MarketplaceCandidate` / `SearchCapabilitiesInput` are all exported.
|
||
- **Build (route):** new `POST /api/marketplace/agent-search` (body `{ need }`) in the marketplace
|
||
route file `packages/server/src/local/routes/marketplace.ts` — runs `searchCapabilities` with deps
|
||
assembled like `local/index.ts:620–657`, returns structured `{ candidates, recommendation,
|
||
groupedByKind }`. Pattern to mirror for shape/contract: `GET /api/skills/suggestions`
|
||
(`packages/server/src/local/routes/skills.ts:393`).
|
||
- **Reuse (deps):** marketplace search `MarketplaceDB.search({query,limit})`
|
||
(`packages/marketplace/src/db.ts:86`); installed-skills source `server.agentState.skills`; native
|
||
tool-name union (currently only assembled at `local/index.ts:624` — lift if reused).
|
||
- **Add (grouping):** a `pickOnePerKind(candidates)` helper (new) to satisfy connector+skill+tool —
|
||
trivial reduce over `candidate.type`.
|
||
- **Install actions (already present, reuse):** `adapter.installMarketplacePackage` /
|
||
`adapter.installPack` / `adapter.connectConnector` / `adapter.installMcp`
|
||
(`apps/web/src/lib/adapter.ts:1338/1292/1971/2017`). Marker/card render reuse:
|
||
`segmentText` + `CapabilityRequestCard` (chat-blocks/).
|
||
- **Count bar:** `SearchResult.installedCount` (`packages/marketplace/src/types.ts:242`) via
|
||
`/api/marketplace/search`; needs workspace-scoping if §09's per-workspace count is taken literally.
|
||
- **Audit (existing, ride along):** `fastify.auditStore?.record(...)` already called on gap in
|
||
skill-tools.ts:461 — a route should record proposals the same way.
|
||
|
||
---
|
||
|
||
## Risks / watch-outs
|
||
|
||
- **Two parallel matchers + a router** (`searchCapabilities` vs `SkillRecommender` vs
|
||
`CapabilityRouter`) — building a new route on the wrong one (e.g. `SkillRecommender`, which is
|
||
skills-only and HTTP-exposed already) would silently drop connectors/MCP. **Use
|
||
`searchCapabilities`.**
|
||
- **`summary` vs structured-candidates confusion** — the tool's return value is markdown; do not parse
|
||
it for the UI. Return the proposal object from the new route.
|
||
- **Keyword-only matching** — no embeddings; verbose/synonym-heavy needs may under-match. Acceptable
|
||
for v1 but the suggestion box may look thin on phrasing mismatch. (`SkillRecommender` has synonym
|
||
expansion; `searchCapabilities` does not.)
|
||
- **Tier gating asymmetry** — marketplace/MCP install is PRO-gated (marketplace.ts:181 `requireTier`),
|
||
starter-pack/skill is free. The suggestion box must reflect this (the inline card already 403→Upgrade,
|
||
CapabilityRequestCard.tsx:55).
|
||
- **Workspace scoping of installs** — marketplace DB is global; the "N in this workspace" framing may
|
||
over-promise isolation that the substrate doesn't provide.
|
||
- **Native tool-name list is closure-local** (index.ts:624) — a route reconstructing deps must not
|
||
drift from the real registered tool set, or agent-pick "already have a tool" answers go stale.
|
||
|
||
---
|
||
|
||
## Open questions for the founder/lead
|
||
|
||
1. **Route shape:** dedicated `POST /api/marketplace/agent-search`, or extend
|
||
`GET /api/marketplace/search` with an `agentPick=true` mode? (The former is cleaner given the verbose
|
||
NL body + structured proposal response.)
|
||
2. **One-of-each-kind vs top-N:** §09 shows exactly connector+skill+tool (3). When a kind has no match
|
||
(e.g. no relevant connector), show 2? Show an empty-kind hint? Define the grouping contract.
|
||
3. **Count bar semantics:** is "N in this workspace" literally per-workspace (needs new
|
||
workspace-scoped install tracking) or is catalog-wide `installedCount` acceptable for v1?
|
||
4. **Suggestion-box "why":** use the engine's `matchReason` (keyword-hit-grade, e.g. "name matches:
|
||
risk") as-is, or have the route pass candidates to the LLM for a one-line natural "why"? The former
|
||
is free + deterministic; the latter is prettier but adds a model call.
|
||
5. **Shared install store ownership:** confirm the frontend "sync" store is a separate PR4 slice that
|
||
agent-pick plugs into (this recon treats it as the integration boundary, not part of Slice 5).
|