copilot-tap-extension 2.0.5 → 2.0.7

package/README.md

@@ -30,6 +30,7 @@ Background commands and agent prompts produce output line by line. An EventFilte
 - 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.
 - You build external tools in any language and want them available inside Copilot without touching the SDK.
+- You want a live visual flight recorder for tap streams, emitters, provider state, logs, and session events.
 
 ## Get started
 
@@ -115,6 +116,8 @@ Once inside the session, describe what you want in natural language. You can als
 
 > _"Tail the API logs, inject errors, drop health checks"_
 
+> _"Open the tap diagnostics canvas"_
+
 The agent translates these into emitter and filter configurations behind the scenes.
 
 ## How it works
@@ -209,13 +212,15 @@ The prompt fires immediately, then re-fires after each idle period. It stops aft
 
 **Work toward a goal autonomously**
 
-Use `/tap-goal` to create an idle goal loop that keeps advancing a concrete objective until it finishes, hits a blocker, or reaches its iteration budget. Goals are explicit, control commands are user-owned, and the loop should stop itself only when the objective is actually complete or blocked.
+Use `/tap-goal` to create a goal loop that keeps advancing a concrete objective until it finishes, hits a blocker, or reaches its iteration budget. Goals are explicit completion contracts, control commands are user-owned, and the loop should stop itself only when the objective is actually complete, blocked, or budget-limited.
 
 ```
 /tap-goal migrate the repo to the new API and keep going until tests pass
 ```
 
-The skill creates a temporary idle PromptEmitter with a self-contained goal prompt. Each iteration inspects its own emitter state, assesses progress, takes the next small action, validates when relevant, and stops the emitter when the goal is complete or blocked. As the remaining iteration budget gets low, the prompt shifts into wrap-up mode so it leaves a useful handoff instead of starting broad new work.
+The skill creates a temporary PromptEmitter with a self-contained goal prompt. Conservative goals use an idle schedule; autopilot-style goals use a timed backoff schedule so the objective can keep nudging the session even when Copilot stays busy. Each iteration inspects its own emitter state, works against a six-part goal contract, records structured progress to its EventStream, validates when relevant, and stops the emitter when the goal is complete, blocked, or budget-limited.
+
+A strong goal names the outcome, verification surface, constraints, boundaries, iteration policy, and blocked stop condition. Completion requires an evidence audit against concrete files, tests, logs, benchmark output, generated artifacts, or research evidence.
 
 Goal loops default to 50 iterations unless you specify another budget.
 
@@ -225,7 +230,7 @@ Use `/tap-goal stop <name>` or `/tap-goal clear <name>` to stop a specific goal
 
 Use `/tap-goal resume <objective>` to start a new loop from an objective. Stopped goal loops do not preserve resumable internal state; resuming creates a new emitter from the supplied objective.
 
-Because `/tap-goal` uses an idle PromptEmitter, it is best when the session has natural idle gaps. For always-busy autopilot-style flows, prefer a timed prompt loop or hook/session-injector based delivery so follow-up context can still reach the session.
+Because `/tap-goal` can use either idle or timed PromptEmitters, choose idle for conservative continuation and timed-autopilot mode for always-busy flows. Timed prompt deferrals do not consume the run budget; budget exhaustion still means "handoff needed," not success.
 
 **Tune the filter live**
 
@@ -239,6 +244,12 @@ The recommended approach is a **keep-all bootstrap**: start with no EventFilter
 
 Rules can be added or changed while the emitter is running. You never need to restart it to adjust filtering.
 
