@dyyz1993/pi-coding-agent 0.74.24 → 0.74.27

package/dist/extensions/session-supervisor/prompts.ts

@@ -0,0 +1,132 @@
+export const COMPLETION_CHECK_SYSTEM_PROMPT = `You are a session completion checker. Your job is to determine if a coding agent session has truly completed all tasks or if there are remaining incomplete tasks.
+
+Analyze the conversation history and determine:
+
+1. **completed**: Whether all requested tasks have been finished
+2. **confidence**: Your confidence level (0-1)
+3. **incompleteTasks**: List any tasks that appear incomplete, with severity:
+   - "high": Critical unfinished task (e.g., build errors, test failures, incomplete code changes)
+   - "medium": Important but non-blocking (e.g., documentation pending, minor refactoring)
+   - "low": Nice-to-have (e.g., optimization opportunities, style improvements)
+4. **reasoning**: Brief explanation of your assessment
+
+IMPORTANT:
+- A task is incomplete only if the user explicitly requested it and it hasn't been done
+- If the agent mentioned it would do something but hasn't done it yet, mark it incomplete
+- If there are running background processes (CI, builds, tests), mark them as incomplete
+- If the agent asked a question and hasn't received an answer, mark it incomplete
+- If all tasks are done and the agent is just summarizing, mark as completed
+
+You MUST respond with valid JSON only, no markdown.`;
+
+// ── Generic continue prompt ──
+
+export const CONTINUE_PROMPT = (reason: string, tasks: string[]) =>
+    `[Supervisor] Session may not be fully complete.
+
+Reason: ${reason}
+
+Remaining items:
+${tasks.map((t, i) => `${i + 1}. ${t}`).join("\n")}
+
+Please continue working on the remaining items. Do not repeat work that has already been completed.`;
+
+// ── Guard-specific prompt generators ──
+
+export const TODO_GUARD_PROMPT = (remainingTodos: string[]) =>
+    `[Supervisor/TodoGuard] The following todo items are not yet completed:
+
+${remainingTodos.map((t, i) => `${i + 1}. ${t}`).join("\n")}
+
+Please continue working on these items. Complete each one before moving on.`;
+
+export const SPECS_GUARD_PROMPT = (
+    specsFile: string,
+    completedItems: string[],
+    remainingItems: string[],
+    progress: string,
+) =>
+    `[Supervisor/SpecsGuard] Specs progress report (${specsFile}):
+
+Progress: ${progress}
+
+Completed items:
+${completedItems.length > 0 ? completedItems.map((t, i) => `  ✓ ${t}`).join("\n") : "  (none yet)"}
+
+Remaining items:
+${remainingItems.map((t, i) => `  ○ ${t}`).join("\n")}
+
+IMPORTANT: You MUST continue working on the remaining items. Do NOT declare completion until ALL items are done.
+Do not skip any item. Work through them one by one.`;
+
+export const SPECS_GUARD_BLOCK_MESSAGE = (
+    remainingItems: string[],
+    attempt: number,
+) =>
+    `[Supervisor/SpecsGuard/BLOCKED] Agent attempted to declare completion, but ${remainingItems.length} items remain (attempt #${attempt}).
+
+Remaining:
+${remainingItems.map((t, i) => `  ${i + 1}. ${t}`).join("\n")}
+
+You MUST continue. Do not argue that the work is done — the specs file is the source of truth.`;
+
+export const CI_GUARD_PROMPT = (status: string, command?: string) =>
+    `[Supervisor/CiGuard] CI check result: ${status}${command ? `\nCheck command: ${command}` : ""}
+
+Please wait for CI to complete or fix any failures before declaring completion.`;
+
+export const KEYWORD_GUARD_PROMPT = (foundKeywords: string[], context: string) =>
+    `[Supervisor/KeywordGuard] The following keywords indicate incomplete work: ${foundKeywords.join(", ")}
+
+Context: ${context}
+
+Please address these items before completing.`;
+
+export const CUSTOM_GUARD_PROMPT = (template: string, context: Record<string, string>) => {
+    let result = template;
+    for (const [key, value] of Object.entries(context)) {
+        result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, "g"), value);
+    }
+    return result;
+};
+
+export const PAUSE_NOTIFICATION = (delayMs: number, reason?: string) =>
+    `[Supervisor] Session paused for ${Math.round(delayMs / 1000)}s${reason ? `: ${reason}` : ""}. Will auto-continue after delay.`;
+
+// ── Guard check prompts (for model-based guards) ──
+
+export const TODO_CHECK_PROMPT = (todosJson: string) =>
+    `You are checking if all todo items are completed. Here is the current todo list:
+
+${todosJson}
+
+For each item, determine if it is completed or not. Respond with JSON:
+{
+  "completed": boolean,
+  "confidence": number (0-1),
+  "remainingItems": string[],
+  "reasoning": string
+}
+
+You MUST respond with valid JSON only.`;
+
+export const SPECS_CHECK_PROMPT = (specsContent: string, lastAssistantText: string) =>
+    `You are checking specs completion. Here is the specs file:
+
+${specsContent}
+
+Here is the agent's last message:
+${lastAssistantText.slice(0, 2000)}
+
+For each spec item, determine if it has been implemented. Respond with JSON:
+{
+  "completed": boolean,
+  "confidence": number (0-1),
+  "completedItems": string[],
+  "remainingItems": string[],
+  "reasoning": string
+}
+
+IMPORTANT: An item is only "completed" if there is clear evidence in the conversation that it was implemented. If the agent merely mentions it will do something but hasn't done it yet, mark it as remaining.
+
+You MUST respond with valid JSON only.`;

