@oh-my-pi/pi-agent-core 16.1.14 → 16.1.16

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [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/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "16.1.14",
+	"version": "16.1.16",
 	"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.14",
-		"@oh-my-pi/pi-catalog": "16.1.14",
-		"@oh-my-pi/pi-natives": "16.1.14",
-		"@oh-my-pi/pi-utils": "16.1.14",
-		"@oh-my-pi/pi-wire": "16.1.14",
-		"@oh-my-pi/snapcompact": "16.1.14",
+		"@oh-my-pi/pi-ai": "16.1.16",
+		"@oh-my-pi/pi-catalog": "16.1.16",
+		"@oh-my-pi/pi-natives": "16.1.16",
+		"@oh-my-pi/pi-utils": "16.1.16",
+		"@oh-my-pi/pi-wire": "16.1.16",
+		"@oh-my-pi/snapcompact": "16.1.16",
 		"@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(