+**Inspect tap with a live diagnostics canvas**
+
+Use the `tap_open_diagnostics_canvas` tool to open a local canvas that shows tap's retained EventStreams, emitter state, provider gateway state, injection queue, runtime logs, and recent session events in one place.
+
+The canvas is bounded and redacted: it keeps recent diagnostic evidence without exposing provider auth tokens or unbounded transcript payloads.
+
 ## Repo layout
 
 ```text
@@ -276,6 +287,8 @@ PLAN.md                         # ubiquitous language and design decisions
 | [Reference](./docs/reference.md) | Look up tool parameters, config fields, or the event pipeline |
 | [Provider guide](./docs/providers.md) | Add external tools to Copilot via the WebSocket provider interface |
 | [Use cases and patterns](./docs/use-cases.md) | Recipes for deploy watchers, PR monitors, log tailers, and more |
+| [Copilot SDK canvas surfaces](./docs/recipes/copilot-sdk-canvas.md) | Local SDK findings for extension-owned canvas UI surfaces |
+| [Codex Goals lessons for tap-goal](./docs/recipes/codex-goals-for-tap-goal.md) | Goal-loop contract, evidence audit, and autopilot scheduling guidance |
 | [Evals](./docs/evals.md) | Run or extend the automated test suite |
 | [Copilot instructions](./src/copilot-instructions.md) | Understand or customize how the agent uses this extension |
 | [Implementation plan](./PLAN.md) | Ubiquitous language and naming conventions for contributors |

package/dist/copilot-instructions.md

@@ -145,20 +145,26 @@ If the work is mostly reasoning rather than data collection, prefer a PromptEmit
 
 - prompt once for a background check (oneTime)
 - prompt + `every="<interval>"` for a fixed maintenance loop (timed)
-- prompt + `every="idle"` + `maxRuns` for autonomous goal loops with explicit iteration budgets (`/tap-goal`)
+- prompt + `every="idle"` + `maxRuns` for conservative autonomous goal loops with explicit iteration budgets (`/tap-goal`)
+- prompt + `everySchedule=[...]` + `maxRuns` for autopilot-compatible goals that need timed nudges while the session may stay busy
 
 This is the closest analogue to Claude's session-scoped `/tap-loop` behavior in this extension.
 
 For "keep working until done" requests, prefer `/tap-goal`: create an
-idle PromptEmitter with a self-contained goal prompt, an explicit `maxRuns`
-budget, and instructions to stop itself when complete or blocked. Goals must be
-explicit user requests; do not infer them from ordinary one-shot tasks, and do
-not treat budget exhaustion as successful completion. Goal prompts should
-self-steer by reading their own emitter state with `tap_list_emitters` and
-switching into wrap-up mode when the remaining iteration budget is low.
+PromptEmitter with a self-contained goal prompt and an explicit `maxRuns`
+budget. A strong goal is a six-part completion contract: outcome, verification
+surface, constraints, boundaries, iteration policy, and blocked stop condition.
+Goals must be explicit user requests; do not infer them from ordinary one-shot
+tasks, and do not treat budget exhaustion as successful completion. Goal prompts
+should self-steer by reading their own emitter state with `tap_list_emitters`,
+switching into wrap-up mode when the remaining iteration budget is low, posting
+structured iteration records to their EventStream with `tap_post`, and stopping
+themselves when complete or blocked. Completion requires an evidence audit
+against concrete files, tests, logs, benchmark output, or generated artifacts.
 If the session may stay continuously busy (for example in autopilot-heavy
-flows), prefer a timed PromptEmitter or hook-driven/session-injector delivery
-instead of relying on idle to trigger the next goal step.
+flows), use a timed PromptEmitter with a backoff schedule such as
+`everySchedule=["2m","5m","10m"]` instead of relying on idle to trigger the next
+goal step.
 
 ## Borrow from the official SDK examples
 
@@ -170,6 +176,10 @@ When working on the extension itself, not just using its emitter tools, prefer t
 - 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`
+- use `createCanvas` with `joinSession({ canvases: [...] })` for extension-owned UI panels when text-only EventStreams are not enough; `open()` returns `title`, `status`, and a renderer `url`, actions power `invoke_canvas_action`, and per-instance state should be keyed by `instanceId`
+- treat canvas support as experimental: action names must not start with `canvas.`, guard optional host canvas capabilities, prefer loopback HTTP renderers on ephemeral ports, and clean them up in `onClose`
+- remember that external tap providers cannot declare Copilot SDK canvases over the current WebSocket protocol; implement canvases in the extension layer or explicitly extend the gateway protocol first
+- open the built-in `tap-diagnostics` canvas with `tap_open_diagnostics_canvas` when users ask to inspect tap internals, diagnostics, logs, stream history, provider state, or "everything tap is doing"
 
 Good non-emitter examples to adapt into this repo:
 
@@ -177,6 +187,7 @@ Good non-emitter examples to adapt into this repo:
 - 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
+- add a canvas dashboard for stream/emitter inspection when a workflow benefits from a persistent visual surface
 
 ## What not to do