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

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [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
+
+- Added support for documenting agent tools on demand through the new `AgentTool.docTopics` method.
+- Added `TOOL_INTERRUPT_ABORT_REASON` so interruptible tools can distinguish queued steering, peer messages, or background completions from a full run abort.
+
+### Changed
+
+- Improved interrupt handling so tools respect wait mode and can be interrupted when appropriate.
+- Updated Anthropic compaction compatibility with signature verification.
+
 ## [18.2.11] - 2026-09-23
 
 ### Fixed

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.
 
@@ -293,7 +293,7 @@ MIT License
 Copyright (c) 2026 Sander Land
   (measured tokenizer vocabulary data, reconstruction model, and reference
   implementation: https://github.com/sanderland/ctok)
-Copyright (c) 2026 Can Bölük and the Oh My Pi contributors
+Copyright (c) 2026 Can Bölük and the omp contributors
 Copyright (c) 2026 Stencil Labs, Inc.
   (Rust implementation and the compact binary vocabulary encoding in
   crates/pi-natives/src/utok/claude)

package/dist/types/agent-loop.d.ts

@@ -32,6 +32,12 @@ export declare function createToolScopedAbortReason(message: string, toolCallMes
  * boundary; this reason stops after persisting the completed tool batch.
  */
 export declare const TERMINAL_TOOL_RESULT_ABORT_REASON: unique symbol;
+/**
+ * Abort reason carried by an interruptible tool's signal when queued steering,
+ * a peer IRC, or a background completion cut it short. Lets a wait tell the
+ * designed wake path apart from an external/user abort of the run.
+ */
+export declare const TOOL_INTERRUPT_ABORT_REASON: unique symbol;
 export declare function resolveOwnedDialectFromEnv(value: string | undefined): Dialect | undefined;
 /**
  * Start an agent loop with a new prompt message.

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/anthropic.d.ts

@@ -1,33 +1,21 @@
 /**
- * Anthropic server-side compaction (`compact-2026-01-12` beta).
+ * Anthropic on-demand compaction (`compact-2026-09-04` beta).
  *
- * The compaction request is the live turn's own request shape — same system
- * prompt, tools, and message history — plus the `compact_20260112` edit with
- * `pause_after_compaction`. The API summarizes the prompt from the already
- * cached prefix and stops; the summary arrives as a `compaction` block that
- * the provider surfaces as an `anthropicCompaction` payload. The summary is
- * plain text, so it doubles as the compaction entry's readable summary for
- * every other provider, while the Anthropic provider replays it as a native
- * block (the API drops everything that precedes it). The retained tail after
- * the cut point is replayed from session entries exactly like a local summary.
+ * The request sends only the prefix to summarize, with the live conversation's
+ * system prompt, tools and thinking settings. The returned signed block
+ * replaces that prefix; the retained tail is replayed from session entries.
  */
 import type { AnthropicCompactionPayload, ApiKey, Effort, Message, Model, SimpleStreamOptions, Tool, Usage } from "@oh-my-pi/pi-ai";
 import { type InstrumentedChatSpanOptions } from "../telemetry.js";
+import type { AgentMessage } from "../types.js";
 export declare const ANTHROPIC_COMPACTION_PRESERVE_KEY = "anthropicCompaction";
-/** The API rejects a `compact_20260112` trigger below this many input tokens. */
-export declare const ANTHROPIC_COMPACTION_MIN_TRIGGER_TOKENS = 50000;
-/**
- * Smallest context the native lane accepts. The trigger sits at the API
- * floor, so a prompt that lands below it is answered instead of compacted;
- * the margin over the floor absorbs the difference between the last reported
- * context size and the compaction request's own input.
- */
-export declare const ANTHROPIC_COMPACTION_MIN_CONTEXT_TOKENS = 55000;
 /** Summary persisted under {@link ANTHROPIC_COMPACTION_PRESERVE_KEY}. */
 export interface AnthropicCompactionPreserveData {
     provider: string;
     content: string;
-    /** Opaque provider state the API attached to the block; replayed verbatim. */
+    /** Signature attached to an on-demand block; replayed verbatim. */
+    signature?: string;
+    /** Legacy threshold block state; replay-only. */
     encryptedContent?: string;
     /** Harness file metadata (`<files>` section) replayed after the native block. */
     filesText?: string;
@@ -51,33 +39,17 @@ export declare function withAnthropicCompactionPreserveData(preserveData: Record
 /** Replay payload for a compaction summary the active model produced natively. */
 export declare function getAnthropicCompactionPayload(preserveData: Record<string, unknown> | undefined): AnthropicCompactionPayload | undefined;
 /**
- * The retained tail as the model will see it, for the summarization
- * instructions: how many of the conversation's final wire messages stay in
- * context verbatim, and the role of the first. The compaction request carries
- * the whole conversation so the prompt cache the live turn wrote is read, but
- * the summary must cover only the history before that tail — the local
- * summarizer never sees the tail, and the rebuilt context replays it after the
- * summary. Counting mirrors the provider's message conversion (consecutive
- * tool results collapse into one user message; developer messages are user
- * messages). Structured for the prompt template, which renders the
- * singular/plural wording; the description quotes no content: quoting the
- * tail would hand the summarizer the very facts it must leave to the tail.
+ * Move the existing keep-tail boundary forward until the summary/tail boundary
+ * alternates wire roles and no tool call is separated from its result. If no
+ * boundary is safe, the request summarizes the entire snapshot (empty tail).
  */
-export interface RetainedTailScope {
-    count: number;
-    role: "assistant" | "user";
-}
-export declare function describeRetainedTail(messages: readonly Message[]): RetainedTailScope | undefined;
-/**
- * Summarization prompt sent as the edit's `instructions`, which replace the
- * API default entirely. The template lays out the retained-tail boundary
- * first, so the summary covers only the history the rebuilt context drops,
- * then the caller's extra context, the same structure prompt as the local
- * summarizer, the caller's focus, and the tool-abstention clause the API
- * recommends when tools are defined (a summarization pass that calls a tool
- * yields no summary).
- */
-export declare function buildAnthropicCompactionInstructions(basePrompt: string, customInstructions: string | undefined, extraContext: string | undefined, retainedTail: RetainedTailScope | undefined): string;
+export declare function findAnthropicCompactionCut(messages: readonly (AgentMessage | {
+    role: "system";
+    content: string;
+    timestamp: number;
+})[], initialCut: number): number;
+/** Instructions replace the API default; the request contains only summarized messages. */
+export declare function buildAnthropicCompactionInstructions(basePrompt: string, customInstructions: string | undefined, extraContext: string | undefined): string;
 export interface AnthropicNativeCompactionRequest {
     systemPrompt: string[];
     messages: Message[];
@@ -88,21 +60,19 @@ export interface AnthropicNativeCompactionRequest {
 }
 export interface AnthropicNativeCompactionResponse {
     content: string;
-    encryptedContent?: string;
+    signature: string;
     usage: Usage;
     model: string;
 }
 export interface AnthropicNativeCompactionOptions extends Pick<SimpleStreamOptions, "initiatorOverride" | "metadata" | "fetch" | "sessionId" | "promptCacheKey" | "providerSessionState" | "maxInFlightRequests">, Pick<InstrumentedChatSpanOptions, "completeImpl" | "telemetry" | "retry"> {
 }
 /**
- * Run one compaction request and return the summary the API wrote, with the
- * opaque `encrypted_content` the API attached for the replay. `completeSimple`
+ * Run one compaction request and return the summary and signature the API wrote. `completeSimple`
  * resolves terminal failures as messages, so their classification is restored
  * here: an aborted response is an `AbortError` (a cancellation, never a native
  * failure) and an error response keeps its HTTP status, so auth and timeout
  * handling downstream classify it the same way as the OpenAI lanes. A response
- * without a summary is a native failure — the API answers the prompt instead
- * when its input never reached the trigger, and returns an empty block when
- * the model called a tool during summarization.
+ * without a summary is a native failure, including tool use, refusals and
+ * output limits; the configured method order can then choose a fallback.
  */
 export declare function requestAnthropicNativeCompaction(model: Model<"anthropic-messages">, apiKey: ApiKey, request: AnthropicNativeCompactionRequest, signal: AbortSignal | undefined, options: AnthropicNativeCompactionOptions): Promise<AnthropicNativeCompactionResponse>;

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

@@ -297,6 +297,8 @@ export interface CompactionPreparation {
     turnPrefixMessages: AgentMessage[];
     /** Messages kept in full after compaction (recent history) */
     recentMessages: AgentMessage[];
+    /** Entry IDs parallel to recentMessages, for an Anthropic-safe keep-tail boundary. */
+    recentEntryIds?: string[];
     /** Whether this is a split turn (cut point in middle of turn) */
     isSplitTurn: boolean;
     tokensBefore: number;

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,13 +2,16 @@ 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";
 export * from "./run-collector.js";
+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/sent-tool-definitions.d.ts

@@ -0,0 +1,17 @@
+import type { Message, Tool } from "@oh-my-pi/pi-ai";
+/**
+ * Last wire definition this Agent sent for each tool name, so a provider that keeps
+ * withdrawn tools declared (Anthropic `tool_removal`) can re-declare them byte-identically.
+ * Used by prepareProviderCall and Agent.buildSideRequestContext.
+ */
+export declare class SentToolDefinitions {
+    #private;
+    /** Remember the definitions a request is about to send. */
+    record(tools: readonly Tool[]): void;
+    /**
+     * Definitions for names the latest `requestControls.tools.declared` in `messages` holds
+     * that are not in `active`; undefined when none. Names never sent by this Agent are
+     * skipped: the provider drops them from the declaration.
+     */
+    inactiveFor(messages: readonly Message[], active: readonly Tool[]): Tool[] | 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

@@ -3,6 +3,7 @@ import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context.js";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector.js";
+import type { SentToolDefinitions } from "./sent-tool-definitions.js";
 import type { AgentTelemetryConfig } from "./telemetry.js";
 /** Stream function - can return sync or Promise for async config lookup */
 export type StreamFn = (...args: Parameters<typeof streamSimple>) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
@@ -35,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;
 }
@@ -117,8 +124,10 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     model: Model;
     /**
      * When to interrupt tool execution for steering messages.
-     * - "immediate" = check after each tool call (default)
-     * - "wait" = defer steering until the current turn completes
+     * - "immediate" = cut interruptible waits short and raise the cooperative
+     *   `steeringSignal` for other running tools (default)
+     * - "wait" = let non-interruptible tools finish undisturbed; interruptible
+     *   waits are still cut short, since they have no work to complete
      */
     interruptMode?: "immediate" | "wait";
     /**
@@ -185,6 +194,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * and provider send.
      */
     transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
+    /** Remembers sent tool definitions to fill {@link Context.inactiveTools}. */
+    sentToolDefinitions?: SentToolDefinitions;
     /**
      * Resolves the API key or resolver for the current model before each LLM call.
      *
@@ -204,8 +215,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     /**
      * Peeks whether steering messages are queued, without consuming them.
      *
-     * Polled while a tool batch runs (unless interruptMode is "wait") to decide
-     * whether to abort in-flight and skip not-yet-started *interruptible* waits;
+     * Polled while a tool batch runs (in "wait" mode, only when the batch holds an
+     * interruptible tool) to decide whether to abort in-flight and skip
+     * not-yet-started *interruptible* waits;
      * every other already-emitted call still executes and the message injects
      * at the batch boundary. The queue keeps
      * owning its messages until the loop reaches the next injection boundary and
@@ -232,7 +244,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Peeks whether IRC messages should interrupt an interruptible waiting tool.
      *
      * Uses the same delivery rules as steering: the poll is non-consuming, only
-     * runs for interruptible tools, and is ignored when interruptMode is "wait".
+     * runs for interruptible tools, and cuts them short even when interruptMode
+     * is "wait".
      * The host owns message injection at the next boundary.
      */
     hasIrcInterrupts?: () => boolean | Promise<boolean>;
@@ -241,8 +254,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * process) is queued for aside injection at the next boundary.
      *
      * Same rules as {@link hasIrcInterrupts}: non-consuming, only cuts
-     * *interruptible* waits short, ignored when interruptMode is "wait". Without
-     * it a completion notice sits behind an hour-long `hub wait` that the agent
+     * *interruptible* waits short, in either interruptMode. Without
+     * it a completion notice sits behind an hour-long `wait` that the agent
      * would have abandoned had it seen the notice. Unlike a peer IRC it never
      * raises {@link ToolCallContext.steeringSignal}: a queued completion must
      * not push ordinary foreground work (auto-background bash/eval) into the
@@ -277,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;
     /**
@@ -351,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:
@@ -528,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], {
@@ -716,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`.
@@ -867,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;
 }
@@ -903,6 +951,12 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
     loadMode?: ToolLoadMode;
     /** Short one-line summary used for tool discovery indexes. */
     summary?: string;
+    /**
+     * On-demand documentation topics (`topic → markdown`), readable as
+     * `xd://<tool>/<topic>`. Lets a tool keep large sub-surfaces out of its
+     * description and advertise only a one-line pointer per topic.
+     */
+    docTopics?(): Readonly<Record<string, string>>;
     /**
      * Concurrency mode for tool scheduling when multiple calls are in one turn.
      * - "shared": can run alongside other shared tools (default)
@@ -926,7 +980,7 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
      * cleanly (e.g. `job` poll), so the abort surfaces the tool's current
      * snapshot rather than corrupting a side effect. Every other call runs to
      * completion even when steering is queued; the message lands at the next
-     * batch boundary. Honored only when `interruptMode` is "immediate".
+     * batch boundary. Honored in both `interruptMode`s.
      */
     interruptible?: boolean | ((args: Partial<Static<TParameters>>) => boolean);
     /**

package/package.json

@@ -1,10 +1,13 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.2.11",
+	"version": "18.3.1",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
-	"author": "Stencil Labs, Inc.",
+	"author": {
+		"name": "Stencil Labs, Inc.",
+		"url": "https://stencil.so"
+	},
 	"contributors": [
 		"Mario Zechner"
 	],
@@ -35,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.2.11",
-		"@oh-my-pi/pi-catalog": "18.2.11",
-		"@oh-my-pi/pi-natives": "18.2.11",
-		"@oh-my-pi/pi-utils": "18.2.11",
-		"@oh-my-pi/pi-wire": "18.2.11",
-		"@oh-my-pi/snapcompact": "18.2.11",
+		"@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.2.11",
+		"@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"