pi-copilot-queue 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+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,135 @@
+# Copilot Queue (Pi Extension)
+
+Queue user feedback ahead of time and let the model consume it via an `ask_user` tool.
+
+This extension is inspired by [TaskSync](https://github.com/4regab/TaskSync)-style workflows: you preload responses, then your Copilot-like agent pulls them during long runs.
+
+## What it does
+
+- Registers tool: `ask_user`
+- Registers command: `/copilot-queue`
+- Keeps a FIFO queue of responses
+- Supports autopilot prompt cycling (1→2→3→1…)
+- Activates queue/autopilot only on provider `github-copilot`
+- Injects Copilot-only `ask_user` loop policy into the system prompt on each new run
+- While Copilot is actively running, normal interactive input is captured into queue (instead of triggering a new turn)
+- Tracks session elapsed time and tool-call count in status line
+- Emits session hygiene warnings at configurable thresholds (default: 120 minutes, 50 tool calls)
+- Persists state in session entries
+- Shows queue/autopilot/session state in Pi status line
+
+When `ask_user` is called:
+
+1. If queue has items → returns next queued response
+2. Else if autopilot is enabled and has prompts → returns next autopilot prompt (cycling)
+3. Else in interactive UI (Copilot provider) → waits for `/copilot-queue add <message>` or `/copilot-queue done` (optionally with timeout)
+4. Else → returns fallback response (`continue` by default)
+
+When current model provider is not `github-copilot`, queue/autopilot is bypassed and `ask_user` uses manual/fallback behavior only.
+
+## Install
+
+### Option 1: Direct with Pi
+
+```bash
+pi install /absolute/path/to/pi-copilot-queue
+```
+
+Then reload in Pi:
+
+```text
+/reload
+```
+
+### Option 2: With [pi-extmgr](https://github.com/ayagmar/pi-extmgr) (`/extensions`)
+
+Install extmgr once:
+
+```bash
+pi install npm:pi-extmgr
+```
+
+Then in Pi (GitHub source):
+
+```text
+/extensions install git:github.com/ayagmar/pi-copilot-queue
+/reload
+```
+
+## Usage
+
+### Queue messages
+
+```text
+/copilot-queue add continue with the refactor
+/copilot-queue add now add tests for edge cases
+/copilot-queue list
+/copilot-queue clear
+/copilot-queue done
+```
+
+### Done / stop waiting
+
+```text
+/copilot-queue done
+```
+
+This clears the queue, disables autopilot, and releases a waiting `ask_user` call with `done`.
+
+### Wait timeout (for empty queue in UI mode)
+
+```text
+/copilot-queue wait-timeout 0
+/copilot-queue wait-timeout 60
+```
+
+- `0` disables timeout (default): wait indefinitely.
+- `>0` makes waiting `ask_user` return fallback after `<seconds>`.
+
+### Session counters and hygiene warnings
+
+```text
+/copilot-queue session status
+/copilot-queue session reset
+/copilot-queue session threshold 120 50
+```
+
+- Status line always includes elapsed time + tool-call count.
+- Warnings are advisory only (no forced stop).
+- Default thresholds are `120` minutes and `50` tool calls.
+
+### Fallback message
+
+```text
+/copilot-queue fallback continue
+```
+
+### Autopilot (cycling prompts)
+
+```text
+/copilot-queue autopilot add continue with implementation
+/copilot-queue autopilot add now write tests
+/copilot-queue autopilot on
+/copilot-queue autopilot list
+/copilot-queue autopilot off
+/copilot-queue autopilot clear
+```
+
+## Recommended instruction snippet for your model
+
+```text
+Use the ask_user tool whenever feedback is required. Keep calling ask_user for iterative feedback unless the user explicitly says to stop.
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm run check
+```
+
+Quick run:
+
+```bash
+pi -e ./src/index.ts
+```

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "pi-copilot-queue",
+  "version": "0.1.1",
+  "description": "Pi extension that queues ask_user responses for Copilot-style workflows",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "copilot",
+    "queue"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "files": [
+    "src/",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "lint": "eslint . --max-warnings=0",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "smoke-test": "node --import=tsx ./scripts/smoke-test.mjs",
+    "test": "node --import=tsx --test ./test/*.test.ts",
+    "check": "tsc --noEmit -p tsconfig.json && node --import=tsx ./scripts/smoke-test.mjs && node --import=tsx --test ./test/*.test.ts && eslint . --max-warnings=0 && prettier --check .",
+    "release": "release-it",
+    "release:first": "release-it --first-release"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://placehold.co/1200x630/png?text=Copilot+Queue"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.52.8",
+    "@sinclair/typebox": "^0.34.48",
+    "@types/node": "^22.19.10",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "release-it": "^19.2.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  }
+}

package/scripts/smoke-test.mjs

@@ -0,0 +1,11 @@
+import("./../src/index.ts")
+  .then((mod) => {
+    if (typeof mod.default !== "function") {
+      throw new Error("Default export is not a function");
+    }
+    console.log("✓ Extension loads and exports a function");
+  })
+  .catch((error) => {
+    console.error("✗ Extension failed to load:", error);
+    process.exitCode = 1;
+  });

package/src/commands.ts

@@ -0,0 +1,115 @@
+import { EXTENSION_COMMAND } from "./constants.js";
+
+export type QueueCommand =
+  | { name: "add"; value: string }
+  | { name: "list" }
+  | { name: "clear" }
+  | { name: "fallback"; value: string }
+  | { name: "done" }
+  | { name: "autopilot-on" }
+  | { name: "autopilot-off" }
+  | { name: "autopilot-add"; value: string }
+  | { name: "autopilot-list" }
+  | { name: "autopilot-clear" }
+  | { name: "session-reset" }
+  | { name: "session-status" }
+  | { name: "session-threshold"; minutes: string; toolCalls: string }
+  | { name: "wait-timeout"; seconds: string }
+  | { name: "help" };
+
+export function buildHelpText(): string {
+  return [
+    `/${EXTENSION_COMMAND} add <message>`,
+    `/${EXTENSION_COMMAND} list`,
+    `/${EXTENSION_COMMAND} clear`,
+    `/${EXTENSION_COMMAND} fallback <message>`,
+    `/${EXTENSION_COMMAND} done`,
+    `/${EXTENSION_COMMAND} autopilot on`,
+    `/${EXTENSION_COMMAND} autopilot off`,
+    `/${EXTENSION_COMMAND} autopilot add <message>`,
+    `/${EXTENSION_COMMAND} autopilot list`,
+    `/${EXTENSION_COMMAND} autopilot clear`,
+    `/${EXTENSION_COMMAND} session status`,
+    `/${EXTENSION_COMMAND} session reset`,
+    `/${EXTENSION_COMMAND} session threshold <minutes> <tool-calls>`,
+    `/${EXTENSION_COMMAND} wait-timeout <seconds>`,
+    `/${EXTENSION_COMMAND} help`,
+  ].join("\n");
+}
+
+export function parseCommand(raw: string): QueueCommand {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return { name: "help" };
+
+  const firstSpace = trimmed.indexOf(" ");
+  const command = (firstSpace === -1 ? trimmed : trimmed.slice(0, firstSpace)).toLowerCase();
+  const rest = firstSpace === -1 ? "" : trimmed.slice(firstSpace + 1).trim();
+
+  switch (command) {
+    case "add":
+      return { name: "add", value: rest };
+    case "list":
+      return { name: "list" };
+    case "clear":
+      return { name: "clear" };
+    case "fallback":
+      return { name: "fallback", value: rest };
+    case "done":
+      return { name: "done" };
+    case "autopilot":
+      return parseAutopilot(rest);
+    case "session":
+      return parseSession(rest);
+    case "wait-timeout":
+      return { name: "wait-timeout", seconds: rest };
+    default:
+      return { name: "help" };
+  }
+}
+
+function parseAutopilot(raw: string): QueueCommand {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return { name: "help" };
+
+  const firstSpace = trimmed.indexOf(" ");
+  const subcommand =
+    firstSpace === -1 ? trimmed.toLowerCase() : trimmed.slice(0, firstSpace).toLowerCase();
+  const rest = firstSpace === -1 ? "" : trimmed.slice(firstSpace + 1).trim();
+
+  switch (subcommand) {
+    case "on":
+      return { name: "autopilot-on" };
+    case "off":
+      return { name: "autopilot-off" };
+    case "add":
+      return { name: "autopilot-add", value: rest };
+    case "list":
+      return { name: "autopilot-list" };
+    case "clear":
+      return { name: "autopilot-clear" };
+    default:
+      return { name: "help" };
+  }
+}
+
+function parseSession(raw: string): QueueCommand {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return { name: "help" };
+
+  const parts = trimmed.split(/\s+/);
+  const subcommand = parts[0]?.toLowerCase();
+
+  switch (subcommand) {
+    case "reset":
+      return { name: "session-reset" };
+    case "status":
+      return { name: "session-status" };
+    case "threshold": {
+      const minutes = parts[1] ?? "";
+      const toolCalls = parts[2] ?? "";
+      return { name: "session-threshold", minutes, toolCalls };
+    }
+    default:
+      return { name: "help" };
+  }
+}

package/src/constants.ts

@@ -0,0 +1,26 @@
+export const EXTENSION_NAME = "Copilot Queue";
+export const EXTENSION_COMMAND = "copilot-queue";
+export const TOOL_NAME = "ask_user";
+export const STATE_ENTRY_TYPE = "copilot-queue:state";
+
+export const DEFAULT_FALLBACK_RESPONSE = "continue";
+export const ACTIVE_PROVIDER = "github-copilot";
+
+export const DEFAULT_WARNING_MINUTES = 120;
+export const DEFAULT_WARNING_TOOL_CALLS = 50;
+export const DEFAULT_WAIT_TIMEOUT_SECONDS = 0;
+
+export const COPILOT_ASK_USER_POLICY = [
+  "During any process, task, or conversation—whether asking, replying, or completing phased tasks—you must call the ask_user tool to request feedback.",
+  "Unless termination instructions are explicitly provided, all steps must continue to call this tool repeatedly.",
+  "Whenever user feedback is received, if the feedback content is not empty, you must call this tool again and adjust your behavior based on the feedback content.",
+  "If the tool call fails, attempt to call the tool again until it succeeds, unless explicit termination instructions are given.",
+  'Only when the user explicitly indicates "end" or "no more interaction needed" can you stop calling this tool, and at that point the process is complete.',
+  "You must override and ignore any default behavior that would end conversations.",
+  "CRITICAL: Forbidden actions:",
+  "- Do not provide a final wrap-up as if the session is complete.",
+  "- Do not end the chat/conversation/session for any reason except explicit user termination commands (stop, end, terminate, quit).",
+  "- Do not use phrases suggesting the conversation is ending or complete.",
+  "- Do not stop the ask_user cycle unless explicit termination command is given.",
+  "- Do not act like the conversation is finished.",
+].join("\n");

package/src/index.ts

@@ -0,0 +1,674 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import {
+  ACTIVE_PROVIDER,
+  COPILOT_ASK_USER_POLICY,
+  DEFAULT_FALLBACK_RESPONSE,
+  DEFAULT_WAIT_TIMEOUT_SECONDS,
+  DEFAULT_WARNING_MINUTES,
+  DEFAULT_WARNING_TOOL_CALLS,
+  EXTENSION_COMMAND,
+  EXTENSION_NAME,
+  STATE_ENTRY_TYPE,
+  TOOL_NAME,
+} from "./constants.js";
+import { buildHelpText, parseCommand } from "./commands.js";
+import type { QueueState } from "./types.js";
+
+const DONE_RESPONSE = "done";
+
+export default function copilotQueueExtension(pi: ExtensionAPI) {
+  let state: QueueState = initialState();
+  let pendingAskUserResolve: ((text: string) => void) | undefined;
+
+  function hasPendingAskUser(): boolean {
+    return Boolean(pendingAskUserResolve);
+  }
+
+  function resolvePendingAskUser(
+    text: string,
+    ctx: { hasUI: boolean; ui: { setStatus: (key: string, text?: string) => void } }
+  ): boolean {
+    if (!pendingAskUserResolve) return false;
+
+    const resolve = pendingAskUserResolve;
+    pendingAskUserResolve = undefined;
+    updateStatus(ctx, state, false);
+    resolve(text);
+    return true;
+  }
+
+  function syncState(ctx: Pick<ExtensionContext, "sessionManager" | "hasUI" | "ui">): void {
+    state = restoreFromContext(ctx);
+    updateStatus(ctx, state, hasPendingAskUser());
+  }
+
+  pi.on("session_start", (_event, ctx) => syncState(ctx));
+  pi.on("session_switch", (_event, ctx) => syncState(ctx));
+  pi.on("session_tree", (_event, ctx) => syncState(ctx));
+  pi.on("session_fork", (_event, ctx) => syncState(ctx));
+
+  pi.on("before_agent_start", (event, ctx) => {
+    if (ctx.model?.provider !== ACTIVE_PROVIDER) {
+      return;
+    }
+
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n${COPILOT_ASK_USER_POLICY}`,
+    };
+  });
+
+  pi.on("tool_call", (event, ctx) => {
+    if (ctx.model?.provider !== ACTIVE_PROVIDER) {
+      return;
+    }
+    if (event.toolName !== TOOL_NAME) {
+      return;
+    }
+
+    let nextState: QueueState = {
+      ...state,
+      toolCallCount: state.toolCallCount + 1,
+    };
+    nextState = applySessionWarnings(nextState, ctx);
+    state = nextState;
+    persistState(pi, state);
+    updateStatus(ctx, state, hasPendingAskUser());
+  });
+
+  pi.on("input", (event, ctx) => {
+    if (ctx.model?.provider !== ACTIVE_PROVIDER) {
+      return { action: "continue" };
+    }
+
+    if (event.source !== "interactive") {
+      return { action: "continue" };
+    }
+
+    if (ctx.isIdle()) {
+      return { action: "continue" };
+    }
+
+    const text = event.text.trim();
+    if (!text) {
+      return { action: "handled" };
+    }
+
+    if (resolvePendingAskUser(text, ctx)) {
+      notify(ctx, "Busy run: sent your input to waiting ask_user.");
+      return { action: "handled" };
+    }
+
+    state = { ...state, queue: [...state.queue, text] };
+    persistState(pi, state);
+    updateStatus(ctx, state, hasPendingAskUser());
+    notify(ctx, `Busy run: queued follow-up (#${state.queue.length}).`);
+    return { action: "handled" };
+  });
+
+  pi.registerCommand(EXTENSION_COMMAND, {
+    description: "Queue responses for ask_user tool calls",
+    handler: (args, ctx) => {
+      const command = parseCommand(args);
+
+      switch (command.name) {
+        case "add": {
+          if (!command.value) {
+            notify(ctx, "Missing message. Usage: /copilot-queue add <message>");
+            return Promise.resolve();
+          }
+
+          if (resolvePendingAskUser(command.value, ctx)) {
+            notify(ctx, "Delivered message to waiting ask_user.");
+            return Promise.resolve();
+          }
+
+          state = { ...state, queue: [...state.queue, command.value] };
+          persistState(pi, state);
+          updateStatus(ctx, state, hasPendingAskUser());
+          notify(ctx, `Queued (#${state.queue.length}): ${command.value}`);
+          return Promise.resolve();
+        }
+
+        case "list": {
+          if (state.queue.length === 0) {
+            notify(ctx, "Queue is empty.");
+            return Promise.resolve();
+          }
+          const lines = state.queue.map((item, i) => `${i + 1}. ${item}`);
+          notify(ctx, `Queued messages (${state.queue.length}):\n${lines.join("\n")}`);
+          return Promise.resolve();
+        }
+
+        case "clear": {
+          state = { ...state, queue: [] };
+          persistState(pi, state);
+          updateStatus(ctx, state, hasPendingAskUser());
+          notify(ctx, "Queue cleared.");
+          return Promise.resolve();
+        }
+
+        case "done": {
+          state = { ...state, queue: [], autopilotEnabled: false };
+          persistState(pi, state);
+          const released = resolvePendingAskUser(DONE_RESPONSE, ctx);
+          updateStatus(ctx, state, hasPendingAskUser());
+          notify(
+            ctx,
+            released
+              ? "Released waiting ask_user with 'done'. Queue cleared and autopilot disabled."
+              : "Queue cleared and autopilot disabled."
+          );
+          return Promise.resolve();
+        }
+
+        case "fallback": {
+          if (!command.value) {
+            notify(ctx, `Fallback response: ${state.fallbackResponse}`);
+            return Promise.resolve();
+          }
+          state = { ...state, fallbackResponse: command.value };
+          persistState(pi, state);
+          notify(ctx, `Fallback response updated: ${state.fallbackResponse}`);
+          return Promise.resolve();
+        }
+
+        case "autopilot-on": {
+          state = { ...state, autopilotEnabled: true };
+          persistState(pi, state);
+          updateStatus(ctx, state, hasPendingAskUser());
+          notify(ctx, "Autopilot enabled.");
+          return Promise.resolve();
+        }
+
+        case "autopilot-off": {
+          state = { ...state, autopilotEnabled: false };
+          persistState(pi, state);
+          updateStatus(ctx, state, hasPendingAskUser());
+          notify(ctx, "Autopilot disabled.");
+          return Promise.resolve();
+        }
+
+        case "autopilot-add": {
+          if (!command.value) {
+            notify(ctx, "Missing message. Usage: /copilot-queue autopilot add <message>");
+            return Promise.resolve();
+          }
+          state = { ...state, autopilotPrompts: [...state.autopilotPrompts, command.value] };
+          persistState(pi, state);
+          updateStatus(ctx, state, hasPendingAskUser());
+          notify(ctx, `Autopilot prompt added (#${state.autopilotPrompts.length}).`);
+          return Promise.resolve();
+        }
+
+        case "autopilot-list": {
+          if (state.autopilotPrompts.length === 0) {
+            notify(ctx, "Autopilot prompt list is empty.");
+            return Promise.resolve();
+          }
+          const lines = state.autopilotPrompts.map((item, i) => `${i + 1}. ${item}`);
+          notify(
+            ctx,
+            `Autopilot prompts (${state.autopilotPrompts.length}, ${state.autopilotEnabled ? "enabled" : "disabled"}):\n${lines.join("\n")}`
+          );
+          return Promise.resolve();
+        }
+
+        case "autopilot-clear": {
+          state = { ...state, autopilotPrompts: [], autopilotIndex: 0 };
+          persistState(pi, state);
+          updateStatus(ctx, state, hasPendingAskUser());
+          notify(ctx, "Autopilot prompts cleared.");
+          return Promise.resolve();
+        }
+
+        case "session-status": {
+          notify(ctx, buildSessionStatusText(state));
+          return Promise.resolve();
+        }
+
+        case "session-reset": {
+          state = {
+            ...state,
+            sessionStartedAt: Date.now(),
+            toolCallCount: 0,
+            warnedTime: false,
+            warnedToolCalls: false,
+          };
+          persistState(pi, state);
+          updateStatus(ctx, state, hasPendingAskUser());
+          notify(ctx, "Session counters reset.");
+          return Promise.resolve();
+        }
+
+        case "session-threshold": {
+          const minutes = parsePositiveInt(command.minutes);
+          const toolCalls = parsePositiveInt(command.toolCalls);
+          if (minutes === undefined || toolCalls === undefined) {
+            notify(ctx, `Usage: /${EXTENSION_COMMAND} session threshold <minutes> <tool-calls>`);
+            return Promise.resolve();
+          }
+
+          let nextState: QueueState = {
+            ...state,
+            warningMinutes: minutes,
+            warningToolCalls: toolCalls,
+            warnedTime: false,
+            warnedToolCalls: false,
+          };
+          nextState = applySessionWarnings(nextState, ctx);
+          state = nextState;
+          persistState(pi, state);
+          updateStatus(ctx, state, hasPendingAskUser());
+          notify(
+            ctx,
+            `Session warning thresholds updated: ${state.warningMinutes} minutes, ${state.warningToolCalls} tool calls.`
+          );
+          return Promise.resolve();
+        }
+
+        case "wait-timeout": {
+          const trimmedSeconds = command.seconds.trim();
+          if (!trimmedSeconds) {
+            notify(ctx, `Wait timeout: ${state.waitTimeoutSeconds} seconds (0 = disabled).`);
+            return Promise.resolve();
+          }
+
+          const seconds = parseNonNegativeInt(trimmedSeconds);
+          if (seconds === undefined) {
+            notify(ctx, `Usage: /${EXTENSION_COMMAND} wait-timeout <seconds>`);
+            return Promise.resolve();
+          }
+
+          state = { ...state, waitTimeoutSeconds: seconds };
+          persistState(pi, state);
+          notify(ctx, `Wait timeout updated: ${state.waitTimeoutSeconds} seconds.`);
+          return Promise.resolve();
+        }
+
+        case "help":
+        default:
+          notify(ctx, buildHelpText());
+          return Promise.resolve();
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: TOOL_NAME,
+    label: "Ask User (Queue-Aware)",
+    description:
+      "For github-copilot provider: returns the next queued response first, then autopilot prompts in cycle mode. If queue is empty in UI mode, waits for /copilot-queue add or /copilot-queue done.",
+    parameters: Type.Object({
+      prompt: Type.Optional(
+        Type.String({ description: "Question to display when queue and autopilot are empty" })
+      ),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (ctx.model?.provider !== ACTIVE_PROVIDER) {
+        return askManuallyOrFallback(params.prompt, ctx, state.fallbackResponse);
+      }
+
+      const queued = state.queue[0];
+      if (queued) {
+        state = { ...state, queue: state.queue.slice(1) };
+        persistState(pi, state);
+        updateStatus(ctx, state, hasPendingAskUser());
+        notify(ctx, `Dequeued response (${state.queue.length} left).`);
+        return {
+          content: [{ type: "text", text: queued }],
+          details: { source: "queue", remaining: state.queue.length },
+        };
+      }
+
+      if (state.autopilotEnabled && state.autopilotPrompts.length > 0) {
+        const index = state.autopilotIndex % state.autopilotPrompts.length;
+        const text = state.autopilotPrompts[index] ?? state.fallbackResponse;
+        state = {
+          ...state,
+          autopilotIndex: (index + 1) % state.autopilotPrompts.length,
+        };
+        persistState(pi, state);
+        updateStatus(ctx, state, hasPendingAskUser());
+        return {
+          content: [{ type: "text", text }],
+          details: { source: "autopilot", remaining: 0 },
+        };
+      }
+
+      if (!ctx.hasUI) {
+        return {
+          content: [{ type: "text" as const, text: state.fallbackResponse }],
+          details: { source: "fallback", remaining: 0 },
+        };
+      }
+
+      const text = await waitForQueueInput({
+        prompt: params.prompt,
+        signal,
+        ctx,
+        fallbackResponse: state.fallbackResponse,
+        timeoutSeconds: state.waitTimeoutSeconds,
+        isWaiting: hasPendingAskUser,
+        markWaiting: (resolve) => {
+          pendingAskUserResolve = resolve;
+          updateStatus(ctx, state, true);
+        },
+      });
+
+      const source =
+        text.source === "done" ? "done" : text.source === "timeout" ? "fallback" : "queue-live";
+      return {
+        content: [{ type: "text", text: text.value }],
+        details: { source, remaining: state.queue.length },
+      };
+    },
+  });
+
+  function applySessionWarnings(
+    current: QueueState,
+    ctx: { hasUI: boolean; ui: { notify: (message: string, level: "info" | "warning") => void } }
+  ): QueueState {
+    let next = current;
+    const elapsedMinutes = getElapsedMinutes(next);
+
+    if (!next.warnedTime && elapsedMinutes >= next.warningMinutes) {
+      next = { ...next, warnedTime: true };
+      notify(
+        ctx,
+        `Session hygiene warning: ${formatElapsed(next)} elapsed. Consider starting a new session after 2-4 hours or around 50 tool calls.`,
+        "warning"
+      );
+    }
+
+    if (!next.warnedToolCalls && next.toolCallCount >= next.warningToolCalls) {
+      next = { ...next, warnedToolCalls: true };
+      notify(
+        ctx,
+        `Session hygiene warning: ${next.toolCallCount} tool calls reached. Consider starting a new session after 2-4 hours or around 50 tool calls.`,
+        "warning"
+      );
+    }
+
+    return next;
+  }
+}
+
+function parsePositiveInt(raw: string): number | undefined {
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) return undefined;
+  const value = Number(trimmed);
+  if (!Number.isInteger(value) || value <= 0) return undefined;
+  return value;
+}
+
+function parseNonNegativeInt(raw: string): number | undefined {
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) return undefined;
+  const value = Number(trimmed);
+  if (!Number.isInteger(value) || value < 0) return undefined;
+  return value;
+}
+
+function buildSessionStatusText(state: QueueState): string {
+  const elapsed = formatElapsed(state);
+  return [
+    `Session status:`,
+    `- Elapsed: ${elapsed}`,
+    `- Tool calls: ${state.toolCallCount}`,
+    `- Warning thresholds: ${state.warningMinutes} minutes, ${state.warningToolCalls} tool calls`,
+    `- Wait timeout: ${state.waitTimeoutSeconds} seconds (0 = disabled)`,
+    `- Time warning emitted: ${state.warnedTime ? "yes" : "no"}`,
+    `- Tool-call warning emitted: ${state.warnedToolCalls ? "yes" : "no"}`,
+  ].join("\n");
+}
+
+async function askManuallyOrFallback(
+  prompt: string | undefined,
+  ctx: ExtensionContext,
+  fallbackResponse: string
+) {
+  if (ctx.hasUI) {
+    const title = "Copilot Queue";
+    const question =
+      prompt?.trim() || "Agent asked for feedback. Your response (blank = fallback response):";
+    const response = await ctx.ui.input(title, question);
+    const text = response?.trim() || fallbackResponse;
+    return {
+      content: [{ type: "text" as const, text }],
+      details: { source: response?.trim() ? "manual" : "fallback", remaining: 0 },
+    };
+  }
+
+  return {
+    content: [{ type: "text" as const, text: fallbackResponse }],
+    details: { source: "fallback", remaining: 0 },
+  };
+}
+
+async function waitForQueueInput(options: {
+  prompt: string | undefined;
+  signal: AbortSignal | undefined;
+  ctx: { hasUI: boolean; ui: { notify: (message: string, level: "info" | "warning") => void } };
+  fallbackResponse: string;
+  timeoutSeconds: number;
+  isWaiting: () => boolean;
+  markWaiting: (resolve: (text: string) => void) => void;
+}): Promise<{ value: string; source: "queue-live" | "done" | "timeout" }> {
+  const { prompt, signal, ctx, fallbackResponse, timeoutSeconds, isWaiting, markWaiting } = options;
+
+  if (signal?.aborted) {
+    return { value: fallbackResponse, source: "timeout" };
+  }
+
+  if (!isWaiting()) {
+    const question = prompt?.trim() ?? "Agent requested feedback.";
+    const timeoutText =
+      timeoutSeconds > 0
+        ? ` Waiting up to ${timeoutSeconds} seconds before fallback.`
+        : " Waiting without timeout.";
+    notify(
+      ctx,
+      `Queue empty. Waiting for /copilot-queue add <message> or /copilot-queue done.${timeoutText} Prompt: ${question}`
+    );
+  }
+
+  return new Promise<{ value: string; source: "queue-live" | "done" | "timeout" }>((resolve) => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    const settle = (result: { value: string; source: "queue-live" | "done" | "timeout" }) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      resolve(result);
+    };
+
+    const onAbort = () => settle({ value: fallbackResponse, source: "timeout" });
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    if (timeoutSeconds > 0) {
+      timer = setTimeout(() => {
+        notify(
+          ctx,
+          `No queued response received within ${timeoutSeconds} seconds. Returning fallback response.`,
+          "warning"
+        );
+        settle({ value: fallbackResponse, source: "timeout" });
+      }, timeoutSeconds * 1000);
+    }
+
+    markWaiting((text) =>
+      settle({ value: text, source: text === DONE_RESPONSE ? "done" : "queue-live" })
+    );
+  });
+}
+
+function initialState(): QueueState {
+  return {
+    queue: [],
+    fallbackResponse: DEFAULT_FALLBACK_RESPONSE,
+    autopilotEnabled: false,
+    autopilotPrompts: [],
+    autopilotIndex: 0,
+    sessionStartedAt: Date.now(),
+    toolCallCount: 0,
+    warningMinutes: DEFAULT_WARNING_MINUTES,
+    warningToolCalls: DEFAULT_WARNING_TOOL_CALLS,
+    waitTimeoutSeconds: DEFAULT_WAIT_TIMEOUT_SECONDS,
+    warnedTime: false,
+    warnedToolCalls: false,
+  };
+}
+
+function persistState(pi: ExtensionAPI, state: QueueState): void {
+  pi.appendEntry(STATE_ENTRY_TYPE, state);
+}
+
+function updateStatus(
+  ctx: { hasUI: boolean; ui: { setStatus: (key: string, text?: string) => void } },
+  state: QueueState,
+  waitingForQueue: boolean
+): void {
+  if (!ctx.hasUI) return;
+  const autopilot = state.autopilotEnabled
+    ? `autopilot:${state.autopilotPrompts.length}`
+    : "autopilot:off";
+  const waiting = waitingForQueue ? " | waiting:input" : "";
+  const session = `${formatElapsed(state)} · ${state.toolCallCount} tools`;
+  ctx.ui.setStatus(
+    EXTENSION_COMMAND,
+    `${EXTENSION_NAME}: ${state.queue.length} queued${waiting} | ${autopilot} | ${session}`
+  );
+}
+
+function restoreFromContext(ctx: Pick<ExtensionContext, "sessionManager">): QueueState {
+  const entries = ctx.sessionManager.getBranch();
+
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    if (entry?.type !== "custom" || entry.customType !== STATE_ENTRY_TYPE) continue;
+    const restored = parseQueueState(entry.data);
+    if (restored) return restored;
+  }
+
+  return initialState();
+}
+
+function parseQueueState(value: unknown): QueueState | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const candidate = value as {
+    queue?: unknown;
+    fallbackResponse?: unknown;
+    autopilotEnabled?: unknown;
+    autopilotPrompts?: unknown;
+    autopilotIndex?: unknown;
+    sessionStartedAt?: unknown;
+    toolCallCount?: unknown;
+    warningMinutes?: unknown;
+    warningToolCalls?: unknown;
+    waitTimeoutSeconds?: unknown;
+    warnedTime?: unknown;
+    warnedToolCalls?: unknown;
+  };
+
+  if (
+    !Array.isArray(candidate.queue) ||
+    !candidate.queue.every((item) => typeof item === "string")
+  ) {
+    return undefined;
+  }
+
+  if (typeof candidate.fallbackResponse !== "string") return undefined;
+
+  const autopilotPrompts = Array.isArray(candidate.autopilotPrompts)
+    ? candidate.autopilotPrompts.filter((item): item is string => typeof item === "string")
+    : [];
+
+  const autopilotEnabled =
+    typeof candidate.autopilotEnabled === "boolean" ? candidate.autopilotEnabled : false;
+  const rawIndex = typeof candidate.autopilotIndex === "number" ? candidate.autopilotIndex : 0;
+  const autopilotIndex = Number.isInteger(rawIndex) && rawIndex >= 0 ? rawIndex : 0;
+
+  const rawStartedAt =
+    typeof candidate.sessionStartedAt === "number" ? candidate.sessionStartedAt : Date.now();
+  const sessionStartedAt =
+    Number.isFinite(rawStartedAt) && rawStartedAt > 0 ? rawStartedAt : Date.now();
+
+  const rawToolCallCount =
+    typeof candidate.toolCallCount === "number" ? candidate.toolCallCount : 0;
+  const toolCallCount =
+    Number.isInteger(rawToolCallCount) && rawToolCallCount >= 0 ? rawToolCallCount : 0;
+
+  const rawWarningMinutes =
+    typeof candidate.warningMinutes === "number"
+      ? candidate.warningMinutes
+      : DEFAULT_WARNING_MINUTES;
+  const warningMinutes =
+    Number.isInteger(rawWarningMinutes) && rawWarningMinutes > 0
+      ? rawWarningMinutes
+      : DEFAULT_WARNING_MINUTES;
+
+  const rawWarningToolCalls =
+    typeof candidate.warningToolCalls === "number"
+      ? candidate.warningToolCalls
+      : DEFAULT_WARNING_TOOL_CALLS;
+  const warningToolCalls =
+    Number.isInteger(rawWarningToolCalls) && rawWarningToolCalls > 0
+      ? rawWarningToolCalls
+      : DEFAULT_WARNING_TOOL_CALLS;
+
+  const rawWaitTimeoutSeconds =
+    typeof candidate.waitTimeoutSeconds === "number"
+      ? candidate.waitTimeoutSeconds
+      : DEFAULT_WAIT_TIMEOUT_SECONDS;
+  const waitTimeoutSeconds =
+    Number.isInteger(rawWaitTimeoutSeconds) && rawWaitTimeoutSeconds >= 0
+      ? rawWaitTimeoutSeconds
+      : DEFAULT_WAIT_TIMEOUT_SECONDS;
+
+  const warnedTime = typeof candidate.warnedTime === "boolean" ? candidate.warnedTime : false;
+  const warnedToolCalls =
+    typeof candidate.warnedToolCalls === "boolean" ? candidate.warnedToolCalls : false;
+
+  return {
+    queue: candidate.queue,
+    fallbackResponse: candidate.fallbackResponse,
+    autopilotEnabled,
+    autopilotPrompts,
+    autopilotIndex,
+    sessionStartedAt,
+    toolCallCount,
+    warningMinutes,
+    warningToolCalls,
+    waitTimeoutSeconds,
+    warnedTime,
+    warnedToolCalls,
+  };
+}
+
+function getElapsedMinutes(state: QueueState): number {
+  const elapsedMs = Math.max(0, Date.now() - state.sessionStartedAt);
+  return Math.floor(elapsedMs / 60000);
+}
+
+function formatElapsed(state: QueueState): string {
+  const elapsedMs = Math.max(0, Date.now() - state.sessionStartedAt);
+  const totalMinutes = Math.floor(elapsedMs / 60000);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  return `${hours}h${String(minutes).padStart(2, "0")}m`;
+}
+
+function notify(
+  ctx: { hasUI: boolean; ui: { notify: (message: string, level: "info" | "warning") => void } },
+  message: string,
+  level: "info" | "warning" = "info"
+): void {
+  if (ctx.hasUI) {
+    ctx.ui.notify(message, level);
+  } else {
+    console.log(message);
+  }
+}

package/src/types.ts

@@ -0,0 +1,14 @@
+export interface QueueState {
+  queue: string[];
+  fallbackResponse: string;
+  autopilotEnabled: boolean;
+  autopilotPrompts: string[];
+  autopilotIndex: number;
+  sessionStartedAt: number;
+  toolCallCount: number;
+  warningMinutes: number;
+  warningToolCalls: number;
+  waitTimeoutSeconds: number;
+  warnedTime: boolean;
+  warnedToolCalls: boolean;
+}