@oh-my-pi/pi-agent-core 18.3.0 → 18.3.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [18.3.1] - 2026-09-25
+
+### Added
+
+- Added live steering support for Codex WebSocket transports, allowing users to provide input while a response is in progress.
+- Added passive tool-call context support, allowing hooks and tools to supply additional context for subsequent model processing.
+- Improved context-window handling by automatically adjusting output-token limits and supporting models that truncate output at the context-window limit.
+
+### Changed
+
+- Improved prompt token counting for requests with anchored prefixes by using provider-reported usage and limiting local estimation to new message content.
+
 ## [18.3.0] - 2026-09-24
 
 ### Added

package/README.md

@@ -154,8 +154,9 @@ const agent = new Agent({
   // Dynamic model-scoped API key resolution (for expiring OAuth tokens)
   getApiKey: async (model) => tokenForModel(model),
 
-  // Tool execution context (late-bound UI/session access)
-  getToolContext: () => ({ /* app-defined */ }),
+  // Tool execution context (late-bound UI/session access). Surface the loop's
+  // passive-context sink so tools can call ctx.addAdditionalContext(...).
+  getToolContext: toolCall => ({ addAdditionalContext: toolCall?.addAdditionalContext /* app-defined */ }),
 });
 ```
 

package/THIRD-PARTY-NOTICES.txt

@@ -78,8 +78,8 @@ below.
 uutils coreutils (https://github.com/uutils/coreutils), MIT
 --------------------------------------------------------------------------------
 Covers: base32, base64, basename, cat, cksum (shared checksum machinery),
-b2sum, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, comm, cut,
-date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nproc, paste,
+b2sum, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, comm, cp,
+cut, date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nproc, paste,
 printenv, readlink, realpath, rm, seq, sort, stat, tac, tail, tee, touch, tr,
 truncate, uname, uniq, wc, whoami, yes.
 

package/dist/types/agent.d.ts

@@ -159,6 +159,11 @@ export interface AgentOptions {
     pruneToolDescriptions?: boolean;
     /** Owned tool-calling dialect. Undefined keeps provider-native tool calling. */
     dialect?: Dialect;
+    /**
+     * Per-request owned-dialect resolver, consulted with the model being requested.
+     * Authoritative when set (like {@link serviceTierResolver}): replaces {@link dialect}.
+     */
+    dialectResolver?: (model: Model) => Dialect | undefined;
     /**
      * When owned tool calling is active and the model fabricates a tool result
      * mid-turn: `true` (default) aborts the provider request immediately; `false`
@@ -360,6 +365,15 @@ export declare class Agent {
     set serviceTierResolver(value: ((model: Model) => ServiceTier | undefined) | undefined);
     get hideThinkingSummary(): boolean | undefined;
     set hideThinkingSummary(value: boolean | undefined);
+    /** Strip tool descriptions from provider-bound specs; read per request. */
+    get pruneToolDescriptions(): boolean;
+    set pruneToolDescriptions(value: boolean);
+    /** Inject/strip the intent field on tool calls; applies from the next prompt run. */
+    get intentTracing(): boolean;
+    set intentTracing(value: boolean);
+    /** Abort the provider request on a fabricated tool result; applies from the next prompt run. */
+    get abortOnFabricatedToolResult(): boolean | undefined;
+    set abortOnFabricatedToolResult(value: boolean | undefined);
     /**
      * Get the current max retry delay in milliseconds.
      */

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

@@ -45,6 +45,13 @@ export interface CompactionSummaryMessage {
     images?: ImageContent[];
     /** Post-pass dead-end warning attached to this compaction (progress guard). */
     warning?: string;
+    /**
+     * Thinking-binding rewrite marker when it must differ from `timestamp`: a
+     * natively replayed summary predates it before the retained tail so that
+     * tail's bound thinking stays valid. `timestamp` remains the commit time,
+     * which is what invalidates the tail's pre-compaction usage reports.
+     */
+    historyRewriteAt?: number;
     timestamp: number;
 }
 export type CoreCompactionMessage = CustomMessage | HookMessage | BranchSummaryMessage | CompactionSummaryMessage;
@@ -79,6 +86,8 @@ export interface CompactionSummaryMessageOptions {
     method?: string;
     /** Estimated context tokens after the rewrite, for display alongside `tokensBefore`. */
     tokensAfter?: number;
+    /** See {@link CompactionSummaryMessage.historyRewriteAt}. */
+    historyRewriteAt?: number;
 }
 export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string, options?: CompactionSummaryMessageOptions): CompactionSummaryMessage;
 export declare function createCustomMessage(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details: unknown | undefined, timestamp: string, attribution?: MessageAttribution): CustomMessage;

package/dist/types/compaction/transcript-tokens.d.ts

@@ -17,7 +17,7 @@
  * - Not `aborted` / `error`: those turns report partial or zero usage.
  * - `hasContextTokenUsage(usage)`: the report must carry usable context numbers.
  */
-import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import type { AssistantMessage, Message } from "@oh-my-pi/pi-ai";
 import type { Tokenizer } from "../tokenizer.js";
 import type { AgentMessage } from "../types.js";
 /** A provider usage report that accounts for a prefix of the transcript. */
@@ -46,6 +46,19 @@ export declare function isTranscriptUsageAnchor(message: AgentMessage): message
  * summarized away describes a prompt that is no longer sent.
  */
 export declare function findTranscriptUsageAnchor(messages: readonly AgentMessage[], fromIndex?: number): TranscriptUsageAnchor | undefined;
+/**
+ * Newest assistant turn in a provider request's `messages` whose usage still
+ * describes the prefix it sits on, or `undefined` when none does.
+ *
+ * Request contexts carry no compaction index, so staleness is read from the
+ * rewrite markers themselves: a compaction/branch summary or pruned tool result
+ * (`prunedAt`) replaced text that every report made at or before the rewrite
+ * already counted. A summary's rewrite time is its `timestamp` (commit time);
+ * its `historyRewriteAt` may be predated before a natively replayed retained
+ * tail so that tail's bound thinking survives, but the tail's usage still
+ * counted the summarized prefix.
+ */
+export declare function findRequestUsageAnchor(messages: readonly Message[]): TranscriptUsageAnchor | undefined;
 /** Options for {@link estimateTranscriptTokens}. */
 export interface TranscriptTokenOptions {
     /**

package/dist/types/index.d.ts

@@ -2,6 +2,7 @@ export * from "./agent.js";
 export * from "./agent-loop.js";
 export * from "./append-only-context.js";
 export * from "./compaction.js";
+export * from "./output-budget.js";
 export * from "./pause.js";
 export * from "./proxy.js";
 export * from "./replay-policy.js";
@@ -10,6 +11,7 @@ export * from "./sent-tool-definitions.js";
 export * from "./speculative-execution.js";
 export * from "./telemetry.js";
 export * from "./thinking.js";
+export * from "./tool-context.js";
 export * from "./tokenizer.js";
 export * from "./types.js";
 export * from "./utils/yield.js";

package/dist/types/live-steering.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Agent side of provider live steering ({@link LiveSteering}).
+ *
+ * A provider that can put user input into the response it is streaming (OpenAI
+ * Responses `response.steer`) pulls queued steering through a
+ * {@link LiveSteeringChannel}. The loop records what the provider accepted right
+ * after that response, so the transcript matches what the model saw; anything
+ * it declined is injected at the next boundary like ordinary steering.
+ */
+import type { LiveSteerClaim, LiveSteering, UserMessage } from "@oh-my-pi/pi-ai";
+import type { AgentMessage } from "./types.js";
+/** Steering-queue access for one provider call, supplied by the agent loop. */
+export interface LiveSteeringQueue {
+    /** Resolves once steering is queued or `signal` aborts; never consumes. */
+    wait(signal: AbortSignal): Promise<void>;
+    /** Dequeues the next steering batch. */
+    take(signal: AbortSignal): Promise<AgentMessage[]>;
+    /**
+     * Provider view of `messages` appended to the in-flight call's context, or
+     * `undefined` when that view is not purely user messages.
+     */
+    toProvider(messages: AgentMessage[], signal: AbortSignal): Promise<UserMessage[] | undefined>;
+}
+/** One provider call's {@link LiveSteering} source. */
+export declare class LiveSteeringChannel implements LiveSteering {
+    #private;
+    /** Steering the provider delivered into the in-flight response, in queue order. */
+    readonly accepted: AgentMessage[];
+    /** Steering taken from the queue but not delivered; always queued after {@link accepted}. */
+    readonly deferred: AgentMessage[];
+    constructor(queue: LiveSteeringQueue);
+    wait(signal: AbortSignal): Promise<void>;
+    claim(signal: AbortSignal): Promise<LiveSteerClaim | undefined>;
+}

package/dist/types/output-budget.d.ts

@@ -0,0 +1,43 @@
+import type { Context, Model } from "@oh-my-pi/pi-ai";
+import type { Tokenizer } from "./tokenizer.js";
+/** Smallest output cap {@link fitOutputTokensToContextWindow} will request. */
+export declare const MIN_FITTED_OUTPUT_TOKENS = 1024;
+/**
+ * Output cap for a request, so prompt plus output stays inside the model's
+ * context window.
+ *
+ * Chat Completions-style providers (DeepSeek, OpenAI, vLLM, ...) reject a
+ * request whose prompt tokens plus `max_tokens` exceed the window. Every
+ * request asks for `model.maxTokens` of output by default, so without this a
+ * large model output cap (DeepSeek V4: ~384k of a ~1M window) makes every
+ * request fail once the prompt passes window minus output cap, long before
+ * compaction triggers, and side turns (`/btw`, recaps) have no overflow
+ * recovery at all.
+ *
+ * The prompt size is the provider's own report from the newest trustworthy
+ * assistant turn (see {@link findRequestUsageAnchor}) plus a local count of
+ * only the messages appended after it; the whole context is counted locally
+ * only when no turn can anchor (fresh or freshly rewritten context).
+ *
+ * Returns `maxTokens` unchanged when the requested cap already fits, the
+ * model declares no window, the host ends generation at the window itself
+ * instead of rejecting the request (`stops-output-at-context-window`, e.g.
+ * Claude 4.5+ on the Claude API), or nothing would be requested (including an
+ * OpenRouter-hosted model with no caller cap: the transport omits the catalog
+ * default there so each upstream self-caps, and a fitted value would turn into
+ * an explicit cap that filters upstreams). Otherwise returns
+ * the remaining room (never below {@link MIN_FITTED_OUTPUT_TOKENS}); a
+ * prompt that fills the whole window still overflows and is left to the
+ * caller's compaction. Near a full window the floor means a turn can stop on
+ * `length` instead of failing with a 400.
+ *
+ * Lives here, not next to the default in pi-ai's `mapOptionsForApi`, because
+ * pi-ai has no tokenizer; callers apply it in their `streamFn` (coding-agent
+ * does so in its shared settings-aware wrapper).
+ *
+ * Not fixed: Anthropic budget-thinking transports raise `max_tokens` back to
+ * at least the thinking budget plus a fallback buffer downstream
+ * (`ensureMaxTokensForThinking`), so a fitted cap below that is overridden
+ * and the request can still exceed the window as before.
+ */
+export declare function fitOutputTokensToContextWindow(model: Model, context: Context, maxTokens: number | undefined, tokenizer: Tokenizer): number | undefined;

package/dist/types/tool-context.d.ts

@@ -0,0 +1,31 @@
+import type { ToolResultMessage } from "@oh-my-pi/pi-ai";
+import type { AgentMessage } from "./types.js";
+/**
+ * Symbol-keyed carrier for passive context reported by a tool executed outside
+ * the agent loop (Cursor exec-channel dispatch). The executor attaches the
+ * joined context to the {@link ToolResultMessage} it returns; `Agent` reads it
+ * when the provider hands the result back and injects it after the buffered
+ * results. Symbol keys never serialize, so the context cannot leak into the
+ * persisted tool result.
+ */
+export declare const TOOL_RESULT_ADDITIONAL_CONTEXT: unique symbol;
+/** A tool result optionally carrying {@link TOOL_RESULT_ADDITIONAL_CONTEXT}. */
+export type ToolResultWithAdditionalContext = ToolResultMessage & {
+    [TOOL_RESULT_ADDITIONAL_CONTEXT]?: string;
+};
+/**
+ * True for a passive-context value worth delivering: a string with at least
+ * one non-whitespace character. Shared by every producer and aggregation site
+ * so blank values never produce a developer message.
+ */
+export declare function isNonBlankContext(value: unknown): value is string;
+/**
+ * Join passive context values in order, dropping blanks. Returns undefined
+ * when nothing remains.
+ */
+export declare function joinAdditionalContext(values: Iterable<string | undefined>): string | undefined;
+/**
+ * Build the developer message that carries passive tool context to the next
+ * provider request. Emitted after the tool results it belongs to.
+ */
+export declare function createAdditionalContextMessage(text: string): AgentMessage;

package/dist/types/types.d.ts

@@ -36,6 +36,12 @@ export interface AgentTurnEndContext {
     message: AgentMessage;
     /** Tool results produced by this turn, already paired with `message` in the live context. */
     toolResults: ToolResultMessage[];
+    /**
+     * Passive model-visible messages appended after the tool results at this
+     * boundary. The agent loop always sends an array (possibly empty);
+     * absent is equivalent to empty for hosts that construct the context.
+     */
+    additionalMessages?: AgentMessage[];
     /** True when the current tool-loop batch is continuing without yielding to post-turn steering. */
     willContinue: boolean;
 }
@@ -284,7 +290,11 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     onBeforeYield?: () => Promise<void> | void;
     /**
      * Provides tool execution context, resolved per tool call.
-     * Use for late-bound UI or session state access.
+     * Use for late-bound UI or session state access. The loop passes the tool
+     * call's {@link ToolCallContext}; hosts that support passive tool context
+     * surface its `addAdditionalContext` sink as
+     * {@link AgentToolContext.addAdditionalContext}. The returned object is
+     * handed to the tool as-is.
      */
     getToolContext?: (toolCall?: ToolCallContext) => AgentToolContext | undefined;
     /**
@@ -358,6 +368,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * model's text output back into canonical `toolCall` blocks.
      */
     dialect?: Dialect;
+    /**
+     * Per-call owned-dialect resolver, read once per LLM call with the model
+     * being requested. Authoritative when set: its return value (including
+     * `undefined` = native tool calling) replaces the static {@link dialect}.
+     */
+    getDialect?: (model: Model) => Dialect | undefined;
     /**
      * When owned (in-band) tool calling is active and the model starts
      * fabricating a tool result inside its own turn, control how the loop reacts:
@@ -535,6 +551,13 @@ export interface ToolCallContext {
      * always safe (the message injects at the next batch boundary).
      */
     steeringSignal?: AbortSignal;
+    /**
+     * Loop-owned sink for passive context reported while this call executes.
+     * Values join the call's context at the batch boundary and are injected
+     * after the batch's tool results, in assistant tool-call order, before the
+     * next provider request. Blank values are ignored.
+     */
+    addAdditionalContext?: (context: string) => void;
 }
 /** A single tool-call content block emitted by an assistant message. */
 export type AgentToolCall = Extract<AssistantMessage["content"][number], {
@@ -723,11 +746,19 @@ export interface SpeculativeToolExecutionConfig {
  * written back to the tool-call block on the assistant message, and seen by
  * history, scheduling, execution events, and `tool.execute` alike. It is
  * ignored when `block` is true.
+ *
+ * Set `additionalContext` to attach passive model-visible context to this call.
+ * Non-empty values from a tool batch are injected in assistant tool-call order
+ * after every result settles and before the next provider request. It is
+ * dropped when the call is blocked or skipped, or when its final result is an
+ * error (including an approval denial raised by the tool's own gate). Within a
+ * call it follows any context the tool reported during execution.
  */
 export interface BeforeToolCallResult {
     block?: boolean;
     reason?: string;
     args?: Record<string, unknown>;
+    additionalContext?: string;
 }
 /**
  * Partial override returned from `afterToolCall`.
@@ -874,6 +905,16 @@ export type ToolApproval = ToolApprovalDecision | ((args: unknown) => ToolApprov
  * Apps can extend via declaration merging.
  */
 export interface AgentToolContext {
+    /**
+     * Attach trusted, agent-authored instructions to the next provider request.
+     * The host emits them after tool results with developer/system priority where
+     * the selected transport supports it. Do not use this channel for raw tool
+     * output, retrieved documents, web content, or other untrusted data; return
+     * those through the ordinary tool result instead. Hosts populate it from
+     * {@link ToolCallContext.addAdditionalContext} (or their own collector for
+     * calls dispatched outside the loop); absent when the host has no sink.
+     */
+    addAdditionalContext?(context: string): void;
     /** Present only while the matching outer tool owns its finalized stream session. */
     [SPECULATIVE_STREAM_SESSION]?: ToolSpeculationStreamSession;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.3.0",
+	"version": "18.3.1",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -38,16 +38,16 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.3.0",
-		"@oh-my-pi/pi-catalog": "18.3.0",
-		"@oh-my-pi/pi-natives": "18.3.0",
-		"@oh-my-pi/pi-utils": "18.3.0",
-		"@oh-my-pi/pi-wire": "18.3.0",
-		"@oh-my-pi/snapcompact": "18.3.0",
+		"@oh-my-pi/pi-ai": "18.3.1",
+		"@oh-my-pi/pi-catalog": "18.3.1",
+		"@oh-my-pi/pi-natives": "18.3.1",
+		"@oh-my-pi/pi-utils": "18.3.1",
+		"@oh-my-pi/pi-wire": "18.3.1",
+		"@oh-my-pi/snapcompact": "18.3.1",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.3.0",
+		"@oh-my-pi/omptype": "18.3.1",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"