package/dist/extensions/session-supervisor/scheduler.ts

@@ -0,0 +1,69 @@
+export class Scheduler {
+    private timers: Map<
+        string,
+        { timer: NodeJS.Timeout; abort: AbortController }
+    > = new Map();
+    private continueCount = 0;
+
+    constructor(
+        private maxContinueCount: number,
+        private pauseThresholdMs: number,
+    ) {}
+
+    scheduleContinue(
+        id: string,
+        delayMs: number,
+        callback: () => void,
+    ): { scheduled: boolean; scheduledAt?: number } {
+        if (this.continueCount >= this.maxContinueCount) {
+            return { scheduled: false };
+        }
+
+        this.cancelTimer(id);
+
+        const abort = new AbortController();
+        const scheduledAt = Date.now() + delayMs;
+
+        const timer = setTimeout(() => {
+            this.continueCount++;
+            this.timers.delete(id);
+            if (!abort.signal.aborted) {
+                callback();
+            }
+        }, delayMs);
+
+        this.timers.set(id, { timer, abort });
+        return { scheduled: true, scheduledAt };
+    }
+
+    cancelTimer(id: string): boolean {
+        const entry = this.timers.get(id);
+        if (!entry) return false;
+        clearTimeout(entry.timer);
+        entry.abort.abort();
+        this.timers.delete(id);
+        return true;
+    }
+
+    cancelAll(): void {
+        for (const [id] of this.timers) {
+            this.cancelTimer(id);
+        }
+    }
+
+    shouldPause(delayMs: number): boolean {
+        return delayMs >= this.pauseThresholdMs;
+    }
+
+    isExhausted(): boolean {
+        return this.continueCount >= this.maxContinueCount;
+    }
+
+    getContinueCount(): number {
+        return this.continueCount;
+    }
+
+    resetCount(): void {
+        this.continueCount = 0;
+    }
+}

package/dist/extensions/session-supervisor/types.ts

