@oh-my-pi/pi-coding-agent 15.13.1 → 15.13.2

package/src/tools/inspect-image.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import { instrumentedCompleteSimple, resolveTelemetry } from "@oh-my-pi/pi-agent-core";
-import { type Api, completeSimple, type Model } from "@oh-my-pi/pi-ai";
+import { type Api, completeSimple, type Model, type ToolExample } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import { z } from "zod/v4";
 import { extractTextContent } from "../commit/utils";
@@ -43,6 +43,32 @@ export class InspectImageTool implements AgentTool<typeof inspectImageSchema, In
 	readonly parameters = inspectImageSchema;
 	readonly strict = false;
 
+	readonly examples: readonly ToolExample<z.input<typeof inspectImageSchema>>[] = [
+		{
+			caption: "OCR with strict formatting",
+			call: {
+				path: "screenshots/error.png",
+				question: "Extract all visible text verbatim. Return as bullet list in reading order.",
+			},
+		},
+		{
+			caption: "Screenshot debugging",
+			call: {
+				path: "screenshots/settings.png",
+				question:
+					"Identify the likely cause of the disabled Save button. Return: (1) observations, (2) likely cause, (3) confidence.",
+			},
+		},
+		{
+			caption: "Scene/object question",
+			call: {
+				path: "photos/shelf.jpg",
+				question:
+					"List all clearly visible product labels and their shelf positions (top/middle/bottom). If unreadable, say unreadable.",
+			},
+		},
+	];
+
 	constructor(
 		private readonly session: ToolSession,
 		private readonly completeImageRequest: typeof completeSimple = completeSimple,

package/src/tools/irc.ts

@@ -10,6 +10,7 @@
  */
 
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
 import { type Component, Text } from "@oh-my-pi/pi-tui";
 import { formatAge, formatDuration, prompt } from "@oh-my-pi/pi-utils";
 import { z } from "zod/v4";
@@ -96,6 +97,46 @@ export class IrcTool implements AgentTool<typeof ircSchema, IrcDetails> {
 	readonly description: string;
 	readonly parameters = ircSchema;
 	readonly strict = true;
+
+	readonly examples: readonly ToolExample<z.input<typeof ircSchema>>[] = [
+		{
+			caption: "List peers",
+			call: { op: "list" },
+		},
+		{
+			caption: "Fire-and-forget DM — same send wakes idle/parked peers",
+			call: {
+				op: "send",
+				to: "AuthLoader",
+				message: "Still touching src/server/auth.ts? I need to add a 401 path.",
+			},
+		},
+		{
+			caption: "Round-trip when you cannot proceed without the answer",
+			call: {
+				op: "send",
+				to: "Main",
+				message: "JWT or session cookies for the auth flow?",
+				await: true,
+			},
+		},
+		{
+			caption: "Block until a specific peer answers",
+			call: { op: "wait", from: "AuthLoader", timeoutMs: 60000 },
+		},
+		{
+			caption: "Drain pending messages",
+			call: { op: "inbox" },
+		},
+		{
+			caption: "Broadcast to live peers (no replies expected)",
+			call: {
+				op: "send",
+				to: "all",
+				message: "About to refactor src/server/middleware/*. Anyone already in there?",
+			},
+		},
+	];
 	readonly loadMode = "discoverable";
 	constructor(private readonly session: ToolSession) {
 		this.description = prompt.render(ircDescription);

package/src/tools/ssh.ts

@@ -1,4 +1,5 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { prompt } from "@oh-my-pi/pi-utils";
 import { z } from "zod/v4";
@@ -135,6 +136,21 @@ export class SshTool implements AgentTool<typeof sshSchema, SSHToolDetails> {
 	readonly concurrency = "exclusive";
 	readonly strict = true;
 
+	readonly examples: readonly ToolExample<z.input<typeof sshSchema>>[] = [
+		{
+			caption: "List files: Linux (on server1 (10.0.0.1) | linux/bash)",
+			call: { host: "server1", command: "ls -la /home/user" },
+		},
+		{
+			caption: "Show running processes: Windows cmd (on winbox (192.168.1.5) | windows/cmd)",
+			call: { host: "winbox", command: "tasklist /v" },
+		},
+		{
+			caption: "Get system info: macOS (on macbook (10.0.0.20) | macos/zsh)",
+			call: { host: "macbook", command: "uname -a && sw_vers" },
+		},
+	];
+
 	readonly #allowedHosts: Set<string>;
 
 	constructor(

package/src/tools/todo.ts

@@ -1,4 +1,5 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { prompt } from "@oh-my-pi/pi-utils";
@@ -270,8 +271,20 @@ function getTaskTargets(phases: TodoPhase[], entry: TodoOpEntryValue, errors: st
 	return phases.flatMap(phase => phase.tasks);
 }
 
+/** Phase name for `init` given a flat `items` list with no explicit `phase`. */
+const DEFAULT_INIT_PHASE = "Tasks";
+
 function initPhases(entry: TodoOpEntryValue, errors: string[]): TodoPhase[] {
-	if (!entry.list) {
+	// Models routinely flatten the single-phase init into `{op:"init", items:[...]}`
+	// (optionally with a bare `phase`) instead of the canonical
+	// `list: [{phase, items}]`. Accept that shape by synthesizing a one-phase list
+	// so a common, recoverable mistake isn't a hard error.
+	const list =
+		entry.list ??
+		(entry.items && entry.items.length > 0
+			? [{ phase: entry.phase ?? DEFAULT_INIT_PHASE, items: entry.items }]
+			: undefined);
+	if (!list) {
 		errors.push("Missing list for init operation");
 		return [];
 	}
@@ -279,7 +292,7 @@ function initPhases(entry: TodoOpEntryValue, errors: string[]): TodoPhase[] {
 	// (every targeting op resolves the first match), so reject them up front.
 	const seenPhases = new Set<string>();
 	const seenTasks = new Set<string>();
-	for (const listEntry of entry.list) {
+	for (const listEntry of list) {
 		if (seenPhases.has(listEntry.phase)) {
 			errors.push(`Duplicate phase "${listEntry.phase}" in init list`);
 		}
@@ -291,7 +304,7 @@ function initPhases(entry: TodoOpEntryValue, errors: string[]): TodoPhase[] {
 			seenTasks.add(content);
 		}
 	}
-	return entry.list.map(listEntry => ({
+	return list.map(listEntry => ({
 		name: listEntry.phase,
 		tasks: listEntry.items.map<TodoItem>(content => ({ content, status: "pending" })),
 	}));
@@ -551,6 +564,71 @@ export class TodoTool implements AgentTool<typeof todoSchema, TodoToolDetails> {
 	readonly parameters = todoSchema;
 	readonly concurrency = "exclusive";
 	readonly strict = true;
+
+	readonly examples: readonly ToolExample<z.input<typeof todoSchema>>[] = [
+		{
+			caption: "Initial setup (multi-phase)",
+			call: {
+				ops: [
+					{
+						op: "init",
+						list: [
+							{ phase: "Foundation", items: ["Scaffold crate", "Wire workspace"] },
+							{ phase: "Auth", items: ["Port credential store", "Wire OAuth providers"] },
+							{ phase: "Verification", items: ["Run cargo test"] },
+						],
+					},
+				],
+			},
+		},
+		{
+			caption: "View current state (read-only)",
+			call: {
+				ops: [{ op: "view" }],
+			},
+		},
+		{
+			caption: "Initial setup (single phase)",
+			call: {
+				ops: [
+					{
+						op: "init",
+						list: [{ phase: "Implementation", items: ["Apply fix", "Run tests"] }],
+					},
+				],
+			},
+		},
+		{
+			caption: "Complete one task",
+			call: {
+				ops: [{ op: "done", task: "Wire workspace" }],
+			},
+		},
+		{
+			caption: "Complete a whole phase",
+			call: {
+				ops: [{ op: "done", phase: "Auth" }],
+			},
+		},
+		{
+			caption: "Remove all tasks",
+			call: {
+				ops: [{ op: "rm" }],
+			},
+		},
+		{
+			caption: "Drop one task",
+			call: {
+				ops: [{ op: "drop", task: "Run cargo test" }],
+			},
+		},
+		{
+			caption: "Append tasks to a phase",
+			call: {
+				ops: [{ op: "append", phase: "Auth", items: ["Handle retries", "Run tests"] }],
+			},
+		},
+	];
 	readonly loadMode = "discoverable";
 	constructor(private readonly session: ToolSession) {
 		this.description = prompt.render(todoDescription);
@@ -839,6 +917,7 @@ export const todoToolRenderer = {
 						expanded,
 						maxCollapsed: PREVIEW_LIMITS.COLLAPSED_ITEMS,
 						itemType: "todo",
+						truncateFrom: "start",
 						renderItem: todo => formatTodoLine(todo, uiTheme, "", completionKeys, spinnerFrame),
 					},
 					uiTheme,

package/src/tui/tree-list.ts

@@ -17,23 +17,45 @@ export interface TreeListOptions<T> {
 	 */
 	maxCollapsedLines?: number;
 	itemType?: string;
+	truncateFrom?: "start" | "end";
 	/** Called once per item with `isLast: false` during budget calculation;
 	 *  line count MUST NOT vary based on `isLast`. */
 	renderItem: (item: T, context: TreeContext) => string | string[];
 }
 
 export function renderTreeList<T>(options: TreeListOptions<T>, theme: Theme): string[] {
-	const { items, expanded = false, maxCollapsed = 8, maxCollapsedLines, itemType = "item", renderItem } = options;
+	const {
+		items,
+		expanded = false,
+		maxCollapsed = 8,
+		maxCollapsedLines,
+		itemType = "item",
+		truncateFrom = "end",
+		renderItem,
+	} = options;
 	const maxItems = expanded ? items.length : Math.min(items.length, maxCollapsed);
 	const linesBudget = !expanded && maxCollapsedLines !== undefined ? maxCollapsedLines : Infinity;
 
+	const candidateIndices: number[] = [];
+	if (truncateFrom === "start") {
+		const startCandidateIdx = Math.max(0, items.length - maxItems);
+		for (let i = startCandidateIdx; i < items.length; i++) {
+			candidateIndices.push(i);
+		}
+	} else {
+		for (let i = 0; i < maxItems; i++) {
+			candidateIndices.push(i);
+		}
+	}
+
 	// Pre-render each candidate item once.
 	// isLast cannot be known at this point (fittingCount is not yet determined);
 	// renderItem implementations MUST NOT vary line count based on isLast.
 	const preRendered: string[][] = [];
-	for (let i = 0; i < maxItems; i++) {
-		const rendered = renderItem(items[i], {
-			index: i,
+	for (let i = 0; i < candidateIndices.length; i++) {
+		const itemIdx = candidateIndices[i];
+		const rendered = renderItem(items[itemIdx], {
+			index: itemIdx,
 			isLast: false,
 			depth: 0,
 			theme,
@@ -43,28 +65,55 @@ export function renderTreeList<T>(options: TreeListOptions<T>, theme: Theme): st
 		preRendered.push(Array.isArray(rendered) ? rendered : rendered ? [rendered] : []);
 	}
 
-	// Determine how many items fit within the line budget.
-	let fittingCount = maxItems;
+	let displayedSlice: { start: number; end: number };
+	let remaining: number;
 	let fittedLineCount = 0;
-	if (linesBudget !== Infinity) {
-		fittingCount = 0;
-		for (let i = 0; i < maxItems; i++) {
-			const count = preRendered[i]!.length;
-			const remainingAfter = items.length - (i + 1);
-			const reservedSummaryLines = remainingAfter > 0 ? 1 : 0;
-			if (fittedLineCount + count + reservedSummaryLines > linesBudget) break;
-			fittedLineCount += count;
-			fittingCount = i + 1;
+
+	if (truncateFrom === "start") {
+		let fittingCount = candidateIndices.length;
+		if (linesBudget !== Infinity) {
+			fittingCount = 0;
+			for (let i = candidateIndices.length - 1; i >= 0; i--) {
+				const count = preRendered[i].length;
+				const remainingBefore = candidateIndices[i];
+				const reservedSummaryLines = remainingBefore > 0 ? 1 : 0;
+				if (fittedLineCount + count + reservedSummaryLines > linesBudget) break;
+				fittedLineCount += count;
+				fittingCount++;
+			}
+		}
+		const start = candidateIndices.length - fittingCount;
+		displayedSlice = { start, end: candidateIndices.length };
+		remaining = candidateIndices.length > 0 ? candidateIndices[start] : 0;
+	} else {
+		let fittingCount = candidateIndices.length;
+		if (linesBudget !== Infinity) {
+			fittingCount = 0;
+			for (let i = 0; i < candidateIndices.length; i++) {
+				const count = preRendered[i].length;
+				const remainingAfter = items.length - (i + 1);
+				const reservedSummaryLines = remainingAfter > 0 ? 1 : 0;
+				if (fittedLineCount + count + reservedSummaryLines > linesBudget) break;
+				fittedLineCount += count;
+				fittingCount = i + 1;
+			}
 		}
+		displayedSlice = { start: 0, end: fittingCount };
+		remaining = items.length - fittingCount;
 	}
 
-	const remaining = items.length - fittingCount;
 	const hasSummary = !expanded && remaining > 0 && (linesBudget === Infinity || fittedLineCount < linesBudget);
 
 	// Emit pre-rendered content with correct isLast-based branch prefixes.
 	const lines: string[] = [];
-	for (let i = 0; i < fittingCount; i++) {
-		const isLast = !hasSummary && i === fittingCount - 1;
+
+	if (truncateFrom === "start" && hasSummary) {
+		lines.push(`${theme.fg("dim", theme.tree.branch)} ${theme.fg("muted", formatMoreItems(remaining, itemType))}`);
+	}
+
+	for (let i = displayedSlice.start; i < displayedSlice.end; i++) {
+		const isLast =
+			truncateFrom === "start" ? i === displayedSlice.end - 1 : !hasSummary && i === displayedSlice.end - 1;
 		const branch = getTreeBranch(isLast, theme);
 		const prefix = `${theme.fg("dim", branch)} `;
 		const continuePrefix = `${theme.fg("dim", getTreeContinuePrefix(isLast, theme))}`;
@@ -76,7 +125,7 @@ export function renderTreeList<T>(options: TreeListOptions<T>, theme: Theme): st
 		}
 	}
 
-	if (hasSummary) {
+	if (truncateFrom === "end" && hasSummary) {
 		lines.push(`${theme.fg("dim", theme.tree.last)} ${theme.fg("muted", formatMoreItems(remaining, itemType))}`);
 	}