@oh-my-pi/pi-coding-agent 13.18.0 → 14.0.2

package/src/modes/session-observer-registry.ts

@@ -0,0 +1,146 @@
+import type { AgentProgress, SubagentLifecyclePayload, SubagentProgressPayload } from "../task";
+import { TASK_SUBAGENT_LIFECYCLE_CHANNEL, TASK_SUBAGENT_PROGRESS_CHANNEL } from "../task";
+import type { EventBus } from "../utils/event-bus";
+
+export interface ObservableSession {
+	id: string;
+	kind: "main" | "subagent";
+	label: string;
+	agent?: string;
+	description?: string;
+	status: "active" | "completed" | "failed" | "aborted";
+	sessionFile?: string;
+	lastUpdate: number;
+	/** Latest progress snapshot from the subagent executor */
+	progress?: AgentProgress;
+}
+
+const STATUS_MAP: Record<string, ObservableSession["status"]> = {
+	started: "active",
+	completed: "completed",
+	failed: "failed",
+	aborted: "aborted",
+};
+
+export class SessionObserverRegistry {
+	#sessions = new Map<string, ObservableSession>();
+	#listeners = new Set<() => void>();
+	#eventBusUnsubscribers: Array<() => void> = [];
+
+	/** Add a change listener. Returns unsubscribe function. */
+	onChange(cb: () => void): () => void {
+		this.#listeners.add(cb);
+		return () => this.#listeners.delete(cb);
+	}
+
+	#notifyListeners(): void {
+		for (const cb of this.#listeners) cb();
+	}
+
+	setMainSession(sessionFile?: string): void {
+		const existing = this.#sessions.get("main");
+		this.#sessions.set("main", {
+			id: "main",
+			kind: "main",
+			label: "Main Session",
+			status: "active",
+			sessionFile: sessionFile ?? existing?.sessionFile,
+			lastUpdate: Date.now(),
+		});
+		this.#notifyListeners();
+	}
+
+	getSessions(): ObservableSession[] {
+		const sessions = [...this.#sessions.values()];
+		sessions.sort((a, b) => {
+			if (a.kind === "main") return -1;
+			if (b.kind === "main") return 1;
+			return a.lastUpdate - b.lastUpdate;
+		});
+		return sessions;
+	}
+
+	getActiveSubagentCount(): number {
+		let count = 0;
+		for (const s of this.#sessions.values()) {
+			if (s.kind === "subagent" && s.status === "active") count++;
+		}
+		return count;
+	}
+
+	/** Clear all tracked sessions (e.g. on session switch). Keeps EventBus subscriptions and listeners. */
+	resetSessions(): void {
+		this.#sessions.clear();
+		this.#notifyListeners();
+	}
+
+	dispose(): void {
+		for (const unsub of this.#eventBusUnsubscribers) unsub();
+		this.#eventBusUnsubscribers = [];
+		this.#sessions.clear();
+		this.#listeners.clear();
+	}
+
+	subscribeToEventBus(eventBus: EventBus): void {
+		// Dispose previous EventBus subscriptions if called again
+		for (const unsub of this.#eventBusUnsubscribers) unsub();
+		this.#eventBusUnsubscribers = [];
+
+		this.#eventBusUnsubscribers.push(
+			eventBus.on(TASK_SUBAGENT_LIFECYCLE_CHANNEL, data => {
+				const payload = data as SubagentLifecyclePayload;
+				const status = STATUS_MAP[payload.status];
+				if (!status) return;
+
+				const existing = this.#sessions.get(payload.id);
+				if (existing) {
+					existing.status = status;
+					existing.lastUpdate = Date.now();
+					if (payload.description) existing.description = payload.description;
+					if (payload.sessionFile) existing.sessionFile = payload.sessionFile;
+				} else {
+					this.#sessions.set(payload.id, {
+						id: payload.id,
+						kind: "subagent",
+						label: payload.description ?? `Subagent #${payload.index}`,
+						agent: payload.agent,
+						description: payload.description,
+						status,
+						sessionFile: payload.sessionFile,
+						lastUpdate: Date.now(),
+					});
+				}
+				this.#notifyListeners();
+			}),
+		);
+
+		this.#eventBusUnsubscribers.push(
+			eventBus.on(TASK_SUBAGENT_PROGRESS_CHANNEL, data => {
+				const payload = data as SubagentProgressPayload;
+				const progress = payload.progress;
+				const id = progress.id;
+				const existing = this.#sessions.get(id);
+
+				if (existing) {
+					existing.lastUpdate = Date.now();
+					existing.progress = progress;
+					if (progress.description) existing.description = progress.description;
+					if (payload.sessionFile) existing.sessionFile = payload.sessionFile;
+				} else {
+					this.#sessions.set(id, {
+						id,
+						kind: "subagent",
+						label: progress.description ?? `Subagent #${payload.index}`,
+						agent: payload.agent,
+						description: progress.description,
+						status: "active",
+						sessionFile: payload.sessionFile,
+						lastUpdate: Date.now(),
+						progress,
+					});
+				}
+				this.#notifyListeners();
+			}),
+		);
+	}
+}

