@linxiraos/pi-agent-core 1.1.27 → 1.2.0

package/CHANGELOG.md

@@ -1,270 +1,8 @@
-# Changelog
-
 ## [Unreleased]
 
-## [1.1.27] - 2026-10-07
-
-- 版本线推进至 1.1.27；本版无独立用户可见变化。
-
-### Breaking Changes
-
-- `Agent.withdrawUndeliveredQueuedMessages()` replaces `withdrawLiveSteering()` and returns `{ steering, followUp }`: it also takes back queued input already dequeued for the next model call, which the aborted run then neither records nor reports in `agent_end` ([#14179](https://github.com/can1357/oh-my-pi/pull/14179) by [@andrebrait](https://github.com/andrebrait))
-
-### Added
-
-- Added `Agent.setOnModelCallSystemPrompt`, called with the exact system prompt each model call is built from ([#14338](https://github.com/can1357/oh-my-pi/pull/14338) by [@will-bogusz](https://github.com/will-bogusz))
-
-### Changed
-
-- `SessionInitEntry.systemPrompt` holds the system prompt blocks as sent; session files written earlier keep one joined string ([#14338](https://github.com/can1357/oh-my-pi/pull/14338) by [@will-bogusz](https://github.com/will-bogusz))
-- Image token estimates now use the catalog's `imageTokens()` formula with its OpenAI Responses wire rule; values are unchanged ([#14286](https://github.com/can1357/oh-my-pi/pull/14286) by [@will-bogusz](https://github.com/will-bogusz)).
-
-### Fixed
-
-- Fixed the context count and auto-compaction trigger pricing every snapcompact archive frame at Opus's high-res rate, which overcounted Codex and Gemini sessions and could re-trigger compaction right after compacting ([#14291](https://github.com/can1357/oh-my-pi/pull/14291) by [@will-bogusz](https://github.com/will-bogusz))
-- Fixed native (OpenAI) compaction being refused as over the context window in sessions with many screenshots. Images were counted as about 1,200 tokens when deciding to compact but 12,000 when checking whether the compaction request fits; both checks now estimate images from their actual dimensions, and a request is no longer refused when only the image estimate pushes it over the window ([#14260](https://github.com/can1357/oh-my-pi/pull/14260) by [@H4vC](https://github.com/H4vC)).
-- Fixed OpenAI and Codex Remote Compaction V2 dropping your recent messages instead of keeping them next to the compaction summary ([#14247](https://github.com/can1357/oh-my-pi/pull/14247) by [@will-bogusz](https://github.com/will-bogusz))
-- Fixed the failed V2 remote compaction warning claiming a V1 fallback on Codex, where V1 does not run ([#14245](https://github.com/can1357/oh-my-pi/pull/14245) by [@will-bogusz](https://github.com/will-bogusz))
-- Fixed Anthropic native compaction being rejected with `Invalid signature in thinking block` (or silently dropping the summarized thinking) on models with preserved thinking ([#14251](https://github.com/can1357/oh-my-pi/pull/14251) by [@will-bogusz](https://github.com/will-bogusz))
-
-## [14.9.5] - 2026-05-12
-
-### Added
-
-- Added an `isError?: boolean` field on `AgentToolResult` so tools can flag a non-throwing failure (e.g. an aggregator that catches per-entry errors). `coerceToolResult` preserves the flag and the agent loop surfaces it as a tool error on the wire.
-
-## [14.9.3] - 2026-05-10
-
-### Added
-
-- Added `onHarmonyLeak` option on `Agent`/loop config to receive GPT-5 Harmony leak audit callbacks
-- Added harmony-leak detection and audit exports to the package index for programmatic leak detection and recovery hooks
-
-### Changed
-
-- Changed OpenAI Codex model runs to detect GPT-5 Harmony protocol leakage during streaming and automatically retry or recover tool calls instead of sending contaminated arguments downstream
-
-### Security
-
-- Hardened tool-call handling against leaked `to=functions.*` protocol tails by truncating or retrying before execution
-- Hardened failure handling so repeated GPT-5 Harmony leak mitigation is retried only up to two times before escalating to an explicit error
-
-## [14.9.0] - 2026-05-10
-
-### Added
-
-- Added `Agent#metadata` field forwarded to every API request; callers can set arbitrary provider metadata (e.g. `metadata.user_id`) once and have it applied to all subsequent stream calls without modifying per-call options
-- Added `Agent#setMetadataResolver(fn)` for installing a function that resolves request metadata at call time. The `metadata` getter dispatches through the resolver on every read (including the snapshot taken per `prompt()`), so callers reflect mutable external state (e.g. live OAuth account UUID after a token refresh) without manual re-syncs. Plain `agent.metadata = …` continues to set a static value and clears any installed resolver.
-- Added an `onSseEvent` agent option and loop config forwarding path for raw provider SSE diagnostics.
-
-## [14.7.6] - 2026-05-07
-
-### Added
-
-- Added `hideThinkingSummary` option/getter/setter on `Agent` and `AgentLoopConfig`. Forwarded to the underlying stream call so providers can omit reasoning/thinking summaries on demand.
-
-## [14.7.2] - 2026-05-06
-
-### Added
-
-- Added `loadMode` option to `AgentTool` to mark built-in tools as `essential` for initial loading or `discoverable` for search activation
-- Added optional `summary` field to `AgentTool` definitions for one-line text used in tool discovery indexes
-
-## [14.7.0] - 2026-05-04
-
-### Breaking Changes
-
-- Changed `Agent` API types so `systemPrompt` is now a list of prompt strings, requiring callers to pass and update system prompts via string arrays
-
-### Changed
-
-- Removed automatic project-context injection into each model call from loop logic
-
-### Removed
-
-- Removed the `projectPrompt` field from agent state/context and the `setProjectPrompt` mutator
-
-## [14.6.2] - 2026-05-03
-
-### Fixed
-
-- Fixed unhandled promise rejection when `getApiKey` or any other async error occurs during `streamAssistantResponse`: agent loop IIFEs now catch and route errors through `EventStream.fail()`, which terminates the `for await` loop and lets `Agent#runLoop`'s catch block create a proper error assistant message instead of crashing
-
-## [14.6.0] - 2026-05-02
-
-### Fixed
-
-- Fixed request cancellation before provider events by emitting an aborted assistant message and ending the stream with `stopReason: "aborted"`
-
-## [14.5.10] - 2026-04-30
-
-### Added
-
-- Added an `onResponse` stream option for observing provider response metadata after response headers arrive.
-
-## [14.2.0] - 2026-04-23
-
-### Changed
-
-- Changed tool dispatch to match model-returned tool calls by either internal tool name or custom wire name, enabling custom OpenAI tool names such as `apply_patch`.
-
-## [14.0.1] - 2026-04-08
-
-### Added
-
-- Added `onAssistantMessageEvent` callback option to inspect assistant streaming events before they are emitted, enabling abort decisions before buffered events continue flowing
-- Added `setAssistantMessageEventInterceptor()` method to dynamically set or update the assistant message event interceptor
-
-## [13.13.0] - 2026-03-18
-
-### Added
-
-- Added `startup.checkUpdate` setting, set to `true` by default, can be disabled to skip the update check on agent initialization
-
-## [13.12.7] - 2026-03-16
-
-### Added
-
-- Added overload for `prompt()` method accepting a string input with optional options parameter
-
-### Fixed
-
-- Fixed stale forced toolChoice being passed to provider after tools are refreshed mid-turn
-
-## [13.9.16] - 2026-03-10
-
-### Added
-
-- Added `onPayload` option to `AgentOptions` to inspect or replace provider payloads before they are sent
+## [1.2.0] - 2026-10-12
 
-## [13.9.3] - 2026-03-07
-
-### Added
-
-- Exported `ThinkingLevel` selector constants and types for configuring agent reasoning behavior
-- Added `inherit` thinking level option to defer reasoning configuration to higher-level selectors
-- Added `serviceTier` option to configure service tier for agent requests
-
-### Changed
-
-- Changed `thinkingLevel` from required string to optional `Effort` type, allowing undefined state
-- Updated `setThinkingLevel()` method to accept `Effort | undefined` instead of `ThinkingLevel` string
-
-## [13.4.0] - 2026-03-01
-
-### Added
-
-- Added `getToolChoice` option to dynamically override tool choice per LLM call
-
-## [13.3.8] - 2026-02-28
-
-### Changed
-
-- Changed intent field name from `agent__intent` to `_i` in tool schemas
-
-### Fixed
-
-- Fixed synthetic tool result text formatting so aborted/error tool results no longer emit `Tool execution was aborted.: Request was aborted` style punctuation.
-
-## [13.3.7] - 2026-02-27
-
-### Added
-
-- Added `lenientArgValidation` option to tools to allow graceful handling of argument validation errors by passing raw arguments to execute() instead of returning an error to the LLM
-
-## [13.3.1] - 2026-02-26
-
-### Added
-
-- Added `topP`, `topK`, `minP`, `presencePenalty`, and `repetitionPenalty` options to `AgentOptions` for fine-grained sampling control
-- Added getter and setter properties for sampling parameters on the `Agent` class to allow runtime configuration
-
-## [13.1.0] - 2026-02-23
-
-### Changed
-
-- Removed per-tool `agent__intent` field description from injected schema to reduce token usage; intent format is now documented once in the system prompt instead of repeated in every tool definition
-
-## [12.19.0] - 2026-02-22
-
-### Changed
-
-- Updated tool result messages to include error details when tool execution fails
-
-## [12.14.0] - 2026-02-19
-
-### Added
-
-- Added `intentTracing` option to enable intent goal extraction from tool calls, allowing models to specify high-level goals via a required `_intent` field that is automatically injected into tool schemas and stripped from arguments before execution
-
-## [12.11.0] - 2026-02-19
-
-### Added
-
-- Exported `AgentBusyError` exception class for handling concurrent agent operations
-
-### Changed
-
-- Agent now throws `AgentBusyError` instead of generic `Error` when attempting concurrent operations
-
-## [12.8.0] - 2026-02-16
-
-### Added
-
-- Added `transformToolCallArguments` option to `AgentOptions` and `AgentLoopConfig` for transforming tool call arguments before execution (e.g. secret deobfuscation)
-
-## [12.2.0] - 2026-02-13
-
-### Added
-
-- Added `providerSessionState` option to share provider state map for session-scoped transport and session caches
-- Added `preferWebsockets` option to hint that websocket transport should be preferred when supported by the provider implementation
-
-## [11.10.0] - 2026-02-10
-
-### Added
-
-- Added `temperature` option to `AgentOptions` to control LLM sampling temperature
-- Added `temperature` getter and setter to `Agent` class for runtime configuration
-
-## [11.6.0] - 2026-02-07
-
-### Added
-
-- Added `hasQueuedMessages()` method to check for pending steering/follow-up messages
-- Resume queued steering and follow-up messages from `continue()` after auto-compaction
-
-### Changed
-
-- Extracted `dequeueSteeringMessages()` and `dequeueFollowUpMessages()` from inline config callbacks
-- Added `skipInitialSteeringPoll` option to `_runLoop()` for correct queue resume ordering
-
-## [11.3.0] - 2026-02-06
-
-### Added
-
-- Added `maxRetryDelayMs` option to AgentOptions to cap server-requested retry delays, allowing higher-level retry logic to handle long waits with user visibility
-
-### Changed
-
-- Updated ThinkingLevel documentation to include support for gpt-5.3 and gpt-5.3-codex models with 'xhigh' thinking level
-
-## [11.2.0] - 2026-02-05
-
-### Fixed
-
-- Fixed handling of aborted requests to properly throw abort errors when stream terminates without a terminal event
-
-## [10.5.0] - 2026-02-04
-
-### Added
-
-- Added `concurrency` option to `AgentTool` to control tool scheduling: "shared" (default, runs in parallel) or "exclusive" (runs alone)
-- Implemented parallel execution of shared tools within a single agent turn for improved performance
-
-### Changed
-
-- Refactored tool execution to support concurrent scheduling with proper interrupt handling and steering message checks
+- 版本线推进至 1.2.0；本版无独立用户可见变化。
 
 ## [9.2.2] - 2026-01-31
 
@@ -396,6 +134,10 @@
 
 Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mono](https://github.com/badlogic/pi-mono).
 
+## [1.1.27] - 2026-10-07
+
+- 版本线推进至 1.1.27；本版无独立用户可见变化。
+
 ## [1.1.25] - 2026-10-03
 
 - 版本线推进至 1.1.25；本版无独立用户可见变化。

package/README.md

@@ -466,7 +466,7 @@ const runCoverage = aggregateAgentRunCoverage(coverages);
 
 ### Tool status reporting
 
-`execute_tool` spans carry `omp.gen_ai.tool.status` ∈
+`execute_tool` spans carry `zeta.gen_ai.tool.status` ∈
 `"ok" | "error" | "skipped" | "blocked" | "timeout" | "aborted"`.
 `beforeToolCall` blocks throw a distinguishable `ToolCallBlockedError`
 internally; the catch path reports `status: "blocked"` instead of conflating

package/dist/types/agent.d.ts

@@ -270,6 +270,11 @@ export declare class Agent {
      * are queued for the next boundary.
      */
     hasBackgroundCompletions?: AgentLoopConfig["hasBackgroundCompletions"];
+    /**
+     * Hook that peeks whether a passive aside is queued for the next boundary;
+     * ends an interruptible wait without interrupting other tools.
+     */
+    hasQueuedAsides?: AgentLoopConfig["hasQueuedAsides"];
     constructor(opts?: AgentOptions);
     /**
      * Get the current session ID used for provider caching.
@@ -412,7 +417,8 @@ export declare class Agent {
     buildSideRequestContext(llmMessages: Message[], systemPrompt?: string[]): Promise<Context>;
     subscribe(fn: (e: AgentEvent) => void): () => void;
     /** Register a listener notified after any steering/follow-up queue mutator
-     *  (enqueue, dequeue-on-delivery, clear, restore) runs. Internal-only signal —
+     *  (enqueue, dequeue-on-delivery, clear, restore, live-steering adoption,
+     *  withdrawal, and landing in the transcript) runs. Internal-only signal —
      *  the queue itself has no concept of display filtering — so listeners
      *  recompute their own snapshot from `peekSteeringQueue()`/`peekFollowUpQueue()`
      *  (or a higher-level view) on notification. */
@@ -457,12 +463,19 @@ export declare class Agent {
     /**
      * Provide a source of non-interrupting "aside" messages (e.g. background-job
      * completions, late LSP diagnostics) drained at each step boundary. Never
-     * aborts in-flight tools. See `AgentLoopConfig.getAsideMessages`.
+     * aborts foreground tools; an interruptible `wait` may end early through the
+     * peek hooks. See `AgentLoopConfig.getAsideMessages`.
      */
     setAsideMessageProvider(fn: (() => AsideMessage[] | Promise<AsideMessage[]>) | undefined): void;
     emitExternalEvent(event: AgentEvent): void;
     setSystemPrompt(v: string[] | string): void;
     setModel(model: Model): void;
+    /**
+     * Route every model this agent adopts through `resolver` (e.g. to fit a
+     * shared catalog row to this agent's own settings), starting with the
+     * current one; `undefined` adopts models as given from now on.
+     */
+    setModelResolver(resolver: ((model: Model) => Model) | undefined): void;
     setThinkingLevel(l: Effort | undefined): void;
     setDisableReasoning(disabled: boolean): void;
     setSteeringMode(mode: "all" | "one-at-a-time"): void;

package/dist/types/compaction/branch-summarization.d.ts

@@ -55,7 +55,7 @@ export interface GenerateBranchSummaryOptions {
     convertToLlm?: ConvertToLlm;
     /**
      * Optional telemetry handle. When provided, the branch summary LLM call is
-     * wrapped in an OTEL chat span tagged with `omp.gen_ai.oneshot.kind = "branch_summary"`.
+     * wrapped in an OTEL chat span tagged with `zeta.gen_ai.oneshot.kind = "branch_summary"`.
      */
     telemetry?: AgentTelemetry;
     /**

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

@@ -34,6 +34,14 @@ export interface CompactionSettings {
     strategy?: "context-full" | "handoff" | "shake" | "snapcompact" | "off";
     thresholdPercent?: number;
     thresholdTokens?: number;
+    /**
+     * Stands in for the context window when the percentage or reserve-based
+     * threshold is computed (when `> 0` and smaller than the window); a positive
+     * `thresholdTokens` still wins and is checked against the real window (at
+     * or past it, the window less its reserve applies). Set by per-model
+     * compaction limits; request and overflow budgets keep the real window.
+     */
+    baseWindowTokens?: number;
     midTurnEnabled?: boolean;
     /**
      * Tokens reserved below the context window for the next prompt + response.
@@ -194,7 +202,7 @@ export interface SummaryOptions {
     /**
      * Optional telemetry handle. When provided, every LLM call emitted during
      * compaction is wrapped in an OTEL chat span tagged with
-     * `omp.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
+     * `zeta.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
      * or `compaction_turn_prefix`). `undefined` keeps the call paths zero-cost.
      */
     telemetry?: AgentTelemetry;
@@ -257,7 +265,7 @@ export interface HandoffOptions {
     metadata?: Record<string, unknown>;
     /**
      * Optional telemetry handle. When provided, the handoff LLM call is
-     * wrapped in an OTEL chat span tagged with `omp.gen_ai.oneshot.kind = "handoff"`.
+     * wrapped in an OTEL chat span tagged with `zeta.gen_ai.oneshot.kind = "handoff"`.
      */
     telemetry?: AgentTelemetry;
     /**

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

@@ -1,5 +1,6 @@
 import type { ImageContent, Message, MessageAttribution, ProviderPayload, TextContent } from "@linxiraos/pi-ai";
 import type { AgentMessage } from "../types.js";
+import type { SessionEntry } from "./entries.js";
 export interface CustomMessage<T = unknown> {
     role: "custom";
     customType: string;
@@ -110,3 +111,8 @@ export declare function convertMessageToLlm(message: AgentMessage): Message | un
  * core LLM roles and the compaction messages owned by this package.
  */
 export declare function defaultConvertToLlm(messages: AgentMessage[]): Message[];
+/**
+ * The context message a session entry contributes, or `undefined` for entries
+ * that don't reach the LLM (compaction markers, labels, model changes, ...).
+ */
+export declare function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined;

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

@@ -4,8 +4,26 @@
 import type { ToolResultMessage } from "@linxiraos/pi-ai";
 import type { Tokenizer } from "../tokenizer.js";
 import type { SessionEntry } from "./entries.js";
+import { type ConvertToLlm } from "./messages.js";
 import { type ProtectedToolMatcher } from "./tool-protection.js";
-export interface PruneConfig {
+/** Bound warm-cache pruning by the provider's prompt-cache lookback window. */
+export interface CacheLookbackConfig {
+    /**
+     * Prompt-cache lookback of the model the next request goes to, in block
+     * positions (catalog `prompt-cache-lookback`; Anthropic: 20). When set,
+     * warm-cache pruning also leaves a result whose rewrite would put the next
+     * request's cache lookup out of reach, whatever its token suffix (see
+     * `cacheLookbackFloor`). Undefined = no lookback bound.
+     */
+    cacheLookbackPositions?: number;
+    /**
+     * Projects context messages to what the provider receives, so lookback
+     * positions count app roles (file mentions, command output, custom
+     * messages) as sent. Default {@link defaultConvertToLlm}.
+     */
+    convertToLlm?: ConvertToLlm;
+}
+export interface PruneConfig extends CacheLookbackConfig {
     /** Keep the most recent tool output tokens intact. */
     protectTokens: number;
     /** Only prune if total savings meets this threshold. */
@@ -37,7 +55,8 @@ export interface PruneConfig {
      * already-sent cache prefix: mutating it forces the provider to re-write the
      * whole suffix (cacheWrite premium). Such results — including superseded and
      * useless ones, which otherwise bypass {@link protectTokens} — are left for
-     * compaction/shake (which rebuild the cache anyway) to reclaim. Undefined =
+     * compaction/shake (which rebuild the cache anyway) to reclaim, as are
+     * results beyond {@link CacheLookbackConfig.cacheLookbackPositions}. Undefined =
      * no cache guard (legacy: superseded/useless prune at any depth).
      */
     cacheWarmSuffixTokens?: number;
@@ -72,7 +91,7 @@ export type SupersedeKeyFn = (toolName: string, args: Record<string, unknown>) =
  * range reads). A summary, truncated page, or notice is not complete.
  */
 export type SupersedeCompleteFn = (message: ToolResultMessage) => boolean;
-export interface SupersedePruneConfig {
+export interface SupersedePruneConfig extends CacheLookbackConfig {
     /** Supersede key function; a newer successful result with the same key supersedes older ones (see {@link SupersedeKeyFn}). */
     supersedeKey?: SupersedeKeyFn;
     /**
@@ -90,7 +109,11 @@ export interface SupersedePruneConfig {
     supersedeComplete?: SupersedeCompleteFn;
     /** Also prune results flagged useless by their tool. Default false. */
     pruneUseless?: boolean;
-    /** Prune a candidate now when all messages after it total at most this many estimated tokens. Default 8 000. */
+    /**
+     * Prune a candidate now when all messages after it total at most this many
+     * estimated tokens and it sits within
+     * {@link CacheLookbackConfig.cacheLookbackPositions}. Default 8 000.
+     */
     suffixTokenLimit?: number;
     /**
      * Prune all candidates when the last message is at least this old: the
@@ -127,10 +150,11 @@ export declare const MIN_PRUNE_TOKENS = 50;
  * candidate is pruned now only when the suffix after it is small (tail case —
  * the read→edit→read loop) or when the context has been idle long enough that
  * the provider cache is cold anyway (then all still-sent candidates flush).
- * Never mutates entries before `keepBoundaryId` (summarized away — not sent).
+ * Never mutates entries before `keepBoundaryId` (summarized away — not sent),
+ * and never walks them unless a sent result's call lives there.
  */
-export declare function pruneSupersededToolResults(entries: SessionEntry[], tokenizer: Tokenizer, config: SupersedePruneConfig): PruneResult;
-export declare function pruneToolOutputs(entries: SessionEntry[], tokenizer: Tokenizer, config?: PruneConfig): PruneResult;
+export declare function pruneSupersededToolResults(entries: readonly SessionEntry[], tokenizer: Tokenizer, config: SupersedePruneConfig): PruneResult;
+export declare function pruneToolOutputs(entries: readonly SessionEntry[], tokenizer: Tokenizer, config?: PruneConfig): PruneResult;
 /**
  * Supersede key for the `read` tool: the file path with the trailing line/raw
  * selector stripped (the read tool's own splitter grammar via

package/dist/types/compaction/tool-protection.d.ts

@@ -6,7 +6,8 @@ export interface ProtectedToolContext {
     readonly toolCall: AgentToolCall | undefined;
 }
 export type ProtectedToolMatcher = string | ((context: ProtectedToolContext) => boolean);
-export declare function collectToolCallsById(entries: readonly SessionEntry[]): Map<string, AgentToolCall>;
+/** Map tool-call ids to their calls across `entries[start, end)` (later calls win). */
+export declare function collectToolCallsById(entries: readonly SessionEntry[], start?: number, end?: number): Map<string, AgentToolCall>;
 /** Return the tool-result message carried by a session entry, if any. */
 export declare function getToolResultMessage(entry: SessionEntry): ToolResultMessage | undefined;
 /**

package/dist/types/index.d.ts

@@ -13,5 +13,6 @@ export * from "./telemetry.js";
 export * from "./thinking.js";
 export * from "./tool-context.js";
 export * from "./tokenizer.js";
+export * from "./tool-arguments.js";
 export * from "./types.js";
 export * from "./utils/yield.js";

package/dist/types/speculative-execution.d.ts

@@ -1,4 +1,4 @@
-import { type AssistantMessage } from "@linxiraos/pi-ai";
+import type { AssistantMessage } from "@linxiraos/pi-ai";
 import type { AgentContext, AgentLoopConfig, AgentTool, AgentToolCall, AgentToolResult, SpeculativeAuthorization, SpeculativeChildDefinition, SpeculativeChildHandle, SpeculativeLaunchContext, SpeculativeToolExecutionConfig, ToolSpeculationEffect, ToolSpeculationStreamSession } from "./types.js";
 export type SpeculativeRawOutcome = {
     result: AgentToolResult<unknown>;