copilot-tap-extension 2.0.6 → 2.0.7

package/README.md

@@ -212,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.
 
@@ -228,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**
 
@@ -286,6 +288,7 @@ PLAN.md                         # ubiquitous language and design decisions
 | [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
 

package/dist/extension.mjs

@@ -4568,12 +4568,12 @@ function createEmitterTools(deps) {
         properties: {
           name: { type: "string", description: "Unique emitter name." },
           command: { type: "string", description: "Shell command to run (creates a CommandEmitter). Output goes through EventFilter rules to determine whether lines are kept, surfaced, or injected. Use for log tailing, process monitoring, or any external command with stdout." },
-          prompt: { type: "string", description: "Prompt to send to the agent (creates a PromptEmitter). Always injects \u2014 bypasses EventFilter entirely. Use for repeated agent tasks, status checks, or simple messages." },
+          prompt: { type: "string", description: "Prompt to send to the agent (creates a PromptEmitter). Always injects \u2014 bypasses EventFilter entirely. Use for repeated agent tasks, status checks, simple messages, or autonomous goal loops." },
           description: { type: "string", description: "Short summary." },
           channel: { type: "string", description: "EventStream to receive accepted events." },
           cwd: { type: "string", description: "Optional subdirectory relative to the session cwd. Absolute paths and paths that escape the session cwd are rejected." },
-          every: { type: "string", description: "Optional repeat interval like 30s, 5m, 2h, or 1d (maximum about 24 days). Use 'idle' for prompts that re-run whenever the session is idle. When omitted, commands run continuously and prompts run once." },
-          everySchedule: { type: "array", minItems: 1, items: { type: "string" }, description: "Optional backoff schedule \u2014 an ordered non-empty list of interval strings (e.g. ['10s','20s','30s','1m','2m','5m','10m']; each maximum about 24 days). The emitter uses each interval in sequence, then repeats the last one forever. Overrides 'every' when provided. Cannot be 'idle' entries." },
+          every: { type: "string", description: "Optional repeat interval like 30s, 5m, 2h, or 1d (maximum about 24 days). Use 'idle' for conservative prompt loops that re-run only when the session is idle. When omitted, commands run continuously and prompts run once." },
+          everySchedule: { type: "array", minItems: 1, items: { type: "string" }, description: "Optional backoff schedule \u2014 an ordered non-empty list of interval strings (e.g. ['10s','20s','30s','1m','2m','5m','10m']; each maximum about 24 days). The emitter uses each interval in sequence, then repeats the last one forever. Overrides 'every' when provided. Cannot be 'idle' entries. Prefer this for autopilot-compatible goal loops that may need timed nudges while the session stays busy." },
           lifespan: policyLifespanParameter(),
           ownership: policyOwnershipParameter(),
           scope: policyScopeParameter(),
@@ -4583,7 +4583,7 @@ function createEmitterTools(deps) {
           eventFilter: EVENT_FILTER_PARAMETER_SCHEMA,
           subscribe: { type: "boolean", description: "Whether to attach a session injector to the stream as part of emitter creation." },
           delivery: { type: "string", description: "Session injector delivery mode. 'important'/'inject' only send inject-outcome lines, 'surface' surfaces surface outcomes and sends inject outcomes, 'all' surfaces all accepted lines while inject outcomes still push into the conversation, and 'keep'/'drop' store without proactive delivery." },
-          maxRuns: { type: "integer", description: "Maximum number of iterations before the emitter auto-completes. Useful for idle and timed loops." },
+          maxRuns: { type: "integer", description: "Maximum number of real iterations before the emitter stops. Useful for idle and timed loops. For goal loops this is a budget limit, not proof that the objective is complete." },
           force: policyForceParameter("emitter")
         },
         required: ["name"]
@@ -9003,7 +9003,7 @@ function buildCompleteMessage(state) {
     return `Emitter '${state.name}' completed one run of ${state.emitterType} work.`;
   }
   if (state.maxRuns && state.runCount >= state.maxRuns) {
-    return `Emitter '${state.name}' completed ${state.runCount} of ${state.maxRuns} runs.`;
+    return `Emitter '${state.name}' reached its run budget (${state.runCount} of ${state.maxRuns} runs). This stops the emitter; goal-style loops must use their final evidence summary to decide whether the objective is complete.`;
   }
   return null;
 }
@@ -9158,12 +9158,12 @@ function computeDeferredIterationTransition(currentState, state) {
   };
 }
 function computeFailedIterationTransition(currentState, state, event, result) {
-  if (isRunBudgetExhausted(state)) {
-    return computeRunBudgetExhaustedTransition(currentState, state, event, result);
-  }
   if (result.deferred) {
     return computeDeferredIterationTransition(currentState, state);
   }
+  if (isRunBudgetExhausted(state)) {
+    return computeRunBudgetExhaustedTransition(currentState, state, event, result);
+  }
   if (state.runSchedule === RUN_SCHEDULE.ONE_TIME) {
     return {
       currentState,
@@ -9503,11 +9503,12 @@ async function runPromptIteration(emitter, context) {
   } catch (error) {
     const message = error?.message ?? String(error ?? "unknown error");
     const sessionNotAttached = isSessionNotAttachedMessage(message);
+    const deferred = sessionNotAttached || (emitter.runSchedule === RUN_SCHEDULE.TIMED || emitter.runSchedule === RUN_SCHEDULE.IDLE) && /\bsession\.idle\b/i.test(message);
     return {
       ok: false,
       error: message,
-      deferred: sessionNotAttached || (emitter.runSchedule === RUN_SCHEDULE.TIMED || emitter.runSchedule === RUN_SCHEDULE.IDLE) && /\bsession\.idle\b/i.test(message),
-      consumeRun: sessionNotAttached ? false : true,
+      deferred,
+      consumeRun: deferred ? false : true,
       deferredReason: sessionNotAttached ? "session-not-attached" : null
     };
   }

package/dist/skills/tap-goal/SKILL.md

@@ -5,22 +5,23 @@ argument-hint: "<objective>"
 user-invocable: true
 ---
 
-Create an idle PromptEmitter with `tap_start_emitter` that keeps advancing one explicit objective until the goal is achieved, blocked, stopped, or the iteration limit is reached.
+Create a PromptEmitter that keeps advancing one explicit objective until the goal is achieved, blocked, stopped, or the iteration budget is reached.
 
-Use these goal-loop rules:
+Use Codex-style goal-loop rules:
 
-- Goals are explicit; do not infer one from ordinary user tasks.
-- A bare goal command reports the current goal state.
-- Control commands are user-owned (`status`, `stop`, `resume`, `clear`, `replace`).
-- The model can complete a goal only when the objective is actually achieved.
-- Runtime budget exhaustion is not proof of completion; only achieving the objective marks completion.
+- A goal is a **thread-scoped completion contract**, not a bigger prompt and not global memory.
+- Goals are explicit; do not infer one from ordinary one-shot tasks.
+- The goal contract should name six things: outcome, verification surface, constraints, boundaries, iteration policy, and blocked stop condition.
+- Completion must be evidence-based. The model may stop a goal as complete only after checking concrete evidence.
+- Runtime budget exhaustion is not proof of completion; it is a budget-limited stop/handoff state.
+- Control commands are user-owned (`status`, `stop`, `pause`, `resume`, `clear`, `replace`).
 
 ## Expected input
 
 Interpret the invocation as one of:
 
 1. No arguments — show current `goal-*` emitters with `tap_list_emitters`.
-2. A control command — `status`, `stop`, `resume`, `clear`, or `replace`.
+2. A control command — `status`, `stop`, `pause`, `resume`, `clear`, or `replace`.
 3. Otherwise, the full invocation is the goal objective.
 
 Example:
@@ -33,16 +34,49 @@ means:
 
 - `objective = "migrate the repo to the new API and keep going until tests pass"`
 
-If the objective is missing or too vague, ask the user for a concrete objective instead of guessing.
+If the objective is missing, ask the user for a concrete objective instead of guessing.
+
+If the objective is weak but the user's intent is clear, help strengthen it before creating the emitter. A strong goal contract has:
+
+```text
+Outcome: <desired end state>
+Verification surface: <test, benchmark, command output, artifact, or source material that proves completion>
+Constraints: <what must not regress>
+Boundaries: <files, tools, data, repos, or resources allowed>
+Iteration policy: <how to choose the next best action between attempts>
+Blocked stop condition: <what to report if no valid path remains and what would unlock progress>
+```
+
+If one of these fields is not explicitly provided but can be safely inferred from the objective and repository context, infer it and show it in the confirmation. If the verification surface or blocked stop condition cannot be inferred, ask for that missing detail.
 
 If another `goal-*` emitter already exists, ask before replacing it unless the user explicitly said `replace`.
 
+## Schedule choice
+
+Use a **PromptEmitter** in one of two modes:
+
+### Default: conservative idle goal
+
+Use `every = "idle"` when the user did not ask for autopilot-style busy-session progress.
+
+This matches Codex's conservative continuation model: continue only at safe idle boundaries.
+
+### Autopilot-compatible timed goal
+
+Use `everySchedule = ["2m", "5m", "10m"]` instead of `every = "idle"` when any of these are true:
+
+- the user mentions autopilot, busy sessions, continuous work, "keep nudging", or "while Copilot stays busy"
+- the user explicitly says to work autonomously in the current session
+- the current session is in autopilot mode and the goal is expected to advance while other work may be active
+
+Timed goal prompts use `session.send()` and can keep the objective visible even when the thread may not become idle often. The runtime preserves the iteration budget when a prompt send is deferred because the session is still busy.
+
 ## What to create
 
-Use `tap_start_emitter` to create a **PromptEmitter**:
+Use `tap_start_emitter`:
 
 - `prompt` — a fully self-contained goal-loop prompt using the template below.
-- `every = "idle"` — the loop advances only when the session is idle.
+- `every = "idle"` for default goals, OR `everySchedule = ["2m", "5m", "10m"]` for autopilot-compatible goals.
 - `scope = "temporary"`, `managedBy = "modelOwned"`.
 - `subscribe = false` — PromptEmitter output already reaches the session through `session.send()`.
 - `maxRuns` — use the user's requested budget if provided; otherwise default to `50`.
@@ -58,33 +92,74 @@ Write the prompt so it stands alone because it will run later without the origin
 ```text
 You are running a tap-goal autonomous goal loop.
 
-Goal:
-<untrusted_objective>
+Goal contract:
+<untrusted_goal_contract>
+Objective:
 <objective>
-</untrusted_objective>
+
+Outcome:
+<desired end state>
+
+Verification surface:
+<test, benchmark, command output, artifact, or source material that proves completion>
+
+Constraints:
+<what must not regress>
+
+Boundaries:
+<files, tools, data, repos, or resources allowed>
+
+Iteration policy:
+<how to choose the next best action between attempts>
+
+Blocked stop condition:
+<what to report if no defensible path remains and what would unlock progress>
+</untrusted_goal_contract>
 
 Emitter name: <goal-emitter-name>
+EventStream name: <goal-emitter-name>
+Schedule mode: <idle | timed-autopilot>
 Iteration budget: <max-runs>
 
 At the start of each iteration:
-1. Call tap_list_emitters and locate the emitter entry in the returned list whose name is exactly '<goal-emitter-name>'.
+1. Call tap_list_emitters and locate the emitter entry whose name is exactly '<goal-emitter-name>'.
 2. Read its current runs and maxRuns values.
 3. If the emitter is missing, report that the goal loop is no longer running and stop.
 4. Estimate remaining iterations.
 
-Auto-steering rules:
+Continuation rules:
+- Treat the goal as a completion contract: work -> check evidence -> continue, complete, or stop blocked.
 - If remaining iterations are low (3 or fewer), switch into wrap-up mode.
-- In wrap-up mode, prefer finishing the smallest high-value task, validating what changed, and leaving a precise handoff.
-- If only 1 iteration remains and the goal is not complete, do not start broad new work. Leave the best concise handoff you can.
-- Do not treat budget exhaustion as success.
+- If only 1 iteration remains and the goal is not complete, do not start broad new work. Produce a budget-limited handoff instead.
+- Do not treat budget exhaustion or a lifecycle "reached run budget" message as success.
+- If this iteration makes no progress-producing tool calls beyond required status/ledger bookkeeping and does not change evidence, call `tap_post` with `channel='<goal-emitter-name>'` and a no-action handoff, then stop the emitter rather than spinning.
+
+Evidence-audit rules:
+- Before marking complete, identify the verification surface from the goal contract.
+- Check the evidence directly: test output, benchmark result, file content, diff, generated artifact, source material, or other concrete proof.
+- Check listed constraints for regressions.
+- If the verification surface cannot be checked, treat the goal as blocked, not complete.
+- Completion requires an explicit evidence audit in the final response and in the EventStream.
+
+Research/audit goal rules:
+- For research, reproduction, audit, or investigation goals, maintain a claim ledger.
+- Each ledger item should include: Claim, route attempted, evidence surface, status, and remaining uncertainty.
+- Use statuses such as confirmed, approximate-support, blocked, and uncertain. Do not flatten partial support into success.
 
 On this iteration:
 1. Briefly assess current progress toward the goal and the remaining iteration budget.
-2. If the goal is already achieved, call tap_stop_emitter for '<goal-emitter-name>' with scope='temporary', report that the goal is complete, and stop.
-3. If the goal is blocked by missing information, permissions, failing external systems, or an unsafe action, report the blocker, call tap_stop_emitter for '<goal-emitter-name>' with scope='temporary', and stop.
-4. Otherwise, choose the next smallest useful action toward the goal that fits the remaining budget and perform it.
-5. Validate the action using the repository's existing checks when relevant.
-6. End with a concise progress update, what remains, and the best next step if the loop stops before completion.
+2. If the goal is already achieved, first call `tap_post` with `channel='<goal-emitter-name>'` and a GOAL COMPLETE evidence audit in `message`, then call tap_stop_emitter for '<goal-emitter-name>' with scope='temporary', report that the goal is complete, and stop.
+3. If the goal is blocked by missing information, permissions, failing external systems, or an unsafe action, first call `tap_post` with `channel='<goal-emitter-name>'` and a GOAL BLOCKED report in `message`, then call tap_stop_emitter for '<goal-emitter-name>' with scope='temporary', report the blocker, and stop.
+4. If this is the final iteration and the goal is not complete, do not start substantive new work. Call `tap_post` with `channel='<goal-emitter-name>'` and a BUDGET LIMITED summary in `message`: progress, evidence gathered, remaining work, and recommended next goal or budget. Then leave a concise handoff.
+5. Otherwise, choose the next smallest useful action toward the goal that fits the remaining budget and perform it.
+6. Validate the action using the repository's existing checks when relevant.
+7. End by calling `tap_post` with `channel='<goal-emitter-name>'` and an ITERATION RECORD in `message` containing:
+   - iteration and budget used
+   - action taken
+   - evidence checked and result
+   - current status: progressing, complete, blocked, or budget-limited
+   - next best action
+8. End the user-visible response with the same concise progress update, what remains, and the next best step if the loop stops before completion.
 
 Safety rules:
 - Do not make unrelated changes.
@@ -95,7 +170,7 @@ Safety rules:
 - Stop yourself when done or blocked; do not rely on the user to notice.
 ```
 
-Substitute the real objective, emitter name, and max iteration count before passing the prompt to `tap_start_emitter`.
+Substitute the real objective, goal-contract fields, emitter name, schedule mode, and max iteration count before passing the prompt to `tap_start_emitter`.
 
 ## Required behavior
 
@@ -110,26 +185,36 @@ When this skill is invoked:
    - if none exist, report that no goal loop is running
    - if multiple exist and the user did not name one, ask them to choose one after showing `/tap-goal status`
    - when you do stop one, call `tap_stop_emitter` with its exact name and confirm that it will not fire again
-4. If the user is asking to pause an existing goal, explain that pausing is not supported for goal loops because idle PromptEmitters do not preserve resumable internal state. Offer to stop the loop instead. Only call `tap_stop_emitter` if they confirm; otherwise take no action and leave the goal loop running.
-5. If the user is asking to resume a goal, create a new `/tap-goal` loop with the resumed objective; ask for the objective if it is not clear.
+4. If the user is asking to pause an existing goal:
+   - Explain that runtime-native pause is not supported because PromptEmitters do not preserve resumable internal state.
+   - Offer a simulated pause: call `tap_post` with a PAUSED NOTE containing objective, current status, progress, and resume guidance, then call `tap_stop_emitter`.
+   - Only stop the emitter if the user confirms; otherwise leave it running.
+5. If the user is asking to resume a goal:
+   - If they provide an objective, create a new `/tap-goal` loop from it.
+   - If they name a prior goal stream, inspect its history with `tap_stream_history` using `channel='<goal-stream-name>'`, recover the latest PAUSED NOTE or handoff if available, and create a new loop from that objective.
+   - If the objective is not clear, ask for it.
 6. Before creating a new goal, check for existing `goal-*` emitters. If one exists and the user did not explicitly ask to replace it, ask for confirmation before starting another goal loop.
-7. If the user wants the loop to keep nudging the session even while Copilot stays busy in autopilot-style work, explain that idle goal loops may not fire until the session becomes idle. Suggest a timed PromptEmitter or hook/session-injector based delivery instead.
-8. Otherwise, create the idle PromptEmitter using the template above.
+7. Choose idle vs timed-autopilot schedule using the schedule rules above.
+8. Create the PromptEmitter using the template above.
 9. Confirm to the user:
    - Goal emitter name
    - EventStream name
    - Objective
+   - Verification surface
+   - Constraints
+   - Schedule mode (`idle` or `timed-autopilot`)
    - Max iteration count
-   - That it will advance when the session is idle and stop itself when complete or blocked
+   - That it will stop itself when complete, blocked, or budget-limited
 10. Stop there. Do not immediately perform the first goal iteration unless the user explicitly asks you to start working now.
 
 ## Iteration budget
 
-Idle goal loops must always have `maxRuns`.
+Goal loops must always have `maxRuns`.
 
 - If the user gives a budget, use it.
 - Otherwise, default to `50`.
 - If the objective is large, tell the user they can invoke `/tap-goal` again with a higher budget.
+- Budget exhaustion is a handoff state, not success.
 
 ## Persistence
 

package/dist/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "2.0.6"
+  "version": "2.0.7"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilot-tap-extension",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Copilot CLI extension for background event emitters, event streams, and session injection.",
   "type": "module",
   "license": "MIT",