@oh-my-pi/pi-agent-core 16.1.15 → 16.1.17

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [16.1.17] - 2026-06-24
+
+### Fixed
+
+- Hardened the agent-loop cooperative yield against backward wall-clock jumps. A stale future timestamp left in the shared yield gate (NTP step, or a fake-timer test mocking `Date.now`) could make `yieldIfDue()` gate forever and stop yielding to the event loop; the gate now treats a backward clock delta as due and re-anchors. The gate is exposed as an injectable `YieldGate` (with `yieldIfDue()` retained as the shared singleton) so it can be exercised without mocking process-global timers.
+
+## [16.1.16] - 2026-06-23
+
+### Added
+
+- Added `generateHandoffFromContext(context, model, options)` to `@oh-my-pi/pi-agent-core/compaction`: runs the handoff oneshot against a fully-built provider `Context` (system prompt, normalized tools, transformed history, trailing handoff prompt) with `streamOptions` mirroring the live turn's cache routing, so a host that owns the transform pipeline can make the handoff request share the prompt cache the main turn populated. `generateHandoff(messages, …)` is unchanged and now delegates to it.
+- Added an optional `systemPrompt` argument to `Agent.buildSideRequestContext(llmMessages, systemPrompt?)`, defaulting to the live agent prompt; callers can pin a different prompt (e.g. handoff generation, which uses the base prompt rather than a per-turn `before_agent_start` hook override).
+
+### Changed
+
+- Updated `buildSideRequestContext` to allow pinning custom system prompts
+
 ## [16.1.10] - 2026-06-21
 
 ### Fixed

package/dist/types/agent.d.ts

