@oh-my-pi/pi-agent-core 15.4.2 → 15.5.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [15.5.0] - 2026-05-26
+### Added
+
+- Added `approval` support to `AgentTool` declarations with the new `ToolTier` and `ToolApproval` APIs, allowing tools to declare capability tiers (`read`, `write`, or `exec`) and optional override/reason metadata for approval gating
+- Added `formatApprovalDetails` on `AgentTool` to append custom detail text or lines to approval prompts
+- Added exported `ToolTier` and `ToolApproval` type aliases for tool approval declarations
+
+### Fixed
+
+- Fixed chat-request telemetry storing the raw scoped `serviceTier` value (`"openai-only"`/`"claude-only"`) in `OpenAIAttr.RequestServiceTier` instead of the resolved wire value (`"priority"`). Dashboards and alerts filtering on the concrete tier name (`service_tier == "priority"`) were broken by the scoped placeholder; `buildChatRequestAttributes` now runs the tier through `resolveServiceTier(serviceTier, provider)` before recording, keeping the `shouldSendServiceTier` gate intact so non-OpenAI providers continue to omit the attribute entirely.
+
 ## [15.3.0] - 2026-05-25
 ### Fixed
 

package/dist/types/types.d.ts

@@ -311,6 +311,23 @@ export interface RenderResultOptions {
     /** Current spinner frame index for animated elements (optional) */
     spinnerFrame?: number;
 }
+/** Capability tier a tool exercises. Determines which approval modes auto-approve it. */
+export type ToolTier = "read" | "write" | "exec";
+/**
+ * Per-tool approval declaration.
+ * - bare tier ("read" / "write" / "exec") — static classification.
+ * - object form — adds a `reason` (shown in the prompt) and/or `override: true`
+ *   (force-prompt even in modes that would otherwise auto-approve this tier).
+ * - function — dynamic, given parsed args. Returns either form above.
+ *
+ * Omitted approvals are treated as "exec" by callers that enforce approvals.
+ */
+export type ToolApprovalDecision = ToolTier | {
+    tier: ToolTier;
+    reason?: string;
+    override?: boolean;
+};
+export type ToolApproval = ToolApprovalDecision | ((args: unknown) => ToolApprovalDecision);
 /**
  * Context passed to tool execution.
  * Apps can extend via declaration merging.
@@ -346,6 +363,10 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
      * - function: `_i` is NOT injected; intent is derived dynamically from (potentially partial / streaming) args.
      */
     intent?: "omit" | "optional" | "require" | ((args: Partial<Static<TParameters>>) => string | undefined);
+    /** Capability tier declaration used by approval gates. Omitted means "exec". */
+    approval?: ToolApproval;
+    /** Lines appended after the standard approval prompt header. */
+    formatApprovalDetails?: (args: unknown) => string | string[] | undefined;
     /** The main execution callback for this tool. */
     execute: AgentToolExecFn<TParameters, TDetails, TTheme>;
     /** Optional custom rendering for tool call display (returns UI component) */

