@oh-my-pi/pi-coding-agent 15.8.2 → 15.9.0

package/src/task/index.ts

@@ -41,6 +41,7 @@ import {
 // Import review tools for side effects (registers subagent tool handlers)
 import "../tools/review";
 import type { LocalProtocolOptions } from "../internal-urls";
+import { loadOverallPlanReference } from "../plan-mode/plan-handoff";
 import { generateCommitMessage } from "../utils/commit-message-generator";
 import * as git from "../utils/git";
 import { discoverAgents, getAgent } from "./discovery";
@@ -131,6 +132,37 @@ export {
 	taskSchema,
 } from "./types";
 
+// Built-in tools whose approval tier is "read" (see tool classes' `approval`).
+// An agent is read-only iff its declared tools are a non-empty subset of this set.
+// Fail-safe: any unknown tool makes the agent not read-only.
+export const READ_ONLY_TOOL_NAMES: ReadonlySet<string> = new Set([
+	"read",
+	"search",
+	"find",
+	"web_search",
+	"ast_grep",
+	"yield",
+	"irc",
+	"ask",
+	"job",
+	"todo",
+	"recall",
+	"reflect",
+	"retain",
+	"memory_edit",
+	"render_mermaid",
+	"inspect_image",
+	"checkpoint",
+	"rewind",
+	"resolve",
+	"report_finding",
+	"search_tool_bm25",
+]);
+
+export function isReadOnlyAgent(agent: AgentDefinition): boolean {
+	return !!agent.tools?.length && agent.tools.every(tool => READ_ONLY_TOOL_NAMES.has(tool));
+}
+
 /**
  * Render the tool description from a cached agent list and current settings.
  */
@@ -157,9 +189,14 @@ function renderDescription(
 		);
 		filteredAgents = filteredAgents.filter(a => allowed.has(a.name));
 	}
