@linxiraos/pi-agent-core 1.1.19 → 1.1.22

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

@@ -33,6 +33,8 @@ export interface TrimRemoteCompactionInputResult {
     rewrittenOutputs: number;
     estimatedTokensBefore: number;
     estimatedTokensAfter: number;
+    /** Whether `input` fits the model window; false means it must not be sent. */
+    fits: boolean;
 }
 /**
  * Preserve the full native transcript unless trailing tool outputs alone push a
@@ -41,6 +43,15 @@ export interface TrimRemoteCompactionInputResult {
  * matching Codex's recovery path for oversized tool turns.
  */
 export declare function trimRemoteCompactionInputToContextWindow(input: Array<Record<string, unknown>>, tokenizer: Tokenizer, contextWindow: number | null | undefined, instructions: string, tools?: unknown[]): TrimRemoteCompactionInputResult;
+/**
+ * Refuse a native compaction request whose prepared input cannot fit the model
+ * window, before any network I/O. Re-expanded history behind an unreadable
+ * native boundary can exceed the window even when live context does not.
+ *
+ * @throws Error flagged `ContextOverflow` when `trimmed.fits` is false, so
+ *   compaction callers skip retries and advance to the next method.
+ */
+export declare function assertRemoteCompactionInputFits(trimmed: TrimRemoteCompactionInputResult, model: Model): void;
 export type OpenAiRemoteCompactionItem = {
     type: "compaction" | "compaction_summary";
     encrypted_content?: string;

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

@@ -82,6 +82,15 @@ export interface SupersedePruneConfig {
     /** Tool-result protection matchers (same contract as {@link PruneConfig.protectedTools}). */
     protectedTools: ProtectedToolMatcher[];
 }
+/**
+ * Generic age-based pruning floor. Below this, blanking a result to
+ * `[Output truncated - N tokens]` recovers nothing — the placeholder itself
+ * costs ~8 tokens, so a sub-floor result grows the context (and churns the
+ * prompt cache) instead of shrinking it. Superseded/useless results keep their
+ * own rules: useless already drops no-savings candidates, superseded prunes for
+ * correctness regardless of size.
+ */
+export declare const MIN_PRUNE_TOKENS = 50;
 /**
  * Prune superseded tool results (e.g. stale `read` outputs replaced by a newer
  * read of the same file) and, when `pruneUseless` is set, results their tool

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 "@linxiraos/pi-ai";
+import type { AssistantMessage, Message } from "@linxiraos/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. */
@@ -37,6 +37,14 @@ export interface TranscriptUsageAnchor {
  * the session-entry walkers.
  */
 export declare function isTranscriptUsageAnchor(message: AgentMessage): message is AssistantMessage;
+/** Options for {@link findTranscriptUsageAnchor}. */
+export interface TranscriptUsageAnchorOptions {
+    /**
+     * Also treat usage reported at or before the newest `prunedAt` as stale,
+     * the same rule {@link findRequestUsageAnchor} applies to request contexts.
+     */
+    skipPrunedAnchors?: boolean;
+}
 /**
  * Newest assistant turn in `messages[fromIndex..]` whose usage can anchor the
  * transcript, or `undefined` when none qualifies (fresh context, or every
@@ -45,7 +53,20 @@ export declare function isTranscriptUsageAnchor(message: AgentMessage): message
  * `fromIndex` excludes turns whose usage is stale — anything a compaction
  * summarized away describes a prompt that is no longer sent.
  */
-export declare function findTranscriptUsageAnchor(messages: readonly AgentMessage[], fromIndex?: number): TranscriptUsageAnchor | undefined;
+export declare function findTranscriptUsageAnchor(messages: readonly AgentMessage[], fromIndex?: number, options?: TranscriptUsageAnchorOptions): 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 {
     /**
@@ -54,6 +75,8 @@ export interface TranscriptTokenOptions {
      * accounting is governed separately by {@link countFromIndex}.
      */
     anchorFromIndex?: number;
+    /** Forwarded to {@link findTranscriptUsageAnchor}. */
+    skipPrunedAnchors?: boolean;
     /**
      * First message whose content is counted locally when no anchor is found.
      * Defaults to 0 (count the whole transcript), which is what a floor

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 "@linxiraos/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,54 @@
+import type { Context, Model } from "@linxiraos/pi-ai";
+import type { Tokenizer } from "./tokenizer.js";
+/** Smallest output cap {@link fitOutputTokensToContextWindow} will request. */
+export declare const MIN_FITTED_OUTPUT_TOKENS = 1024;
+/**
+ * Absolute headway subtracted from the remaining room (unconditionally, on anchored and
+ * fully-local counts alike). Proportional padding covers
+ * tokenizer drift that scales with the prompt, but a host can still count a few tokens more
+ * than any local estimate can see (chat-template framing, reasoning wrappers). Measured
+ * against a 262,144-token host: fitted caps landed +11 to +42 tokens over and were rejected
+ * with 400s. 64 tokens covers the observed drift with margin to spare; the
+ * {@link MIN_FITTED_OUTPUT_TOKENS} floor still applies.
+ */
+export declare const OUTPUT_FIT_HEADWAY_TOKENS = 64;
+/**
+ * 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 minus {@link OUTPUT_FIT_HEADWAY_TOKENS} (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 "@linxiraos/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/speculative-execution.d.ts

@@ -1,5 +1,5 @@
 import { type AssistantMessage } from "@linxiraos/pi-ai";
-import type { AgentContext, AgentLoopConfig, AgentTool, AgentToolCall, AgentToolResult, SpeculativeChildDefinition, SpeculativeChildHandle, SpeculativeToolExecutionConfig, ToolSpeculationEffect, ToolSpeculationStreamSession } from "./types.js";
+import type { AgentContext, AgentLoopConfig, AgentTool, AgentToolCall, AgentToolResult, SpeculativeAuthorization, SpeculativeChildDefinition, SpeculativeChildHandle, SpeculativeLaunchContext, SpeculativeToolExecutionConfig, ToolSpeculationEffect, ToolSpeculationStreamSession } from "./types.js";
 export type SpeculativeRawOutcome = {
     result: AgentToolResult<unknown>;
     isError: boolean;
@@ -55,6 +55,7 @@ export declare class SpeculativeOperationCoordinator {
      */
     directExecutionArgsFor(toolCallId: string, rawArgs: Readonly<Record<string, unknown>>): Record<string, unknown> | undefined;
     reconcileFinalCalls(calls: ReadonlyMap<string, AgentToolCall>): Promise<void>;
+    authorizeLaunch(context: SpeculativeLaunchContext): Promise<SpeculativeAuthorization>;
     discardChildren(parentToolCallId: string, reason: string): Promise<void>;
     claim(tool: AgentTool | undefined, toolCall: AgentToolCall, args: Record<string, unknown>): Promise<SpeculativeRawOutcome | undefined>;
     admitFinalized(context: AgentContext, toolCall: AgentToolCall, loopConfig: AgentLoopConfig, signal: AbortSignal | undefined): void;

package/dist/types/telemetry.d.ts

@@ -2,7 +2,7 @@
  * OpenTelemetry instrumentation for the agent loop.
  *
  * Implements the OpenTelemetry GenAI semantic conventions
- * (https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus `pi.gen_ai.*`
+ * (https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus `omp.gen_ai.*`
  * extension attributes for run summaries, dashboard summaries, and cost hints
  * that are useful to downstream observability UIs.
  *
@@ -78,35 +78,41 @@ export declare const enum OpenAIAttr {
     ResponseServiceTier = "openai.response.service_tier"
 }
 /** Project extension attributes. Kept out of the reserved `gen_ai.*` namespace. */
-export declare const enum PiGenAIAttr {
-    AgentStepNumber = "pi.gen_ai.agent.step.number",
-    AgentStepCount = "pi.gen_ai.agent.step.count",
-    RequestReasoningEffort = "pi.gen_ai.request.reasoning.effort",
-    RequestToolChoice = "pi.gen_ai.request.tool.choice",
-    RequestAvailableTools = "pi.gen_ai.request.available_tools",
-    RequestMessages = "pi.gen_ai.request.messages",
-    ResponseText = "pi.gen_ai.response.text",
-    ResponseToolCalls = "pi.gen_ai.response.tool_calls",
-    ResponseUpstreamProvider = "pi.gen_ai.response.upstream_provider",
-    UsageTotalTokens = "pi.gen_ai.usage.total_tokens",
-    UsageServerSideTools = "pi.gen_ai.usage.server_tool_requests",
-    CostEstimatedUsd = "pi.gen_ai.cost.estimated_usd",
-    CostInputUsd = "pi.gen_ai.cost.input_usd",
-    CostOutputUsd = "pi.gen_ai.cost.output_usd",
-    CostUnavailableReason = "pi.gen_ai.cost.unavailable_reason",
-    ToolStatus = "pi.gen_ai.tool.status",
-    ToolCallIntent = "pi.gen_ai.tool.call.intent",
-    HandoffFromAgentName = "pi.gen_ai.handoff.from_agent.name",
-    HandoffFromAgentId = "pi.gen_ai.handoff.from_agent.id",
-    HandoffToAgentName = "pi.gen_ai.handoff.to_agent.name",
-    HandoffToAgentId = "pi.gen_ai.handoff.to_agent.id",
-    OneshotKind = "pi.gen_ai.oneshot.kind",
-    GatewayName = "pi.gen_ai.gateway.name",
-    GatewayEndpoint = "pi.gen_ai.gateway.endpoint",
-    GatewayCallId = "pi.gen_ai.gateway.call_id",
-    GatewayRoutedTo = "pi.gen_ai.gateway.routed_to",
+export declare const enum OmpGenAIAttr {
+    AgentStepNumber = "omp.gen_ai.agent.step.number",
+    AgentStepCount = "omp.gen_ai.agent.step.count",
+    RequestReasoningEffort = "omp.gen_ai.request.reasoning.effort",
+    RequestToolChoice = "omp.gen_ai.request.tool.choice",
+    RequestAvailableTools = "omp.gen_ai.request.available_tools",
+    RequestMessages = "omp.gen_ai.request.messages",
+    ResponseText = "omp.gen_ai.response.text",
+    ResponseToolCalls = "omp.gen_ai.response.tool_calls",
+    ResponseUpstreamProvider = "omp.gen_ai.response.upstream_provider",
+    UsageTotalTokens = "omp.gen_ai.usage.total_tokens",
+    UsageServerSideTools = "omp.gen_ai.usage.server_tool_requests",
+    CostEstimatedUsd = "omp.gen_ai.cost.estimated_usd",
+    CostInputUsd = "omp.gen_ai.cost.input_usd",
+    CostOutputUsd = "omp.gen_ai.cost.output_usd",
+    CostUnavailableReason = "omp.gen_ai.cost.unavailable_reason",
+    ToolStatus = "omp.gen_ai.tool.status",
+    ToolCallIntent = "omp.gen_ai.tool.call.intent",
+    HandoffFromAgentName = "omp.gen_ai.handoff.from_agent.name",
+    HandoffFromAgentId = "omp.gen_ai.handoff.from_agent.id",
+    HandoffToAgentName = "omp.gen_ai.handoff.to_agent.name",
+    HandoffToAgentId = "omp.gen_ai.handoff.to_agent.id",
+    OneshotKind = "omp.gen_ai.oneshot.kind",
+    GatewayName = "omp.gen_ai.gateway.name",
+    GatewayEndpoint = "omp.gen_ai.gateway.endpoint",
+    GatewayCallId = "omp.gen_ai.gateway.call_id",
+    GatewayRoutedTo = "omp.gen_ai.gateway.routed_to",
     /** Cloudflare AI Gateway response-cache status (`cf-aig-cache-status`), never prompt-cache. */
-    GatewayResponseCacheStatus = "pi.gen_ai.gateway.response_cache.status"
+    GatewayResponseCacheStatus = "omp.gen_ai.gateway.response_cache.status",
+    /** Caller-level reason a judgment ran (`find`, `ttsr`, `judge_batch`, …). */
+    JudgmentPurpose = "omp.gen_ai.judgment.purpose",
+    /** Questions the caller asked in one judgment request. */
+    JudgmentQuestions = "omp.gen_ai.judgment.questions",
+    /** Questions answered from the local judgment cache instead of the provider. */
+    JudgmentCachedQuestions = "omp.gen_ai.judgment.cached_questions"
 }
 /** GenAI operation names — values for {@link GenAIAttr.OperationName}. */
 export declare const GenAIOperation: {
@@ -114,6 +120,8 @@ export declare const GenAIOperation: {
     readonly ExecuteTool: "execute_tool";
     readonly InvokeAgent: "invoke_agent";
     readonly Handoff: "handoff";
+    /** Typed judgment over a state (System One or a prompted judge model); a project extension value. */
+    readonly Judgment: "judgment";
     readonly GenerateContent: "generate_content";
     readonly TextCompletion: "text_completion";
     readonly CreateAgent: "create_agent";
@@ -121,7 +129,7 @@ export declare const GenAIOperation: {
 };
 export type GenAIOperationName = (typeof GenAIOperation)[keyof typeof GenAIOperation];
 /** Identifies which agent span a callback is reporting on. */
-export type TelemetrySpanKind = "invoke_agent" | "chat" | "execute_tool" | "handoff";
+export type TelemetrySpanKind = "invoke_agent" | "chat" | "execute_tool" | "handoff" | "judgment";
 /**
  * Aggregated usage + cost surface passed to {@link AgentTelemetryConfig.costEstimator}.
  * Mirrors the bucketed shape we already emit as span attributes so the
@@ -144,9 +152,9 @@ export interface CostEstimatorContext {
 }
 /**
  * Cost estimator result.
- *   { usd: number }                — cost is known; emitted as pi.gen_ai.cost.estimated_usd
+ *   { usd: number }                — cost is known; emitted as omp.gen_ai.cost.estimated_usd
  *   { unavailable: string }        — cost is intentionally unknown; emitted as
- *                                    pi.gen_ai.cost.unavailable_reason
+ *                                    omp.gen_ai.cost.unavailable_reason
  *   undefined                      — no opinion; nothing emitted
  */
 export type CostEstimate = {
@@ -177,6 +185,8 @@ export interface CostDelta {
  */
 export interface ChatUsageEvent {
     readonly span: Span;
+    /** Operation that produced the usage: `chat` for model turns, `judgment` for typed judgments. */
+    readonly operation: GenAIOperationName;
     readonly agent: AgentIdentity | undefined;
     readonly conversationId: string | undefined;
     readonly stepNumber: number | undefined;
@@ -195,7 +205,7 @@ export interface ChatUsageEvent {
      *
      * Use this to reconcile gateway-issued ids (e.g. `x-litellm-call-id`) with
      * downstream billing / spend dashboards. Known gateway patterns are also
-     * auto-stamped on the chat span as `pi.gen_ai.gateway.*` attributes.
+     * auto-stamped on the chat span as `omp.gen_ai.gateway.*` attributes.
      */
     readonly headers: Readonly<Record<string, string>> | undefined;
 }
@@ -417,7 +427,7 @@ export interface GatewayHeaderDetection {
 export declare function detectGatewayFromHeaders(headers: Readonly<Record<string, string>> | undefined): GatewayHeaderDetection | undefined;
 /**
  * Bounded Cloudflare AI Gateway response-cache statuses emitted on
- * {@link PiGenAIAttr.GatewayResponseCacheStatus}. Distinct from provider
+ * {@link OmpGenAIAttr.GatewayResponseCacheStatus}. Distinct from provider
  * prompt-cache token counters (`gen_ai.usage.cache_*`).
  *
  * Cloudflare documents `HIT` / `MISS` on `cf-aig-cache-status`; `bypass` covers
@@ -453,6 +463,39 @@ export interface ManualChatTelemetryOptions {
     readonly endSpan?: boolean;
 }
 export declare function recordManualChatTelemetry(telemetry: AgentTelemetry | undefined, options: ManualChatTelemetryOptions): Promise<Span | undefined>;
+/**
+ * One judgment attempt reported to {@link recordJudgmentTelemetry}: a billed
+ * System One request, one prompted-model attempt, or a request answered
+ * entirely from the local judgment cache.
+ */
+export interface JudgmentTelemetryOptions {
+    readonly provider: string;
+    /** Requested model id. */
+    readonly model: string;
+    /** Model that answered, when the provider resolves an alias (`jev-latest` → `jev-1.13.0`). */
+    readonly responseModel?: string;
+    /** Caller-level reason the judgment ran; stamped as {@link OmpGenAIAttr.JudgmentPurpose}. */
+    readonly purpose: string;
+    /** Priced usage of this attempt — the same amount the session ledger bills. */
+    readonly usage: Usage;
+    readonly stopReason: StopReason;
+    readonly errorMessage?: string;
+    /** Epoch ms the attempt started. */
+    readonly startTime: number;
+    /** Questions in the request; omitted for prompted backends, which report per completion attempt. */
+    readonly questions?: number;
+    /** Questions answered from the local cache rather than the provider. */
+    readonly cachedQuestions?: number;
+}
+/**
+ * Emit one `judgment` span per judgment attempt and forward any billed usage
+ * to `onCostDelta` / `onChatUsage` with `operation: "judgment"`. Cost is the
+ * attempt's own priced usage rather than {@link AgentTelemetryConfig.costEstimator},
+ * so spans, metrics, and the session ledger agree on every judgment dollar.
+ * Attempts that billed nothing (cache hits, pre-response failures) keep their
+ * span but fire no usage hooks. No-op when telemetry is disabled.
+ */
+export declare function recordJudgmentTelemetry(telemetry: AgentTelemetry | undefined, options: JudgmentTelemetryOptions): Promise<void>;
 /**
  * Options accepted by {@link instrumentedCompleteSimple}. Mirrors the
  * `streamAssistantResponse` chat-span lifecycle for oneshot LLM calls
@@ -465,7 +508,7 @@ export interface InstrumentedChatSpanOptions {
     /** Step index recorded on the span; defaults to `-1` for non-loop calls. */
     readonly stepNumber?: number;
     /**
-     * Tag stamped onto `pi.gen_ai.oneshot.kind`. Values used by the agent:
+     * Tag stamped onto `omp.gen_ai.oneshot.kind`. Values used by the agent:
      * `compaction_summary`, `compaction_short_summary`, `compaction_turn_prefix`,
      * `handoff`, `branch_summary`, `image_question`. Free-form to allow callers
      * outside this package to add new kinds without bumping the helper.
@@ -535,7 +578,7 @@ export declare function finishExecuteToolSpan(telemetry: AgentTelemetry | undefi
     readonly toolName: string;
 }): void;
 /** Span attribute carrying the terminal {@link ToolStatus}. */
-export declare const EXECUTE_TOOL_STATUS_ATTR = PiGenAIAttr.ToolStatus;
+export declare const EXECUTE_TOOL_STATUS_ATTR = OmpGenAIAttr.ToolStatus;
 /**
  * Record a tool that bypassed the span lifecycle entirely (pre-run
  * interrupt, post-execution tail sweep for calls that never produced a
@@ -570,30 +613,30 @@ export declare function finishInvokeAgentSpan(telemetry: AgentTelemetry | undefi
  * calling this helper.
  */
 export declare function fireOnRunEnd(telemetry: AgentTelemetry, summary: AgentRunSummary, coverage: AgentRunCoverage): void;
-/** Aggregate `pi.gen_ai.agent.*` attributes stamped on the `invoke_agent` span. */
-export declare const enum PiGenAIAggregateAttr {
-    ChatsCount = "pi.gen_ai.agent.chats.count",
-    ChatsTotalLatencyMs = "pi.gen_ai.agent.chats.total_latency_ms",
-    ChatsStopReasonPrefix = "pi.gen_ai.agent.chats.stop_reason.",
-    ToolsCount = "pi.gen_ai.agent.tools.count",
-    ToolsOkCount = "pi.gen_ai.agent.tools.ok.count",
-    ToolsErrorCount = "pi.gen_ai.agent.tools.error.count",
-    ToolsSkippedCount = "pi.gen_ai.agent.tools.skipped.count",
-    ToolsBlockedCount = "pi.gen_ai.agent.tools.blocked.count",
-    ToolsTimeoutCount = "pi.gen_ai.agent.tools.timeout.count",
-    ToolsAbortedCount = "pi.gen_ai.agent.tools.aborted.count",
-    ToolsTotalLatencyMs = "pi.gen_ai.agent.tools.total_latency_ms",
-    ToolsInvoked = "pi.gen_ai.agent.tools.invoked",
-    ToolsAvailable = "pi.gen_ai.agent.tools.available",
-    ToolsUnused = "pi.gen_ai.agent.tools.unused",
-    UsageInputTokensTotal = "pi.gen_ai.agent.usage.input_tokens.total",
-    UsageOutputTokensTotal = "pi.gen_ai.agent.usage.output_tokens.total",
-    UsageCacheReadInputTokensTotal = "pi.gen_ai.agent.usage.cache_read.input_tokens.total",
-    UsageCacheCreationInputTokensTotal = "pi.gen_ai.agent.usage.cache_creation.input_tokens.total",
-    UsageReasoningOutputTokensTotal = "pi.gen_ai.agent.usage.reasoning.output_tokens.total",
-    UsageTotalTokensTotal = "pi.gen_ai.agent.usage.total_tokens.total",
-    CostEstimatedUsdTotal = "pi.gen_ai.agent.cost.estimated_usd.total",
-    ErrorsCount = "pi.gen_ai.agent.errors.count"
+/** Aggregate `omp.gen_ai.agent.*` attributes stamped on the `invoke_agent` span. */
+export declare const enum OmpGenAIAggregateAttr {
+    ChatsCount = "omp.gen_ai.agent.chats.count",
+    ChatsTotalLatencyMs = "omp.gen_ai.agent.chats.total_latency_ms",
+    ChatsStopReasonPrefix = "omp.gen_ai.agent.chats.stop_reason.",
+    ToolsCount = "omp.gen_ai.agent.tools.count",
+    ToolsOkCount = "omp.gen_ai.agent.tools.ok.count",
+    ToolsErrorCount = "omp.gen_ai.agent.tools.error.count",
+    ToolsSkippedCount = "omp.gen_ai.agent.tools.skipped.count",
+    ToolsBlockedCount = "omp.gen_ai.agent.tools.blocked.count",
+    ToolsTimeoutCount = "omp.gen_ai.agent.tools.timeout.count",
+    ToolsAbortedCount = "omp.gen_ai.agent.tools.aborted.count",
+    ToolsTotalLatencyMs = "omp.gen_ai.agent.tools.total_latency_ms",
+    ToolsInvoked = "omp.gen_ai.agent.tools.invoked",
+    ToolsAvailable = "omp.gen_ai.agent.tools.available",
+    ToolsUnused = "omp.gen_ai.agent.tools.unused",
+    UsageInputTokensTotal = "omp.gen_ai.agent.usage.input_tokens.total",
+    UsageOutputTokensTotal = "omp.gen_ai.agent.usage.output_tokens.total",
+    UsageCacheReadInputTokensTotal = "omp.gen_ai.agent.usage.cache_read.input_tokens.total",
+    UsageCacheCreationInputTokensTotal = "omp.gen_ai.agent.usage.cache_creation.input_tokens.total",
+    UsageReasoningOutputTokensTotal = "omp.gen_ai.agent.usage.reasoning.output_tokens.total",
+    UsageTotalTokensTotal = "omp.gen_ai.agent.usage.total_tokens.total",
+    CostEstimatedUsdTotal = "omp.gen_ai.agent.cost.estimated_usd.total",
+    ErrorsCount = "omp.gen_ai.agent.errors.count"
 }
 /**
  * Run `fn` with `span` activated on the OTEL context. Spans created

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

@@ -0,0 +1,32 @@
+import type { ToolResultMessage } from "@linxiraos/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 and repeats of an
+ * earlier value (compared without surrounding whitespace; the first original
+ * is kept). 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;