copilot-tap-extension 2.0.8 → 2.0.9

package/docs/recipes/ambient-guardian.md

@@ -0,0 +1,314 @@
+# Recipe: Ambient Guardian — Continuous Background Intelligence
+
+## The insight
+
+Skills fire when invoked. tap fires when something happens. The gap between these two is **time** — the 30 seconds between a teammate's force-push and your next `git push` that will conflict. The 90 seconds between a deploy and the error spike it causes. The silent period while CI is failing and you're still writing code that depends on it passing.
+
+The Ambient Guardian is a pattern where tap maintains a continuous awareness of your environment and interrupts **only when something needs your attention right now**. Not a dashboard. Not a notification system. A runtime that understands what you're doing and correlates it with what's happening around you.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  Copilot CLI session                                      │
+│                                                          │
+│  ┌─────────────────────────────────────────────────────┐ │
+│  │  Ambient Guardian (tap extension layer)              │ │
+│  │                                                     │ │
+│  │  onPreToolUse ──► gate actions against live state    │ │
+│  │  onPostToolUse ──► track what you're working on     │ │
+│  │  transform callbacks ──► rewrite rules per context  │ │
+│  └────────┬───────────┬───────────┬────────────────────┘ │
+│           │           │           │                       │
+│  ┌────────▼──┐ ┌──────▼───┐ ┌────▼──────┐               │
+│  │ Emitter:  │ │ Emitter: │ │ Emitter:  │               │
+│  │ git state │ │ CI watch │ │ env probe │               │
+│  │ (30s poll)│ │ (gh api) │ │ (custom)  │               │
+│  └────────┬──┘ └──────┬───┘ └────┬──────┘               │
+│           │           │          │                        │
+│  ┌────────▼───────────▼──────────▼──────┐                │
+│  │  Correlation PromptEmitter (idle)     │                │
+│  │  Reads all streams, finds patterns,   │                │
+│  │  decides what to surface              │                │
+│  └───────────────────────────────────────┘                │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Why skills can't do this
+
+A skill can check CI status when you ask. But:
+
+1. You don't ask until you're about to push — by then you've built on a broken foundation for 20 minutes.
+2. A skill can't correlate a deploy, an error spike, and a PR comment that happened 90 seconds apart. It sees one thing at a time.
+3. A skill can't physically block a `git push` mid-execution. `onPreToolUse` can.
+4. A skill can't rewrite the system prompt to say "be conservative, production is degraded." Transform callbacks can.
+
+The value is in what happens **between user messages** — the silence when nobody is asking questions but the world is changing.
+
+## Components
+
+### 1. Environment emitters (the eyes)
+
+Three CommandEmitters running continuously:
+
+**Git state watcher** — polls every 30 seconds:
+```bash
+git fetch --quiet 2>/dev/null; \
+echo "branch=$(git branch --show-current)"; \
+echo "ahead=$(git rev-list --count @{u}..HEAD 2>/dev/null || echo 0)"; \
+echo "behind=$(git rev-list --count HEAD..@{u} 2>/dev/null || echo 0)"; \
+echo "dirty=$(git status --porcelain | wc -l)"; \
+echo "conflicts=$(git diff --name-only --diff-filter=U | wc -l)"
+```
+
+**CI watcher** — polls GitHub Actions:
+```bash
+gh run list --branch $(git branch --show-current) --limit 3 --json status,conclusion,name,createdAt
+```
+
+**Deploy/infra probe** — customizable per project (Kubernetes, AWS, Vercel, etc.):
+```bash
+kubectl get pods -l app=myservice --no-headers | awk '{print $1, $3, $4, $5}'
+```
+
+### 2. EventFilter rules (noise control)
+
+```json
+[
+  { "match": "behind=0",          "outcome": "drop"    },
+  { "match": "dirty=0",           "outcome": "drop"    },
+  { "match": "conflicts=[1-9]",   "outcome": "inject"  },
+  { "match": "behind=[1-9]",      "outcome": "surface" },
+  { "match": "status.*failure",   "outcome": "inject"  },
+  { "match": "CrashLoopBackOff",  "outcome": "inject"  },
+  { "match": ".*",                "outcome": "keep"    }
+]
+```
+
+Most polls produce nothing interesting → dropped. Only real signals break through.
+
+### 3. Correlation engine (the brain)
+
+A PromptEmitter on idle schedule that reads across all streams:
+
+```
+prompt: |
+  You are a background correlation engine. Read the recent events
+  from all streams and look for patterns:
+  - Did something change in one stream that explains an event in another?
+  - Is there a time correlation between events across streams?
+  - Is the developer's current work going to collide with something
+    that just happened?
+
+  Only report if you find a genuine correlation. Say nothing if
+  everything looks normal. Be terse — one sentence max.
+
+  Stream history:
+  {{git_stream_last_10}}
+  {{ci_stream_last_10}}
+  {{deploy_stream_last_10}}
+```
+
+### 4. Action gating (onPreToolUse)
+
+Before tool calls execute, the guardian checks live state:
+
+```js
+onPreToolUse: async ({ toolName, toolArgs }) => {
+  // Block push if CI is failing
+  if (toolName === "shell" && isGitPush(toolArgs.command)) {
+    const ciState = streams.latest("ci-watch");
+    if (ciState?.includes("failure")) {
+      return {
+        permissionDecision: "deny",
+        permissionDecisionReason:
+          "CI is currently failing on this branch. Fix the failing " +
+          "tests before pushing, or the failure will block the PR."
+      };
+    }
+  }
+
+  // Warn before editing files that have upstream changes
+  if (toolName === "edit") {
+    const gitState = streams.latest("git-watch");
+    if (gitState?.behind > 0) {
+      return {
+        additionalContext:
+          `Warning: your branch is ${gitState.behind} commits behind ` +
+          `origin. The file you're editing may have upstream changes. ` +
+          `Consider pulling first.`
+      };
+    }
+  }
+}
+```
+
+### 5. Context-adaptive system prompt (transform callbacks)
+
+```js
+registerTransformCallbacks(new Map([
+  ["code_change_rules", (current) => {
+    const branch = streams.latest("git-watch")?.branch;
+    const ciStatus = streams.latest("ci-watch")?.status;
+    const deploying = streams.latest("deploy-watch")?.deploying;
+
+    const additions = [];
+
+    if (branch === "main" || branch === "master") {
+      additions.push(
+        "You are on the production branch. Require explicit user " +
+        "confirmation before any file write. Suggest a feature branch."
+      );
+    }
+
+    if (ciStatus === "failure") {
+      additions.push(
+        "CI is currently failing. Prioritize fixing tests over new features."
+      );
+    }
+
+    if (deploying) {
+      additions.push(
+        "A production deploy is in progress. Do not suggest database " +
+        "migrations or infrastructure changes until it completes."
+      );
+    }
+
+    return additions.length > 0
+      ? current + "\n\n" + additions.join("\n")
+      : current;
+  }]
+]));
+```
+
+## Example scenarios
+
+### Scenario A: The silent conflict
+
+```
+You're writing code on feature/auth (10 minutes in)
+    │
+    ▼
+Git emitter detects: branch is now 2 commits behind origin
+    │
+    ▼
+EventFilter: behind=[1-9] → surface
+    │
+    ▼
+Timeline shows: "※ tap: feature/auth is 2 commits behind origin"
+    │
+    ▼
+You keep working (it's just a surface, not an inject)
+    │
+    ▼
+5 minutes later, you ask Copilot to edit src/auth.ts
+    │
+    ▼
+onPreToolUse fires → checks git state → one of the upstream
+  commits touched src/auth.ts
+    │
+    ▼
+Copilot receives: "Warning: src/auth.ts was modified in an upstream
+  commit (abc123 by Alice, 7 min ago). Your edit may conflict.
+  Consider pulling first."
+    │
+    ▼
+You pull, resolve cleanly, then continue. Saved 20 minutes of
+  merge conflict debugging.
+```
+
+### Scenario B: The cascading failure
+
+```
+3 events arrive over 90 seconds:
+
+  2:01pm — deploy emitter: "v2.4.2 deployed to prod"
+  2:02pm — CI emitter: "staging pipeline failed: connection refused"
+  2:03pm — deploy emitter: "pod auth-service restart count: 4"
+    │
+    ▼
+Correlation PromptEmitter (idle) reads all streams:
+    │
+    ▼
+Injects: "Deploy v2.4.2 is causing auth-service crash loops
+  (4 restarts in 2 min). Staging CI is failing with connection
+  refused — likely same root cause. Consider rolling back."
+    │
+    ▼
+Meanwhile, transform callback has already added to system prompt:
+  "Production is degraded. Do not suggest changes to auth-service
+   configuration. Prioritize investigation and rollback."
+    │
+    ▼
+You say: "rollback" — Copilot already knows the context,
+  runs the rollback command immediately.
+```
+
+### Scenario C: The preemptive gate
+
+```
+You ask Copilot: "push my changes"
+    │
+    ▼
+onPreToolUse fires for shell(git push)
+    │
+    ▼
+Guardian checks:
+  ✗ CI status: failure (test/auth.spec.ts)
+  ✗ Uncommitted files: 2 files not in this branch's scope
+  ✓ Branch: feature/auth (not main)
+  ✓ No deploy in progress
+    │
+    ▼
+Returns: permissionDecision: "deny"
+  reason: "CI is failing on test/auth.spec.ts (your branch).
+           Also, you have 2 uncommitted files (config.json,
+           .env.local) that aren't related to this PR.
+           Fix the test first, then stash or commit the
+           unrelated files."
+    │
+    ▼
+Copilot: "I can't push right now — CI is failing and you
+  have unrelated uncommitted files. Want me to fix the
+  failing test first?"
+```
+
+## Configuration
+
+In `tap.config.json`:
+
+```json
+{
+  "guardian": {
+    "emitters": {
+      "git": { "every": "30s", "enabled": true },
+      "ci": { "every": "60s", "enabled": true },
+      "deploy": { "command": "kubectl get pods ...", "every": "60s", "enabled": false }
+    },
+    "correlation": { "schedule": "idle", "enabled": true },
+    "gating": {
+      "blockPushOnCIFailure": true,
+      "warnOnUpstreamChanges": true,
+      "blockMainBranchWrites": true
+    }
+  }
+}
+```
+
+## Phased delivery
+
+| Phase | Scope |
+|---|---|
+| **1. Git + CI emitters** | Two CommandEmitters with EventFilter rules, surface/inject thresholds |
+| **2. onPreToolUse gating** | Block push on CI failure, warn on upstream conflicts |
+| **3. Transform callbacks** | Context-adaptive system prompt based on branch/CI/deploy state |
+| **4. Correlation engine** | PromptEmitter that reads across streams and synthesizes |
+| **5. Configuration** | Per-project guardian config in tap.config.json |
+
+## Open questions
+
+- **Polling frequency** — 30s for git, 60s for CI? Configurable per project?
+- **Gate strictness** — deny vs. warn? Should the user be able to override gates?
+- **Correlation prompt** — how to keep it cheap (token-wise) while effective?
+- **Multi-repo** — does the guardian follow you across repos, or reset per project?
+- **Override mechanism** — `--force` style escape hatch for gates?

package/docs/recipes/browser-bridge.md

@@ -0,0 +1,162 @@
+# Recipe: Browser Bridge — Copilot CLI ↔ Live Web Pages
+
+Connect Copilot CLI to any browser tab via a local WebSocket relay and [Detour](https://chromewebstore.google.com/detail/detour/cinkplogkjggmgdkaflhlemcdhchninp) (a Chrome extension that injects scripts into pages).
+
+## How it works
+
+```
+Copilot CLI (※ tap)  ◄─ws─►  Bridge Server  ◄─ws─►  Injected JS (via Detour)
+                              ws://localhost:9400       running in page MAIN world
+```
+
+1. A standalone **bridge server** runs locally on a WebSocket port.
+2. **Detour injects a client script** into target pages — no changes to Detour needed. Detour already runs arbitrary JS in the MAIN world and bypasses CSP. The bridge client is just another script it injects.
+3. **tap dynamically registers tools** when the bridge connects via `session.registerTools()` — Copilot sees browser tools appear and disappear as the bridge connects/disconnects.
+4. **Push events** (console, annotations) flow from the browser through a tap emitter into the Copilot session.
+
+## Architecture
+
+### Bridge server (standalone)
+
+A minimal Node.js WebSocket relay. Clients self-identify as `agent` (Copilot) or `browser` (injected page script). The bridge routes messages between them.
+
+```
+npx copilot-bridge
+# or
+node bridge/server.mjs
+```
+
+Zero knowledge of tap or Detour — it just relays JSON.
+
+### Injected script (via Detour)
+
+A self-contained JS file hosted locally or on a CDN. Added to Detour as a script injection rule on target pages. It:
+
+- Connects to `ws://localhost:9400`
+- Identifies as `browser`
+- Handles action requests (screenshot, DOM query, JS exec)
+- Pushes events (console, annotations) to the bridge
+
+### tap integration — dynamic tool registration
+
+The Copilot SDK supports `session.registerTools()` at runtime (`CopilotSession.registerTools`). tap doesn't need to predefine browser tools — it registers them when the bridge connects and removes them when it disconnects.
+
+```js
+// When bridge connects and browser is available:
+session.registerTools([
+  ...existingTapTools,
+  {
+    name: "browser_screenshot",
+    description: "Capture the visible browser viewport as a PNG screenshot",
+    handler: async () => bridge.request("screenshot")
+  },
+  {
+    name: "browser_exec",
+    description: "Execute JS in the page MAIN world, return result",
+    parameters: { type: "object", properties: { js: { type: "string" } }, required: ["js"] },
+    handler: async ({ js }) => bridge.request("js.exec", { js })
+  }
+]);
+
+// When bridge disconnects — re-register without browser tools:
+session.registerTools(existingTapTools);
+```
+
+This pattern generalizes: any WebSocket-connected service can surface tools into Copilot at runtime — not just the browser bridge. The bridge announces what actions the connected browser supports, and tap materializes them as tools.
+
+## Protocol
+
+JSON over WebSocket. Request/response with correlation IDs.
+
+### Handshake
+
+```json
+{ "type": "hello", "role": "agent", "name": "copilot-tap" }
+{ "type": "hello", "role": "browser", "name": "detour-bridge-client" }
+```
+
+### Request → Response
+
+```json
+// agent sends
+{ "type": "request", "id": "r1", "action": "screenshot", "params": {} }
+
+// browser responds
+{ "type": "response", "id": "r1", "data": { "image": "data:image/png;base64,..." } }
+```
+
+### Push (browser → agent, unsolicited)
+
+```json
+{ "type": "push", "action": "comment", "data": { "text": "Fix this button", "selector": "#submit-btn", "url": "https://..." } }
+```
+
+## Actions
+
+| Action | Direction | What it does |
+|---|---|---|
+| `screenshot` | agent → browser | `html2canvas` or Canvas API capture of viewport |
+| `dom.query` | agent → browser | `querySelector` → outerHTML, textContent, attributes |
+| `dom.react` | agent → browser | React fiber walk → component name, file, line, props |
+| `js.exec` | agent → browser | Run arbitrary JS in page context, return result |
+| `page.info` | agent → browser | URL, title, meta, `document.readyState` |
+| `comment` | browser → agent | User annotation from page → Copilot session |
+| `console` | browser → agent | Intercepted `console.*` calls → tap emitter |
+| `navigate` | agent → browser | `window.location.href = url` |
+
+## Use cases
+
+### Get a screenshot into Copilot
+
+```
+> take a screenshot of the current page
+```
+
+tap calls `tap_browser_screenshot` → bridge → injected script captures viewport → base64 flows back → Copilot sees the image.
+
+### React component context (like react-grab)
+
+```
+> what React component renders the sidebar?
+```
+
+tap calls `tap_browser_query` with a selector or `tap_browser_react_context` → walks React fiber tree → returns component name, source file, line number, props → Copilot has full context without searching the codebase.
+
+### Live console monitoring
+
+A tap CommandEmitter connects to the bridge and streams `console` push events. EventFilter drops noise, injects errors:
+
+```json
+{ "match": "error|warn|uncaught", "outcome": "inject" }
+{ "match": ".*", "outcome": "keep" }
+```
+
+### Page annotations → Copilot
+
+User selects an element on the page, types a comment. The injected script pushes it to the bridge → tap injects it into the Copilot session. Like react-grab but the context goes straight into the conversation, not the clipboard.
+
+### Copilot drives the browser
+
+```
+> click the submit button and tell me what happens
+```
+
+tap calls `tap_browser_exec` with `document.querySelector('#submit').click()` → injected script runs it → returns result or captures DOM changes.
+
+## Phased delivery
+
+| Phase | Scope |
+|---|---|
+| **1. Prove the round-trip** | Bridge server + injected client script + `screenshot` action + one tap tool |
+| **2. DOM + React context** | `dom.query`, `dom.react`, `page.info` actions and tap tools |
+| **3. Bidirectional** | `js.exec`, `comment` push, `console` push, `navigate` |
+| **4. Polish** | Auto-reconnect, multi-tab targeting, annotation overlay UI, error handling |
+
+## Open questions
+
+- **Bridge as npm package?** `npx copilot-bridge` or should tap auto-start it?
+- **Multi-tab** — target active tab by default, allow tab ID targeting?
+- **Screenshot method** — `html2canvas` (full fidelity) vs Canvas API (faster)?
+- **Security** — localhost-only binding, optional shared secret?
+- **Image delivery** — base64 inline vs write to temp file and return path?
+- **React context** — bundle react-grab extraction logic or write lightweight version?

package/docs/recipes/codex-goals-for-tap-goal.md

@@ -0,0 +1,136 @@
+# Codex Goals lessons for `/tap-goal`
+
+This recipe records the design lessons borrowed from OpenAI's
+[Using Goals in Codex](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex)
+guide and maps them to ※ tap's `/tap-goal` skill.
+
+## Core lesson
+
+A goal is a **completion contract** attached to the current thread:
+
+```text
+work -> check evidence -> continue, complete, or stop blocked
+```
+
+It is not open-ended background autonomy. The objective persists, but evidence
+decides whether work is complete.
+
+## Strong goal contract
+
+Before starting a goal loop, make these fields explicit:
+
+| Field | Purpose |
+| --- | --- |
+| Outcome | Desired end state |
+| Verification surface | Test, benchmark, command output, artifact, source material, or report that proves completion |
+| Constraints | What must not regress |
+| Boundaries | Files, tools, data, repositories, or resources in scope |
+| Iteration policy | How to choose the next experiment/action after each attempt |
+| Blocked stop condition | When to stop, what to report, and what would unlock progress |
+
+Weak:
+
+```text
+/tap-goal improve performance
+```
+
+Strong:
+
+```text
+/tap-goal Reduce p95 checkout latency below 120 ms, verified by the checkout benchmark,
+while keeping the correctness suite green. Use only checkout service files,
+benchmark fixtures, and related tests. Between iterations, record what changed,
+what the benchmark showed, and the next best experiment. If blocked, stop with
+attempted paths, evidence, blocker, and next input needed.
+```
+
+## Runtime mapping in tap
+
+Codex Goals continue at safe idle boundaries. Tap supports that as:
+
+```json
+{ "prompt": "...", "every": "idle", "maxRuns": 50 }
+```
+
+Copilot CLI autopilot can keep a session continuously busy, so `/tap-goal` also
+supports timed autopilot-compatible goals:
+
+```json
+{ "prompt": "...", "everySchedule": ["2m", "5m", "10m"], "maxRuns": 50 }
+```
+
+Timed prompt sends that are deferred because the session is busy do not consume
+the real iteration budget.
+
+## Evidence audit before completion
+
+Before a goal stops as complete, the prompt must record:
+
+```text
+GOAL COMPLETE
+Verification surface checked: <specific evidence>
+Result observed: <what it showed>
+Constraints checked: <what did not regress>
+Conclusion: complete
+```
+
+If the verification surface cannot be checked, the goal is blocked, not
+complete.
+
+## Iteration ledger
+
+Each iteration should post a structured EventStream note with `tap_post`:
+
+```text
+ITERATION RECORD
+Iteration: <runs> of <maxRuns>
+Action taken: <smallest useful action>
+Evidence checked: <test/output/artifact/result>
+Status: progressing | complete | blocked | budget-limited
+Next best action: <next step>
+```
+
+This makes the EventStream an audit trail rather than only a notification log.
+
+## Research and reproduction goals
+
+For research goals, maintain a claim ledger:
+
+```text
+Claim: <specific claim>
+Route: <how it was tested>
+Evidence surface: <what was checked>
+Status: confirmed | approximate-support | blocked | uncertain
+Remaining uncertainty: <what is missing>
+```
+
+The final output should preserve epistemic levels instead of flattening partial
+support into success.
+
+## Figure lessons from the Codex guide
+
+The guide's figures reinforce these workflow rules:
+
+1. A goal turns a one-turn exchange into an evidence-checked continuation loop.
+2. Goal state is thread-scoped and includes durable state, continuation,
+   controls, and evidence checks.
+3. Continuation is gated: active goal, idle thread, and no queued user input.
+4. Strong goals visibly name end state, verification surface, and constraints.
+5. Research goals decompose source claims into evidence channels before status.
+6. Final research output preserves confirmed, approximate, blocked, and
+   uncertain support levels.
+7. The UI example shows goal mode as an explicit command/input affordance rather
+   than hidden background work.
+
+## Budget handling
+
+`maxRuns` is a safety budget. Reaching it means "budget-limited handoff," not
+"goal complete." The final budget-limited iteration should post:
+
+```text
+BUDGET LIMITED
+Progress: <what was achieved>
+Evidence gathered: <what is known>
+Remaining work: <what is not done>
+Recommended next goal/budget: <next invocation>
+```