copilot-tap-extension 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+<p align="center">
+  <img src="./tap.svg" width="80" height="80" alt="※ tap">
+</p>
+
+<h1 align="center">※ tap</h1>
+
+<p align="center">
+  <em>Background event filtering and injection for Copilot CLI.</em><br>
+  <sub>Look here, this matters.</sub>
+</p>
+
+---
+
+Copilot CLI already runs background tasks, but their output sits idle until you check it. This extension adds **filtering and auto-injection** on top of that capability.
+
+Background commands and agent prompts produce output line by line. An EventFilter decides what to drop, what to store, and what to push into your session. Important events arrive without you asking.
+
+| Without this extension | With it |
+| --- | --- |
+| You check background output manually | Important lines are pushed into your conversation |
+| No way to filter noisy output | Rules drop noise, keep context, inject signal |
+| No scheduled prompt re-runs | Prompts repeat on a timer or fire when idle |
+| Output stays in the background task | Matched events arrive in your session as they happen |
+
+## Who is this for?
+
+- You tail logs and want failures injected into your session while you keep coding.
+- You maintain a repo and want PR reviews, CI failures, or new issues surfaced automatically.
+- You run long builds and want to know when they finish or break -- without watching.
+- You poll an API or dashboard and want the agent to react when something changes.
+- You re-ask the same prompt periodically and want it on a timer or running whenever idle.
+
+## Get started
+
+Prerequisites: [Node.js](https://nodejs.org/) and [Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli).
+
+```bash
+git clone https://github.com/amitse/copilot-tap-extension
+cd copilot-tap-extension
+npm install
+cp tap.config.example.json tap.config.json
+copilot
+```
+
+On Windows, replace `cp` with `copy`.
+
+The config file tells the extension which emitters to auto-start. The example defines a heartbeat emitter:
+
+```json
+{
+  "emitters": [
+    {
+      "name": "heartbeat",
+      "command": "node ./examples/heartbeat.mjs",
+      "autoStart": true,
+      "eventFilter": [
+        { "match": "booting", "outcome": "drop" },
+        { "match": "warning|error", "outcome": "inject" },
+        { "match": ".*", "outcome": "keep" }
+      ]
+    }
+  ]
+}
+```
+
+This runs the heartbeat script on session start, drops boot messages, injects warnings and errors, and keeps everything else in the stream.
+
+Once inside the session, describe what you want in natural language. You can also use `/loop` to set up scheduled prompts directly:
+
+> _"Watch my build logs and tell me if anything fails"_
+
+> _"/loop 5m check for new PR review comments"_
+
+> _"Tail the API logs, inject errors, drop health checks"_
+
+The agent translates these into emitter and filter configurations behind the scenes.
+
+## How it works
+
+An **EventEmitter** is a background worker attached to your session. There are two kinds:
+
+- A **CommandEmitter** runs a shell command and captures stdout line by line.
+- A **PromptEmitter** runs an agent prompt -- once, on a recurring interval, or whenever the session is idle.
+
+Each emitter writes to an **EventStream**, an in-memory log of accepted output. The stream is created automatically and shares the emitter's name.
+
+For CommandEmitters, an **EventFilter** decides what happens to each line. It is an ordered list of regex rules -- first match wins:
+
+| Outcome | What happens |
+| --- | --- |
+| **drop** | Discarded. Never enters the stream. |
+| **keep** | Stored in the EventStream for later review. |
+| **surface** | Stored and shown in the session timeline. |
+| **inject** | Stored, shown, and pushed into your conversation. |
+
+Outcomes are inclusive: **inject** implies **surface**, and **surface** implies **keep**. Only **drop** is outside this chain.
+
+PromptEmitter output bypasses the filter and always injects.
+
+A **SessionInjector** controls whether stream updates are pushed into your session proactively. Enable it when you want important events to arrive as they happen.
+
+Filters are hot-swappable while the emitter runs. `ownership="modelOwned"` lets the agent tune rules; `ownership="userOwned"` locks them to your specification.
+
+Emitters are **temporary** by default and last only for the current session. Set `lifespan="persistent"` to save an emitter to config and restore it next session.
+
+Run schedules control timing: **continuous** (command runs until stopped), **timed** (repeats on an interval), **oneTime** (runs once), or **idle** (prompt re-runs when the session has nothing else to do).
+
+## What you can do
+
+**Watch something in the background**
+
+Tell Copilot to watch a log, build, or command. It creates a CommandEmitter, filters the output, and only interrupts you when something needs attention.
+
+```
+"Start a deploy watcher that tails our CI logs.
+ Drop health checks, inject any failures or rollbacks."
+```
+
+You keep coding. Twenty minutes later, Copilot interrupts: "Run 48291: deployment rollback triggered on prod."
+
+**Loop a prompt on a schedule**
+
+A PromptEmitter re-runs an agent prompt at a fixed interval. Useful for PR comments, CI status, or ticket queues.
+
+```
+/loop 15m Check for new failing CI runs or PR review comments.
+         Summarize only actionable items.
+```
+
+Every 15 minutes the agent scans and reports back. No news means no interruption.
+
+**Run a prompt when idle**
+
+Use `/loop idle` to re-run a prompt whenever the session has nothing else to do. Set `maxRuns` to cap iterations.
+
+```
+/loop idle Scan for new issues labeled urgent. Summarize what changed.
+```
+
+The prompt fires immediately, then re-fires after each idle period. It stops after reaching the iteration limit.
+
+**Tune the filter live**
+
+The recommended approach is a **keep-all bootstrap**: start with no EventFilter rules so all output flows into the stream. Read the stream history to learn what the output looks like, then add rules progressively:
+
+```
+1. Drop the noise:    { "match": "health_check|heartbeat", "outcome": "drop" }
+2. Inject the signal: { "match": "error|failure|rollback",  "outcome": "inject" }
+3. Keep the rest:     { "match": ".*",                       "outcome": "keep" }
+```
+
+Rules can be added or changed while the emitter is running. You never need to restart it to adjust filtering.
+
+## Repo layout
+
+```text
+.github/
+  extensions/tap/extension.mjs  # extension entry point (loads the runtime)
+  skills/loop/                  # /loop skill for scheduled and idle prompts
+  copilot-instructions.md       # agent guidance for using this extension
+src/
+  emitter/                      # supervisor, lifecycle, spawn, line router
+  streams/                      # EventStream store and notification dispatcher
+  tools/                        # tool definitions (emitters, streams, filters)
+  config/                       # persistent config store (tap.config.json)
+  format/                       # display formatters for emitters and streams
+  session/                      # session port abstraction
+  util/                         # normalization, text, time, path helpers
+  hooks.mjs                     # session lifecycle hooks
+  tap-runtime.mjs               # runtime factory (wires everything together)
+tap.svg                         # ※ mark — the tap icon
+docs/
+  evolution-of-tap-icon.html    # design evolution: 20 agents, 20 metaphors, one mark
+examples/heartbeat.mjs          # demo CommandEmitter
+evals/                          # eval harness and test cases
+tap.config.example.json         # starter config (copy to tap.config.json)
+PLAN.md                         # ubiquitous language and design decisions
+```
+
+## Further reading
+
+| Document | When to read it |
+| --- | --- |
+| [Reference](./docs/reference.md) | Look up tool parameters, config fields, or the event pipeline |
+| [Use cases and patterns](./docs/use-cases.md) | Recipes for deploy watchers, PR monitors, log tailers, and more |
+| [Evals](./docs/evals.md) | Run or extend the automated test suite |
+| [Copilot instructions](./.github/copilot-instructions.md) | Understand or customize how the agent uses this extension |
+| [Implementation plan](./PLAN.md) | Ubiquitous language and naming conventions for contributors |
+| [Evolution of the ※ icon](./docs/evolution-of-tap-icon.html) | 20 metaphors, 10 variants, one mark — the design story behind ※ tap |
+
+## Contributing
+
+Before opening a PR, run the local checks:
+
+```bash
+npm run check              # syntax check
+npm run evals:smoke        # smoke test
+npm run evals:validate-modes  # interactive vs prompt-mode gap
+```
+
+The runtime has no production dependencies. Dev dependencies (`@github/copilot-sdk`, `yaml`) are used for the eval harness and extension loading.
+
+If you add a new tool or change the event pipeline, update the [reference](./docs/reference.md). If you add a new workflow pattern, add it to [use cases](./docs/use-cases.md).
+
+## License
+
+[MIT](./LICENSE)

package/bin/install.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import os from "node:os";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(__dirname, "..");
+const distDir = path.join(pkgRoot, "dist");
+
+const BRAND = "※ tap";
+const EXT_DIR_NAME = "tap";
+
+function usage() {
+  console.log(`
+${BRAND} — Copilot CLI extension installer
+
+Usage:
+  npx copilot-tap-extension [options]
+
+Options:
+  --global, -g     Install to ~/.copilot/  (default)
+  --local,  -l     Install to .github/  (project-scoped)
+  --force,  -f     Overwrite existing files without prompting
+  --help,   -h     Show this help message
+
+Installs:
+  extensions/tap/extension.mjs    The bundled ※ tap extension
+  skills/loop/SKILL.md            The /loop skill for prompt-based loops
+  copilot-instructions.md         Agent instructions for using ※ tap
+`);
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const flags = { scope: "global", force: false, help: false };
+  for (const arg of args) {
+    switch (arg) {
+      case "--global":
+      case "-g":
+        flags.scope = "global";
+        break;
+      case "--local":
+      case "-l":
+        flags.scope = "local";
+        break;
+      case "--force":
+      case "-f":
+        flags.force = true;
+        break;
+      case "--help":
+      case "-h":
+        flags.help = true;
+        break;
+      default:
+        console.error(`Unknown option: ${arg}`);
+        usage();
+        process.exit(1);
+    }
+  }
+  return flags;
+}
+
+function getTargetRoot(scope) {
+  if (scope === "global") {
+    return path.join(os.homedir(), ".copilot");
+  }
+  return path.join(process.cwd(), ".github");
+}
+
+function copyArtifact(src, dest, label, flags) {
+  if (!existsSync(src)) {
+    console.error(`  ✗ ${label}: source not found (${src})`);
+    return false;
+  }
+  if (existsSync(dest) && !flags.force) {
+    console.log(`  ⊘ ${label}: already exists, skipping (use --force to overwrite)`);
+    return true;
+  }
+  mkdirSync(path.dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+  console.log(`  ✓ ${label}`);
+  return true;
+}
+
+function install(flags) {
+  const targetRoot = getTargetRoot(flags.scope);
+  const scopeLabel = flags.scope === "global" ? "global (~/.copilot)" : "local (.github)";
+
+  console.log(`\n${BRAND} — installing (${scopeLabel})\n`);
+
+  const artifacts = [
+    {
+      src: path.join(distDir, "extension.mjs"),
+      dest: path.join(targetRoot, "extensions", EXT_DIR_NAME, "extension.mjs"),
+      label: "extensions/tap/extension.mjs"
+    },
+    {
+      src: path.join(distDir, "skills", "loop", "SKILL.md"),
+      dest: path.join(targetRoot, "skills", "loop", "SKILL.md"),
+      label: "skills/loop/SKILL.md"
+    },
+    {
+      src: path.join(distDir, "copilot-instructions.md"),
+      dest: path.join(targetRoot, "copilot-instructions.md"),
+      label: "copilot-instructions.md"
+    }
+  ];
+
+  let allOk = true;
+  for (const { src, dest, label } of artifacts) {
+    if (!copyArtifact(src, dest, label, flags)) {
+      allOk = false;
+    }
+  }
+
+  console.log();
+  if (allOk) {
+    console.log(`✓ ${BRAND} installed to ${targetRoot}`);
+  } else {
+    console.error(`⚠  Some artifacts could not be installed.`);
+    process.exit(1);
+  }
+}
+
+const flags = parseArgs(process.argv);
+
+if (flags.help) {
+  usage();
+  process.exit(0);
+}
+
+install(flags);

package/dist/copilot-instructions.md

@@ -0,0 +1,187 @@
+# Copilot instructions for ※ tap
+
+Use this extension as a background-awareness layer for long-running or polled signals.
+
+## Mental model
+
+- An **EventEmitter** is the only primary resource users define — a background shell command (CommandEmitter) or agent prompt (PromptEmitter).
+- An **EventStream** is automatically created for each emitter (same name) and stores accepted output.
+- An **EventFilter** is an ordered rule list owned by the emitter: `[{ match, outcome }]` — first match wins.
+  - Outcomes: `drop` (discard), `keep` (store in EventStream), `surface` (keep + show in timeline), `inject` (keep + surface + inject into Copilot)
+- A **SessionInjector** is derived automatically per EventStream and controls whether updates are proactively injected into the session.
+
+PromptEmitter events always inject (no filter applied). CommandEmitter events go through the EventFilter. The EventFilter is hot-swappable while the emitter runs.
+
+The extension injects EventStream updates directly from emitter output with `session.send()`. It does not depend on transcript events like `user.message` or `assistant.message`.
+
+## When to use it
+
+Reach for EventEmitters when the user wants to:
+
+- watch something over time
+- babysit a PR, build, issue queue, deploy, or inbox
+- keep working while a background process or poller runs
+- get interrupted only for important changes
+- store short rolling history for a live stream
+
+Reach for **PromptEmitters** when the user wants the agent itself to periodically re-check something, summarize changes, or perform maintenance without waiting for another manual prompt.
+
+## Default operating pattern
+
+1. Start with a **temporary** emitter (`lifespan="temporary"`) unless the workflow is obviously recurring across multiple agent sessions.
+2. The EventStream is created automatically with the same name as the emitter.
+3. Enable the SessionInjector if the emitter should proactively surface updates.
+4. Start with a keep-all bootstrap policy (no EventFilter rules) to learn the stream shape.
+5. Let a few events arrive.
+6. Inspect EventStream history.
+7. Tighten the EventFilter:
+   - add `{ "match": "<noise>", "outcome": "drop" }` rules first
+   - add `{ "match": "<signal>", "outcome": "inject" }` rules for important events
+   - use `{ "match": ".*", "outcome": "keep" }` as a catch-all to store everything else
+8. If the work should repeat inside the session, add `runInterval`.
+9. If the emitter proves useful across sessions, persist it and switch ownership to `ownership="userOwned"` unless the user explicitly wants ongoing model control.
+
+## Recommended tool sequence
+
+Use these tools in roughly this order:
+
+1. `tap_start_emitter` — create the EventEmitter
+2. `tap_enable_injector` — enable the SessionInjector if the emitter should proactively surface updates
+3. `tap_stream_history` — read EventStream history after a few events
+4. `tap_set_event_filter` — update the EventFilter rules
+5. `tap_post` — leave structured notes or summaries in the EventStream
+6. `tap_stop_emitter` — stop the emitter when the task ends or if the stream is no longer useful
+
+## Good defaults
+
+### For unknown or noisy streams
+
+- `lifespan="temporary"`
+- `ownership="modelOwned"`
+- `subscribe=true`
+- No EventFilter rules initially (keep-all bootstrap policy)
+- Let events accumulate, then add rules progressively
+
+### For prompt-driven maintenance
+
+- use `prompt` instead of `command` (creates a PromptEmitter)
+- add `runInterval` for a fixed session-scoped timed schedule
+- use oneTime PromptEmitter when the user wants a background check only once
+- keep the first prompt concise and action-oriented
+
+### For recurring team workflows
+
+- `lifespan="persistent"`
+- `ownership="userOwned"`
+- `autoStart=true` only if the user wants it every session
+- stable EventStream naming
+- user-approved EventFilter rules
+
+## Ownership rules
+
+Ownership lives on the EventEmitter only. EventStream and SessionInjector are derived.
+
+Treat these as **userOwned** by default:
+
+- persistent emitters
+- security, compliance, finance, or release-gating workflows
+- email or external notification rules
+- org-specific routing rules or thresholds
+
+Treat these as safe for **modelOwned**:
+
+- temporary emitters created for one task
+- temporary SessionInjectors
+- live EventFilter tuning to reduce noise
+- exploratory emitters where the stream shape is not yet known
+
+Never override a userOwned persistent emitter or its EventFilter unless the user explicitly asks. If the extension requires `transferOwnership=true`, use it only for an explicit user request.
+
+## How to tighten EventFilters
+
+The EventFilter is an ordered rule list — first match wins. Prefer this progression:
+
+1. **Observe first.** Let the raw stream teach you the vocabulary (keep-all bootstrap).
+2. **Drop obvious noise.** Add `{ "match": "<noise>", "outcome": "drop" }` rules for polling chatter, heartbeats, bot messages, deprecations, duplicate summaries.
+3. **Inject important signals.** Add `{ "match": "<signal>", "outcome": "inject" }` for events that should interrupt the session.
+4. **Surface useful context.** Add `{ "match": "<context>", "outcome": "surface" }` for events worth showing in the timeline.
+5. **Catch-all.** End with `{ "match": ".*", "outcome": "keep" }` to store everything else in the EventStream.
+
+Good examples:
+
+- log tail: drop timestamps, retries, and health-check chatter; inject `error|fatal|panic`
+- PR watcher: drop bot comments and repeated status updates; inject `changes requested|failed|approved`
+- ticket queue: inject `sla-breach|high-priority|escalated`; keep everything else
+
+## Temporary vs persistent
+
+Use **temporary** (`lifespan="temporary"`) when:
+
+- the user is debugging, triaging, or investigating
+- the correct EventFilter is not obvious yet
+- the stream exists only for one task, incident, PR, or release window
+- the timed schedule should end with the session
+
+Use **persistent** (`lifespan="persistent"`) when:
+
+- the same workflow should come back next session
+- the command and thresholds are stable
+- the user wants a reusable operating pattern
+
+## Everything is code
+
+If no ready-made CLI exists, create or use a small script that prints one meaningful line per event. Good CommandEmitters are often:
+
+- API pollers
+- webhook log tails
+- release-note fetchers
+- GitHub CLI pollers
+- local watch scripts
+- validation scripts for builds, tests, deploys, ETL, or compliance
+
+Prefer normalized output over raw dumps. EventFilters work much better when each line already carries a stable tag or status word.
+
+If the work is mostly reasoning rather than data collection, prefer a PromptEmitter:
+
+- prompt once for a background check (oneTime)
+- prompt + `runInterval` for a fixed maintenance loop (timed)
+
+This is the closest analogue to Claude's session-scoped `/loop` behavior in this extension.
+
+## Borrow from the official SDK examples
+
+When working on the extension itself, not just using its emitter tools, prefer these SDK patterns:
+
+- use `session.log()` for user-visible diagnostics; never rely on `console.log()`
+- use hooks such as `onUserPromptSubmitted`, `onPreToolUse`, `onPostToolUse`, and `onErrorOccurred` to shape behavior
+- use `session.on(...)` listeners for tool lifecycle, assistant messages, session idle, and errors when you need event-driven behavior
+- use `session.send()` for asynchronous follow-up prompts and `session.sendAndWait()` only when the extension must wait for an answer
+- use `onPermissionRequest` and `onUserInputRequest` for guarded flows instead of custom ad hoc prompting
+- use `fs.watch` or `watchFile` when the extension should react to manual file edits or workspace artifacts such as `plan.md`
+
+Good non-emitter examples to adapt into this repo:
+
+- after an edit tool runs, trigger a lint or test emitter automatically
+- watch a config file and refresh the corresponding emitter when the user edits it
+- add a helper tool that fetches one-shot data from an API while emitters continue to watch background streams
+- log EventFilter updates and emitter lifecycle events to the timeline for observability
+
+## What not to do
+
+- Do not create one giant mixed EventStream for unrelated workflows.
+- Do not make a noisy stream persistent before you understand it.
+- Do not skip the keep-all bootstrap policy for chatty sources — observe first, then add rules.
+- Do not mutate userOwned persistent emitters or their EventFilter without explicit permission.
+- Do not use EventStreams as a transcript mirror; use them for emitter-driven context.
+
+## A strong operating recipe
+
+When the user says "watch this" and the stream shape is unclear:
+
+1. Create a temporary EventEmitter (CommandEmitter or PromptEmitter).
+2. Enable the SessionInjector.
+3. Start with keep-all bootstrap (no EventFilter rules).
+4. Wait for a few real events.
+5. Read EventStream history.
+6. Add EventFilter rules progressively (drop noise → inject signal → keep the rest).
+7. If the workflow proves valuable, ask or decide to create the persistent, userOwned version.