package/dist/types/utils/yield.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cooperative yield utility for preventing Bun event-loop busy-wait.
+ *
+ * Bun 1.3.x (JavaScriptCore) does not automatically yield to the kernel when
+ * the microtask queue is continuously non-empty.  In long-running agent loops
+ * (LLM streaming, tool execution) this causes ~100% CPU usage even when the
+ * process is simply waiting for I/O.
+ *
+ * `yieldIfDue()` uses a compensated sleep that retries `scheduler.wait()`
+ * until the requested wall-clock duration has actually elapsed.  This is
+ * necessary because napi callbacks (e.g. `Shell.run` chunk callbacks via
+ * `uv_async_send`) can wake the event loop prematurely, causing the timer
+ * to return after only ~1–2 ms regardless of the requested duration.
+ *
+ * The minimum effective sleep is ~20 ms per yield; at ~30 yield calls/second
+ * this gives 600 ms/second of kernel sleep → ~40% CPU under active load.
+ */
+/**
+ * Yield to the Bun event loop, sleeping for at least 20 ms — but at most
+ * once every {@link YIELD_INTERVAL_MS}. Callers in hot paths can invoke
+ * this freely; only the slow path actually sleeps.
+ */
+export declare function yieldIfDue(): Promise<void>;
+export declare class ExponentialYield {
+    #private;
+    constructor(opts?: {
+        minMs?: number;
+        maxMs?: number;
+        multiplier?: number;
+    });
+    notifyActivity(): void;
+    sleep(signal?: AbortSignal): Promise<number>;
+    /**
+     * Race `racers` against an exponentially-backed-off cooperative yield.
+     * The losing sleep is cancelled as soon as a racer settles, so no stray
+     * timers keep the event loop alive past the racer's resolution.
+     */
+    race<T>(racers: Array<Promise<T>>): Promise<T>;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "15.4.2",
+	"version": "15.5.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,9 +35,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "15.4.2",
-		"@oh-my-pi/pi-natives": "15.4.2",
-		"@oh-my-pi/pi-utils": "15.4.2",
+		"@oh-my-pi/pi-ai": "15.5.0",
+		"@oh-my-pi/pi-natives": "15.5.0",
+		"@oh-my-pi/pi-utils": "15.5.0",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -48,6 +48,7 @@ import type {
 	AgentToolResult,
 	StreamFn,
 } from "./types";
+import { yieldIfDue } from "./utils/yield";
 
 /** Sentinel returned by the abort race in `streamAssistantResponse`. */
 const ABORTED: unique symbol = Symbol("agent-loop-aborted");
@@ -463,6 +464,9 @@ async function runLoopBody(
 
 		// Inner loop: process tool calls and steering messages
 		while (hasMoreToolCalls || pendingMessages.length > 0) {
+			// Yield at the top of each iteration to prevent busy-wait when
+			// the agent loop is executing tool calls back-to-back.
+			await yieldIfDue();
 			if (!firstTurn) {
 				stream.push({ type: "turn_start" });
 			} else {
@@ -785,6 +789,9 @@ async function streamAssistantResponse(
 					if (next.done) break;
 
 					const event = next.value;
+					// Yield to the event loop periodically to prevent busy-wait
+					// when the LLM is streaming chunks faster than the loop can rest.
+					await yieldIfDue();
 
 					switch (event.type) {
 						case "start":
@@ -1208,6 +1215,9 @@ async function executeToolCalls(
 	}
 
 	await Promise.allSettled(tasks);
+	// Yield after batch tool execution to let GC and I/O catch up,
+	// especially when tool results are large (e.g. bash output).
+	await yieldIfDue();
 
 	for (const record of records) {
 		if (!record.toolResultMessage) {

package/src/telemetry.ts

@@ -30,6 +30,7 @@ import {
 	completeSimple,
 	type Message,
 	type Model,
+	resolveServiceTier,
 	type ServiceTier,
 	type SimpleStreamOptions,
 	type StopReason,
@@ -749,7 +750,8 @@ function buildChatRequestAttributes(stepNumber: number, request: ChatRequestSnap
 		attrs[GenAIAttr.RequestStopSequences] = [...request.stopSequences];
 	}
 	if (request.serviceTier && shouldSendServiceTier(request.serviceTier, provider)) {
-		attrs[OpenAIAttr.RequestServiceTier] = request.serviceTier;
+		const resolved = resolveServiceTier(request.serviceTier, provider);
+		if (resolved) attrs[OpenAIAttr.RequestServiceTier] = resolved;
 	}
 	if (request.reasoningEffort) attrs[PiGenAIAttr.RequestReasoningEffort] = request.reasoningEffort;
 	const toolChoice = serializeToolChoice(request.toolChoice);

package/src/types.ts

@@ -369,6 +369,21 @@ export interface RenderResultOptions {
 	spinnerFrame?: number;
 }
 
+/** Capability tier a tool exercises. Determines which approval modes auto-approve it. */
+export type ToolTier = "read" | "write" | "exec";
+
+/**
+ * Per-tool approval declaration.
+ * - bare tier ("read" / "write" / "exec") — static classification.
+ * - object form — adds a `reason` (shown in the prompt) and/or `override: true`
+ *   (force-prompt even in modes that would otherwise auto-approve this tier).
+ * - function — dynamic, given parsed args. Returns either form above.
+ *
+ * Omitted approvals are treated as "exec" by callers that enforce approvals.
+ */
+export type ToolApprovalDecision = ToolTier | { tier: ToolTier; reason?: string; override?: boolean };
+export type ToolApproval = ToolApprovalDecision | ((args: unknown) => ToolApprovalDecision);
+
 /**
  * Context passed to tool execution.
  * Apps can extend via declaration merging.
@@ -418,6 +433,12 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
 	 */
 	intent?: "omit" | "optional" | "require" | ((args: Partial<Static<TParameters>>) => string | undefined);
 
+	/** Capability tier declaration used by approval gates. Omitted means "exec". */
+	approval?: ToolApproval;
+
+	/** Lines appended after the standard approval prompt header. */
+	formatApprovalDetails?: (args: unknown) => string | string[] | undefined;
+
 	/** The main execution callback for this tool. */
 	execute: AgentToolExecFn<TParameters, TDetails, TTheme>;
 

package/src/utils/yield.ts

@@ -0,0 +1,120 @@
+/**
+ * Cooperative yield utility for preventing Bun event-loop busy-wait.
+ *
+ * Bun 1.3.x (JavaScriptCore) does not automatically yield to the kernel when
+ * the microtask queue is continuously non-empty.  In long-running agent loops
+ * (LLM streaming, tool execution) this causes ~100% CPU usage even when the
+ * process is simply waiting for I/O.
+ *
+ * `yieldIfDue()` uses a compensated sleep that retries `scheduler.wait()`
+ * until the requested wall-clock duration has actually elapsed.  This is
+ * necessary because napi callbacks (e.g. `Shell.run` chunk callbacks via
+ * `uv_async_send`) can wake the event loop prematurely, causing the timer
+ * to return after only ~1–2 ms regardless of the requested duration.
+ *
+ * The minimum effective sleep is ~20 ms per yield; at ~30 yield calls/second
+ * this gives 600 ms/second of kernel sleep → ~40% CPU under active load.
+ */
+
+import { scheduler } from "node:timers/promises";
+
+const YIELD_SLEEP_MS = 20;
+const YIELD_INTERVAL_MS = 50;
+
+/**
+ * Wall-clock timestamp of the last completed yield. Module-level so that
+ * tight loops sharing this helper collectively respect the gate, not just
+ * one caller at a time.
+ */
+let lastYieldAt = 0;
+
+/**
+ * Sleep for at least `ms` milliseconds of wall-clock time.
+ * Retries the wait if it returns prematurely (which can happen when napi
+ * callbacks wake the event loop via `uv_async_send`). When `signal` is
+ * provided, the wait is cancellable and silently returns on abort instead
+ * of throwing — callers race against another promise that decides what to
+ * do next.
+ */
+async function sleepAtLeast(ms: number, signal?: AbortSignal): Promise<void> {
+	const start = performance.now();
+	let remaining = ms;
+	while (remaining > 0) {
+		if (signal?.aborted) return;
+		try {
+			await scheduler.wait(remaining, { signal });
+		} catch (err) {
+			if ((err as { name?: string })?.name === "AbortError") return;
+			throw err;
+		}
+		remaining = ms - (performance.now() - start);
+	}
+}
+
+/**
+ * Yield to the Bun event loop, sleeping for at least 20 ms — but at most
+ * once every {@link YIELD_INTERVAL_MS}. Callers in hot paths can invoke
+ * this freely; only the slow path actually sleeps.
+ */
+export async function yieldIfDue(): Promise<void> {
+	const now = Date.now();
+	if (now - lastYieldAt < YIELD_INTERVAL_MS) return;
+	await sleepAtLeast(YIELD_SLEEP_MS);
+	lastYieldAt = Date.now();
+}
+
+// --- ExponentialYield ---
+
+const EXP_DEFAULT_MIN_MS = 20;
+const EXP_DEFAULT_MAX_MS = 10_000;
+const EXP_DEFAULT_MULTIPLIER = 2;
+
+export class ExponentialYield {
+	#currentMs: number;
+	readonly #minMs: number;
+	readonly #maxMs: number;
+	readonly #multiplier: number;
+
+	constructor(opts?: { minMs?: number; maxMs?: number; multiplier?: number }) {
+		this.#minMs = opts?.minMs ?? EXP_DEFAULT_MIN_MS;
+		this.#maxMs = opts?.maxMs ?? EXP_DEFAULT_MAX_MS;
+		this.#multiplier = opts?.multiplier ?? EXP_DEFAULT_MULTIPLIER;
+		this.#currentMs = this.#minMs;
+	}
+
+	notifyActivity(): void {
+		this.#currentMs = this.#minMs;
+	}
+
+	async sleep(signal?: AbortSignal): Promise<number> {
+		const ms = this.#currentMs;
+		await sleepAtLeast(ms, signal);
+		this.#currentMs = Math.min(this.#currentMs * this.#multiplier, this.#maxMs);
+		return ms;
+	}
+
+	/**
+	 * Race `racers` against an exponentially-backed-off cooperative yield.
+	 * The losing sleep is cancelled as soon as a racer settles, so no stray
+	 * timers keep the event loop alive past the racer's resolution.
+	 */
+	async race<T>(racers: Array<Promise<T>>): Promise<T> {
+		const racer = Promise.race(racers);
+		const controller = new AbortController();
+		try {
+			const yieldMarker = Symbol("exp-yield");
+			for (;;) {
+				const result = await Promise.race<T | typeof yieldMarker>([
+					racer,
+					this.sleep(controller.signal).then(() => yieldMarker as T | typeof yieldMarker),
+				]);
+				if (result !== yieldMarker) {
+					this.notifyActivity();
+					return result;
+				}
+			}
+		} finally {
+			controller.abort();
+		}
+	}
+}