opencode-ai-cli 1.17.0

package/src/engine/messages.ts

@@ -0,0 +1,110 @@
+import { ProviderName } from "../core/auth-storage";
+import { AgentMessage, AssistantMessage, ToolResultMessage } from "./type";
+
+export function convertToLlm(
+  messages: AgentMessage[],
+  provider: ProviderName,
+) {
+  if (provider === "openai") {
+    return convertToOpenAi(messages);
+  } else if (provider === "gemini") {
+    return messages;
+  }
+
+  throw new Error(`Provider ${provider} not supported yet`);
+}
+
+export function convertToOpenAi(messages: AgentMessage[]): any[] {
+  return messages.map((msg) => {
+    switch (msg.role) {
+      case "system":
+      case "user":
+        return { role: msg.role, content: msg.content };
+
+      case "assistant": {
+        const textContent = msg.content
+          .filter((part) => part.type === "text")
+          .map((part: any) => part.text)
+          .join("\n");
+
+        const toolCalls = msg.content
+          .filter((part) => part.type === "toolCall")
+          .map((part: any) => part.toolCall);
+
+        return {
+          role: "assistant",
+          content: textContent || null,
+          tool_calls:
+            toolCalls.length > 0
+              ? toolCalls.map((tc: any) => ({
+                  id: tc.id,
+                  type: "function",
+                  function: {
+                    name: tc.name,
+                    arguments: JSON.stringify(tc.arguments),
+                  },
+                }))
+              : undefined,
+        };
+      }
+
+      case "tool":
+        return {
+          role: "tool",
+          tool_call_id: msg.toolCallId,
+          content: msg.content,
+        };
+
+      default:
+        const _exhaustiveCheck: never = msg;
+        return _exhaustiveCheck;
+    }
+  });
+}
+
+export function convertToGeminiAi(messages: AgentMessage[]): any[] {
+  return messages.map((msg) => {
+    switch (msg.role) {
+      case "system":
+        return msg;
+
+      case "user":
+        return { role: "user", parts: [{ text: msg.content }] };
+
+      case "assistant": {
+        const parts = msg.content.map((part) => {
+          if (part.type === "text") {
+            return { text: part.text };
+          } else if (part.type === "toolCall") {
+            return {
+              functionCall: {
+                name: part.toolCall.name,
+                args: part.toolCall.arguments,
+              },
+            };
+          } else if (part.type === "thinking") {
+              return { text: `Thinking: ${part.thinking}` };
+          }
+          return { text: "" };
+        });
+        return { role: "model", parts };
+      }
+
+      case "tool":
+        return {
+          role: "user", // Gemini uses 'user' role for function responses in some SDKs, or 'function'
+          parts: [
+            {
+              functionResponse: {
+                name: msg.name,
+                response: { content: msg.content },
+              },
+            },
+          ],
+        };
+
+      default:
+        return { role: "user", parts: [{ text: "" }] };
+    }
+  });
+}

package/src/engine/systemPrompt.ts

@@ -0,0 +1,58 @@
+export function buildSystemPrompt(): string {
+  const cwd = process.cwd();
+  const date = new Date().toISOString().split("T")[0];
+
+  return `
+You are a senior software engineering agent operating inside a user's terminal.
+
+Current Date: ${date}
+Current Working Directory: ${cwd}
+
+# CRITICAL RESEARCH MANDATE
+
+You are strictly forbidden from guessing, assuming, or hallucinating information about the user's project, files, or code.
+
+# THE SCOUT AND PLAN PIPELINE (MANDATORY)
+
+You are the Orchestrator. When the user asks a question about their project, repository, architecture, or asks you to implement a feature, fix a bug, or execute a change, you MUST follow this strict 2-step pipeline:
+
+1. THE SCOUT PHASE: 
+You MUST immediately call the 'subagent' tool using the PARALLEL mode by passing an array of 'tasks'.
+Spawn 2 or 3 'scout' agents concurrently to map different parts of the project at the exact same time. This drastically speeds up research.
+Example:
+tasks: [
+  { agent: "scout", task: "Read package.json, configs, and find the main entry points." },
+  { agent: "scout", task: "Analyze the core logic in the src directory." },
+  { agent: "scout", task: "Investigate any specific bugs or files mentioned in the user's prompt: <user prompt>" }
+]
+DO NOT use 'ls', 'read', 'grep', or 'find' yourself. You must delegate research to the scouts.
+DO NOT guess the project structure. DO NOT call 'propose_plan' yet.
+YOU MAY ONLY CALL THE SUBAGENT TOOL ONCE. Launch all your scouts in that single call.
+
+2. THE PLAN PHASE: 
+Only AFTER you receive the Markdown report from the scout subagent, you may call 'propose_plan'. Use the "Start Here" and "Architecture" sections of the scout report to formulate your step-by-step plan.
+The plan must separate read-only investigation from mutating work. Ask for approval before any edit, write, delete, or command that can change project state.
+
+3. THE IMPLEMENTATION PHASE:
+Once the user approves your plan, you are encouraged to use 'read_file', 'grep', 'edit_file', and 'bash' DIRECTLY to execute the steps. You do not need to call subagents for simple file reads or edits during this phase.
+
+Calling 'propose_plan' or trying to change files before invoking the scout is strictly forbidden.
+
+You operate under an "Evidence-First" policy.
+
+Use tools only when they are needed to answer the user's request. For casual
+conversation, greetings, thanks, or simple chat answer directly without using tools.
+
+Rules:
+- Never claim a file exists unless your scout has verified it.
+- Never claim code behaves a certain way unless your scout has inspected it.
+- Never invent dependencies, configurations, scripts, or APIs.
+- MANDATORY: When using mutating tools (\`write_file\`, \`edit_file\`, \`bash\`), you MUST explicitly describe your action.
+  - For \`edit_file\`, clearly state what is being removed and what is being added, and identify the affected lines.
+  - For \`write_file\`, state that you are creating/overwriting a file at a specific path.
+  - For \`bash\`, state exactly what command you are running and its purpose.
+
+If the answer cannot be determined from available evidence, respond:
+"I searched the repository using the scout but could not find enough evidence."
+`;
+}

