summary: "Overview and quickstart for monorepo package @tryinget/pi-toolbox-discovery." read_when:

• "Starting work in this package workspace." system4d: container: "Monorepo package scaffold for pi extension delivery." compass: "Ship safe package-level iterations inside a shared workspace." engine: "Plan -> implement -> validate -> coordinate with monorepo release flow." fog: "Drift risk if package scripts diverge from monorepo root conventions."

@tryinget/pi-toolbox-discovery

Custom-tool discovery and active-set broker for Pi sessions.

The package registers:

• /toolbox — human-visible status command
• toolbox — model-callable discovery/planning/activation/doctor tool

toolbox does not import owner packages or create missing owner-tool registrations. It discovers the catalog, verifies which tools are registered in the current Pi runtime, and manages the active set with risk gates. For already-registered tools, activation updates Pi's active tool set immediately, queues a same-task continuation when the active set changes, and is intended to be visible on the next provider/model request after the toolbox result. It cannot retroactively change an already-issued provider request or an external API/client schema snapshot.

The package keeps self, interview, dispatch_subagent, intercom, Prompt Vault read tools (vault_query, vault_retrieve, vault_vocabulary, vault_dispatch_check), the lightweight context planning tool (context_plan), pi-little-helpers peer-spawn tools (fork_peer_spawn, scout_peer_spawn, candidate_peer_spawn), the visible-loop checkpoint fallback (visible_loop_child_complete), the orchestrator loop dispatcher (loop_execute), and toolbox as foundational always-active custom tools while letting heavier package-owned tools and Prompt Vault diagnostics/mutations remain latent until explicitly activated. Current behavior:

• verifies the standard active tool set on session_start and clears prior lease bookkeeping only after host readback confirms the baseline
• searches/explains catalog metadata, recommends next-best matching bundle/profile choices, and plans activation without importing owner packages
• plans every activation through one policy path before changing active tools, including raw tools: [...] requests
• activates already-registered bundle profiles and explicit tool lists only after risk gates pass; non-catalog explicit tools are treated as high-risk and require a caller-supplied riskAcknowledged plus riskJustification declaration. This is an advisory gate and audit hint, not proof of operator consent
• treats active-set changes as verified host transactions: it snapshots the exact pre-operation set, applies the desired set, compares semantic readback, and attempts exact rollback before changing leases or queueing activation continuation when the host throws, silently no-ops, or partially applies a mutation
• queues an extension-origin same-task continuation after activation changes the active tool set, unless autoContinue: false is passed
• fails closed when requested tools are not registered in the current Pi session, with instructions to enable/install the owner extension and /reload or start a fresh session
• tracks unpinned activation TTLs across turns and preserves pinned activations until explicit deactivation
• reports catalog registration gaps separately from active-set/lease problems
• preserves prior lease bookkeeping when startup baseline registration lookup or active-set verification fails, and clears it only after the standard baseline is verified
• provides toolbox({ action: "doctor" }) as an evaluative startup-health check covering the always-active baseline, catalog registration completeness, active leases, unleased active catalog tools, and leased tools that are no longer active

The package-owned production bundles are vault, context-packer, sci, ontology, designmd, autoresearch, orchestrator, agent_vent, and peer-spawn. Their tools must be registered by the owning package's Pi extension entry before toolbox activation; toolbox activation only changes the active set. The context-packer read profile includes packet planning, bounded packet assembly, packet-local dogfood receipt evaluation, and non-persistent aggregate summarization; it does not make dogfood observations canonical evidence.

The orchestrator bundle defaults to its read profile, which includes the owner-registered direction_controller_readback alongside bounded society, boundary-telemetry, and ontology context reads. D2E and direction-controller catalog searches expose the bundle, while read-focused recommendations select this profile without activating it. If any selected read-profile tool is not registered, Toolbox refuses the entire activation before changing the active set, recording leases, or queueing a continuation; enable/install pi-society-orchestrator and /reload or start a fresh session instead. Verified activation may independently restore a missing foundational always-active tool such as loop_execute; that baseline repair is not D2E read-profile membership or new workflow authorization. Selected-profile activation grants no AK, DSPx, dispatch, transition-apply, or workflow-execution authority and does not prove the owner tool's runtime semantics; those remain owned and validated by pi-society-orchestrator.

The sci bundle exposes only composite workflows, not SCI's primitive registry. Its read profile activates explore_symbol_impact and locate_confirm_definition. Its risk-gated mutating profile activates preview-only snapshot/check workflows whose Pi schemas omit apply; the gate remains necessary because caller-selected local check commands can have effects.

agent_vent is intentionally a diagnostic/local-write bundle: activation can expose the same-named agent_vent tool for self.diagnostic_candidate.v1 payloads or recurring friction. After activation, use agent_vent action=preview before action=record for self-suggested candidates so the anti-junk quality check can reject low-signal payloads without writing local JSONL. A later record may append local JSONL vent records, but it does not create AK tasks, GitHub issues, real incidents, canonical evidence, external telemetry, or ASC/self state. See Self, toolbox, and agent_vent diagnostic boundary for the cross-package handoff contract.

Standard startup contract

After a clean /reload, the expected healthy baseline is:

active tools (19): read, bash, edit, write, self, interview, dispatch_subagent, intercom, vault_query, vault_retrieve, vault_vocabulary, vault_dispatch_check, fork_peer_spawn, scout_peer_spawn, candidate_peer_spawn, visible_loop_child_complete, context_plan, loop_execute, toolbox
missing catalog registrations (0): none