@@ -329,8 +329,13 @@ export declare class Agent {
      * in-band dialect sessions stay tools-less (matching their no-native-tools wire
      * shape and avoiding tool-markup leakage). `llmMessages` is already converted
      * (and, in production, obfuscated) by the caller.
+     *
+     * `systemPrompt` defaults to the live agent prompt so the side request hits the
+     * same cached prefix as the main loop. Callers that must pin a different prompt
+     * (e.g. handoff generation, which uses the base prompt rather than a per-turn
+     * `before_agent_start` hook override) pass it explicitly.
      */
-    buildSideRequestContext(llmMessages: Message[]): Promise<Context>;
+    buildSideRequestContext(llmMessages: Message[], systemPrompt?: string[]): Promise<Context>;
     subscribe(fn: (e: AgentEvent) => void): () => void;
     setProviderResponseInterceptor(fn: SimpleStreamOptions["onResponse"] | undefined): void;
     setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void;

package/dist/types/compaction/compaction.d.ts

@@ -4,7 +4,7 @@
  * Pure functions for compaction logic. The session manager handles I/O,
  * and after compaction the session is reloaded.
  */
-import { type ApiKey, type FetchImpl, type MessageAttribution, type Model, type Tool, type Usage } from "@oh-my-pi/pi-ai";
+import { type ApiKey, type Context, type FetchImpl, type MessageAttribution, type Model, type SimpleStreamOptions, type Tool, type Usage } from "@oh-my-pi/pi-ai";
 import { type AgentTelemetry } from "../telemetry";
 import { ThinkingLevel } from "../thinking";
 import type { AgentMessage } from "../types";
@@ -177,6 +177,35 @@ export interface HandoffOptions {
     thinkingLevel?: ThinkingLevel;
 }
 export declare function renderHandoffPrompt(customInstructions?: string): string;
+export interface HandoffFromContextOptions {
+    /**
+     * Stream options mirrored from the live agent turn: `apiKey`, `signal`, the
+     * `sessionId`/`promptCacheKey` cache-routing pair, `serviceTier`, and the
+     * session's payload/response hooks. Sending the same routing + payload shape
+     * the main loop uses is what lets the handoff oneshot READ the provider
+     * prompt cache the live turn populated instead of cold-missing the whole
+     * prefix. `reasoning` and `toolChoice` are set internally and override
+     * anything provided here.
+     */
+    streamOptions: SimpleStreamOptions;
+    /** See {@link HandoffOptions.telemetry}. */
+    telemetry?: AgentTelemetry;
+    /** See {@link HandoffOptions.thinkingLevel}. */
+    thinkingLevel?: ThinkingLevel;
+}
+/**
+ * Run the handoff oneshot against a fully-built provider {@link Context}.
+ *
+ * The caller assembles `context` exactly like a live agent turn — same system
+ * prompt, normalized tools, transformed + obfuscated message history, with the
+ * trailing handoff-prompt message already appended — and supplies
+ * `streamOptions` that mirror the live turn's cache routing. That keeps the
+ * cache-preserving context construction in the host (which owns the transform
+ * pipeline) while this function centralizes the handoff request contract:
+ * `toolChoice: "none"`, clamped reasoning effort, oneshot telemetry, text-only
+ * extraction, and provider-error mapping.
+ */
+export declare function generateHandoffFromContext(context: Context, model: Model, options: HandoffFromContextOptions): Promise<string>;
 export declare function generateHandoff(messages: AgentMessage[], model: Model, apiKey: ApiKey, options: HandoffOptions, signal?: AbortSignal): Promise<string>;
 export interface CompactionPreparation {
     /** UUID of first entry to keep */

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

@@ -29,9 +29,28 @@ export declare class EventLoopKeepalive {
     [Symbol.dispose](): void;
 }
 /**
- * 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.
+ * Cooperative yield gate. Sleeps for at least {@link YieldGateOptions.sleepMs}
+ * but at most once every {@link YieldGateOptions.intervalMs}; hot-path callers
+ * invoke it freely and only the slow path actually sleeps.
+ *
+ * The clock and sleep are injectable so tests drive the gate logic without
+ * touching process-global `Date.now`/`scheduler.wait` — globals a concurrent
+ * test file can restore mid-run, which previously made the shared gate flake.
+ */
+export interface YieldGateOptions {
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    intervalMs?: number;
+    sleepMs?: number;
+}
+export declare class YieldGate {
+    #private;
+    constructor(opts?: YieldGateOptions);
+    yieldIfDue(signal?: AbortSignal): Promise<void>;
+}
+/**
+ * Yield to the Bun event loop, sleeping for at least 20 ms — but at most once
+ * every {@link YIELD_INTERVAL_MS} across all callers.
  */
 export declare function yieldIfDue(): Promise<void>;
 export declare class ExponentialYield {

package/package.json

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

package/src/agent.ts

@@ -677,8 +677,16 @@ export class Agent {
 	 * in-band dialect sessions stay tools-less (matching their no-native-tools wire
 	 * shape and avoiding tool-markup leakage). `llmMessages` is already converted
 	 * (and, in production, obfuscated) by the caller.
+	 *
+	 * `systemPrompt` defaults to the live agent prompt so the side request hits the
+	 * same cached prefix as the main loop. Callers that must pin a different prompt
+	 * (e.g. handoff generation, which uses the base prompt rather than a per-turn
+	 * `before_agent_start` hook override) pass it explicitly.
 	 */
-	async buildSideRequestContext(llmMessages: Message[]): Promise<Context> {
+	async buildSideRequestContext(
+		llmMessages: Message[],
+		systemPrompt: string[] = this.#state.systemPrompt,
+	): Promise<Context> {
 		const model = this.#state.model;
 		if (!model) throw new Error("No active model on agent");
 		const ownedDialect = this.#dialect ?? resolveOwnedDialectFromEnv(Bun.env.PI_DIALECT);
@@ -691,7 +699,7 @@ export class Agent {
 					preferredDialect(model.id),
 					this.#pruneToolDescriptions,
 				) ?? []);
-		let context: Context = { systemPrompt: this.#state.systemPrompt, messages, tools };
+		let context: Context = { systemPrompt, messages, tools };
 		if (this.#transformProviderContext) context = await this.#transformProviderContext(context, model);
 		return context;
 	}

package/src/compaction/compaction.ts

@@ -8,12 +8,14 @@
 import {
 	type ApiKey,
 	type AssistantMessage,
+	type Context,
 	Effort,
 	type FetchImpl,
 	type Message,
 	type MessageAttribution,
 	type Model,
 	ProviderHttpError,
+	type SimpleStreamOptions,
 	type Tool,
 	type Usage,
 	withAuth,
@@ -771,6 +773,61 @@ export function renderHandoffPrompt(customInstructions?: string): string {
 	});
 }
 
+export interface HandoffFromContextOptions {
+	/**
+	 * Stream options mirrored from the live agent turn: `apiKey`, `signal`, the
+	 * `sessionId`/`promptCacheKey` cache-routing pair, `serviceTier`, and the
+	 * session's payload/response hooks. Sending the same routing + payload shape
+	 * the main loop uses is what lets the handoff oneshot READ the provider
+	 * prompt cache the live turn populated instead of cold-missing the whole
+	 * prefix. `reasoning` and `toolChoice` are set internally and override
+	 * anything provided here.
+	 */
+	streamOptions: SimpleStreamOptions;
+	/** See {@link HandoffOptions.telemetry}. */
+	telemetry?: AgentTelemetry;
+	/** See {@link HandoffOptions.thinkingLevel}. */
+	thinkingLevel?: ThinkingLevel;
+}
+
+/**
+ * Run the handoff oneshot against a fully-built provider {@link Context}.
+ *
+ * The caller assembles `context` exactly like a live agent turn — same system
+ * prompt, normalized tools, transformed + obfuscated message history, with the
+ * trailing handoff-prompt message already appended — and supplies
+ * `streamOptions` that mirror the live turn's cache routing. That keeps the
+ * cache-preserving context construction in the host (which owns the transform
+ * pipeline) while this function centralizes the handoff request contract:
+ * `toolChoice: "none"`, clamped reasoning effort, oneshot telemetry, text-only
+ * extraction, and provider-error mapping.
+ */
+export async function generateHandoffFromContext(
+	context: Context,
+	model: Model,
+	options: HandoffFromContextOptions,
+): Promise<string> {
+	const response = await instrumentedCompleteSimple(
+		model,
+		context,
+		{
+			...options.streamOptions,
+			reasoning: resolveCompactionEffort(model, options.thinkingLevel),
+			toolChoice: "none",
+		},
+		{ telemetry: options.telemetry, oneshotKind: "handoff" },
+	);
+
+	if (response.stopReason === "error") {
+		throw createSummarizationError("Handoff generation failed", response);
+	}
+
+	return response.content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map(c => c.text)
+		.join("\n");
+}
+
 export async function generateHandoff(
 	messages: AgentMessage[],
 	model: Model,
@@ -789,32 +846,20 @@ export async function generateHandoff(
 		},
 	];
 
-	const response = await instrumentedCompleteSimple(
+	return generateHandoffFromContext(
+		{ systemPrompt: options.systemPrompt, messages: requestMessages, tools: options.tools },
 		model,
 		{
-			systemPrompt: options.systemPrompt,
-			messages: requestMessages,
-			tools: options.tools,
-		},
-		{
-			apiKey,
-			signal,
-			reasoning: resolveCompactionEffort(model, options.thinkingLevel),
-			toolChoice: "none",
-			initiatorOverride: options.initiatorOverride,
-			metadata: options.metadata,
+			streamOptions: {
+				apiKey,
+				signal,
+				initiatorOverride: options.initiatorOverride,
+				metadata: options.metadata,
+			},
+			telemetry: options.telemetry,
+			thinkingLevel: options.thinkingLevel,
 		},
-		{ telemetry: options.telemetry, oneshotKind: "handoff" },
 	);
-
-	if (response.stopReason === "error") {
-		throw createSummarizationError("Handoff generation failed", response);
-	}
-
-	return response.content
-		.filter((c): c is { type: "text"; text: string } => c.type === "text")
-		.map(c => c.text)
-		.join("\n");
 }
 
 async function generateShortSummary(

package/src/utils/yield.ts

@@ -45,13 +45,6 @@ export class EventLoopKeepalive {
 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
@@ -76,15 +69,59 @@ async function sleepAtLeast(ms: number, signal?: AbortSignal): Promise<void> {
 }
 
 /**
- * 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.
+ * Cooperative yield gate. Sleeps for at least {@link YieldGateOptions.sleepMs}
+ * but at most once every {@link YieldGateOptions.intervalMs}; hot-path callers
+ * invoke it freely and only the slow path actually sleeps.
+ *
+ * The clock and sleep are injectable so tests drive the gate logic without
+ * touching process-global `Date.now`/`scheduler.wait` — globals a concurrent
+ * test file can restore mid-run, which previously made the shared gate flake.
+ */
+export interface YieldGateOptions {
+	now?: () => number;
+	sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+	intervalMs?: number;
+	sleepMs?: number;
+}
+
+export class YieldGate {
+	#lastYieldAt = 0;
+	readonly #now: () => number;
+	readonly #sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+	readonly #intervalMs: number;
+	readonly #sleepMs: number;
+
+	constructor(opts: YieldGateOptions = {}) {
+		this.#now = opts.now ?? (() => Date.now());
+		this.#sleep = opts.sleep ?? sleepAtLeast;
+		this.#intervalMs = opts.intervalMs ?? YIELD_INTERVAL_MS;
+		this.#sleepMs = opts.sleepMs ?? YIELD_SLEEP_MS;
+	}
+
+	async yieldIfDue(signal?: AbortSignal): Promise<void> {
+		const now = this.#now();
+		const elapsed = now - this.#lastYieldAt;
+		// `elapsed < 0` means the wall clock moved backward relative to the last
+		// yield (NTP step, fake-timer test, or a stale future timestamp left by
+		// another caller): treat it as due and re-anchor rather than gate forever.
+		if (elapsed >= 0 && elapsed < this.#intervalMs) return;
+		await this.#sleep(this.#sleepMs, signal);
+		this.#lastYieldAt = this.#now();
+	}
+}
+
+/**
+ * Process-wide gate shared by all hot-path callers so tight loops collectively
+ * respect the interval rather than each sleeping independently.
+ */
+const sharedYieldGate = new YieldGate();
+
+/**
+ * Yield to the Bun event loop, sleeping for at least 20 ms — but at most once
+ * every {@link YIELD_INTERVAL_MS} across all callers.
  */
-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();
+export function yieldIfDue(): Promise<void> {
+	return sharedYieldGate.yieldIfDue();
 }
 
 // ---------------------------------------------------------------------------