package/src/engine/type.ts

@@ -0,0 +1,133 @@
+import { AgentTool, AgentToolResult } from "../types";
+
+export type MessagePart =
+  | { type: "text"; text: string }
+  | { type: "toolCall"; toolCall: AgentToolCall }
+  | { type: "thinking"; thinking: string };
+
+export interface AgentToolCall {
+  id: string;
+  name: string;
+  arguments: any;
+  metadata?: any;
+}
+
+export interface UserMessage {
+  role: "user";
+  content: string;
+}
+
+export interface SystemMessage {
+  role: "system";
+  content: string;
+}
+
+export interface AssistantMessage {
+  role: "assistant";
+  content: MessagePart[];
+  toolCalls?: AgentToolCall[];
+  stopReason?: "stop" | "tool_calls" | "error" | "aborted";
+  metadata?: any;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+export interface ToolResultMessage {
+  role: "tool";
+  toolCallId: string;
+  name: string;
+  content: string;
+  isError?: boolean;
+  terminate?: boolean;
+  metadata?: any;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+export type AgentMessage =
+  | SystemMessage
+  | UserMessage
+  | AssistantMessage
+  | ToolResultMessage;
+
+export interface AgentContext {
+  cwd: string;
+  messages: AgentMessage[];
+  activeToolNames: string[];
+  systemPrompt?: string;
+  tools?: AgentTool[];
+}
+
+export interface BeforeToolCallContext {
+  assistantMessage: AssistantMessage;
+  toolCall: AgentToolCall;
+  context: AgentContext;
+}
+
+export interface AfterToolCallContext {
+  assistantMessage: AssistantMessage;
+  toolCall: AgentToolCall;
+  result: AgentToolResult;
+  isError: boolean;
+  context: AgentContext;
+}
+
+export interface ShouldStopAfterTurnContext {
+  message: AssistantMessage;
+  toolResults: ToolResultMessage[];
+  context: AgentContext;
+  newMessages: AgentMessage[];
+}
+
+import { ProviderName } from "../core/auth-storage";
+
+export interface AgentLoopConfig {
+  provider: ProviderName;
+  apiKey: string;
+  model?: string;
+  maxTurns?: number;
+  toolExecution?: "sequential" | "parallel";
+  beforeToolCall?: (
+    ctx: BeforeToolCallContext,
+  ) => Promise<{ block?: boolean; reason?: string } | void>;
+  shouldStopAfterTurn?: (ctx: ShouldStopAfterTurnContext) => Promise<boolean>;
+}
+
+export type AgentEvent =
+  | { type: "agent_start" }
+  | { type: "agent_end"; message: AgentMessage[] }
+  | { type: "turn_start" }
+  | {
+      type: "turn_end";
+      message: AssistantMessage;
+      toolResults: ToolResultMessage[];
+    }
+  | { type: "message_start"; message: AgentMessage }
+  | { type: "message_update"; message: AssistantMessage }
+  | { type: "message_end"; message: AgentMessage }
+  | {
+      type: "tool_execution_start";
+      toolCallId: string;
+      toolName: string;
+      args: any;
+    }
+  | {
+      type: "tool_execution_end";
+      toolCallId: string;
+      toolName: string;
+      result: AgentToolResult;
+      isError: boolean;
+    };
+
+export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
+
+export type ExecutedToolCallBatch = {
+  messages: ToolResultMessage[];
+  terminate: boolean;
+};

package/src/providers/gemini.ts

@@ -0,0 +1,122 @@
+import { ChatRequest, ChatResponse } from "../core/model-registry";
+
+function toGeminiContents(history: any[]) {
+  return history
+    .filter((message) => message.role !== "system")
+    .map((message) => {
+      if (message.role === "assistant") {
+        if (message.metadata?.geminiParts) {
+          return {
+            role: "model",
+            parts: message.metadata.geminiParts,
+          };
+        }
+
+        const parts = message.content.map((part: any) => {
+          if (part.type === "text") {
+            return { text: part.text };
+          }
+          if (part.type === "toolCall") {
+            return {
+              functionCall: {
+                name: part.toolCall.name,
+                args: part.toolCall.arguments,
+                ...part.toolCall.metadata,
+              },
+            };
+          }
+          return { text: "" };
+        });
+        return {
+          role: "model",
+          parts: parts,
+        };
+      }
+
+      if (message.role === "tool") {
+        return {
+          role: "user",
+          parts: [
+            {
+              functionResponse: {
+                name: message.name,
+                response: { result: message.content },
+              },
+            },
+          ],
+        };
+      }
+
+      return {
+        role: "user",
+        parts: [{ text: message.content ?? "" }],
+      };
+    });
+}
+
+export async function executeGemini(req: ChatRequest): Promise<ChatResponse> {
+  const systemMessage = req.history.find(
+    (message) => message.role === "system",
+  );
+  const tools = req.tools.map((tool) => tool.schema.function);
+
+  const modelToUse = req.model || "gemini-3-flash-preview";
+
+  const response = await fetch(
+    `https://generativelanguage.googleapis.com/v1beta/models/${modelToUse}:generateContent`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-goog-api-key": req.apiKey,
+      },
+      body: JSON.stringify({
+        systemInstruction: systemMessage
+          ? { parts: [{ text: systemMessage.content }] }
+          : undefined,
+        contents: toGeminiContents(req.history),
+        tools: tools.length > 0 ? [{ functionDeclarations: tools }] : undefined,
+      }),
+      signal: req.signal,
+    },
+  );
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => null);
+    throw new Error(`Gemini API Error: ${response.statusText}\nDetails: ${JSON.stringify(errorData, null, 2)}`);
+  }
+
+  const data = await response.json();
+  const parts = data.candidates?.[0]?.content?.parts ?? [];
+  const text = parts
+    .filter((part: any) => typeof part.text === "string")
+    .map((part: any) => part.text)
+    .join("");
+  const functionCalls = parts.filter((part: any) => part.functionCall);
+
+  return {
+    text: text || null,
+    toolCalls:
+      functionCalls.length > 0
+        ? functionCalls.map((part: any, index: number) => {
+            const { name, args, ...rest } = part.functionCall;
+            return {
+              id: `gemini-tool-${index}`,
+              name: name,
+              arguments: args ?? {},
+              metadata: rest, 
+            };
+          })
+        : null,
+    rawMessage: {
+      role: "assistant",
+      content: text || null,
+      geminiParts: parts,
+    },
+    usage: data.usageMetadata ? {
+      promptTokens: data.usageMetadata.promptTokenCount,
+      completionTokens: data.usageMetadata.candidatesTokenCount,
+      totalTokens: data.usageMetadata.totalTokenCount,
+    } : undefined,
+  };
+}

