copilot-tap-extension 2.0.7 → 2.0.9

package/docs/recipes/universal-tool-gateway.md

@@ -0,0 +1,202 @@
+# Recipe: Universal Tool Gateway — Dynamic Capabilities via Script Injection
+
+## The insight
+
+Detour injects arbitrary JS into any web page. `session.registerTools()` adds tools to Copilot at runtime. Combine them: **any script, in any environment, can expose capabilities to Copilot dynamically.**
+
+Instead of building separate extensions with hardcoded tools, tap becomes a **runtime tool gateway**. Connected clients announce tool definitions over WebSocket, tap materializes them in the Copilot session. When clients disconnect, their tools vanish.
+
+## Architecture
+
+```
+                        ┌─────────────────────────────┐
+                        │  Copilot CLI session         │
+                        │                             │
+                        │  ※ tap (tool gateway)        │
+                        │  session.registerTools(...)  │
+                        └──────────┬──────────────────┘
+                                   │ ws
+                        ┌──────────▼──────────────────┐
+                        │  Bridge Server               │
+                        │  ws://localhost:9400          │
+                        └──┬──────┬──────┬──────┬─────┘
+                           │      │      │      │
+                    ┌──────▼┐ ┌───▼───┐ ┌▼────┐ ┌▼──────────┐
+                    │Browser│ │Electron│ │Node │ │Any process │
+                    │(Detour)│ │ app   │ │script│ │with WS    │
+                    └───────┘ └───────┘ └─────┘ └───────────┘
+```
+
+Every connected client is just a script that:
+1. Opens a WebSocket to the bridge
+2. Sends a `hello` with its tool definitions
+3. Handles tool invocations when Copilot calls them
+4. Optionally pushes events (→ tap emitter → Copilot session)
+
+## How tool definitions travel over the wire
+
+### Client announces capabilities
+
+```json
+{
+  "type": "hello",
+  "role": "provider",
+  "name": "my-app",
+  "tools": [
+    {
+      "name": "app_get_user",
+      "description": "Get the currently logged-in user from the app",
+      "parameters": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "app_search",
+      "description": "Search the app's data",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string" }
+        },
+        "required": ["query"]
+      }
+    }
+  ]
+}
+```
+
+### tap materializes tools in Copilot
+
+When a provider connects, tap:
+1. Reads the tool definitions from the `hello` message
+2. Creates handler functions that route calls through the bridge
+3. Calls `session.registerTools([...existingTools, ...newTools])`
+4. Copilot immediately sees the new tools
+
+When a provider disconnects, tap re-registers without those tools.
+
+### Copilot calls a dynamic tool
+
+```
+User: "who is logged in?"
+
+Copilot calls: app_get_user({})
+  → tap routes to bridge
+    → bridge routes to "my-app" provider
+      → provider executes, returns { user: "alice" }
+    → bridge routes response back
+  → tap returns result to Copilot
+
+Copilot: "The logged-in user is alice."
+```
+
+## What this enables
+
+### Browser pages (via Detour)
+
+Inject a bridge client script into any web page. The script announces tools based on what's available in that page's context.
+
+```js
+// Injected into a React app — announces React-specific tools
+bridge.announce({
+  tools: [
+    { name: "react_component_tree", description: "Get the React component tree" },
+    { name: "react_state", description: "Read React state for a component" },
+    { name: "page_screenshot", description: "Screenshot the viewport" }
+  ]
+});
+```
+
+### Electron / desktop apps
+
+Any Electron app can include a bridge client. Copilot gets tools to read app state, trigger actions, inspect UI.
+
+### Internal tools and dashboards
+
+Inject a bridge client into your company's admin dashboard. Copilot can now query production data, check deployment status, read monitoring dashboards — all through dynamically registered tools.
+
+### CI/CD and DevOps
+
+A bridge client in your CI pipeline announces build/deploy tools. Copilot can trigger deploys, check build status, read test results.
+
+### Other terminal processes
+
+A Node script or Python process connects to the bridge and exposes domain-specific tools. A data pipeline announces query tools. A test runner announces result inspection tools.
+
+## Protocol
+
+### Messages
+
+| Type | Direction | Purpose |
+|---|---|---|
+| `hello` | provider → bridge | Announce name + tool definitions |
+| `tools.update` | provider → bridge | Update tool definitions (add/remove) |
+| `tool.call` | bridge → provider | Copilot invoked a tool, execute it |
+| `tool.result` | provider → bridge | Return tool execution result |
+| `push` | provider → bridge | Unsolicited event (→ tap emitter) |
+| `goodbye` | provider → bridge | Graceful disconnect, remove tools |
+
+### Tool call flow
+
+```
+Copilot → tap handler → bridge.request("tool.call", { provider, tool, args })
+  → bridge routes to provider
+  → provider executes
+  → provider sends tool.result
+  → bridge routes back
+  → tap handler returns result to Copilot
+```
+
+## The bridge client SDK
+
+A tiny JS module (~50 lines) that any script includes to become a provider:
+
+```js
+import { createBridgeClient } from "copilot-bridge-client";
+
+const bridge = createBridgeClient({
+  url: "ws://localhost:9400",
+  name: "my-app"
+});
+
+bridge.tool("get_user", "Get the current user", {}, async () => {
+  return { user: getCurrentUser() };
+});
+
+bridge.tool("search", "Search data", {
+  query: { type: "string" }
+}, async ({ query }) => {
+  return await searchDatabase(query);
+});
+
+bridge.connect();
+```
+
+That's it. Copilot now has `get_user` and `search` tools.
+
+## Implications
+
+1. **Extensions become optional.** Instead of packaging tools into a Copilot extension, any running process can expose tools dynamically.
+2. **Capabilities are composable.** Open a React app in Chrome → React tools appear. Start a deploy script → deploy tools appear. Tools come and go based on what's running.
+3. **Skills become injectable.** A provider can also send context/instructions along with tools, giving Copilot domain knowledge about how to use them.
+4. **tap becomes a tool multiplexer.** Its core job shifts from "emitter runtime" to "dynamic tool gateway that routes between Copilot and any connected service."
+
+## Relationship to MCP
+
+This is the inverse of MCP (Model Context Protocol):
+- **MCP**: Copilot connects to external servers that expose tools
+- **Bridge**: External services connect to Copilot (via tap) and expose tools
+
+The bridge pattern is more dynamic — tools appear and disappear based on runtime state. And the provider can be anything that runs JS (browser tab, Electron, Node, etc.) with zero infrastructure beyond the bridge relay.
+
+## Phased delivery
+
+| Phase | Scope |
+|---|---|
+| **1. Bridge server + protocol** | WebSocket relay, hello/tool.call/tool.result messages |
+| **2. tap integration** | Dynamic registerTools on provider connect/disconnect |
+| **3. Bridge client SDK** | Tiny JS module for providers to include |
+| **4. Detour recipe** | Example: inject bridge client into a web page via Detour |
+| **5. Push events** | Provider → tap emitter pipeline for unsolicited events |
+| **6. Context injection** | Providers send instructions/context alongside tools |

