copilot-tap-extension 2.0.8 → 2.0.9

package/docs/providers.md

@@ -0,0 +1,242 @@
+# Extending ※ tap with Providers
+
+External processes can register tools with your Copilot session through the **Provider Interface**. A provider connects via WebSocket, authenticates, declares its tools, and handles calls — without knowing anything about the Copilot SDK.
+
+```
+┌─────────────────┐       WebSocket (JSON)       ┌─────────────────┐
+│  ※ tap Gateway   │◄── ws://localhost:9400 ──►   │    Provider      │
+│                  │                              │  (your process)  │
+│ Owns Copilot SDK │  ── sessions ──────────►     │ Knows nothing    │
+│ Runs WS server   │  ◄── auth ─────────────     │ about Copilot    │
+│ Registers tools  │  ── hello.ack ─────────►     │ Declares tools   │
+│ Dispatches calls │  ◄── hello ────────────     │ Handles calls    │
+│                  │  ── tool.call ─────────►     │                  │
+│                  │  ◄── tool.result ──────     │                  │
+│                  │  ◄── push ─────────────     │ Pushes events    │
+│                  │  ◄── tools.update ─────     │ Updates tools    │
+└─────────────────┘                              └─────────────────┘
+```
+
+## Quick start
+
+### 1. Start a Copilot session
+
+The gateway starts automatically on loopback port 9400 (`127.0.0.1`, reachable as `localhost`) when ※ tap loads. It generates an auth token and exposes it in two local-only discovery locations:
+
+- `TAP_PROVIDER_TOKEN` for providers launched with the Copilot environment.
+- `<COPILOT_HOME or ~/.copilot>/extensions/tap/.provider-token` for sibling terminals and SDK auto-discovery.
+
+The token directory is created with restrictive permissions (`0700`), the token file is written as `0600`, and the token file is removed when the gateway stops.
+
+### 2. Write a provider
+
+A provider is any process that speaks the WebSocket protocol. Here's a minimal example in Node.js:
+
+```js
+import WebSocket from "ws";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function discoverToken() {
+  if (process.env.TAP_PROVIDER_TOKEN) return process.env.TAP_PROVIDER_TOKEN;
+  const copilotHome = process.env.COPILOT_HOME || path.join(os.homedir(), ".copilot");
+  return fs.readFileSync(path.join(copilotHome, "extensions", "tap", ".provider-token"), "utf8").trim();
+}
+
+const TOKEN = discoverToken();
+const ws = new WebSocket("ws://localhost:9400");
+
+ws.on("open", () => {
+  ws.send(JSON.stringify({ type: "auth", token: TOKEN }));
+});
+
+ws.on("message", (raw) => {
+  const msg = JSON.parse(raw);
+
+  switch (msg.type) {
+    case "sessions":
+      // Bind to the first available session and register tools
+      ws.send(JSON.stringify({
+        type: "hello",
+        name: "my-provider",
+        protocolVersion: 2,
+        session: msg.active[0].id,
+        tools: [{
+          name: "greet",
+          description: "Greet someone by name",
+          parameters: {
+            type: "object",
+            properties: { name: { type: "string" } },
+            required: ["name"]
+          }
+        }]
+      }));
+      break;
+
+    case "hello.ack":
+      console.log(`Registered as ${msg.providerId}`);
+      break;
+
+    case "tool.call":
+      // Handle the call and return a result
+      ws.send(JSON.stringify({
+        type: "tool.result",
+        id: msg.id,
+        data: `Hello, ${msg.args.name}!`
+      }));
+      break;
+
+    case "tool.cancel":
+      ws.send(JSON.stringify({
+        type: "tool.result",
+        id: msg.id,
+        error: "Cancelled",
+        errorCode: "CANCELLED"
+      }));
+      break;
+
+    case "session.lifecycle":
+      if (msg.state === "shutdown.pending") {
+        ws.send(JSON.stringify({ type: "goodbye", reason: "session ending" }));
+        ws.close();
+      }
+      break;
+
+    case "error":
+      console.error(`[${msg.code}]: ${msg.message}`);
+      break;
+  }
+});
+```
+
+### 3. Run it
+
+```bash
+# If you are in the terminal where Copilot is running, the token is also in env:
+echo $TAP_PROVIDER_TOKEN   # macOS/Linux
+echo %TAP_PROVIDER_TOKEN%  # Windows
+
+# In another terminal, either pass the token explicitly:
+TAP_PROVIDER_TOKEN=ptk-... node my-provider.mjs
+
+# Or let the SDK/sample discover it from
+# <COPILOT_HOME or ~/.copilot>/extensions/tap/.provider-token:
+node my-provider.mjs
+```
+
+Once connected, the `greet` tool appears in Copilot alongside the existing ※ tap tools. Ask Copilot to use it:
+
+> _"Use the greet tool to say hello to Alice"_
+
+## Connection lifecycle
+
+```
+AwaitAuth ──auth──► AwaitHello ──hello──► Bound ──goodbye/disconnect──► Disconnected
+```
+
+1. **AwaitAuth** — Provider sends `auth` with the token. Gateway responds with `sessions` (list of active sessions).
+2. **AwaitHello** — Provider sends `hello` with its name, protocol version, session choice, and tool definitions. Gateway responds with `hello.ack`.
+3. **Bound** — Provider receives `tool.call` messages and responds with `tool.result`. It may also send `push` events or replace its tool list with `tools.update`. Gateway sends `session.lifecycle` events.
+4. **Disconnected** — On `goodbye`, WebSocket close, or crash. All tools are removed and in-flight calls fail.
+
+On `session.lifecycle` with `state: "shutdown.pending"`, send `goodbye` promptly. The gateway keeps existing provider sockets open until `goodbye` or the shutdown deadline, then closes any remaining sockets.
+
+## Message reference
+
+| Direction | Type | When |
+|---|---|---|
+| Provider → Gateway | `auth` | First message — send the token |
+| Gateway → Provider | `sessions` | After auth — pick a session |
+| Provider → Gateway | `hello` | After sessions — register tools |
+| Gateway → Provider | `hello.ack` | Bound — tools are live; includes `providerId` and `sessionId` |
+| Gateway → Provider | `tool.call` | Copilot invokes your tool |
+| Provider → Gateway | `tool.result` | Your response (exactly one per call) |
+| Gateway → Provider | `tool.cancel` | Timeout/interrupt — respond with `CANCELLED` |
+| Provider → Gateway | `push` | Store, surface, or inject a provider event |
+| Provider → Gateway | `tools.update` | Replace this provider's tool list |
+| Gateway → Provider | `session.lifecycle` | Session state changes (`started`, `idle`, `shutdown.pending`) |
+| Gateway → Provider | `error` | Something went wrong |
+| Provider → Gateway | `goodbye` | Before disconnecting |
+
+## Tool definitions
+
+Each tool in the `hello` message needs:
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | yes | Unique tool name (must not conflict with tap tools or other providers) |
+| `description` | yes | What the tool does |
+| `parameters` | yes | JSON Schema object describing the arguments |
+| `timeout` | no | Max execution time in ms |
+
+A provider can register up to **100 tools**.
+
+Bound providers may replace the entire list with:
+
+```json
+{ "type": "tools.update", "tools": [ /* same tool definition shape as hello.tools */ ] }
+```
+
+The update is session-bound: if `sessionId` is supplied it must match the session selected in `hello`. Success is silent and triggers the same debounced tool refresh as provider connect/disconnect. Rejected updates receive `error` (for example `TOOL_CONFLICT`), and the previously registered tool list stays active. In-flight calls to tools removed by an accepted update continue to their normal result, timeout, cancellation, or disconnect outcome.
+
+## Push events
+
+The provider SDK helpers map to bound-provider `push` messages:
+
+```js
+provider.keep("stored in the provider stream only");
+provider.surface("visible in the Copilot timeline");
+provider.push("inject this into the active session");
+```
+
+Wire shape:
+
+```json
+{ "type": "push", "level": "inject", "event": "Browser page asks for help", "stream": "detour" }
+```
+
+`level` must be `keep`, `surface`, or `inject`. `stream` is optional and defaults to the provider name. Pushes are delivered only to the session chosen in `hello`; an optional `sessionId` must match that bound session. `metadata` may be a JSON object and is stored with the event.
+
+## Error handling
+
+| Code | Fatal? | Meaning |
+|---|---|---|
+| `AUTH_FAILED` | Yes | Bad token — connection closes |
+| `UNSUPPORTED_VERSION` | Yes | Wrong `protocolVersion` — connection closes |
+| `INVALID_SESSION` | No | Session ID doesn't exist — pick another |
+| `TOOL_CONFLICT` | No | Tool name already taken — rename and retry |
+| `PAYLOAD_TOO_LARGE` | No | Message exceeds size limit |
+
+Payload limits: `tool.result` max 5 MB, all other messages max 2 MB.
+
+When a bound provider has in-flight `tool.call` messages, malformed JSON,
+oversized messages, or invalid `tool.result` messages that cannot be correlated
+are fail-fast: one pending call is rejected with the protocol error; multiple
+pending calls cause the provider to disconnect and all in-flight calls to fail
+with `DISCONNECTED`.
+
+## Writing providers in other languages
+
+The protocol is plain JSON over WebSocket. Any language with a WebSocket client works. See [the full spec](./docs/recipes/provider-interface-core-profile.md) for a Python example.
+
+## Multiple providers
+
+Multiple providers can connect simultaneously. Each gets its own tool namespace. The gateway debounces tool registration (200ms) so multiple providers connecting at the same time trigger only one reload.
+
+## Dynamic tool registration
+
+When a provider connects or disconnects, ※ tap:
+
+1. Merges all provider tools with the existing tap tools
+2. Calls `session.registerTools()` to update the in-memory handler map
+3. Calls `session.rpc.extensions.reload()` to make the CLI pick up the new tools
+
+This happens automatically — providers just connect and their tools appear.
+
+After binding, providers can also send `tools.update` to replace their own tool list without reconnecting. ※ tap validates the new definitions, rejects conflicts without changing the active list, and uses the same debounced `registerTools()` + extension reload path on success.
+
+## Further reading
+
+- [Core Profile spec](./docs/recipes/provider-interface-core-profile.md) — Full protocol specification with state machine, error codes, and payload limits
+- [Test provider example](./examples/test-provider.mjs) — A runnable example you can try immediately