+	const renderedAgents = filteredAgents.map(agent => ({
+		name: agent.name,
+		description: agent.description,
+		readOnly: isReadOnlyAgent(agent),
+	}));
 	const { contextEnabled, customSchemaEnabled } = getTaskSimpleModeCapabilities(simpleMode);
 	return prompt.render(taskDescriptionTemplate, {
-		agents: filteredAgents,
+		agents: renderedAgents,
 		spawningDisabled,
 		MAX_CONCURRENCY: maxConcurrency,
 		isolationEnabled,
@@ -772,6 +809,17 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		// across the whole tree and outputs land flat in the parent's dir.
 		const parentArtifactManager = this.session.getArtifactManager?.() ?? undefined;
 
+		// When the session is executing an approved plan, hand the overall plan to
+		// every subagent so they share the main agent's plan context. Skipped in
+		// plan mode (read-only exploration uses planModeSubagentPrompt instead) and
+		// when no plan file exists at the session's reference path.
+		const planReference = planModeState?.enabled
+			? undefined
+			: await loadOverallPlanReference(
+					this.session.getPlanReferencePath?.() ?? "local://PLAN.md",
+					localProtocolOptions,
+				);
+
 		// Initialize progress tracking
 		const progressMap = new Map<number, AgentProgress>();
 
@@ -898,6 +946,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						task: renderSubagentUserPrompt(task.assignment, simpleMode),
 						assignment: task.assignment.trim(),
 						context: sharedContext,
+						planReference,
 						description: task.description,
 						index,
 						id: task.id,
@@ -955,6 +1004,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						task: renderSubagentUserPrompt(task.assignment, simpleMode),
 						assignment: task.assignment.trim(),
 						context: sharedContext,
+						planReference,
 						description: task.description,
 						index,
 						id: task.id,

package/src/telemetry-export.ts

@@ -0,0 +1,126 @@
+/**
+ * OTLP trace export bootstrap.
+ *
+ * oh-my-pi's agent core (`@oh-my-pi/pi-agent-core`) emits OpenTelemetry GenAI
+ * spans through the global `@opentelemetry/api` tracer, but only when a
+ * TracerProvider is registered in the process — otherwise the API returns a
+ * no-op tracer and the spans are silently dropped. The shipped CLI never
+ * registered one, so headless / embedded hosts (e.g. an ACP harness that
+ * spawns `omp` as a child process) had no way to collect omp's internal traces.
+ *
+ * This module registers a NodeTracerProvider with an OTLP/proto exporter when
+ * the standard `OTEL_EXPORTER_OTLP_ENDPOINT` (or `..._TRACES_ENDPOINT`) env var
+ * is set, following the zero-code OTEL env contract: the exporter reads its
+ * endpoint, headers, and timeout from `OTEL_EXPORTER_OTLP_*` itself. The
+ * consuming process configures the destination entirely through env; omp stays
+ * provider-agnostic and ships no vendor coupling. Only the `http/protobuf`
+ * transport is supported — an `OTEL_EXPORTER_OTLP*_PROTOCOL` of `grpc` or
+ * `http/json` declines rather than misrouting spans.
+ *
+ * The OTLP/proto exporter on the 2.x line is used deliberately: the 1.x line
+ * deadlocks under Bun — its `req.on('close')` handler fires a spurious failure
+ * after the success path. `exporter-trace-otlp-proto@0.218` paired with
+ * `sdk-trace-base@2.7` exports cleanly on Bun.
+ */
+import { logger, postmortem } from "@oh-my-pi/pi-utils";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+
+/**
+ * Periodic flush interval. A long-lived `omp` process (the ACP server is
+ * spawned once and reused across many turns) would otherwise hold finished
+ * spans until the batch window elapses or the process exits.
+ */
+const FLUSH_INTERVAL_MS = 30_000;
+
+let provider: NodeTracerProvider | undefined;
+
+/**
+ * Whether {@link initTelemetryExport} registered a real provider. The CLI uses
+ * this to decide whether to switch on the agent loop's telemetry config — there
+ * is no point emitting spans into a no-op tracer.
+ */
+export function isTelemetryExportEnabled(): boolean {
+	return provider !== undefined;
+}
+
+/**
+ * Register the global TracerProvider + OTLP exporter when an OTLP endpoint is
+ * configured via env. Idempotent, and a no-op when no endpoint is set (or when
+ * the OTEL kill-switches are engaged), so it is safe to call unconditionally at
+ * startup.
+ */
+export function initTelemetryExport(): void {
+	if (provider) return;
+	// The OTEL env contract parses booleans and enum lists case-insensitively, so
+	// OTEL_SDK_DISABLED=TRUE and OTEL_TRACES_EXPORTER=None must also disable export.
+	if (process.env.OTEL_SDK_DISABLED?.trim().toLowerCase() === "true") return;
+	if (tracesExporterDisabled(process.env.OTEL_TRACES_EXPORTER)) return;
+
+	const endpoint = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+	if (!endpoint) return;
+
+	// We only ship the http/protobuf transport (the line validated on Bun). The
+	// OTEL contract lets OTEL_EXPORTER_OTLP*_PROTOCOL select grpc / http/json;
+	// rather than silently send protobuf-over-HTTP to a grpc :4317 port and lose
+	// every span, decline when an unsupported protocol is requested.
+	const protocol = (process.env.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL ?? process.env.OTEL_EXPORTER_OTLP_PROTOCOL)
+		?.trim()
+		.toLowerCase();
+	if (protocol && protocol !== "http/protobuf") {
+		logger.warn(
+			`OTEL trace export disabled: OTEL_EXPORTER_OTLP_PROTOCOL=${protocol} is unsupported (only http/protobuf)`,
+		);
+		return;
+	}
+
+	// The exporter reads endpoint/headers/timeout from OTEL_EXPORTER_OTLP_* itself,
+	// so there is nothing to thread through here.
+	const exporter = new OTLPTraceExporter();
+	const tracerProvider = new NodeTracerProvider({
+		resource: resourceFromAttributes({
+			"service.name": process.env.OTEL_SERVICE_NAME ?? "oh-my-pi",
+		}),
+		spanProcessors: [new BatchSpanProcessor(exporter)],
+	});
+	// register() installs the global tracer provider and the W3C trace-context +
+	// baggage propagators; the explicit AsyncLocalStorage context manager keeps
+	// parent/child span linkage working under Bun.
+	tracerProvider.register({ contextManager: new AsyncLocalStorageContextManager().enable() });
+	provider = tracerProvider;
+
+	const flushTimer = setInterval(() => {
+		provider?.forceFlush().catch(() => {});
+	}, FLUSH_INTERVAL_MS);
+	flushTimer.unref();
+
+	// Shut down through postmortem rather than a bare signal listener. postmortem
+	// owns SIGINT/SIGTERM/SIGHUP/exit and quit(), and awaits registered cleanups
+	// before calling process.exit — so the batch processor's final OTLP export
+	// completes instead of being cut off mid-flight on the shutdown path.
+	postmortem.register("otel-trace-export", async () => {
+		clearInterval(flushTimer);
+		await provider?.shutdown();
+	});
+}
+
+/**
+ * Parse the `OTEL_TRACES_EXPORTER` selection. The value is a case-insensitive,
+ * comma-separated list; the literal `none` disables span export entirely.
+ */
+function tracesExporterDisabled(raw: string | undefined): boolean {
+	if (!raw) return false;
+	return raw.split(",").some(entry => entry.trim().toLowerCase() === "none");
+}
+
+/**
+ * Flush any buffered spans to the exporter. No-op when export is disabled.
+ * Hosts embedding the agent can call this at natural boundaries (e.g. the end
+ * of a turn) so traces surface promptly rather than on the batch interval.
+ */
+export async function flushTelemetryExport(): Promise<void> {
+	await provider?.forceFlush();
+}

package/src/tiny/compiled-runtime.ts

@@ -0,0 +1,179 @@
+import * as fs from "node:fs";
+import * as Module from "node:module";
+import * as path from "node:path";
+
+/**
+ * Bun's compiled-binary module resolver only finds `<pkg>/index.js` for bare
+ * specifiers loaded from the *real* filesystem — it ignores `main`/`exports`
+ * (issue #1763). The tiny-model Transformers.js runtime is `bun install`ed into
+ * a cache directory at runtime, and its graph (`@huggingface/transformers` →
+ * `onnxruntime-node` → `onnxruntime-common`, plus an eager `require("sharp")`)
+ * all point `main`/`exports` at nested files, so the stock resolver cannot load
+ * any of them. We patch `Module._resolveFilename` to resolve those bare
+ * specifiers against the cache ourselves, honoring `main`/`exports`.
+ *
+ * This module is filesystem-pure aside from {@link installRuntimeModuleResolver}
+ * mutating the `node:module` resolver, so the resolution logic is unit-testable
+ * without a compiled binary.
+ */
+
+/** Conditions honored when resolving an `exports` map for a CommonJS `require`. */
+const RUNTIME_CONDITIONS: Record<string, true> = { node: true, require: true, default: true };
+
+/** Extension probes appended to a `main`/`exports` target that lacks one. */
+const RUNTIME_EXTENSIONS: readonly string[] = [".js", ".cjs", ".mjs", ".json", ".node"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Walk a conditional `exports` target (string, array of fallbacks, or a
+ * condition object) and return the first relative path that matches a runtime
+ * condition in declaration order. Returns `null` when nothing applies (e.g.
+ * `import`-only targets).
+ */
+export function selectConditionalTarget(target: unknown): string | null {
+	if (typeof target === "string") return target;
+	if (Array.isArray(target)) {
+		for (const entry of target) {
+			const resolved = selectConditionalTarget(entry);
+			if (resolved) return resolved;
+		}
+		return null;
+	}
+	if (isRecord(target)) {
+		for (const condition in target) {
+			if (!RUNTIME_CONDITIONS[condition]) continue;
+			const resolved = selectConditionalTarget(target[condition]);
+			if (resolved) return resolved;
+		}
+	}
+	return null;
+}
+
+/** Resolve a relative target inside a package to a concrete file path, probing extensions and `index`. */
+function resolveFileTarget(pkgDir: string, relative: string): string | null {
+	const base = path.join(pkgDir, relative);
+	const candidates = [base, ...RUNTIME_EXTENSIONS.map(ext => base + ext)];
+	for (const candidate of candidates) {
+		try {
+			const stat = fs.statSync(candidate);
+			if (stat.isFile()) return candidate;
+			if (stat.isDirectory()) {
+				const indexed = resolveFileTarget(candidate, "index");
+				if (indexed) return indexed;
+			}
+		} catch {
+			// missing candidate — keep probing
+		}
+	}
+	return null;
+}
+
+function resolveExportsEntry(
+	pkgDir: string,
+	exports: Record<string, unknown>,
+	subpath: string | undefined,
+): string | null {
+	let subpathMap = false;
+	for (const key in exports) {
+		subpathMap = key === "." || key.startsWith("./");
+		break;
+	}
+	if (subpathMap) {
+		const key = subpath ? `./${subpath}` : ".";
+		if (!(key in exports)) return null;
+		const target = selectConditionalTarget(exports[key]);
+		return target ? resolveFileTarget(pkgDir, target) : null;
+	}
+	// A bare condition map only describes the package root, so a subpath
+	// request falls through to plain path joining at the call site.
+	if (subpath) return null;
+	const target = selectConditionalTarget(exports);
+	return target ? resolveFileTarget(pkgDir, target) : null;
+}
+
+/**
+ * Split a bare specifier into its package name and optional subpath, handling
+ * scoped packages (`@scope/name/sub` → `@scope/name` + `sub`).
+ */
+export function splitBareSpecifier(specifier: string): { packageName: string; subpath: string | undefined } {
+	const segments = specifier.split("/");
+	const take = specifier.startsWith("@") ? 2 : 1;
+	const packageName = segments.slice(0, take).join("/");
+	const subpath = segments.length > take ? segments.slice(take).join("/") : undefined;
+	return { packageName, subpath };
+}
+
+/**
+ * Resolve a bare specifier against an installed `node_modules` directory,
+ * honoring `exports` (CommonJS conditions), then `main`, then `index.js`.
+ * Returns an absolute file path, or `null` when the package/entry is absent.
+ */
+export function resolveRuntimeModule(runtimeNodeModules: string, specifier: string): string | null {
+	const { packageName, subpath } = splitBareSpecifier(specifier);
+	const pkgDir = path.join(runtimeNodeModules, ...packageName.split("/"));
+	const manifest = readManifest(pkgDir);
+	if (!manifest) return subpath ? resolveFileTarget(pkgDir, subpath) : null;
+
+	const { exports } = manifest;
+	if (typeof exports === "string" || isRecord(exports)) {
+		const map = typeof exports === "string" ? { ".": exports } : exports;
+		const resolved = resolveExportsEntry(pkgDir, map, subpath);
+		if (resolved) return resolved;
+	}
+	if (subpath) return resolveFileTarget(pkgDir, subpath);
+	if (typeof manifest.main === "string") {
+		const resolved = resolveFileTarget(pkgDir, manifest.main);
+		if (resolved) return resolved;
+	}
+	return resolveFileTarget(pkgDir, "index.js");
+}
+
+function readManifest(pkgDir: string): Record<string, unknown> | null {
+	try {
+		const parsed: unknown = JSON.parse(fs.readFileSync(path.join(pkgDir, "package.json"), "utf8"));
+		return isRecord(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+
+interface ModuleResolver {
+	_resolveFilename(request: string, parent: unknown, isMain: boolean, options?: unknown): string;
+}
+
+const PATCHED = Symbol.for("omp.tiny.compiledRuntimeResolver");
+
+interface ResolverOptions {
+	/** Absolute path to the runtime cache's `node_modules`. */
+	runtimeNodeModules: string;
+	/** Bare specifier → absolute file path overrides (e.g. `sharp` → no-op stub). */
+	stubs?: Record<string, string>;
+}
+
+/**
+ * Patch `node:module`'s resolver (idempotently) so bare specifiers that the
+ * stock compiled-binary resolver cannot find fall back to the runtime cache.
+ * Stock resolution is tried first, so this never changes behavior for modules
+ * that already resolve (the worker's own bundled imports, node builtins).
+ */
+export function installRuntimeModuleResolver({ runtimeNodeModules, stubs = {} }: ResolverOptions): void {
+	const resolver = (Module as unknown as { default?: ModuleResolver } & ModuleResolver).default ?? Module;
+	const target = resolver as unknown as ModuleResolver & { [PATCHED]?: boolean };
+	if (target[PATCHED]) return;
+	const original = target._resolveFilename.bind(target);
+	target._resolveFilename = (request: string, parent: unknown, isMain: boolean, options?: unknown): string => {
+		try {
+			return original(request, parent, isMain, options);
+		} catch (error) {
+			const stub = stubs[request];
+			if (stub) return stub;
+			const resolved = resolveRuntimeModule(runtimeNodeModules, request);
+			if (resolved) return resolved;
+			throw error;
+		}
+	};
+	target[PATCHED] = true;
+}

package/src/tiny/worker.ts

@@ -10,6 +10,7 @@ import type {
 import { getTinyModelsCacheDir, isCompiledBinary, prompt } from "@oh-my-pi/pi-utils";
 import packageJson from "../../package.json" with { type: "json" };
 import tinyTitleSystemPrompt from "../prompts/system/tiny-title-system.md" with { type: "text" };
+import { installRuntimeModuleResolver, resolveRuntimeModule } from "./compiled-runtime";
 import { resolveTinyModelDevicePreference, type TinyModelDevice, tinyModelDeviceLoadOrder } from "./device";
 import { resolveTinyModelDtypeOverride, type TinyModelDtype } from "./dtype";
 import {
@@ -28,6 +29,7 @@ const STOP_DECODE_WINDOW_TOKENS = 32;
 const MEMORY_COMPLETION_MAX_NEW_TOKENS = 256;
 const TINY_TITLE_SYSTEM_PROMPT = prompt.render(tinyTitleSystemPrompt);
 const TRANSFORMERS_PACKAGE = "@huggingface/transformers";
+const COMPILED_TRANSFORMERS_VERSION = process.env.PI_TINY_TRANSFORMERS_VERSION;
 const sourceRequire = createRequire(import.meta.url);
 const INSTALL_LOCK_ATTEMPTS = 240;
 const INSTALL_LOCK_SLEEP_MS = 250;
@@ -67,6 +69,7 @@ function resolveTransformersVersionSpec(): string {
 		manifest.optionalDependencies?.[TRANSFORMERS_PACKAGE] ?? manifest.dependencies?.[TRANSFORMERS_PACKAGE];
 	if (!versionSpec) throw new Error(`${TRANSFORMERS_PACKAGE} is missing from package.json optionalDependencies`);
 	if (!versionSpec.startsWith("catalog:")) return versionSpec;
+	if (COMPILED_TRANSFORMERS_VERSION) return COMPILED_TRANSFORMERS_VERSION;
 	const installed = sourceRequire(`${TRANSFORMERS_PACKAGE}/package.json`) as { version: string };
 	return installed.version;
 }
@@ -117,6 +120,7 @@ function getTinyTitleRuntimeDir(): string {
 
 async function acquireInstallLock(runtimeDir: string): Promise<() => Promise<void>> {
 	const lockDir = `${runtimeDir}.lock`;
+	await fs.mkdir(path.dirname(lockDir), { recursive: true });
 	for (let attempt = 0; attempt < INSTALL_LOCK_ATTEMPTS; attempt++) {
 		try {
 			await fs.mkdir(lockDir);
@@ -216,6 +220,23 @@ async function ensureCompiledTransformersRuntime(
 	}
 }
 
+/**
+ * Prepare the freshly-installed compiled runtime for loading: stub `sharp`
+ * (the tiny models are text-generation only, so the native image pipeline is
+ * dead weight) and patch the module resolver so Transformers.js's bare requires
+ * (`onnxruntime-node`, `onnxruntime-common`) resolve against the cache. Returns
+ * the absolute Transformers.js entrypoint to `require`.
+ */
+async function prepareCompiledRuntime(runtimeDir: string): Promise<string> {
+	const nodeModules = path.join(runtimeDir, "node_modules");
+	const sharpStub = path.join(runtimeDir, "omp-sharp-stub.cjs");
+	await Bun.write(sharpStub, "module.exports = {};\n");
+	installRuntimeModuleResolver({ runtimeNodeModules: nodeModules, stubs: { sharp: sharpStub } });
+	const entry = resolveRuntimeModule(nodeModules, TRANSFORMERS_PACKAGE);
+	if (!entry) throw new Error(`Unable to resolve ${TRANSFORMERS_PACKAGE} in compiled runtime at ${nodeModules}`);
+	return entry;
+}
+
 function configureTransformers(transformers: TransformersRuntime): TransformersRuntime {
 	transformers.env.cacheDir = getTinyModelsCacheDir();
 	transformers.env.allowLocalModels = false;
@@ -232,8 +253,9 @@ async function loadTransformers(
 	transformersRuntime = (async () => {
 		if (!isCompiledBinary()) return configureTransformers(sourceRequire(TRANSFORMERS_PACKAGE) as TransformersRuntime);
 		const runtimeDir = await ensureCompiledTransformersRuntime(transport, requestId, modelKey);
-		const require_ = createRequire(path.join(runtimeDir, "package.json"));
-		return configureTransformers(require_(TRANSFORMERS_PACKAGE) as TransformersRuntime);
+		const entry = await prepareCompiledRuntime(runtimeDir);
+		const require_ = createRequire(entry);
+		return configureTransformers(require_(entry) as TransformersRuntime);
 	})().catch(error => {
 		transformersRuntime = null;
 		throw error;