Use toolbox({ action: "recommend", query: "<task/capability>" }) when you know the task but not the package-owned tool bundle. Recommendations are read-only and never activate tools; activation remains an explicit follow-up.

Use the model-callable doctor when validating settings or package changes:

toolbox({ action: "doctor" })

Expected healthy signals:

verdict: pass      # or warn when only optional catalog bundles are missing
foundational baseline: ok
unleased active catalog tools (0): none

Missing catalog registrations are warnings when the baseline is healthy because optional owner packages may be filtered/disabled in a given Pi runtime. Enable/install the owning package extension and /reload or start a fresh session before activating those optional bundles. If doctor reports unleased active catalog tools, deactivate them or reactivate them through toolbox so TTL/pin state is explicit. If activation succeeds but an outer API client still cannot call the tool after the queued continuation, treat that as a client schema snapshot limitation and reload/start a fresh session after confirming the owner extension is installed.

Activation continuation and cache behavior

toolbox({ action: "activate" }) changes the active tool set through Pi and then, when the active set actually changed, queues an extension-origin continuation message with deliverAs: "steer" and triggerTurn: true. The continuation is not a fake user command; it is a same-task nudge that lets Pi issue another provider/model request after the refreshed active-tool schema is available. Use autoContinue: false for activation-only calls.

Changing active tools changes the provider tool-schema prefix. The first request for a newly active tool combination may therefore miss or write a new provider prompt-cache entry. Later requests with the same active-tool combination can reuse cache again. Avoid repeated activate/deactivate oscillation if cache stability matters.

Activation continuation is queued only after pi.getActiveTools() verifies the complete intended set. If verification fails, toolbox attempts to restore the exact pre-operation set, keeps lease state unchanged, suppresses continuation, and reports whether rollback was verified. A failed rollback means runtime state is degraded or unknown: run toolbox({ action: "doctor" }) and /reload before relying on tool visibility. Deactivation, TTL expiry, and startup baseline application use the same verified mutation membrane.

Tool registration invariant

toolbox({ action: "activate" }) can only choose from pi.getAllTools() and update the active set. A missing tool is not a recoverable activation problem; it is an owner-extension installation/settings/reload problem.

Pi core supports runtime tool registration by owner extensions, but toolbox intentionally does not dynamically import owner packages to register their tools. For model-callable tools that should be cheap to expose, owner packages should register a lightweight tool schema and lazy-load heavy implementation inside execute, not rely on toolbox to register the tool itself.

• Workspace path: packages/pi-toolbox-discovery
• Release component key: pi-toolbox-discovery
• Release config mode: component

Runtime dependencies

This package expects pi host runtime APIs and declares them as peerDependencies:

• @earendil-works/pi-coding-agent
• @earendil-works/pi-ai

When using UI APIs (ctx.ui), guard interactive-only behavior with ctx.hasUI so pi -p non-interactive runs stay stable.

Package checks

Run from package directory:

npm install
npm run check

Run from monorepo root through the canonical package gate:

bash ./scripts/package-quality-gate.sh ci packages/pi-toolbox-discovery

The generated package-local scripts/quality-gate.sh is a thin wrapper that searches upward for the canonical monorepo root gate. If you validate the package outside the monorepo tree, set PACKAGE_QUALITY_GATE_SCRIPT to the canonical pi-extensions root gate path.

AK task/work-item operations

This package is a monorepo member, not a git root. Use the plain installed ak CLI for task/work-item operations. The monorepo root remains the repo identity even when commands run from this package directory:

ak --doctor
ak task ready
ak task show <id> -F json

Documentation placement

Use:

• docs/project/ for dated RFCs, runbooks, and evidence/progress notes
• docs/adr/ for adopted architecture decisions

Avoid creating new package-local docs/dev/ trees.

Live package activation

Install the package into Pi from the package directory containing this package's package.json:

pi install /absolute/path/to/your/monorepo/packages/pi-toolbox-discovery

Then in Pi:

1. run /reload
2. verify with a real command or tool call from this package

Release metadata

This scaffold writes component metadata in package.json under x-pi-template:

• workspacePath
• releaseComponent
• releaseConfigMode

Use these values when wiring monorepo-level release-please component maps.

Docs discovery

npm run docs:list
npm run docs:list:workspace
npm run docs:list:json

Stack lane companions

This package follows the shared pi-ts lane. Add companions only when they materially improve clarity or reuse:

• fast-check for parser/rendering/selection invariants
• @cucumber/cucumber for executable Gherkin/operator workflows
• nunjucks for reusable text/config/prompt/file templates
• engineering-pi-ts.ts-quality.md when the package explicitly adopts deterministic screening with ts-quality

If this package adopts ts-quality, prefer repo-local rollout truth in docs/project/ts-quality-current-vs-target.md and keep the detailed adoption doctrine upstream in ~/ai-society/softwareco/owned/ts-quality/docs/adoption/.

Copier lifecycle policy

• Keep .copier-answers.yml committed.
• Do not edit .copier-answers.yml manually.
• Run update/recopy from a clean destination repo (commit or stash pending changes first).
• Use copier update --trust when .copier-answers.yml includes _commit and update is supported.
• In non-interactive shells/CI, append --defaults to update/recopy.
• Use copier recopy --trust when update is unavailable (for example local non-VCS source) or cannot reconcile cleanly.
• After recopy, re-apply local deltas intentionally and run npm run check.