@linxiraos/pi-agent-core 1.1.26 → 1.2.0

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

@@ -1,10 +1,29 @@
 /**
  * Tool output pruning utilities for compaction.
  */
+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. */
@@ -18,6 +37,8 @@ export interface PruneConfig {
      * unchanged.
      */
     supersedeKey?: SupersedeKeyFn;
+    /** Whether a keyed result shows its whole target (see {@link SupersedePruneConfig.supersedeComplete}). */
+    supersedeComplete?: SupersedeCompleteFn;
     /** Useless-flagged results bypass the protect window (see {@link USELESS_NOTICE}). Default true. */
     pruneUseless?: boolean;
     /**
@@ -34,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;
@@ -56,18 +78,42 @@ export declare const SUPERSEDED_NOTICE = "[Superseded by a newer read of this fi
 export declare const USELESS_NOTICE = "[Uneventful result elided]";
 /**
  * Maps a tool call to a supersede key. Results sharing a key form a group in
- * which every result except the newest is a supersede candidate. A key `K`
- * additionally supersedes keys with prefix `K + "\u0000"` (selector-free read
- * supersedes selector-carrying reads of the same base path). Return
- * `undefined` to exempt a call from supersede grouping.
+ * which a newer successful result supersedes every older one. A key `K` also
+ * covers keys with prefix `K + "\u0000"`: they are superseded only when the
+ * newest successful result for `K` is complete (see
+ * {@link SupersedeCompleteFn}). Return `undefined` to exempt a call from
+ * supersede grouping.
  */
 export type SupersedeKeyFn = (toolName: string, args: Record<string, unknown>) => string | undefined;
-export interface SupersedePruneConfig {
-    /** Supersede key function; results sharing a key supersede older ones. */
+/**
+ * Whether a successful keyed result shows its whole target, so a result for a
+ * parent key (e.g. a selector-free read) may supersede child-key results (e.g.
+ * range reads). A summary, truncated page, or notice is not complete.
+ */
+export type SupersedeCompleteFn = (message: ToolResultMessage) => boolean;
+export interface SupersedePruneConfig extends CacheLookbackConfig {
+    /** Supersede key function; a newer successful result with the same key supersedes older ones (see {@link SupersedeKeyFn}). */
     supersedeKey?: SupersedeKeyFn;
+    /**
+     * Whether a successful keyed result is complete. Absent, every successful
+     * result is complete. Child-key results are superseded only when the parent
+     * key's newest successful result is complete; same-key results follow
+     * newest-wins, since a same-key re-read that shows a different view means
+     * the target changed. A failed result supersedes only older failed results.
+     *
+     * Trade-off, by design: after `read foo.ts:50-200` → edit → a bare
+     * `read foo.ts` that returns a summary, the pre-edit range stays in context
+     * until a complete bare read or a same-range re-read. Keeping possibly stale
+     * detail is preferred over losing detail the summary does not show.
+     */
+    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
@@ -104,18 +150,20 @@ 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
  * {@link splitReadSelector}, e.g. `src/foo.ts:50-200`, `:2-4:raw`).
  * Internal/URL-scheme paths (`skill://…`, `https://…`) are exempt.
- * Selector-free reads key on the bare path; selector-carrying reads key on
- * `path + "\u0000" + selector`, so two reads collide only when the newer is
- * selector-free or the selectors are identical (the pass's prefix rule lets a
- * bare-path read supersede selector-carrying reads of the same file).
+ * Selector-free reads key on the bare path; line-range reads key on
+ * `path + "\u0000" + selector`, so a complete bare-path read can supersede them.
+ * `raw` and `conflicts` reads show a different form than a plain read (e.g. raw
+ * notebook JSON vs converted notebook text), so they key on
+ * `path + "\u0001" + selector` and are superseded only by the same selector.
  */
 export declare function readToolSupersedeKey(toolName: string, args: Record<string, unknown>): string | undefined;

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

@@ -26,6 +26,11 @@ export declare function splitReadSelector(path: string): {
  * and matches its write/edit path when computing Read/Write/RW markers.
  */
 export declare function stripReadSelector(path: string): string;
+/**
+ * Whether a selector from {@link splitReadSelector} shows the file in a form other
+ * than its plain lines: verbatim `raw` bytes or the merge `conflicts` view.
+ */
+export declare function isAlternateFormReadSelector(sel: string): boolean;
 /**
  * Whether `path` references a `scheme://` URL (internal URI or web URL) rather
  * than a filesystem path that belongs in the compaction `<files>` summary.

package/dist/types/image-tokens.d.ts

@@ -0,0 +1,29 @@
+import type { ImageContent } from "@linxiraos/pi-ai";
+import { type ImageSize } from "@linxiraos/pi-catalog/compat/image-tokenization";
+/**
+ * Dimension-based image token estimates shared by the local context counter
+ * ({@link Tokenizer.countMessage}) and the native remote-compaction fit probe.
+ * Both sides must price the same image the same way: when they disagreed
+ * (1.2k flat locally vs a 12k flat worst case remotely) an image-heavy session
+ * stayed under the local compaction trigger yet was refused as over-window by
+ * the remote probe.
+ *
+ * Follows the catalog's image rule for the OpenAI Responses wire (GPT-5.5's
+ * 32px patches, a per-detail pixel limit and patch budget, x1.2 multiplier),
+ * which is also a close upper estimate for other providers once omp has
+ * downscaled the image (≤1568px by default).
+ */
+/** OpenAI image `detail` values; `undefined` means the provider default (`auto`). */
+export type ImageDetail = ImageContent["detail"];
+export type { ImageSize };
+/**
+ * Estimated input tokens for one image. Unknown dimensions (undecodable data,
+ * remote URLs, provider file ids) charge the detail level's full patch budget.
+ */
+export declare function estimateImageTokens(size: ImageSize | null | undefined, detail?: ImageDetail): number;
+/** Pixel size read from the header of base64-encoded image data, or null. */
+export declare function base64ImageSize(base64: string): ImageSize | null;
+/** Pixel size of a `data:<mime>;base64,` URL, or null for any other URL. */
+export declare function dataUrlImageSize(url: string): ImageSize | null;
+/** {@link estimateImageTokens} for an in-memory image block. */
+export declare function estimateImageContentTokens(image: Pick<ImageContent, "data" | "detail">): number;

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>;

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 `omp.gen_ai.*`
+ * (https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus `zeta.gen_ai.*`
  * extension attributes for run summaries, dashboard summaries, and cost hints
  * that are useful to downstream observability UIs.
  *
@@ -79,40 +79,40 @@ export declare const enum OpenAIAttr {
 }
 /** Project extension attributes. Kept out of the reserved `gen_ai.*` namespace. */
 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",
+    AgentStepNumber = "zeta.gen_ai.agent.step.number",
+    AgentStepCount = "zeta.gen_ai.agent.step.count",
+    RequestReasoningEffort = "zeta.gen_ai.request.reasoning.effort",
+    RequestToolChoice = "zeta.gen_ai.request.tool.choice",
+    RequestAvailableTools = "zeta.gen_ai.request.available_tools",
+    RequestMessages = "zeta.gen_ai.request.messages",
+    ResponseText = "zeta.gen_ai.response.text",
+    ResponseToolCalls = "zeta.gen_ai.response.tool_calls",
+    ResponseUpstreamProvider = "zeta.gen_ai.response.upstream_provider",
+    UsageTotalTokens = "zeta.gen_ai.usage.total_tokens",
+    UsageServerSideTools = "zeta.gen_ai.usage.server_tool_requests",
+    CostEstimatedUsd = "zeta.gen_ai.cost.estimated_usd",
+    CostInputUsd = "zeta.gen_ai.cost.input_usd",
+    CostOutputUsd = "zeta.gen_ai.cost.output_usd",
+    CostUnavailableReason = "zeta.gen_ai.cost.unavailable_reason",
+    ToolStatus = "zeta.gen_ai.tool.status",
+    ToolCallIntent = "zeta.gen_ai.tool.call.intent",
+    HandoffFromAgentName = "zeta.gen_ai.handoff.from_agent.name",
+    HandoffFromAgentId = "zeta.gen_ai.handoff.from_agent.id",
+    HandoffToAgentName = "zeta.gen_ai.handoff.to_agent.name",
+    HandoffToAgentId = "zeta.gen_ai.handoff.to_agent.id",
+    OneshotKind = "zeta.gen_ai.oneshot.kind",
+    GatewayName = "zeta.gen_ai.gateway.name",
+    GatewayEndpoint = "zeta.gen_ai.gateway.endpoint",
+    GatewayCallId = "zeta.gen_ai.gateway.call_id",
+    GatewayRoutedTo = "zeta.gen_ai.gateway.routed_to",
     /** Cloudflare AI Gateway response-cache status (`cf-aig-cache-status`), never prompt-cache. */
-    GatewayResponseCacheStatus = "omp.gen_ai.gateway.response_cache.status",
+    GatewayResponseCacheStatus = "zeta.gen_ai.gateway.response_cache.status",
     /** Caller-level reason a judgment ran (`find`, `ttsr`, `judge_batch`, …). */
-    JudgmentPurpose = "omp.gen_ai.judgment.purpose",
+    JudgmentPurpose = "zeta.gen_ai.judgment.purpose",
     /** Questions the caller asked in one judgment request. */
-    JudgmentQuestions = "omp.gen_ai.judgment.questions",
+    JudgmentQuestions = "zeta.gen_ai.judgment.questions",
     /** Questions answered from the local judgment cache instead of the provider. */
-    JudgmentCachedQuestions = "omp.gen_ai.judgment.cached_questions"
+    JudgmentCachedQuestions = "zeta.gen_ai.judgment.cached_questions"
 }
 /** GenAI operation names — values for {@link GenAIAttr.OperationName}. */
 export declare const GenAIOperation: {
@@ -145,16 +145,24 @@ export interface ChatUsageSnapshot {
 }
 /** Context passed to the cost estimator. */
 export interface CostEstimatorContext {
+    /** OTel provider label (`gen_ai.provider.name`). */
     readonly provider: string;
+    /** Provider id before OTel normalization (e.g. `openai-codex` for the `openai` label). */
+    readonly providerId: string | undefined;
+    /** Model id reported on the response; a provider may report a served model instead of the requested one. */
     readonly model: string;
+    /** Requested model id, when the caller knows it. */
+    readonly modelId: string | undefined;
     readonly serviceTier: ServiceTier | undefined;
     readonly usage: ChatUsageSnapshot;
+    /** Cost the provider already computed for this request; the value persisted with the message. */
+    readonly usageCost: Usage["cost"];
 }
 /**
  * Cost estimator result.
- *   { usd: number }                — cost is known; emitted as omp.gen_ai.cost.estimated_usd
+ *   { usd: number }                — cost is known; emitted as zeta.gen_ai.cost.estimated_usd
  *   { unavailable: string }        — cost is intentionally unknown; emitted as
- *                                    omp.gen_ai.cost.unavailable_reason
+ *                                    zeta.gen_ai.cost.unavailable_reason
  *   undefined                      — no opinion; nothing emitted
  */
 export type CostEstimate = {
@@ -205,7 +213,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 `omp.gen_ai.gateway.*` attributes.
+     * auto-stamped on the chat span as `zeta.gen_ai.gateway.*` attributes.
      */
     readonly headers: Readonly<Record<string, string>> | undefined;
 }
@@ -390,6 +398,8 @@ export interface ChatRequestSnapshot {
  */
 export declare function finishChatSpan(telemetry: AgentTelemetry | undefined, span: Span | undefined, message: AssistantMessage, options: {
     readonly stepNumber: number;
+    /** Requested model id; `message.model` may name a served fallback model instead. */
+    readonly modelId?: string;
     readonly serviceTier?: ServiceTier;
     readonly responseHeaders?: Readonly<Record<string, string>>;
     readonly baseUrl?: string;
@@ -508,10 +518,10 @@ export interface InstrumentedChatSpanOptions {
     /** Step index recorded on the span; defaults to `-1` for non-loop calls. */
     readonly stepNumber?: number;
     /**
-     * Tag stamped onto `omp.gen_ai.oneshot.kind`. Values used by the agent:
+     * Tag stamped onto `zeta.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.
+     * `handoff`, `branch_summary`, `image_question`, `skill_description`. Free-form
+     * to allow callers outside this package to add new kinds without bumping the helper.
      */
     readonly oneshotKind?: string;
     /** Extra span attributes applied verbatim. */
@@ -613,30 +623,30 @@ export declare function finishInvokeAgentSpan(telemetry: AgentTelemetry | undefi
  * calling this helper.
  */
 export declare function fireOnRunEnd(telemetry: AgentTelemetry, summary: AgentRunSummary, coverage: AgentRunCoverage): void;
-/** Aggregate `omp.gen_ai.agent.*` attributes stamped on the `invoke_agent` span. */
+/** Aggregate `zeta.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"
+    ChatsCount = "zeta.gen_ai.agent.chats.count",
+    ChatsTotalLatencyMs = "zeta.gen_ai.agent.chats.total_latency_ms",
+    ChatsStopReasonPrefix = "zeta.gen_ai.agent.chats.stop_reason.",
+    ToolsCount = "zeta.gen_ai.agent.tools.count",
+    ToolsOkCount = "zeta.gen_ai.agent.tools.ok.count",
+    ToolsErrorCount = "zeta.gen_ai.agent.tools.error.count",
+    ToolsSkippedCount = "zeta.gen_ai.agent.tools.skipped.count",
+    ToolsBlockedCount = "zeta.gen_ai.agent.tools.blocked.count",
+    ToolsTimeoutCount = "zeta.gen_ai.agent.tools.timeout.count",
+    ToolsAbortedCount = "zeta.gen_ai.agent.tools.aborted.count",
+    ToolsTotalLatencyMs = "zeta.gen_ai.agent.tools.total_latency_ms",
+    ToolsInvoked = "zeta.gen_ai.agent.tools.invoked",
+    ToolsAvailable = "zeta.gen_ai.agent.tools.available",
+    ToolsUnused = "zeta.gen_ai.agent.tools.unused",
+    UsageInputTokensTotal = "zeta.gen_ai.agent.usage.input_tokens.total",
+    UsageOutputTokensTotal = "zeta.gen_ai.agent.usage.output_tokens.total",
+    UsageCacheReadInputTokensTotal = "zeta.gen_ai.agent.usage.cache_read.input_tokens.total",
+    UsageCacheCreationInputTokensTotal = "zeta.gen_ai.agent.usage.cache_creation.input_tokens.total",
+    UsageReasoningOutputTokensTotal = "zeta.gen_ai.agent.usage.reasoning.output_tokens.total",
+    UsageTotalTokensTotal = "zeta.gen_ai.agent.usage.total_tokens.total",
+    CostEstimatedUsdTotal = "zeta.gen_ai.agent.cost.estimated_usd.total",
+    ErrorsCount = "zeta.gen_ai.agent.errors.count"
 }
 /**
  * Run `fn` with `span` activated on the OTEL context. Spans created

package/dist/types/tokenizer.d.ts

@@ -1,5 +1,6 @@
 import type { Model } from "@linxiraos/pi-ai";
 import * as natives from "@linxiraos/pi-natives";
+import * as snapcompact from "@linxiraos/pi-snapcompact";
 import type { AgentMessage } from "./types.js";
 /** Maps the catalog-resolved tokenizer family to its native implementation. */
 export declare function tokenizerEncodingForModel(model: Pick<Model, "tokenizer"> | null | undefined): natives.Encoding | null;
@@ -42,14 +43,15 @@ export interface TokenBudgetCheck {
  * Model-aware local token counter. Immutable: the catalog-resolved encoding
  * is fixed at construction, so a cached count can never straddle two
  * encodings. An `Agent` owns one for its active model (swapping the instance
- * when the model's encoding changes); one-shot flows construct their own for
- * the model that will be billed. Known tokenizer families use exact native
- * counts; unknown models keep the fast byte estimate (or o200k when
- * `PI_TOKENIZER_ACCURATE=1`).
+ * when the model's encoding or snapcompact frame pricing changes); one-shot
+ * flows construct their own for the model that will be billed. Known
+ * tokenizer families use exact native counts; unknown models keep the fast
+ * byte estimate (or o200k when `PI_TOKENIZER_ACCURATE=1`).
  */
 export declare class Tokenizer {
     #private;
-    constructor(model?: Pick<Model, "tokenizer"> | null);
+    readonly frameBillingKey: string;
+    constructor(model?: (Pick<Model, "tokenizer"> & snapcompact.ShapeTarget) | null);
     get encoding(): natives.Encoding | null;
     countTokens(text: string | string[], mode?: TokenCountMode): number;
     /**
@@ -70,7 +72,8 @@ export declare class Tokenizer {
      * Settled historical messages are counted once and reused until an owner
      * (prune/shake/strip-images) calls `invalidateMessageCache`; streaming
      * assistants bypass the memo entirely (see the message-cache settle-gate
-     * invariant). Image blocks charge a fixed per-image estimate.
+     * invariant). Image blocks charge {@link estimateImageContentTokens}, the
+     * same dimension-based estimate the native remote-compaction probe applies.
      */
     countMessage(message: AgentMessage, options?: MessageCountOptions): number;
     /** Sum of {@link countMessage} over `messages`. */

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

@@ -0,0 +1,19 @@
+import { type ToolCall } from "@linxiraos/pi-ai";
+import type { AgentTool } from "./types.js";
+/**
+ * Where a call's `__parseError`/`__rawJson` keys came from.
+ * - `"parsed"`: a provider stream parsed the arguments, so `__parseError` is a
+ *   genuine parse-failure sentinel and is never handed to a tool.
+ * - `"payload"`: the arguments are a payload the model wrote (eval tool bridge,
+ *   `xd://` device content), so those keys are forged and only stripped.
+ */
+export type ToolArgumentSource = "parsed" | "payload";
+/**
+ * Validate a call's arguments against `tool`'s schema, honoring
+ * {@link AgentTool.lenientArgValidation}: on a schema mismatch a lenient tool
+ * receives its raw arguments minus the internal `__parseError`/`__rawJson`
+ * sentinels. Malformed JSON from a provider stream is never lenient.
+ *
+ * @throws the validation error when the tool is strict or the arguments failed to parse.
+ */
+export declare function validateAgentToolArguments(tool: AgentTool, toolCall: ToolCall, source?: ToolArgumentSource): ToolCall["arguments"];

package/dist/types/types.d.ts

@@ -269,6 +269,16 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * background.
      */
     hasBackgroundCompletions?: () => boolean | Promise<boolean>;
+    /**
+     * Peeks whether a passive aside (an extension or user message queued with
+     * `deliverAs: "aside"`) is waiting for injection at the next boundary.
+     *
+     * Same rules as {@link hasBackgroundCompletions}: non-consuming, ends only
+     * *interruptible* waits, never raises {@link ToolCallContext.steeringSignal}.
+     * The host still injects the aside once at the boundary; ordinary running
+     * tools finish first.
+     */
+    hasQueuedAsides?: () => boolean | Promise<boolean>;
     /**
      * Returns follow-up messages to process after the agent would otherwise stop.
      *
@@ -281,7 +291,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Returns non-interrupting "aside" messages to inject at a step boundary.
      *
      * Polled after each tool batch (before the next LLM call) AND at the yield
-     * check. Unlike steering, these NEVER abort in-flight tools — they are passive
+     * check. Unlike steering, these never abort foreground tools (only an
+     * interruptible `wait` ends early, via the peek hooks) — they are passive
      * notifications (e.g. background-job completions, late LSP diagnostics) that
      * should reach the model between requests without waiting for the agent to
      * fully stop. Returned messages are appended to the context with normal

package/package.json

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