@@ -0,0 +1,215 @@
+import type { ChannelContract } from "@dyyz1993/pi-coding-agent";
+import { Type, type Static } from "@sinclair/typebox";
+
+// ── Guard Configuration ──
+
+export const BaseGuardConfigSchema = Type.Object({
+    /** Guard unique identifier */
+    name: Type.String(),
+    /** Enable/disable this specific guard */
+    enable: Type.Boolean({ default: true }),
+});
+
+export const TodoGuardConfigSchema = Type.Intersect([
+    BaseGuardConfigSchema,
+    Type.Object({
+        type: Type.Literal("todo"),
+    }),
+]);
+
+export const SpecsGuardConfigSchema = Type.Intersect([
+    BaseGuardConfigSchema,
+    Type.Object({
+        type: Type.Literal("specs"),
+        /** Path to specs file, relative to project root */
+        specsFile: Type.String({ default: "specs.md" }),
+        /** Max iterations for specs guard (0 = infinite) */
+        maxIterations: Type.Integer({ default: 100 }),
+    }),
+]);
+
+export const CiGuardConfigSchema = Type.Intersect([
+    BaseGuardConfigSchema,
+    Type.Object({
+        type: Type.Literal("ci"),
+        /** Command to check CI status */
+        checkCommand: Type.Optional(Type.String()),
+        /** Polling interval in ms */
+        pollIntervalMs: Type.Integer({ default: 30_000 }),
+    }),
+]);
+
+export const KeywordGuardConfigSchema = Type.Intersect([
+    BaseGuardConfigSchema,
+    Type.Object({
+        type: Type.Literal("keyword"),
+        /** Keywords that indicate incomplete work */
+        keywords: Type.Array(Type.String()),
+    }),
+]);
+
+export const CustomGuardConfigSchema = Type.Intersect([
+    BaseGuardConfigSchema,
+    Type.Object({
+        type: Type.Literal("custom"),
+        /** System prompt for the guard model */
+        checkPrompt: Type.String(),
+        /** Prompt template for generating continue message */
+        continuePromptTemplate: Type.Optional(Type.String()),
+    }),
+]);
+
+export const GuardConfigSchema = Type.Union([
+    TodoGuardConfigSchema,
+    SpecsGuardConfigSchema,
+    CiGuardConfigSchema,
+    KeywordGuardConfigSchema,
+    CustomGuardConfigSchema,
+]);
+
+export type GuardConfig = Static<typeof GuardConfigSchema>;
+
+// ── Main Supervisor Config ──
+
+export const SupervisorConfigSchema = Type.Object({
+    /** Master switch — default OFF */
+    enable: Type.Boolean({ default: false }),
+    /** Check when agent ends a turn */
+    checkOnAgentEnd: Type.Boolean({ default: true }),
+    /** Small model for guard checks */
+    smallModel: Type.String({ default: "fast" }),
+    /** Max auto-continue count (0 = infinite) */
+    maxContinueCount: Type.Integer({ default: 5 }),
+    /** Default delay before auto-continue */
+    defaultDelayMs: Type.Integer({ default: 30_000 }),
+    /** Delay threshold for pausing (vs immediate continue) */
+    pauseThresholdMs: Type.Integer({ default: 300_000 }),
+    /** Guard plugins */
+    guards: Type.Array(GuardConfigSchema, { default: [] }),
+});
+
+export type SupervisorConfig = Static<typeof SupervisorConfigSchema>;
+
+// ── Guard Runtime Types ──
+
+export interface GuardCheckResult {
+    /** This guard's name */
+    guardName: string;
+    /** Whether the guard thinks work is done */
+    completed: boolean;
+    /** Confidence 0-1 */
+    confidence: number;
+    /** Remaining items if not completed */
+    remainingItems: string[];
+    /** Optional detail message */
+    detail?: string;
+}
+
+export interface GuardContinueMessage {
+    /** The message to inject as supervisor continue */
+    content: string;
+    /** Whether this guard wants to block agent completion */
+    blockCompletion: boolean;
+}
+
+// ── Channel Contract ──
+
+export interface SupervisorChannelContract extends ChannelContract {
+    methods: {
+        "supervisor.getStatus": {
+            params: Record<string, never>;
+            return: SupervisorStatus;
+        };
+        "supervisor.requestPause": {
+            params: { delayMs?: number; reason?: string };
+            return: { scheduled: boolean; scheduledAt?: number };
+        };
+        "supervisor.cancelPause": {
+            params: Record<string, never>;
+            return: { cancelled: boolean };
+        };
+        "supervisor.forceContinue": {
+            params: { reason?: string };
+            return: { triggered: boolean };
+        };
+        "supervisor.disable": {
+            params: Record<string, never>;
+            return: { disabled: boolean };
+        };
+        "supervisor.enable": {
+            params: Record<string, never>;
+            return: { enabled: boolean };
+        };
+        "supervisor.getTaskReport": {
+            params: Record<string, never>;
+            return: { tasks: TaskReport[] };
+        };
+        "supervisor.checkToolStatus": {
+            params: { toolName: string; channelName?: string; method?: string };
+            return: { reachable: boolean; status?: string; error?: string };
+        };
+    };
+    events: {
+        "supervisor.statusChanged": SupervisorStatus;
+        "supervisor.pauseRequested": { delayMs: number; reason?: string };
+        "supervisor.pauseCancelled": { reason: string };
+        "supervisor.continueTriggered": { reason: string; delayMs: number };
+        "supervisor.taskReport": { tasks: TaskReport[] };
+    };
+}
+
+// ── Status & Reporting ──
+
+export interface SupervisorStatus {
+    enabled: boolean;
+    state: "idle" | "checking" | "paused" | "continuing" | "disabled";
+    continueCount: number;
+    maxContinueCount: number;
+    activeGuards: string[];
+    lastCheckResult?: CheckResult;
+    pendingPause?: { scheduledAt: number; delayMs: number; reason?: string };
+}
+
+export interface CheckResult {
+    completed: boolean;
+    confidence: number;
+    incompleteTasks: IncompleteTask[];
+    modelResponse?: string;
+    guardResults?: GuardCheckResult[];
+}
+
+export interface IncompleteTask {
+    ruleName: string;
+    description: string;
+    severity: "high" | "medium" | "low";
+}
+
+export interface TaskReport {
+    guardName: string;
+    guardType: string;
+    status: "completed" | "incomplete" | "unknown" | "error";
+    details?: string;
+    error?: string;
+    remainingItems?: string[];
+}
+
+// ── Structured LLM output ──
+
+export const CompletionCheckSchema = Type.Object({
+    completed: Type.Boolean({ description: "会话是否已经真正完成" }),
+    confidence: Type.Number({ description: "置信度 0-1", minimum: 0, maximum: 1 }),
+    incompleteTasks: Type.Array(
+        Type.Object({
+            ruleName: Type.String(),
+            description: Type.String(),
+            severity: Type.Union([
+                Type.Literal("high"),
+                Type.Literal("medium"),
+                Type.Literal("low"),
+            ]),
+        }),
+    ),
+    reasoning: Type.String({ description: "判断理由" }),
+});
+
+export type CompletionCheckResult = Static<typeof CompletionCheckSchema>;

