@oh-my-pi/pi-coding-agent 15.0.1 → 15.1.0

package/src/modes/theme/theme.ts

@@ -11,9 +11,8 @@ import {
 } from "@oh-my-pi/pi-natives";
 import type { EditorTheme, MarkdownTheme, SelectListTheme, SymbolTheme } from "@oh-my-pi/pi-tui";
 import { adjustHsv, getCustomThemesDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
-import { type Static, Type } from "@sinclair/typebox";
-import { TypeCompiler } from "@sinclair/typebox/compiler";
 import chalk from "chalk";
+import * as z from "zod/v4";
 // Embed theme JSON files at build time
 import darkThemeJson from "./dark.json" with { type: "json" };
 import { defaultThemes } from "./defaults";
@@ -95,6 +94,7 @@ export type SymbolKey =
 	| "icon.pause"
 	| "icon.loop"
 	| "icon.folder"
+	| "icon.scratchFolder"
 	| "icon.file"
 	| "icon.git"
 	| "icon.branch"
@@ -258,6 +258,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.pause": "⏸",
 	"icon.loop": "↻",
 	"icon.folder": "📁",
+	"icon.scratchFolder": "🗑",
 	"icon.file": "📄",
 	"icon.git": "⎇",
 	"icon.branch": "⑂",
@@ -476,6 +477,8 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.loop": "\uf021",
 	// pick:  | alt:  
 	"icon.folder": "\uf115",
+	// pick:  | alt:
+	"icon.scratchFolder": "\uf014",
 	// pick:  | alt:  
 	"icon.file": "\uf15b",
 	// pick:  | alt:  ⎇
@@ -678,6 +681,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.pause": "||",
 	"icon.loop": "loop",
 	"icon.folder": "[D]",
+	"icon.scratchFolder": "[T]",
 	"icon.file": "[F]",
 	"icon.git": "git:",
 	"icon.branch": "@",
@@ -802,118 +806,111 @@ const SPINNER_FRAMES: Record<SymbolPreset, Record<SpinnerType, string[]>> = {
 // Types & Schema
 // ============================================================================
 
-const ColorValueSchema = Type.Union([
-	Type.String(), // hex "#ff0000", var ref "primary", or empty ""
-	Type.Integer({ minimum: 0, maximum: 255 }), // 256-color index
+const colorValueSchema = z.union([
+	z.string(), // hex "#ff0000", var ref "primary", or empty ""
+	z.number().int().min(0).max(255), // 256-color index
 ]);
 
-type ColorValue = Static<typeof ColorValueSchema>;
-
-// Use Type.Union here (not StringEnum) because TypeCompiler doesn't support Type.Unsafe
-const SymbolPresetSchema = Type.Union([Type.Literal("unicode"), Type.Literal("nerd"), Type.Literal("ascii")]);
-
-const SymbolsSchema = Type.Optional(
-	Type.Object({
-		preset: Type.Optional(SymbolPresetSchema),
-		overrides: Type.Optional(Type.Record(Type.String(), Type.String())),
-	}),
+type ColorValue = z.infer<typeof colorValueSchema>;
+
+const THEME_COLOR_KEYS = [
+	"accent",
+	"border",
+	"borderAccent",
+	"borderMuted",
+	"success",
+	"error",
+	"warning",
+	"muted",
+	"dim",
+	"text",
+	"thinkingText",
+	"selectedBg",
+	"userMessageBg",
+	"userMessageText",
+	"customMessageBg",
+	"customMessageText",
+	"customMessageLabel",
+	"toolPendingBg",
+	"toolSuccessBg",
+	"toolErrorBg",
+	"toolTitle",
+	"toolOutput",
+	"mdHeading",
+	"mdLink",
+	"mdLinkUrl",
+	"mdCode",
+	"mdCodeBlock",
+	"mdCodeBlockBorder",
+	"mdQuote",
+	"mdQuoteBorder",
+	"mdHr",
+	"mdListBullet",
+	"toolDiffAdded",
+	"toolDiffRemoved",
+	"toolDiffContext",
+	"syntaxComment",
+	"syntaxKeyword",
+	"syntaxFunction",
+	"syntaxVariable",
+	"syntaxString",
+	"syntaxNumber",
+	"syntaxType",
+	"syntaxOperator",
+	"syntaxPunctuation",
+	"thinkingOff",
+	"thinkingMinimal",
+	"thinkingLow",
+	"thinkingMedium",
+	"thinkingHigh",
+	"thinkingXhigh",
+	"bashMode",
+	"pythonMode",
+	"statusLineBg",
+	"statusLineSep",
+	"statusLineModel",
+	"statusLinePath",
+	"statusLineGitClean",
+	"statusLineGitDirty",
+	"statusLineContext",
+	"statusLineSpend",
+	"statusLineStaged",
+	"statusLineDirty",
+	"statusLineUntracked",
+	"statusLineOutput",
+	"statusLineCost",
+	"statusLineSubagents",
+] as const;
+
+const themeColorsSchema = z.object(
+	Object.fromEntries(THEME_COLOR_KEYS.map(key => [key, colorValueSchema])) as unknown as {
+		[K in (typeof THEME_COLOR_KEYS)[number]]: typeof colorValueSchema;
+	},
 );
 
-const ThemeJsonSchema = Type.Object({
-	$schema: Type.Optional(Type.String()),
-	name: Type.String(),
-	vars: Type.Optional(Type.Record(Type.String(), ColorValueSchema)),
-	colors: Type.Object({
-		// Core UI (10 colors)
-		accent: ColorValueSchema,
-		border: ColorValueSchema,
-		borderAccent: ColorValueSchema,
-		borderMuted: ColorValueSchema,
-		success: ColorValueSchema,
-		error: ColorValueSchema,
-		warning: ColorValueSchema,
-		muted: ColorValueSchema,
-		dim: ColorValueSchema,
-		text: ColorValueSchema,
-		thinkingText: ColorValueSchema,
-		// Backgrounds & Content Text (11 colors)
-		selectedBg: ColorValueSchema,
-		userMessageBg: ColorValueSchema,
-		userMessageText: ColorValueSchema,
-		customMessageBg: ColorValueSchema,
-		customMessageText: ColorValueSchema,
-		customMessageLabel: ColorValueSchema,
-		toolPendingBg: ColorValueSchema,
-		toolSuccessBg: ColorValueSchema,
-		toolErrorBg: ColorValueSchema,
-		toolTitle: ColorValueSchema,
-		toolOutput: ColorValueSchema,
-		// Markdown (10 colors)
-		mdHeading: ColorValueSchema,
-		mdLink: ColorValueSchema,
-		mdLinkUrl: ColorValueSchema,
-		mdCode: ColorValueSchema,
-		mdCodeBlock: ColorValueSchema,
-		mdCodeBlockBorder: ColorValueSchema,
-		mdQuote: ColorValueSchema,
-		mdQuoteBorder: ColorValueSchema,
-		mdHr: ColorValueSchema,
-		mdListBullet: ColorValueSchema,
-		// Tool Diffs (3 colors)
-		toolDiffAdded: ColorValueSchema,
-		toolDiffRemoved: ColorValueSchema,
-		toolDiffContext: ColorValueSchema,
-		// Syntax Highlighting (9 colors)
-		syntaxComment: ColorValueSchema,
-		syntaxKeyword: ColorValueSchema,
-		syntaxFunction: ColorValueSchema,
-		syntaxVariable: ColorValueSchema,
-		syntaxString: ColorValueSchema,
-		syntaxNumber: ColorValueSchema,
-		syntaxType: ColorValueSchema,
-		syntaxOperator: ColorValueSchema,
-		syntaxPunctuation: ColorValueSchema,
-		// Thinking Level Borders (6 colors)
-		thinkingOff: ColorValueSchema,
-		thinkingMinimal: ColorValueSchema,
-		thinkingLow: ColorValueSchema,
-		thinkingMedium: ColorValueSchema,
-		thinkingHigh: ColorValueSchema,
-		thinkingXhigh: ColorValueSchema,
-		// Bash Mode (1 color)
-		bashMode: ColorValueSchema,
-		// Python Mode (1 color)
-		pythonMode: ColorValueSchema,
-		// Footer Status Line
-		statusLineBg: ColorValueSchema,
-		statusLineSep: ColorValueSchema,
-		statusLineModel: ColorValueSchema,
-		statusLinePath: ColorValueSchema,
-		statusLineGitClean: ColorValueSchema,
-		statusLineGitDirty: ColorValueSchema,
-		statusLineContext: ColorValueSchema,
-		statusLineSpend: ColorValueSchema,
-		statusLineStaged: ColorValueSchema,
-		statusLineDirty: ColorValueSchema,
-		statusLineUntracked: ColorValueSchema,
-		statusLineOutput: ColorValueSchema,
-		statusLineCost: ColorValueSchema,
-		statusLineSubagents: ColorValueSchema,
-	}),
-	export: Type.Optional(
-		Type.Object({
-			pageBg: Type.Optional(ColorValueSchema),
-			cardBg: Type.Optional(ColorValueSchema),
-			infoBg: Type.Optional(ColorValueSchema),
-		}),
-	),
-	symbols: SymbolsSchema,
+const symbolPresetSchema = z.enum(["unicode", "nerd", "ascii"]);
+
+const themeJsonSchema = z.object({
+	$schema: z.string().optional(),
+	name: z.string(),
+	vars: z.record(z.string(), colorValueSchema).optional(),
+	colors: themeColorsSchema,
+	export: z
+		.object({
+			pageBg: colorValueSchema.optional(),
+			cardBg: colorValueSchema.optional(),
+			infoBg: colorValueSchema.optional(),
+		})
+		.optional(),
+	symbols: z
+		.object({
+			preset: symbolPresetSchema.optional(),
+			overrides: z.record(z.string(), z.string()).optional(),
+		})
+		.optional(),
 });
 
-type ThemeJson = Static<typeof ThemeJsonSchema>;
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- TypeBox CJS/ESM type mismatch
-const validateThemeJson = TypeCompiler.Compile(ThemeJsonSchema as any);
+type ThemeJson = z.infer<typeof themeJsonSchema>;
 
 export type ThemeColor =
 	| "accent"
@@ -1457,6 +1454,7 @@ export class Theme {
 			pause: this.#symbols["icon.pause"],
 			loop: this.#symbols["icon.loop"],
 			folder: this.#symbols["icon.folder"],
+			scratchFolder: this.#symbols["icon.scratchFolder"],
 			file: this.#symbols["icon.file"],
 			git: this.#symbols["icon.git"],
 			branch: this.#symbols["icon.branch"],
@@ -1632,18 +1630,20 @@ async function loadThemeJson(name: string): Promise<ThemeJson> {
 	} catch (error) {
 		throw new Error(`Failed to parse theme ${name}: ${error}`);
 	}
-	if (!validateThemeJson.Check(json)) {
-		const errors = Array.from(validateThemeJson.Errors(json));
+	const parsed = themeJsonSchema.safeParse(json);
+	if (!parsed.success) {
 		const missingColors: string[] = [];
 		const otherErrors: string[] = [];
 
-		for (const e of errors) {
-			// Check for missing required color properties
-			const match = e.path.match(/^\/colors\/(\w+)$/);
-			if (match && e.message.includes("Required")) {
-				missingColors.push(match[1]);
+		for (const issue of parsed.error.issues) {
+			const parts = issue.path;
+			const colorKey = parts.length === 2 && parts[0] === "colors" && typeof parts[1] === "string" ? parts[1] : null;
+
+			if (colorKey && issue.code === "invalid_type" && (issue as { received?: unknown }).received === undefined) {
+				missingColors.push(colorKey);
 			} else {
-				otherErrors.push(`  - ${e.path}: ${e.message}`);
+				const pathStr = parts.length === 0 ? "/" : `/${parts.map(String).join("/")}`;
+				otherErrors.push(`  - ${pathStr}: ${issue.message}`);
 			}
 		}
 
@@ -1660,7 +1660,7 @@ async function loadThemeJson(name: string): Promise<ThemeJson> {
 
 		throw new Error(errorMessage);
 	}
-	return json as ThemeJson;
+	return parsed.data;
 }
 
 interface CreateThemeOptions {

package/src/modes/types.ts

@@ -1,4 +1,5 @@
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { CompactionOutcome } from "@oh-my-pi/pi-agent-core/compaction";
 import type { AssistantMessage, ImageContent, Message, UsageReport } from "@oh-my-pi/pi-ai";
 import type { Component, Container, EditorTheme, Loader, Spacer, Text, TUI } from "@oh-my-pi/pi-tui";
 import type { KeybindingsManager } from "../config/keybindings";
@@ -13,7 +14,6 @@ import type { CompactOptions } from "../extensibility/extensions/types";
 import type { MCPManager } from "../mcp";
 import type { PlanApprovalDetails } from "../plan-mode/approved-plan";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
-import type { CompactionOutcome } from "../session/compaction";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
 import type { LspStartupServerInfo } from "../tools";

package/src/modes/utils/context-usage.ts

@@ -1,10 +1,10 @@
+import type { CompactionSettings } from "@oh-my-pi/pi-agent-core/compaction";
+import { effectiveReserveTokens, estimateTokens, resolveThresholdTokens } from "@oh-my-pi/pi-agent-core/compaction";
 import type { Model } from "@oh-my-pi/pi-ai";
 import { countTokens } from "@oh-my-pi/pi-natives";
 import { formatNumber } from "@oh-my-pi/pi-utils";
 import type { Skill } from "../../extensibility/skills";
 import type { AgentSession } from "../../session/agent-session";
-import type { CompactionSettings } from "../../session/compaction";
-import { effectiveReserveTokens, estimateTokens, resolveThresholdTokens } from "../../session/compaction";
 import type { Tool } from "../../tools";
 import type { theme as Theme } from "../theme/theme";
 

package/src/prompts/tools/github.md

@@ -6,10 +6,10 @@ Pick the operation via `op`. Each op uses a subset of the parameters:
 - `pr_create` — Create a pull request. Either provide `title` (and optional `body`) or set `fill: true` to auto-fill from commits. Optional `base` (target, defaults to repo default), `head` (source, defaults to current branch), `draft`, `repo`, `reviewer[]`, `assignee[]`, `label[]`. Returns the new PR URL plus a summary.
 - `pr_checkout` — Check one or more pull requests out into dedicated git worktrees. Optional `pr` (number, URL, branch, or array of any of those — pass an array to batch-check-out multiple PRs in one call), `repo`, `force` (reset existing local branch).
 - `pr_push` — Push a checked-out PR branch back to its source branch. Requires the branch to have been checked out via `op: pr_checkout` (carries push metadata). Optional `branch`; defaults to the current checked-out git branch. Optional `forceWithLease`.
-- `search_issues` — Search issues using normal GitHub issue search syntax. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`, `dateField`.
-- `search_prs` — Search pull requests using normal GitHub PR search syntax. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`, `dateField`.
-- `search_code` — Search code with GitHub code search syntax. Required `query`. Optional `repo`, `limit`. Returns matching paths with surrounding fragments. Date filtering (`since`/`until`) is **not** supported by GitHub code search.
-- `search_commits` — Search commits across GitHub. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`. `dateField` is ignored — always uses `committer-date`.
+- `search_issues` — Search issues using normal GitHub issue search syntax. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`, `dateField`. Defaults `repo` to the current checkout's `owner/repo` when omitted; pass an explicit `repo:`/`org:`/`user:` qualifier in `query` to search outside it.
+- `search_prs` — Search pull requests using normal GitHub PR search syntax. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`, `dateField`. Defaults `repo` to the current checkout's `owner/repo` when omitted; pass an explicit `repo:`/`org:`/`user:` qualifier in `query` to search outside it.
+- `search_code` — Search code with GitHub code search syntax. Required `query`. Optional `repo`, `limit`. Returns matching paths with surrounding fragments. Defaults `repo` to the current checkout's `owner/repo` when omitted; pass an explicit `repo:`/`org:`/`user:` qualifier in `query` to search outside it. Date filtering (`since`/`until`) is **not** supported by GitHub code search.
+- `search_commits` — Search commits across GitHub. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`. `dateField` is ignored — always uses `committer-date`. Defaults `repo` to the current checkout's `owner/repo` when omitted; pass an explicit `repo:`/`org:`/`user:` qualifier in `query` to search outside it.
 - `search_repos` — Search repositories across GitHub. Optional `query` (required unless `since`/`until` is set), `limit`, `since`, `until`, `dateField` (use query qualifiers like `org:`, `language:` instead of `repo`).
 - Date filter format for `since` / `until`: relative duration `<n><unit>` (`m`/`h`/`d`/`w`/`mo`/`y`, e.g. `3d`, `12h`, `2w`), an ISO date `YYYY-MM-DD`, or an ISO datetime. Translated to a single GitHub-search qualifier (`created:≥…`, `created:≤…`, or `created:since..until`). `dateField: "updated"` maps to `updated:` for issues/prs and `pushed:` for repos. When you only want a date filter and no keywords, omit `query` entirely.
 - `run_watch` — Watch a GitHub Actions workflow run. Optional `run` (id or URL). Omitting `run` watches all workflow runs for the current HEAD commit; `branch` falls back to the current branch. Optional `tail` (log lines per failed job). Streams snapshots, fast-fails on the first detected job failure (with a brief grace period to capture concurrent failures), then fetches tailed logs for the failed jobs. The full failed-job logs are saved as a session artifact for on-demand reads.

package/src/prompts/tools/hashline.md

@@ -66,36 +66,35 @@ When braces bound your edit, you SHOULD prefer these shapes:
 </common-failures>
 
 <case file="mod.ts">
-{{hline 1 "const DEF = \"guest\";"}}
-{{hline 2 "export function label(name) {"}}
+{{hline 1 "const TITLE = \"Mr\";"}}
+{{hline 2 "export function greet(name) {"}}
 {{hline 3 "\treturn ["}}
-{{hline 4 "\t\tname?.trim() || DEF,"}}
-{{hline 5 "\t\t\" • \","}}
-{{hline 6 "\t].join(\"\");"}}
+{{hline 4 "\t\tTITLE,"}}
+{{hline 5 "\t\tname?.trim() || \"guest\","}}
+{{hline 6 "\t].join(\" \");"}}
 {{hline 7 "}"}}
 </case>
 
 <examples>
 # Replace one line (the payload must re-emit the original indentation)
 @@ mod.ts
-= {{hrefr 4}}..{{hrefr 4}}
-{{hsep}}		name?.trim().toUpperCase() || DEF,
+= {{hrefr 1}}..{{hrefr 1}}
+{{hsep}}const TITLE = "Mrs";
 
 # Replace a full multiline statement (widen to a self-contained boundary)
 @@ mod.ts
 = {{hrefr 3}}..{{hrefr 6}}
 {{hsep}}	return [
-{{hsep}}		name?.trim() || DEF,
-{{hsep}}		"·",
-{{hsep}}		" • ",
-{{hsep}}	].join("");
+{{hsep}}		"Mrs",
+{{hsep}}		name?.trim() || "guest",
+{{hsep}}	].join(" ");
 
 # Insert AFTER/BEFORE a line
 @@ mod.ts
-+ {{hrefr 3}}
-{{hsep}}		"·",
++ {{hrefr 4}}
+{{hsep}}		"Dr",
 < {{hrefr 5}}
-{{hsep}}		"·",
+{{hsep}}		"Dr",
 
 # Append to file
 @@ mod.ts
@@ -112,13 +111,12 @@ When braces bound your edit, you SHOULD prefer these shapes:
 </examples>
 
 <anti-pattern>
-# WRONG — replaces 3 lines just to add one.
+# WRONG — replaces 2 lines just to add one.
 @@ mod.ts
-= {{hrefr 1}}..{{hrefr 3}}
-{{hsep}}const DEF = "guest";
+= {{hrefr 1}}..{{hrefr 2}}
+{{hsep}}const TITLE = "Mr";
 {{hsep}}const DEBUG = false;
-{{hsep}}export function label(name) {
-{{hsep}}	return [
+{{hsep}}export function greet(name) {
 # RIGHT — same effect, one-line insert
 @@ mod.ts
 + {{hrefr 1}}
@@ -127,17 +125,15 @@ When braces bound your edit, you SHOULD prefer these shapes:
 # WRONG — replace from the middle of a larger statement (error-prone)
 @@ mod.ts
 = {{hrefr 4}}..{{hrefr 5}}
-{{hsep}}		name?.trim() || DEF,
-{{hsep}}		"·",
-{{hsep}}		" • ",
+{{hsep}}		"Dr",
+{{hsep}}		name?.trim() || "guest",
 # RIGHT — widen to the full statement
 @@ mod.ts
 = {{hrefr 3}}..{{hrefr 6}}
 {{hsep}}	return [
-{{hsep}}		name?.trim() || DEF,
-{{hsep}}		"·",
-{{hsep}}		" • ",
-{{hsep}}	].join("");
+{{hsep}}		"Dr",
+{{hsep}}		name?.trim() || "guest",
+{{hsep}}	].join(" ");
 </anti-pattern>
 
 <critical>

package/src/prompts/tools/read.md

@@ -1,46 +1,58 @@
-Reads the content at the specified path or URL.
+Read files, directories, archives, SQLite databases, images, documents, internal resources, and web URLs through a single `path` string.
 
 <instruction>
-The `read` tool is multi-purpose and more capable than it looks — inspects files, directories, archives, SQLite databases, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), **and URLs**.
-- You MUST parallelize reads when exploring related files
-- For URLs, `read` fetches the page and returns clean extracted text/markdown by default (reader-mode). It handles HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs, etc. You SHOULD reach for `read` — not a browser/puppeteer tool — for fetching and inspecting web content.
+- One tool for filesystem, archives, SQLite, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), internal URIs, and web URLs (reader-mode by default).
+- You SHOULD parallelize independent reads when exploring related files.
+- You SHOULD reach for `read` — not a browser/puppeteer tool — for fetching web content.
+</instruction>
 
 ## Parameters
-- `path` — file path or URL (required). Append `:<sel>` for line ranges or raw mode (for example `src/foo.ts:50-200` or `src/foo.ts:raw`).
+
+- `path` — required. Local path, internal URI (`skill://`, `agent://`, `artifact://`, `memory://`, `rule://`, `local://`, `mcp://`), or URL. Append `:<sel>` for line ranges, raw mode, or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
 
 ## Selectors
 
-|`path` suffix|Behavior|
-|---|---|
-|_(omitted)_|For parseable code files, return a structural summary. Otherwise read from the start (up to {{DEFAULT_LIMIT}} lines).|
-|`:50`|Read from line 50 onward|
-|`:50-200`|Read lines 50-200|
-|`:50+150`|Read 150 lines starting at line 50|
-|`:20+1`|Read exactly one line|
-|`:5-16,960-973`|Read multiple ranges in one call (comma-separated; ranges sort and merge automatically)|
-|`:raw`|Read verbatim text without anchors or summarization|
-|`:conflicts`|Return a one-line-per-block index of every merge conflict in the file|
+Append `:<sel>` to `path`. The bare path falls back to the default mode.
+
+- _(none)_ — parseable code → structural summary (signatures kept, bodies elided); other files → read from the start (up to {{DEFAULT_LIMIT}} lines).
+- `:50` — read from line 50 onward.
+- `:50-200` — lines 50–200 inclusive.
+- `:50+150` — 150 lines starting at line 50.
+- `:20+1` — exactly one line.
+- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged).
+- `:raw` — verbatim text; no anchors, no summary, no line prefixes.
+- `:2-4:raw` or `:raw:2-4` — range AND verbatim; the two compose in either order.
+- `:conflicts` — one-line-per-block index of every unresolved git merge conflict.
+
+# Files
+
+- Reading a directory path returns a depth-limited dirent listing.
+{{#if IS_HL_MODE}}
+- Reading a file with an explicit selector returns lines prefixed with `line+hash` anchors: `41th|def alpha():`. The 2-char hash is a content fingerprint that `edit` / `apply_patch` consume — copy it verbatim, NEVER fabricate.
+{{else}}
+{{#if IS_LINE_NUMBER_MODE}}
+- Reading a file with an explicit selector returns lines prefixed with line numbers: `41|def alpha():`.
+{{/if}}
+{{/if}}
+- Parseable code without a selector returns a **structural summary**: declarations kept, large bodies collapsed to `..` (merged brace pair) or `…` (standalone). Summarized output ends with a footer of the form:
+
+  `[NN lines across MM elided regions; read <path>:raw or a line range like <path>:1-9999 for verbatim content]`
 
-# Filesystem
-- Reading a directory path returns a list of dirents.
-  {{#if IS_HL_MODE}}
-- Reading a file with an explicit selector returns lines prefixed with anchors (line+hash): `41th|def alpha():`
-  {{else}}
-  {{#if IS_LINE_NUMBER_MODE}}
-- Reading a file with an explicit selector returns lines prefixed with line numbers: `41|def alpha():`
-  {{/if}}
-  {{/if}}
-- Reading a parseable code file without a selector returns a structural summary with signatures/declarations kept and large bodies collapsed to `…`. Use `:raw` or an explicit range such as `:1-9999` for verbatim content.
+  If the elided body is what you actually need, re-issue the **exact selector the footer names**. NEVER guess what's inside `..` / `…` — those markers carry no content.
 
-# Inspection
+# Documents & Notebooks
 
-Extracts text from PDF, Word, PowerPoint, Excel, RTF, EPUB, and Jupyter notebook files. Notebooks are shown as editable `# %% [type] cell:N` text; edits to that text are applied back to the underlying `.ipynb` JSON while preserving notebook metadata where possible. Can inspect images.
+Extracts text from PDF, Word, PowerPoint, Excel, RTF, and EPUB. Notebooks (`.ipynb`) are shown as editable `# %% [type] cell:N` text; edits round-trip back to the underlying JSON preserving notebook metadata. Add `:raw` to a notebook to bypass the converter and read the JSON directly.
 
-# Directories & Archives
+# Images
 
-Directories and archive roots return a list of entries. Supports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read contents, and append a selector to the archive entry such as `archive.zip:dir/file.ts:50-60`.
+Reading an image path returns metadata (mime, bytes, dimensions, channels, alpha). For actual visual analysis, call `inspect_image` with the path and a question describing what to inspect.
 
-# SQLite Databases
+# Archives
+
+Supports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read a member, and append a normal selector to the inner path: `archive.zip:dir/file.ts:50-60`.
+
+# SQLite
 
 For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 - `file.db` — list tables with row counts
@@ -52,13 +64,19 @@ For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 
 # URLs
 
-Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom feeds, JSON endpoints, PDFs at URLs, and similar text-based resources. Returns clean reader-mode text/markdown — no browser required. Use a `:raw` suffix for untouched HTML. URL line selectors mirror the file form (`:50`, `:50-100`, `:50+150`, `:raw`). If a URL would otherwise look like `host:port`, add a trailing slash before the selector (e.g. `https://example.com/:80`).
-</instruction>
+- Default reader-mode: HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs → clean text/markdown.
+- `:raw` returns untouched HTML; line selectors (`:50`, `:50-100`, `:50+150`) paginate the cached fetched output.
+- Bare `host:port` URLs collide with the selector grammar — add a trailing slash before the selector: `https://example.com/:80`.
+
+# Internal URIs
+
+`skill://<name>`, `agent://<id>`, `artifact://<id>`, `memory://root`, `rule://<name>`, `local://<name>.md`, `mcp://<uri>` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated.
 
 <critical>
-- You MUST use `read` for every file, directory, archive, and URL read. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, and `wget` are **FORBIDDEN** for inspection — any such Bash call is a bug, regardless of how short or convenient it looks.
-- You MUST prefer `read` over a browser/puppeteer tool for fetching URL content; only use a browser if `read` fails to deliver reasonable content.
-- You MUST always include the `path` parameter — never call `read` with an empty argument object `{}`.
-- For specific line ranges, append the selector to `path` (e.g. `path="src/foo.ts:50-200"`, `path="src/foo.ts:50+150"`) — NEVER reach for `sed -n`, `awk NR`, or `head`/`tail` pipelines.
-- You MAY use path suffix selectors with URL reads; the tool paginates cached fetched output.
+- You MUST use `read` for every file, directory, archive, and URL inspection. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, `wget` are FORBIDDEN — any such bash call is a bug, regardless of how short or convenient it looks.
+- You MUST prefer `read` over a browser/puppeteer tool for URL content; only reach for a browser when `read` cannot deliver reasonable content.
+- You MUST always include `path`. NEVER call `read` with `{}`.
+- For line ranges, append the selector to `path` (`path="src/foo.ts:50-200"`, `path="src/foo.ts:50+150"`). NEVER substitute `sed -n`, `awk NR`, or `head`/`tail` pipelines.
+- Summary footer says `read <path>:raw …`? Re-issue the exact selector it names. NEVER guess what's inside `..` / `…` markers — they carry no content.
+- You MAY combine selectors with URL reads and internal URIs; both paginate the cached resolved output.
 </critical>

package/src/sdk.ts

@@ -2,6 +2,7 @@ import {
 	Agent,
 	type AgentEvent,
 	type AgentMessage,
+	type AgentTelemetryConfig,
 	type AgentTool,
 	INTENT_FIELD,
 	type ThinkingLevel,
@@ -244,6 +245,17 @@ export interface CreateAgentSessionOptions {
 
 	/** Whether UI is available (enables interactive tools like ask). Default: false */
 	hasUI?: boolean;
+
+	/**
+	 * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
+	 * Passing `{}` enables the loop's GenAI-semantic-convention spans. See
+	 * {@link AgentTelemetryConfig} for the full surface (hooks, content capture,
+	 * cost estimator, agent identity).
+	 *
+	 * Safe to enable without an OTEL SDK registered in the host: the
+	 * `@opentelemetry/api` package returns a no-op tracer in that case.
+	 */
+	telemetry?: AgentTelemetryConfig;
 }
 
 /** Result from createAgentSession */
@@ -920,18 +932,24 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	// it. On timeout we forward `undefined` to ToolSession; buildSystemPromptInternal
 	// will re-race the same promise through its own withDeadline path. Background
 	// work continues so caches still warm.
-	const raceWithDeadline = <T>(name: string, work: Promise<T>): Promise<T | undefined> =>
-		Promise.race([
+	const raceWithDeadline = async <T>(name: string, work: Promise<T>): Promise<T | undefined> => {
+		let timedOut = false;
+		const result = await Promise.race([
 			work,
 			Bun.sleep(STARTUP_SCAN_DEADLINE_MS).then(() => {
-				logger.warn("Startup scan exceeded deadline; deferring to system prompt fallback", {
-					name,
-					timeoutMs: STARTUP_SCAN_DEADLINE_MS,
-					cwd,
-				});
+				timedOut = true;
 				return undefined;
 			}),
 		]);
+		if (timedOut) {
+			logger.warn("Startup scan exceeded deadline; deferring to system prompt fallback", {
+				name,
+				timeoutMs: STARTUP_SCAN_DEADLINE_MS,
+				cwd,
+			});
+		}
+		return result;
+	};
 	const [contextFiles, resolvedWorkspaceTree] = await Promise.all([
 		contextFilesPromise,
 		raceWithDeadline("buildWorkspaceTree", workspaceTreePromise),
@@ -1093,6 +1111,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			settings,
 			authStorage,
 			modelRegistry,
+			getTelemetry: () => agent?.telemetry,
 		};
 
 		// Wire process-wide internal URL singletons owned by their real classes.
@@ -1746,6 +1765,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			},
 			intentTracing: !!intentField,
 			getToolChoice: () => session?.nextToolChoice(),
+			telemetry: options.telemetry,
 		});
 
 		cursorEventEmitter = event => agent.emitExternalEvent(event);
@@ -1754,11 +1774,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		if (hasExistingSession) {
 			agent.replaceMessages(existingSession.messages);
 		} else {
-			// Save initial model and thinking level for new sessions so they can be restored on resume
+			// Save initial model, thinking level, and service tier for new sessions so they can be restored on resume.
 			if (model) {
 				sessionManager.appendModelChange(`${model.provider}/${model.id}`);
 			}
 			sessionManager.appendThinkingLevelChange(thinkingLevel);
+			if (initialServiceTier) {
+				sessionManager.appendServiceTierChange(initialServiceTier);
+			}
 		}
 
 		session = new AgentSession({