package/docs/reference.md

@@ -0,0 +1,229 @@
+# Reference
+
+Technical reference for copilot-tap-extension. For a quick overview, see the [README](../README.md).
+
+## Canonical vocabulary
+
+These terms are used consistently across the code, tool descriptions, and config schema.
+
+| Term | Meaning |
+| --- | --- |
+| `emitter` | A running background unit (CommandEmitter or PromptEmitter) |
+| `stream` | Named EventStream storing accepted emitter output and notes |
+| `sessionInjector` | Per-stream proactive delivery state |
+| `eventFilter` | Ordered rule list on the emitter: `[{ match, outcome }]` |
+| `emitterType` | Work source: `command` or `prompt` |
+| `lifespan` | `temporary` (session-only) or `persistent` (written to config) |
+| `ownership` | `userOwned` (protected) or `modelOwned` (agent can tune) |
+| `runSchedule` | `continuous`, `timed`, or `oneTime` |
+| `runInterval` | Repeat interval for timed work (e.g. `5m`, `2h`) |
+| `autoStart` | Whether a persistent emitter starts automatically next session |
+
+## Emitter types
+
+| Type | Definition | Best for |
+| --- | --- | --- |
+| **Continuous Command** | `command` only | Log tails, watch scripts, long-running jobs |
+| **Timed Command** | `command` + `runInterval` | API polling, recurring validators |
+| **One-shot Prompt** | `prompt` only | Background agent check (runs once) |
+| **Timed Prompt** | `prompt` + `runInterval` | `/tap-loop`-style maintenance tasks |
+
+## Event outcomes
+
+Each EventFilter rule maps a regex to one of four outcomes (first match wins):
+
+| Outcome | Behavior |
+| --- | --- |
+| `drop` | Discard — does not enter the EventStream |
+| `keep` | Store in the EventStream |
+| `surface` | Keep + show in session timeline via `session.log()` |
+| `inject` | Keep + surface + inject into Copilot via `session.send()` |
+
+PromptEmitter events always inject (bypass the EventFilter).
+
+## Event processing pipeline
+
+```
+Emitter output
+    |
+    v
+EventFilter (first match wins)
+    |-- drop    → discarded
+    |-- keep    → stored in EventStream
+    |-- surface → stored + shown in timeline
+    +-- inject  → stored + shown + injected into session
+    |
+    +-- no match → default: keep
+
+PromptEmitter events always inject (bypass EventFilter)
+```
+
+Start with no filter rules (keep-all bootstrap), observe the stream with `tap_stream_history`, then progressively add rules to drop noise and inject signal.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `tap_start_emitter` | Start a background emitter (command, prompt, or timed) |
+| `tap_stop_emitter` | Stop an emitter |
+| `tap_list_emitters` | Show all running + persistent emitters |
+| `tap_set_event_filter` | Update filter rules on a running emitter |
+| `tap_stream_history` | Read recent EventStream entries |
+| `tap_post` | Append a note to any EventStream |
+| `tap_list_streams` | List all EventStreams + injector state |
+| `tap_enable_injector` | Enable proactive session delivery |
+| `tap_disable_injector` | Disable proactive delivery |
+| `tap_open_diagnostics_canvas` | Open/focus the live diagnostics canvas |
+| `tap_get_session_state` | Read current Copilot mode/model/tasks/schedules/canvas state |
+| `tap_set_session_mode` | Guarded session mode switch with explicit confirmation |
+| `tap_query_records` | Read structured tap records persisted in the session workspace |
+| `tap_verify_goal_output` | Verify goal evidence from files, streams, or caller-supplied command evidence |
+| `tap_audit_claims` | Audit structured goal claims against concrete evidence surfaces |
+
+## Diagnostics canvas
+
+Tap declares an experimental Copilot SDK canvas named `tap-diagnostics`. Open it with:
+
+```text
+tap_open_diagnostics_canvas
+```
+
+The canvas is a bounded local flight recorder for:
+
+- EventStreams and recent entries
+- running and configured emitters
+- EventFilter and SessionInjector state
+- provider gateway state and registered tools
+- notification queue state
+- emitter-run traces and goal ledger streams
+- current eval/control-plane evidence when available
+- tap runtime logs
+- recent SDK session events
+
+The renderer is served from a loopback-only ephemeral HTTP server and is closed when the canvas instance closes. Sensitive gateway token values are redacted, and retained event payloads are bounded so the canvas stays responsive.
+
+## Loop semantics
+
+The extension supports session-scoped timed schedules:
+
+- `runInterval: "5m"` re-runs work on a fixed interval
+- Commands with `runInterval` re-run after each completion
+- Timed PromptEmitters fire immediately, then repeat on the interval
+- Prompts without `runInterval` run once
+- Timed schedules do not catch up missed runs
+- If a timed PromptEmitter fires while the session is busy, that run defers to the next interval
+- Persistent config restores the emitter next session, but this is not a durable cloud scheduler
+
+The repo also ships a **`tap-loop` skill** (`src/skills/tap-loop`) for quick setup:
+
+```text
+/tap-loop 5m check the deploy
+```
+
+For long-horizon work, the repo also ships a **`tap-goal` skill**
+(`src/skills/tap-goal`). A goal is explicit, status/control commands are
+user-owned, and completion should only be reported when the objective is
+actually achieved. In ※ tap it is implemented as a PromptEmitter with a required
+iteration budget. Conservative goals use `every="idle"`; autopilot-compatible
+goals use a timed backoff schedule such as `everySchedule=["2m","5m","10m"]` so
+the objective can keep nudging the session while Copilot may stay busy.
+
+A strong tap goal follows the Codex-style goal contract: outcome, verification
+surface, constraints, boundaries, iteration policy, and blocked stop condition.
+Each iteration self-steers by reading its own emitter state, posts a structured
+iteration record to its EventStream, validates against concrete evidence when
+relevant, and shifts into wrap-up mode when the remaining budget is low. Budget
+exhaustion is a handoff state, not success:
+
+```text
+/tap-goal migrate the repo to the new API and keep going until tests pass
+```
+
+## Ownership model
+
+Ownership lives on the EventEmitter only. EventStream and SessionInjector are derived.
+
+- **`userOwned`** — protected; the model must pass `transferOwnership=true` to override
+- **`modelOwned`** — safe for the model to adjust during the session
+
+## Usage patterns
+
+### Watch something temporarily
+
+```
+lifespan="temporary"
+subscribe=true
+EventFilter: [{ "match": "error|warning|ready", "outcome": "inject" }, { "match": ".*", "outcome": "drop" }]
+```
+
+### Persistent deploy watcher
+
+```
+lifespan="persistent"
+autoStart=true
+ownership="userOwned"
+```
+
+### Let the model tune noise
+
+Use `ownership="modelOwned"` on a temporary emitter so the agent can adjust the EventFilter during the task.
+
+## Example config
+
+```json
+{
+  "streams": [
+    {
+      "name": "ops",
+      "description": "Operational events from background emitters",
+      "sessionInjector": {
+        "enabled": true,
+        "delivery": "important",
+        "ownership": "userOwned"
+      }
+    },
+    {
+      "name": "repo-maintenance",
+      "description": "Prompt-based maintenance loop",
+      "sessionInjector": {
+        "enabled": true,
+        "delivery": "important",
+        "ownership": "userOwned"
+      }
+    }
+  ],
+  "emitters": [
+    {
+      "name": "heartbeat",
+      "description": "Demo background status stream",
+      "command": "node ./examples/heartbeat.mjs",
+      "stream": "ops",
+      "autoStart": true,
+      "includeStderr": true,
+      "ownership": "userOwned",
+      "eventFilter": [
+        { "match": "booting", "outcome": "drop" },
+        { "match": "ready|healthy", "outcome": "surface" },
+        { "match": "warning|error", "outcome": "inject" },
+        { "match": ".*", "outcome": "keep" }
+      ]
+    },
+    {
+      "name": "repo-maintenance",
+      "description": "Prompt-based loop for repo health checks",
+      "prompt": "Check whether there are new failing runs, PR review comments, or issue escalations worth addressing. Summarize only actionable changes.",
+      "runInterval": "15m",
+      "stream": "repo-maintenance",
+      "autoStart": false,
+      "ownership": "userOwned"
+    }
+  ]
+}
+```
+
+## Limits
+
+- Extension-level approximation, not a native runtime primitive.
+- In-memory state resets on `/clear`.
+- Notifications are batched to reduce spam.
+- Emitters run with the extension's trust level — only run commands you trust.