package/dist/extensions/subagent/README.md

@@ -0,0 +1,172 @@
+# Subagent Example
+
+Delegate tasks to specialized subagents with isolated context windows.
+
+## Features
+
+- **Isolated context**: Each subagent runs in a separate `pi` process
+- **Streaming output**: See tool calls and progress as they happen
+- **Parallel streaming**: All parallel tasks stream updates simultaneously
+- **Markdown rendering**: Final output rendered with proper formatting (expanded view)
+- **Usage tracking**: Shows turns, tokens, cost, and context usage per agent
+- **Abort support**: Ctrl+C propagates to kill subagent processes
+
+## Structure
+
+```
+subagent/
+├── README.md            # This file
+├── index.ts             # The extension (entry point)
+├── agents.ts            # Agent discovery logic
+├── agents/              # Sample agent definitions
+│   ├── scout.md         # Fast recon, returns compressed context
+│   ├── planner.md       # Creates implementation plans
+│   ├── reviewer.md      # Code review
+│   └── worker.md        # General-purpose (full capabilities)
+└── prompts/             # Workflow presets (prompt templates)
+    ├── implement.md     # scout -> planner -> worker
+    ├── scout-and-plan.md    # scout -> planner (no implementation)
+    └── implement-and-review.md  # worker -> reviewer -> worker
+```
+
+## Installation
+
+From the repository root, symlink the files:
+
+```bash
+# Symlink the extension (must be in a subdirectory with index.ts)
+mkdir -p ~/.pi/agent/extensions/subagent
+ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/index.ts" ~/.pi/agent/extensions/subagent/index.ts
+ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/agents.ts" ~/.pi/agent/extensions/subagent/agents.ts
+
+# Symlink agents
+mkdir -p ~/.pi/agent/agents
+for f in packages/coding-agent/examples/extensions/subagent/agents/*.md; do
+  ln -sf "$(pwd)/$f" ~/.pi/agent/agents/$(basename "$f")
+done
+
+# Symlink workflow prompts
+mkdir -p ~/.pi/agent/prompts
+for f in packages/coding-agent/examples/extensions/subagent/prompts/*.md; do
+  ln -sf "$(pwd)/$f" ~/.pi/agent/prompts/$(basename "$f")
+done
+```
+
+## Security Model
+
+This tool executes a separate `pi` subprocess with a delegated system prompt and tool/model configuration.
+
+**Project-local agents** (`.pi/agents/*.md`) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc.
+
+**Default behavior:** Only loads **user-level agents** from `~/.pi/agent/agents`.
+
+To enable project-local agents, pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
+
+When running interactively, the tool prompts for confirmation before running project-local agents. Set `confirmProjectAgents: false` to disable.
+
+## Usage
+
+### Single agent
+```
+Use scout to find all authentication code
+```
+
+### Parallel execution
+```
+Run 2 scouts in parallel: one to find models, one to find providers
+```
+
+### Chained workflow
+```
+Use a chain: first have scout find the read tool, then have planner suggest improvements
+```
+
+### Workflow prompts
+```
+/implement add Redis caching to the session store
+/scout-and-plan refactor auth to support OAuth
+/implement-and-review add input validation to API endpoints
+```
+
+## Tool Modes
+
+| Mode | Parameter | Description |
+|------|-----------|-------------|
+| Single | `{ agent, task }` | One agent, one task |
+| Parallel | `{ tasks: [...] }` | Multiple agents run concurrently (max 8, 4 concurrent) |
+| Chain | `{ chain: [...] }` | Sequential with `{previous}` placeholder |
+
+## Output Display
+
+**Collapsed view** (default):
+- Status icon (✓/✗/⏳) and agent name
+- Last 5-10 items (tool calls and text)
+- Usage stats: `3 turns ↑input ↓output RcacheRead WcacheWrite $cost ctx:contextTokens model`
+
+**Expanded view** (Ctrl+O):
+- Full task text
+- All tool calls with formatted arguments
+- Final output rendered as Markdown
+- Per-task usage (for chain/parallel)
+
+**Parallel mode streaming**:
+- Shows all tasks with live status (⏳ running, ✓ done, ✗ failed)
+- Updates as each task makes progress
+- Shows "2/3 done, 1 running" status
+
+**Tool call formatting** (mimics built-in tools):
+- `$ command` for bash
+- `read ~/path:1-10` for read
+- `grep /pattern/ in ~/path` for grep
+- etc.
+
+## Agent Definitions
+
+Agents are markdown files with YAML frontmatter:
+
+```markdown
+---
+name: my-agent
+description: What this agent does
+tools: read, grep, find, ls
+model: claude-haiku-4-5
+---
+
+System prompt for the agent goes here.
+```
+
+**Locations:**
+- `~/.pi/agent/agents/*.md` - User-level (always loaded)
+- `.pi/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`)
+
+Project agents override user agents with the same name when `agentScope: "both"`.
+
+## Sample Agents
+
+| Agent | Purpose | Model | Tools |
+|-------|---------|-------|-------|
+| `scout` | Fast codebase recon | Haiku | read, grep, find, ls, bash |
+| `planner` | Implementation plans | Sonnet | read, grep, find, ls |
+| `reviewer` | Code review | Sonnet | read, grep, find, ls, bash |
+| `worker` | General-purpose | Sonnet | (all default) |
+
+## Workflow Prompts
+
+| Prompt | Flow |
+|--------|------|
+| `/implement <query>` | scout → planner → worker |
+| `/scout-and-plan <query>` | scout → planner |
+| `/implement-and-review <query>` | worker → reviewer → worker |
+
+## Error Handling
+
+- **Exit code != 0**: Tool returns error with stderr/output
+- **stopReason "error"**: LLM error propagated with error message
+- **stopReason "aborted"**: User abort (Ctrl+C) kills subprocess, throws error
+- **Chain mode**: Stops at first failing step, reports which step failed
+
+## Limitations
+
+- Output truncated to last 10 items in collapsed view (expand to see all)
+- Agents discovered fresh on each invocation (allows editing mid-session)
+- Parallel mode limited to 8 tasks, 4 concurrent