package/docs/recipes/adaptive-agent.md

@@ -0,0 +1,303 @@
+# Recipe: Adaptive Agent — Self-Tuning Behavior via Session Observation
+
+## The insight
+
+Every Copilot session starts from zero. The AI doesn't know that you corrected it about the import style yesterday. It doesn't know that you always run tests after editing test files. It doesn't know that the last 3 times it suggested `jsonwebtoken`, you replaced it with the project's custom JWT library.
+
+Skills can encode known rules. But they can't **discover** rules by observing what happens in sessions. The Adaptive Agent watches the session — tool calls, user corrections, assistant mistakes — and builds a living knowledge base that rewrites the system prompt via transform callbacks. The agent gets better over time, not because someone wrote instructions, but because the extension observed and learned.
+
+## Why skills can't do this
+
+1. A skill is static text. It can say "use custom JWT library." But someone has to write that rule. The adaptive agent discovers it by watching you replace `jsonwebtoken` twice.
+2. A skill can't watch `assistant.message` events to detect when the AI makes a mistake. The extension can.
+3. A skill can't watch `user.message` events to detect correction patterns ("no, actually..."). The extension can.
+4. A skill can't rewrite its own content. Transform callbacks can modify the system prompt every turn based on accumulated observations.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Copilot CLI session                                         │
+│                                                             │
+│  session.on("user.message") ─────┐                          │
+│  session.on("assistant.message")──┤                          │
+│  onPostToolUse ───────────────────┤                          │
+│                                   ▼                          │
+│                        ┌──────────────────┐                  │
+│                        │  Observer Module  │                  │
+│                        │                  │                  │
+│                        │  Detects:        │                  │
+│                        │  • Corrections   │                  │
+│                        │  • Patterns      │                  │
+│                        │  • Failures      │                  │
+│                        │  • Preferences   │                  │
+│                        └────────┬─────────┘                  │
+│                                 │                             │
+│                                 ▼                             │
+│                        ┌──────────────────┐                  │
+│                        │  Memory Store    │                  │
+│                        │  (workspace/     │                  │
+│                        │   memory.json)   │                  │
+│                        └────────┬─────────┘                  │
+│                                 │                             │
+│                                 ▼                             │
+│                        ┌──────────────────┐                  │
+│                        │  Transform       │                  │
+│                        │  Callbacks       │──► system prompt  │
+│                        │  (every turn)    │   rewritten with  │
+│                        │                  │   learned rules   │
+│                        └──────────────────┘                  │
+└─────────────────────────────────────────────────────────────┘
+         │
+         │ onSessionEnd
+         ▼
+┌──────────────────┐
+│  Distill          │
+│  PromptEmitter    │
+│  (one-time)       │
+│                  │
+│  Summarize what   │
+│  was learned      │
+│  this session     │
+│  → persist to     │
+│  memory.json      │
+└──────────────────┘
+```
+
+## Components
+
+### 1. Observer module (event listeners)
+
+Hooks into three event sources to watch the session:
+
+```js
+// Watch user messages for correction patterns
+session.on("user.message", (event) => {
+  const msg = event.data.content?.toLowerCase() ?? "";
+  // Detect corrections: "no", "actually", "don't use", "wrong", "instead"
+  if (correctionPattern.test(msg)) {
+    observer.recordCorrection({
+      userMessage: event.data.content,
+      // The previous assistant message is what was wrong
+      previousAssistantAction: observer.lastAssistantAction,
+      timestamp: Date.now()
+    });
+  }
+});
+
+// Watch assistant messages to track what the AI does
+session.on("assistant.message", (event) => {
+  observer.lastAssistantAction = {
+    content: event.data.content,
+    toolRequests: event.data.toolRequests
+  };
+});
+
+// Watch tool calls to track workflow patterns
+onPostToolUse: ({ toolName, toolArgs, result }) => {
+  observer.recordToolUse({
+    tool: toolName,
+    args: toolArgs,
+    succeeded: result.type === "success",
+    file: toolArgs?.path || toolArgs?.file,
+    timestamp: Date.now()
+  });
+}
+```
+
+### 2. Pattern detection
+
+The observer accumulates raw events. A PromptEmitter on idle periodically distills patterns:
+
+```
+prompt: |
+  Review these raw observations from the current session and extract
+  durable learnings. Only output learnings that:
+  - Are specific to THIS codebase (not generic advice)
+  - Were demonstrated at least once clearly
+  - Would prevent a future mistake or save time
+
+  Format each as a single instruction sentence.
+  Output nothing if no clear learnings emerged.
+
+  Observations:
+  {{corrections}}
+  {{tool_failures}}
+  {{repeated_sequences}}
+```
+
+Example output:
+```json
+[
+  "Use the custom JWT library at src/lib/jwt.ts instead of jsonwebtoken — user corrected this.",
+  "Always run npm test after editing files in test/ — user does this manually every time.",
+  "The staging environment uses port 3001, not 3000 — the agent used the wrong port twice."
+]
+```
+
+### 3. Memory store (workspace persistence)
+
+Learnings accumulate in `workspace/memory.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "learnings": [
+    {
+      "rule": "Use src/lib/jwt.ts instead of jsonwebtoken for JWT operations",
+      "confidence": 0.9,
+      "observations": 2,
+      "firstSeen": "2026-04-24T10:00:00Z",
+      "lastSeen": "2026-04-25T14:30:00Z",
+      "source": "user-correction"
+    },
+    {
+      "rule": "Run npm test after editing files in test/",
+      "confidence": 0.7,
+      "observations": 3,
+      "firstSeen": "2026-04-24T11:00:00Z",
+      "lastSeen": "2026-04-26T09:00:00Z",
+      "source": "repeated-pattern"
+    },
+    {
+      "rule": "Staging environment is on port 3001",
+      "confidence": 0.8,
+      "observations": 2,
+      "firstSeen": "2026-04-25T14:00:00Z",
+      "lastSeen": "2026-04-25T14:05:00Z",
+      "source": "tool-failure-correction"
+    }
+  ],
+  "lastDistilled": "2026-04-26T09:30:00Z"
+}
+```
+
+### 4. Transform callback (system prompt rewriting)
+
+Every turn, the learned rules are injected into the system prompt:
+
+```js
+registerTransformCallbacks(new Map([
+  ["custom_instructions", (current) => {
+    const memory = readMemoryStore();
+    if (!memory.learnings.length) return current;
+
+    const rules = memory.learnings
+      .filter(l => l.confidence >= 0.6)
+      .sort((a, b) => b.confidence - a.confidence)
+      .slice(0, 15)  // cap to avoid prompt bloat
+      .map(l => `- ${l.rule}`)
+      .join("\n");
+
+    return current + "\n\n" +
+      "## Learned from previous sessions\n\n" +
+      "These rules were learned by observing your corrections " +
+      "and patterns. Follow them unless the user explicitly " +
+      "asks otherwise.\n\n" + rules;
+  }]
+]));
+```
+
+### 5. Session-end distillation
+
+When the session ends, a one-time PromptEmitter reviews the raw observations and updates the memory store:
+
+```js
+onSessionEnd: async () => {
+  const observations = observer.getSessionObservations();
+  if (observations.length === 0) return;
+
+  // Fire a one-time prompt to distill learnings
+  const distilled = await distillLearnings(observations);
+
+  // Merge with existing memory
+  const memory = readMemoryStore();
+  for (const learning of distilled) {
+    const existing = memory.learnings.find(
+      l => semanticallySimilar(l.rule, learning.rule)
+    );
+    if (existing) {
+      existing.confidence = Math.min(1.0, existing.confidence + 0.1);
+      existing.observations += 1;
+      existing.lastSeen = new Date().toISOString();
+    } else {
+      memory.learnings.push({
+        rule: learning.rule,
+        confidence: 0.5,  // new learnings start at 0.5
+        observations: 1,
+        firstSeen: new Date().toISOString(),
+        lastSeen: new Date().toISOString(),
+        source: learning.source
+      });
+    }
+  }
+
+  // Decay old learnings that haven't been reinforced
+  for (const l of memory.learnings) {
+    const daysSinceLastSeen = (Date.now() - new Date(l.lastSeen)) / 86400000;
+    if (daysSinceLastSeen > 30) {
+      l.confidence -= 0.1;
+    }
+  }
+
+  // Prune low-confidence learnings
+  memory.learnings = memory.learnings.filter(l => l.confidence > 0.2);
+  writeMemoryStore(memory);
+}
+```
+
+## Example: How a learning forms
+
+```
+Session 1:
+  Agent suggests: import jwt from 'jsonwebtoken'
+  User says: "no, use the custom one at src/lib/jwt.ts"
+  Observer records: correction, jsonwebtoken → src/lib/jwt.ts
+  Session ends → memory.json gets: { rule: "Use src/lib/jwt.ts...", confidence: 0.5 }
+
+Session 2:
+  Transform callback injects the rule into system prompt
+  Agent correctly uses: import { sign } from './lib/jwt.ts'
+  No correction needed → confidence stays at 0.5
+
+Session 3:
+  Different context — agent is writing a new auth endpoint
+  Agent uses src/lib/jwt.ts without being told
+  User says nothing (implicit approval) → confidence bumps to 0.6
+
+Session 5:
+  Confidence at 0.7. The rule is now firmly established.
+  The agent never makes this mistake again in this repo.
+  Nobody wrote an instruction. It was learned.
+```
+
+## What gets learned (categories)
+
+| Category | Detection method | Example |
+|---|---|---|
+| **Library preferences** | User corrects import/require | "Use date-fns not moment" |
+| **Workflow sequences** | Repeated tool call patterns | "Run tests after editing test files" |
+| **Environment facts** | Tool failures + corrections | "Staging is port 3001" |
+| **Code conventions** | User rewrites AI output | "Use single quotes not double" |
+| **Architecture rules** | User rejects suggestions | "Don't put business logic in controllers" |
+| **Command preferences** | User overrides commands | "Use pnpm not npm in this repo" |
+
+## Phased delivery
+
+| Phase | Scope |
+|---|---|
+| **1. Observer + raw logging** | Hook into user.message, assistant.message, onPostToolUse. Log to EventStream. |
+| **2. Memory store** | workspace/memory.json with read/write. Load on session start. |
+| **3. Transform callback** | Inject learned rules into custom_instructions section every turn. |
+| **4. Session-end distillation** | PromptEmitter at session end to distill raw observations into learnings. |
+| **5. Confidence decay** | Time-based decay for stale learnings. Reinforcement on reuse. |
+| **6. User control** | Tool to list/remove/edit learned rules: `tap_memory_list`, `tap_memory_forget`. |
+
+## Open questions
+
+- **Privacy** — learnings are repo-scoped by default. Should they ever be user-global?
+- **Conflict resolution** — what if two sessions produce contradictory learnings?
+- **Prompt budget** — how many learned rules before the system prompt gets too long? Cap at 15? 20?
+- **Semantic similarity** — how to detect that two rules are about the same thing? Exact match? Embedding?
+- **Observation quality** — not every "no" is a correction. How to reduce false positives?
+- **User trust** — should learned rules be surfaced for approval before taking effect?