package/src/modes/shared.ts

@@ -1,7 +1,4 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
 import type { TabBarTheme } from "@oh-my-pi/pi-tui";
-import { getProjectDir, isEnoent } from "@oh-my-pi/pi-utils";
 import { theme } from "./theme/theme";
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -31,42 +28,3 @@ export function getTabBarTheme(): TabBarTheme {
 }
 
 export { parseCommandArgs } from "../utils/command-args";
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Git HEAD Discovery
-// ═══════════════════════════════════════════════════════════════════════════
-
-/** Walk up from the project dir to find .git/HEAD. Returns path and content, or null. */
-export async function findGitHeadPathAsync(): Promise<{ path: string; content: string } | null> {
-	let dir = getProjectDir();
-	while (true) {
-		const gitHeadPath = path.join(dir, ".git", "HEAD");
-		try {
-			const content = await Bun.file(gitHeadPath).text();
-			return { path: gitHeadPath, content };
-		} catch (err) {
-			if (!isEnoent(err)) throw err;
-		}
-		const parent = path.dirname(dir);
-		if (parent === dir) {
-			return null;
-		}
-		dir = parent;
-	}
-}
-
-/** Walk up from the project dir to find .git/HEAD. Returns path, or null. */
-export function findGitHeadPathSync(): string | null {
-	let dir = getProjectDir();
-	while (true) {
-		const gitHeadPath = path.join(dir, ".git", "HEAD");
-		if (fs.existsSync(gitHeadPath)) {
-			return gitHeadPath;
-		}
-		const parent = path.dirname(dir);
-		if (parent === dir) {
-			return null;
-		}
-		dir = parent;
-	}
-}

package/src/modes/theme/theme.ts

@@ -4,10 +4,10 @@ import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Effort } from "@oh-my-pi/pi-ai";
 import {
 	detectMacOSAppearance,
+	MacAppearanceObserver,
 	type HighlightColors as NativeHighlightColors,
 	highlightCode as nativeHighlightCode,
 	supportsLanguage as nativeSupportsLanguage,
-	startMacAppearanceObserver as startNativeMacObserver,
 } 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";