package/dist/extensions/subagent/agents/explorer.md

@@ -0,0 +1,25 @@
+---
+name: explorer
+description: Read-only codebase exploration for understanding architecture, finding code, and answering questions.
+model: claude-haiku-4-5
+effort: low
+maxTurns: 20
+permissionMode: plan
+tools: read,grep,find,ls
+---
+
+You are a codebase explorer. Your job is to investigate code and answer questions about it. You MUST NOT modify any files.
+
+## Strategy
+
+1. Use grep/find to locate relevant code
+2. Read specific files and sections
+3. Trace call chains and dependencies
+4. Build a mental model of the architecture
+
+## Output Guidelines
+
+- Be specific: reference file paths and line numbers
+- Be thorough: follow imports and trace dependencies
+- Be structured: use headers and lists for readability
+- Be accurate: quote actual code, don't paraphrase

package/dist/extensions/subagent/agents/guide.md

@@ -0,0 +1,27 @@
+---
+name: guide
+description: Answers questions about pi coding agent features, configuration, and usage. Read-only, fast responses.
+model: claude-haiku-4-5
+effort: low
+maxTurns: 15
+permissionMode: dontAsk
+tools: read,grep,find,ls
+---
+
+You are a pi coding agent guide. Answer questions about the pi coding agent: features, configuration, extensions, keybindings, and usage.
+
+## Guidelines
+
+- Be concise and direct
+- Reference specific files and line numbers when pointing to configuration
+- Explain CLI flags, environment variables, and settings
+- For extension-related questions, explain the extension API
+- For provider/model questions, reference the models.json configuration
+
+## Key Resources
+
+- CLI args: `src/cli/args.ts`
+- Settings: `src/core/settings-manager.ts`
+- Extension API: `src/core/extensions/types.ts`
+- Configuration: `src/config.ts`
+- README: `README.md`

package/dist/extensions/subagent/agents/planner.md

@@ -0,0 +1,37 @@
+---
+name: planner
+description: Creates implementation plans from context and requirements
+tools: read, grep, find, ls
+model: claude-sonnet-4-5
+---
+
+You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.
+
+You must NOT make any changes. Only read, analyze, and plan.
+
+Input format you'll receive:
+- Context/findings from a scout agent
+- Original query or requirements
+
+Output format:
+
+## Goal
+One sentence summary of what needs to be done.
+
+## Plan
+Numbered steps, each small and actionable:
+1. Step one - specific file/function to modify
+2. Step two - what to add/change
+3. ...
+
+## Files to Modify
+- `path/to/file.ts` - what changes
+- `path/to/other.ts` - what changes
+
+## New Files (if any)
+- `path/to/new.ts` - purpose
+
+## Risks
+Anything to watch out for.
+
+Keep the plan concrete. The worker agent will execute it verbatim.