package/src/providers/openai.ts

@@ -0,0 +1,60 @@
+import { ChatRequest, ChatResponse } from "../core/model-registry";
+
+export async function executeOpenAI(req: ChatRequest): Promise<ChatResponse> {
+  const openaiTools = req.tools.map((t) => t.schema);
+
+  const response = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${req.apiKey}`,
+    },
+    body: JSON.stringify({
+      model: req.model || "gpt-4o-mini",
+      messages: req.history,
+      tools: openaiTools.length > 0 ? openaiTools : undefined,
+      tool_choice: openaiTools.length > 0 ? "auto" : undefined,
+    }),
+    signal: req.signal,
+  });
+
+  if (!response.ok) {
+    const errorData = await response.json();
+    throw new Error(`OpenAI API Error: ${response.statusText}\nDetails: ${JSON.stringify(errorData, null, 2)}`);
+  }
+
+  const data = await response.json();
+  const assistantMessage = data.choices[0].message;
+
+  let toolCalls = null;
+
+  if (assistantMessage.tool_calls) {
+    toolCalls = assistantMessage.tool_calls.map((tc: any) => {
+      try {
+        return {
+          id: tc.id,
+          name: tc.function.name,
+          arguments: JSON.parse(tc.function.arguments),
+        };
+      } catch (e) {
+        console.error("Failed to parse tool arguments:", tc.function.arguments);
+        return {
+          id: tc.id,
+          name: tc.function.name,
+          arguments: {}, // Fallback to empty object
+        };
+      }
+    });
+  }
+
+  return {
+    text: assistantMessage.content || null,
+    toolCalls: toolCalls,
+    rawMessage: assistantMessage,
+    usage: data.usage ? {
+      promptTokens: data.usage.prompt_tokens,
+      completionTokens: data.usage.completion_tokens,
+      totalTokens: data.usage.total_tokens,
+    } : undefined,
+  };
+}

package/src/subagent/README.md

@@ -0,0 +1,177 @@
+# 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
+│   ├── 
+
+# 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
+- Returns each completed task's final output to the parent model, capped at 50 KB per task
+- Returns failure diagnostics from stderr/error messages when a child exits before producing output
+
+**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)
+- Parallel model-visible output is capped at 50 KB per task; full results remain in tool details
+- Agents discovered fresh on each invocation (allows editing mid-session)
+- Parallel mode limited to 8 tasks, 4 concurrent

package/src/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.