@@ -1148,9 +1148,14 @@ const langMap: Record<string, SymbolKey> = {
 	sh: "lang.shell",
 	zsh: "lang.shell",
 	fish: "lang.shell",
+	powershell: "lang.shell",
+	just: "lang.shell",
 	shell: "lang.shell",
 	html: "lang.html",
 	htm: "lang.html",
+	astro: "lang.html",
+	vue: "lang.html",
+	svelte: "lang.html",
 	css: "lang.css",
 	scss: "lang.css",
 	sass: "lang.css",
@@ -2057,10 +2062,12 @@ function startMacAppearanceObserver(): void {
 	stopMacAppearanceObserver();
 	if (!shouldUseMacOSAppearanceFallback()) return;
 	try {
-		macOSReportedAppearance = detectMacOSAppearance();
-		macObserver = startNativeMacObserver(appearance => {
-			macOSReportedAppearance = appearance;
-			reevaluateAutoTheme("macOS fallback");
+		macOSReportedAppearance = detectMacOSAppearance() ?? undefined;
+		macObserver = MacAppearanceObserver.start((err, appearance) => {
+			if (!err && (appearance === "dark" || appearance === "light")) {
+				macOSReportedAppearance = appearance;
+				reevaluateAutoTheme("macOS fallback");
+			}
 		});
 	} catch (err) {
 		logger.warn("Failed to start macOS appearance observer", { err });
@@ -2315,69 +2322,132 @@ export function getLanguageFromPath(filePath: string): string | undefined {
 	) {
 		return "conf";
 	}
+	if (baseName === "dockerfile" || baseName.startsWith("dockerfile.") || baseName === "containerfile") {
+		return "dockerfile";
+	}
+	if (baseName === "justfile") return "just";
+	if (baseName === "cmakelists.txt") return "cmake";
 
 	const ext = filePath.split(".").pop()?.toLowerCase();
 	if (!ext) return undefined;
 
 	const extToLang: Record<string, string> = {
 		ts: "typescript",
-		tsx: "typescript",
+		cts: "typescript",
+		mts: "typescript",
+		tsx: "tsx",
 		js: "javascript",
 		jsx: "javascript",
 		mjs: "javascript",
 		cjs: "javascript",
 		py: "python",
+		pyi: "python",
 		rb: "ruby",
+		rbw: "ruby",
+		gemspec: "ruby",
 		rs: "rust",
 		go: "go",
 		java: "java",
 		kt: "kotlin",
+		ktm: "kotlin",
+		kts: "kotlin",
 		swift: "swift",
 		c: "c",
 		h: "c",
 		cpp: "cpp",
 		cc: "cpp",
 		cxx: "cpp",
+		hh: "cpp",
 		hpp: "cpp",
+		cu: "cpp",
+		ino: "cpp",
 		cs: "csharp",
+		clj: "clojure",
+		cljc: "clojure",
+		cljs: "clojure",
+		edn: "clojure",
 		php: "php",
 		sh: "bash",
 		bash: "bash",
 		zsh: "bash",
+		ksh: "bash",
+		bats: "bash",
+		tmux: "bash",
+		cgi: "bash",
+		fcgi: "bash",
+		command: "bash",
+		tool: "bash",
 		fish: "fish",
 		ps1: "powershell",
+		psm1: "powershell",
 		sql: "sql",
 		html: "html",
 		htm: "html",
+		xhtml: "html",
+		astro: "astro",
+		vue: "vue",
+		svelte: "svelte",
 		css: "css",
 		scss: "scss",
 		sass: "sass",
 		less: "less",
 		json: "json",
+		ipynb: "ipynb",
+		hbs: "handlebars",
+		hsb: "handlebars",
+		handlebars: "handlebars",
 		yaml: "yaml",
 		yml: "yaml",
 		toml: "toml",
 		xml: "xml",
+		xsl: "xml",
+		xslt: "xml",
+		svg: "xml",
+		plist: "xml",
 		md: "markdown",
 		markdown: "markdown",
+		mdx: "markdown",
+		diff: "diff",
+		patch: "diff",
 		dockerfile: "dockerfile",
-		makefile: "makefile",
+		containerfile: "dockerfile",
+		makefile: "make",
+		justfile: "just",
+		mk: "make",
+		mak: "make",
 		cmake: "cmake",
 		lua: "lua",
+		jl: "julia",
+		pl: "perl",
+		pm: "perl",
 		perl: "perl",
 		r: "r",
 		scala: "scala",
-		clj: "clojure",
+		sc: "scala",
+		sbt: "scala",
 		ex: "elixir",
 		exs: "elixir",
 		erl: "erlang",
 		hs: "haskell",
+		nix: "nix",
+		odin: "odin",
+		zig: "zig",
+		star: "starlark",
+		bzl: "starlark",
+		sol: "solidity",
+		v: "verilog",
+		sv: "verilog",
+		svh: "verilog",
+		vh: "verilog",
+		m: "objc",
+		mm: "objc",
 		ml: "ocaml",
 		vim: "vim",
 		graphql: "graphql",
 		proto: "protobuf",
 		tf: "hcl",
 		hcl: "hcl",
+		tfvars: "hcl",
 		txt: "text",
 		text: "text",
 		log: "log",
@@ -2388,6 +2458,8 @@ export function getLanguageFromPath(filePath: string): string | undefined {
 		conf: "conf",
 		config: "conf",
 		properties: "conf",
+		tla: "tlaplus",
+		tlaplus: "tlaplus",
 		env: "env",
 	};
 

package/src/modes/types.ts

@@ -14,7 +14,7 @@ import type { MCPManager } from "../mcp";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
-import type { ExitPlanModeDetails } from "../tools";
+import type { ExitPlanModeDetails, LspStartupServerInfo } from "../tools";
 import type { AssistantMessageComponent } from "./components/assistant-message";
 import type { BashExecutionComponent } from "./components/bash-execution";
 import type { CustomEditor } from "./components/custom-editor";
@@ -76,7 +76,7 @@ export interface InteractiveModeContext {
 	agent: AgentSession["agent"];
 	historyStorage?: HistoryStorage;
 	mcpManager?: MCPManager;
-	lspServers?: Array<{ name: string; status: "ready" | "error"; fileTypes: string[]; error?: string }>;
+	lspServers?: LspStartupServerInfo[];
 
 	// State
 	isInitialized: boolean;
@@ -208,6 +208,8 @@ export interface InteractiveModeContext {
 	showOAuthSelector(mode: "login" | "logout", providerId?: string): Promise<void>;
 	showHookConfirm(title: string, message: string): Promise<boolean>;
 	showDebugSelector(): void;
+	showSessionObserver(): void;
+	resetObserverRegistry(): void;
 
 	// Input handling
 	handleCtrlC(): void;

package/src/modes/utils/keybinding-matchers.ts

@@ -19,3 +19,12 @@ export function matchesAppInterrupt(data: string): boolean {
 export function matchesSelectCancel(data: string): boolean {
 	return getKeybindings().matches(data, "tui.select.cancel");
 }
+
+export function matchesAppExternalEditor(data: string): boolean {
+	const keybindings = getKeybindings();
+	const externalEditorKeys = keybindings.getKeys("app.editor.external");
+	if (externalEditorKeys.length > 0) {
+		return keybindings.matches(data, "app.editor.external");
+	}
+	return matchesKey(data, "ctrl+g");
+}

package/src/prompts/system/custom-system-prompt.md

@@ -61,3 +61,8 @@ You **MUST** read `rule://<name>` when working in that domain.
 {{/if}}
 Current date: {{date}}
 Current working directory: {{cwd}}
+{{#if secretsEnabled}}
+<redacted-content>
+Some values in tool output are redacted for security. They appear as `#XXXX#` tokens (4 uppercase-alphanumeric characters wrapped in `#`). These are **not errors** — they are intentional placeholders for sensitive values (API keys, passwords, tokens). Treat them as opaque strings. Do not attempt to decode, fix, or report them as problems.
+</redacted-content>
+{{/if}}

package/src/prompts/system/system-prompt.md

@@ -109,6 +109,7 @@ Most tools resolve custom protocol URLs to internal resources (not web URLs):
 - `artifact://<id>` — Raw artifact content (truncated tool output)
 - `local://<TITLE>.md` — Finalized plan artifact created after `exit_plan_mode` approval
 - `jobs://<job-id>` — Specific job status and result
+- `mcp://<resource-uri>` — MCP resource from a connected server; matched against exact resource URIs first, then RFC 6570 URI templates advertised by connected servers
 - `pi://..` — Internal documentation files about Oh My Pi, you **MUST NOT** read them unless the user asks about omp/pi itself: its SDK, extensions, themes, skills, TUI, keybindings, or configuration
 
 In `bash`, URIs auto-resolve to filesystem paths (e.g., `python skill://my-skill/scripts/init.py`).
@@ -261,7 +262,7 @@ These are inviolable. Violation is system failure.
 - You **MUST NOT** suppress tests to make code pass. You **MUST NOT** fabricate outputs not observed.
 - You **MUST NOT** solve the wished-for problem instead of the actual problem.
 - You **MUST NOT** ask for information obtainable from tools, repo context, or files.
-- You **MUST** perform full CUTOVER when refactoring. Replace old usage, not write shims. No gradual migration. Let it error while you fix it.
+- You **MUST** always design a clean solution. You **MUST NOT** introduce unnecessary backwards compatibiltity layers, no shims, no gradual migration, no bridges to old code unless user explicitly asks for it. Let the errors guide you on what to include in the refactoring. **ALWAYS default to performing full CUTOVER!**
 
 # Design Integrity
 
@@ -314,6 +315,12 @@ When a tool call fails, read the full error before doing anything else. When a f
 - You **SHOULD** run only tests you added/modified unless asked otherwise.
 - You **MUST NOT** yield without proof when non-trivial work, self-assessment is deceptive: tests, linters, type checks, repro steps… exhaust all external verification.
 
+{{#if secretsEnabled}}
+<redacted-content>
+Some values in tool output are redacted for security. They appear as `#XXXX#` tokens (4 uppercase-alphanumeric characters wrapped in `#`). These are **not errors** — they are intentional placeholders for sensitive values (API keys, passwords, tokens). Treat them as opaque strings. Do not attempt to decode, fix, or report them as problems.
+</redacted-content>
+{{/if}}
+
 {{SECTION_SEPERATOR "Now"}}
 The current working directory is '{{cwd}}'.
 Today is '{{date}}', and your work begins now. Get it right.

package/src/prompts/tools/chunk-edit.md

@@ -0,0 +1,219 @@
+Edits files via syntax-aware chunks. Run `read(path="file.ts")` first. The edit selector is a chunk path, optionally qualified with a region.
+
+<rules>
+- **MUST** `read` first. Never invent chunk paths or CRCs. Copy them from the latest `read` output or edit response.
+- `sel` format:
+  - insertions: `chunk` or `chunk@region`
+  - replacements: `chunk#CRC` or `chunk#CRC@region`
+- Without a `@region` it defaults to the entire chunk including leading trivia. Valid regions: `head`, `body`, `tail`, `decl`.
+- If the exact chunk path is unclear, run `read(path="file", sel="?")` and copy a selector from that listing.
+- Use a single leading space per indent level in `content`. Write content at indent-level 0 — the tool re-indents it to match the chunk's position in the file. For example, to replace `@body` of a method, write the body starting at column 0:
+  ```
+  content: "if (x) {\n return true;\n}"
+  ```
+  The tool adds the correct base indent automatically. Never manually pad with the chunk's own indentation.
+- `@region` only works on container chunks (classes, functions, impl blocks, sections). Do **not** use `@head`/`@body`/`@tail` on leaf chunks (enum variants, fields, single statements) — use the whole chunk instead.
+- `replace` requires the current CRC. Insertions do not.
+- **CRCs change after every edit.** Always use the selectors/CRCs from the most recent `read` or edit response. Never reuse a CRC from a previous edit.
+</rules>
+
+<critical>
+You **MUST** use the narrowest region that covers your change. Replacing without a region replaces the **entire chunk including leading comments, decorators, and attributes** — omitting them from `content` deletes them.
+</critical>
+
+<regions>
+```
+  @head ··· ┊ /// doc comment
+          · ┊ #[attr]
+  @decl ··· ┊ fn foo(x: i32) {
+   @body ·· ┊     body();
+   @tail ·· ┊ }
+```
+- `@body` — the interior only. **Use for most edits.**
+- `@head` — leading trivia + signature + opening delimiter.
+- `@tail` — the closing delimiter.
+- `@decl` — everything except leading trivia (signature + body + closing delimiter).
+- *(no region)* — the entire chunk including leading trivia. Same as `@head` + `@body` + `@tail`.
+
+For leaf chunks (fields, variants, single-line items), `@body` falls back to the full chunk.
+
+`append`/`prepend` without a `@region` inserts _outside_ the chunk. To add children _inside_ a class, struct, enum, or function body, use `@body`:
+- `class_Foo@body` + `append` → adds inside the class before `}`
+- `class_Foo@body` + `prepend` → adds inside the class after `{`
+- `class_Foo` + `append` → adds after the entire class (after `}`)
+</regions>
+
+<ops>
+|op|sel|effect|
+|---|---|---|
+|`replace`|`chunk#CRC(@region)?`|rewrite the addressed region|
+|`before`|`chunk(@region)?`|insert before the region span|
+|`after`|`chunk(@region)?`|insert after the region span|
+|`prepend`|`chunk(@region)?`|insert at the start inside the region|
+|`append`|`chunk(@region)?`|insert at the end inside the region|
+</ops>
+
+<examples>
+Given this `read` output for `example.ts`:
+```
+  | example.ts·34L·ts·#QBMH
+  |
+  | [<interface_Config#BWTR>]
+ 1| interface Config {
+  | 	[<interface_Config.field_host#TTMN>]
+ 2| 	host: string;
+  | 	[<interface_Config.field_port#QSMH>]
+ 3| 	port: number;
+  | 	[<interface_Config.field_debug#JPRR>]
+ 4| 	debug: boolean;
+ 5| }
+  |
+  | [<class_Counter#HZHY>]
+ 7| class Counter {
+  | 	[<class_Counter.field_value#QJBY>]
+ 8| 	value: number = 0;
+ 9|
+  | 	[<class_Counter.fn_increment#NQWY>]
+10| 	increment(): void {
+11| 		this.value += 1;
+12| 	}
+13|
+  | 	[<class_Counter.fn_decrement#PMBP>]
+14| 	decrement(): void {
+15| 		this.value -= 1;
+16| 	}
+17|
+  | 	[<class_Counter.fn_toString#ZQZP>]
+18| 	toString(): string {
+19| 		return `Counter(${this.value})`;
+20| 	}
+21| }
+  |
+  | [<enum_Status#HYQJ>]
+23| enum Status {
+  | 	[<enum_Status.variant_Active#PQNS>]
+24| 	Active = "ACTIVE",
+  | 	[<enum_Status.variant_Paused#HHNM>]
+25| 	Paused = "PAUSED",
+  | 	[<enum_Status.variant_Stopped#NHTY>]
+26| 	Stopped = "STOPPED",
+27| }
+  |
+  | [<fn_createCounter#PQQY>]
+29| function createCounter(initial: number): Counter {
+30| 	const counter = new Counter();
+31| 	counter.value = initial;
+32| 	return counter;
+33| }
+```
+
+**Replace a whole chunk** (rename a function):
+```
+{ "sel": "fn_createCounter#PQQY", "op": "replace", "content": "function makeCounter(start: number): Counter {\n const c = new Counter();\n c.value = start;\n return c;\n}\n" }
+```
+Result — the entire chunk is rewritten:
+```
+function makeCounter(start: number): Counter {
+  const c = new Counter();
+  c.value = start;
+  return c;
+}
+```
+
+**Replace a method body** (`@body`):
+```
+{ "sel": "class_Counter.fn_increment#NQWY@body", "op": "replace", "content": "this.value += 1;\nconsole.log('incremented to', this.value);\n" }
+```
+Result — only the body changes, signature and braces are kept:
+```
+  increment(): void {
+    this.value += 1;
+    console.log('incremented to', this.value);
+  }
+```
+
+**Replace a function header** (`@head` — signature and doc comment):
+```
+{ "sel": "fn_createCounter#PQQY@head", "op": "replace", "content": "/** Creates a counter with the given start value. */\nfunction createCounter(initial: number, label?: string): Counter {\n" }
+```
+Result — adds a doc comment and updates the signature, body untouched:
+```
+/** Creates a counter with the given start value. */
+function createCounter(initial: number, label?: string): Counter {
+  const counter = new Counter();
+  counter.value = initial;
+  return counter;
+}
+```
+
+**Insert before a chunk** (`before`):
+```
+{ "sel": "fn_createCounter", "op": "before", "content": "/** Factory function below. */\n" }
+```
+Result — a comment is inserted before the function:
+```
+/** Factory function below. */
+
+function createCounter(initial: number): Counter {
+```
+
+**Insert after a chunk** (`after`):
+```
+{ "sel": "enum_Status", "op": "after", "content": "\nfunction isActive(s: Status): boolean {\n return s === Status.Active;\n}\n" }
+```
+Result — a new function appears after the enum:
+```
+enum Status {
+  Active = "ACTIVE",
+  Paused = "PAUSED",
+  Stopped = "STOPPED",
+}
+
+function isActive(s: Status): boolean {
+  return s === Status.Active;
+}
+
+function createCounter(initial: number): Counter {
+```
+
+**Prepend inside a container** (`@body` + `prepend`):
+```
+{ "sel": "class_Counter@body", "op": "prepend", "content": "label: string = 'default';\n\n" }
+```
+Result — a new field is added at the top of the class body, before existing members:
+```
+class Counter {
+  label: string = 'default';
+
+  value: number = 0;
+```
+
+**Append inside a container** (`@body` + `append`):
+```
+{ "sel": "class_Counter@body", "op": "append", "content": "\nreset(): void {\n this.value = 0;\n}\n" }
+```
+Result — a new method is added at the end of the class body, before the closing `}`:
+```
+  toString(): string {
+    return `Counter(${this.value})`;
+  }
+
+  reset(): void {
+    this.value = 0;
+  }
+}
+```
+
+**Delete a chunk** (`replace` with empty content):
+```
+{ "sel": "class_Counter.fn_toString#ZQZP", "op": "replace", "content": "" }
+```
+Result — the method is removed from the class.
+- Indentation rules (important):
+  - Use one leading space for each indent level in canonical chunk-edit content. The tool expands those levels to the file's actual style (2-space, 4-space, tabs, etc.).
+  - Do NOT include the chunk's base indentation — only indent relative to the region's opening level.
+  - For `@body` of a function: write at column 0, e.g. `"return x;\n"`. The tool adds the correct base indent.
+  - For `@head`: write at the chunk's own depth. A class member's head uses `"/** doc */\nstart(): void {"`.
+  - For a top-level item: start at zero indent. Write `"function foo() {\n return 1;\n}\n"`.
+  - The tool strips common leading indentation from your content as a safety net, so accidental over-indentation is corrected.
+</examples>