@linxiraos/pi-ai 1.0.0

package/dist/types/usage.d.ts

@@ -0,0 +1,527 @@
+import type { FetchImpl, Provider } from "./types.js";
+export type UsageUnit = "percent" | "tokens" | "requests" | "usd" | "minutes" | "bytes" | "unknown";
+export type UsageStatus = "ok" | "warning" | "exhausted" | "unknown";
+/** Time window for a limit (e.g. 5h, 7d, monthly). */
+export interface UsageWindow {
+    /** Stable identifier (e.g. "5h", "7d", "monthly"). */
+    id: string;
+    /** Human label (e.g. "5 Hour", "7 Day"). */
+    label: string;
+    /** Window duration in milliseconds, when known. */
+    durationMs?: number;
+    /** Absolute reset timestamp in milliseconds since epoch. */
+    resetsAt?: number;
+    /**
+     * Verb rendered before the {@link resetsAt} countdown (e.g. "tick", "regen").
+     * Defaults to "resets" — override for rolling windows where the timestamp is
+     * an incremental regeneration step rather than a full window reset.
+     */
+    resetLabel?: string;
+}
+/** Quantitative usage data. */
+export interface UsageAmount {
+    /** Amount used in the given unit. */
+    used?: number;
+    /** Maximum limit in the given unit. */
+    limit?: number;
+    /** Remaining amount in the given unit. */
+    remaining?: number;
+    /** Fraction used (0..1). */
+    usedFraction?: number;
+    /** Fraction remaining (0..1). */
+    remainingFraction?: number;
+    /** Unit for the amounts (percent, tokens, etc.). */
+    unit: UsageUnit;
+}
+/** Scope metadata describing what the limit applies to. */
+export interface UsageScope {
+    provider: Provider;
+    accountId?: string;
+    projectId?: string;
+    orgId?: string;
+    modelId?: string;
+    tier?: string;
+    windowId?: string;
+    shared?: boolean;
+}
+/** Normalized limit entry for a single window or quota bucket. */
+export interface UsageLimit {
+    /** Stable identifier for this limit entry. */
+    id: string;
+    /** Human label for display. */
+    label: string;
+    scope: UsageScope;
+    window?: UsageWindow;
+    amount: UsageAmount;
+    status?: UsageStatus;
+    notes?: string[];
+}
+/**
+ * Per-credit detail for a saved/banked rate-limit reset.
+ *
+ * Populated when the provider's listing endpoint returns individual credit
+ * metadata (e.g. OpenAI Codex `wham/rate-limit-reset-credits`). Callers that
+ * only need the count can ignore this; display layers use `expiresAt` to show
+ * when banked resets expire ([#3339](https://github.com/can1357/oh-my-pi/issues/3339)).
+ */
+export interface UsageResetCreditDetail {
+    /** ISO timestamp when the credit was granted. */
+    grantedAt?: string;
+    /** ISO timestamp when the credit expires and can no longer be redeemed. */
+    expiresAt?: string;
+    /** Backend status, e.g. `available`, `redeemed`. */
+    status?: string;
+}
+/**
+ * Saved/banked rate-limit resets an account can redeem on demand.
+ *
+ * Surfaced by providers that let users defer a usage-window reset and spend it
+ * later (OpenAI Codex "saved rate limit resets"). The redeem itself is a
+ * separate, provider-specific action; this is the read-only count for display.
+ */
+export interface UsageResetCredits {
+    /** Number of resets available to redeem right now. */
+    availableCount: number;
+    /** Individual credit details (expiry dates, etc.) when the provider exposes them. */
+    credits?: UsageResetCreditDetail[];
+}
+/** Aggregated usage report for a provider. */
+export interface UsageReport {
+    provider: Provider;
+    fetchedAt: number;
+    limits: UsageLimit[];
+    /** Saved rate-limit resets the account can redeem, when the provider reports them. */
+    resetCredits?: UsageResetCredits;
+    /**
+     * Provider-wide disclaimers shown once above per-account sections.
+     * Use this for caveats that apply to every limit (e.g. "OMP-observed
+     * spend only"). Per-limit notes that differ per window (e.g. "Overage
+     * requests: N") stay on {@link UsageLimit.notes}.
+     */
+    notes?: string[];
+    metadata?: Record<string, unknown>;
+    raw?: unknown;
+}
+/**
+ * Resolve a limit's used fraction (0..1; >1 means overage) from whichever
+ * amount fields the provider populated. Precedence mirrors the usage UIs:
+ * explicit fraction > used/limit > percent-unit used > inverted remaining.
+ */
+export declare function resolveUsedFraction(limit: UsageLimit): number | undefined;
+/**
+ * One recorded usage-limit snapshot: a single limit window of one account at
+ * a point in time. The usage cache itself is latest-snapshot-only; history
+ * rows are appended by the auth storage layer whenever a fresh report is
+ * fetched, so limit utilization stays inspectable over time.
+ */
+export interface UsageHistoryEntry {
+    /** Epoch ms the report was fetched. */
+    recordedAt: number;
+    provider: Provider;
+    /** Stable credential identity key (account/email/project derived). */
+    accountKey: string;
+    email?: string;
+    accountId?: string;
+    /** {@link UsageLimit.id} of the recorded window. */
+    limitId: string;
+    /** Human label of the limit. */
+    label: string;
+    windowLabel?: string;
+    /** Used fraction (0..1) when resolvable. */
+    usedFraction?: number;
+    status?: UsageStatus;
+    /** Epoch ms the window resets, when known. */
+    resetsAt?: number;
+}
+/** Filter for reading recorded usage history. */
+export interface UsageHistoryQuery {
+    provider?: string;
+    /** Inclusive lower bound on {@link UsageHistoryEntry.recordedAt} (epoch ms). */
+    sinceMs?: number;
+}
+/** One observed provider request cost, attributed to the credential that made it. */
+export interface UsageCostHistoryEntry {
+    /** Epoch ms the request completed. */
+    recordedAt: number;
+    provider: Provider;
+    /** Stable credential identity key (account/email/project/secret derived). */
+    accountKey: string;
+    /** Estimated request cost in USD. */
+    costUsd: number;
+}
+/** Filter for reading observed request costs. */
+export interface UsageCostHistoryQuery {
+    provider?: string;
+    accountKey?: string;
+    /** Inclusive lower bound on {@link UsageCostHistoryEntry.recordedAt} (epoch ms). */
+    sinceMs?: number;
+}
+/**
+ * Aggregated request usage a client observed for one (provider, model) pair.
+ * Clients fold every completed request into per-pair buckets and flush them to
+ * the auth broker on a short cadence, so the broker can attribute token burn
+ * to the install that produced it.
+ */
+export interface ObservedUsageEntry {
+    /** Epoch ms of the newest request folded into this bucket. */
+    at: number;
+    provider: Provider;
+    model: string;
+    /** Completed requests folded into this bucket. */
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** Estimated USD cost of the folded requests (0 when unknown). */
+    costUsd: number;
+}
+/** One client's observed-usage report, keyed by its stable install id. */
+export interface ClientUsageReport {
+    /** Stable per-machine install id — the client primary key. */
+    installId: string;
+    /** Human-readable machine name for display surfaces. */
+    hostname?: string;
+    entries: ObservedUsageEntry[];
+}
+/** Per-provider aggregate of one client's recorded usage. */
+export interface ClientProviderUsage {
+    provider: string;
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    costUsd: number;
+}
+/** One known client with its usage aggregates over the queried window. */
+export interface ClientUsageClientSummary {
+    installId: string;
+    hostname?: string;
+    firstSeen: number;
+    lastSeen: number;
+    providers: ClientProviderUsage[];
+}
+/** Aggregated per-client usage recorded by the broker host. */
+export interface ClientUsageSummary {
+    clients: ClientUsageClientSummary[];
+}
+export declare const usageUnitSchema: import("@linxiraos/pi-omptype").FluentType<"bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd", "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd">;
+export declare const usageStatusSchema: import("@linxiraos/pi-omptype").FluentType<"exhausted" | "ok" | "unknown" | "warning", "exhausted" | "ok" | "unknown" | "warning">;
+export declare const usageWindowSchema: import("@linxiraos/pi-omptype").FluentType<{
+    durationMs?: number | undefined;
+    id: string;
+    label: string;
+    resetLabel?: string | undefined;
+    resetsAt?: number | undefined;
+}, {
+    durationMs?: number | undefined;
+    id: string;
+    label: string;
+    resetLabel?: string | undefined;
+    resetsAt?: number | undefined;
+}>;
+export declare const usageAmountSchema: import("@linxiraos/pi-omptype").FluentType<{
+    limit?: number | undefined;
+    remaining?: number | undefined;
+    remainingFraction?: number | undefined;
+    unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
+    used?: number | undefined;
+    usedFraction?: number | undefined;
+}, {
+    limit?: number | undefined;
+    remaining?: number | undefined;
+    remainingFraction?: number | undefined;
+    unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
+    used?: number | undefined;
+    usedFraction?: number | undefined;
+}>;
+export declare const usageScopeSchema: import("@linxiraos/pi-omptype").FluentType<{
+    accountId?: string | undefined;
+    modelId?: string | undefined;
+    orgId?: string | undefined;
+    projectId?: string | undefined;
+    provider: string;
+    shared?: boolean | undefined;
+    tier?: string | undefined;
+    windowId?: string | undefined;
+}, {
+    accountId?: string | undefined;
+    modelId?: string | undefined;
+    orgId?: string | undefined;
+    projectId?: string | undefined;
+    provider: string;
+    shared?: boolean | undefined;
+    tier?: string | undefined;
+    windowId?: string | undefined;
+}>;
+export declare const usageLimitSchema: import("@linxiraos/pi-omptype").FluentType<{
+    amount: {
+        limit?: number | undefined;
+        remaining?: number | undefined;
+        remainingFraction?: number | undefined;
+        unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
+        used?: number | undefined;
+        usedFraction?: number | undefined;
+    };
+    id: string;
+    label: string;
+    notes?: string[] | undefined;
+    scope: {
+        accountId?: string | undefined;
+        modelId?: string | undefined;
+        orgId?: string | undefined;
+        projectId?: string | undefined;
+        provider: string;
+        shared?: boolean | undefined;
+        tier?: string | undefined;
+        windowId?: string | undefined;
+    };
+    status?: "exhausted" | "ok" | "unknown" | "warning" | undefined;
+    window?: {
+        durationMs?: number | undefined;
+        id: string;
+        label: string;
+        resetLabel?: string | undefined;
+        resetsAt?: number | undefined;
+    } | undefined;
+}, {
+    amount: {
+        limit?: number | undefined;
+        remaining?: number | undefined;
+        remainingFraction?: number | undefined;
+        unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
+        used?: number | undefined;
+        usedFraction?: number | undefined;
+    };
+    id: string;
+    label: string;
+    notes?: string[] | undefined;
+    scope: {
+        accountId?: string | undefined;
+        modelId?: string | undefined;
+        orgId?: string | undefined;
+        projectId?: string | undefined;
+        provider: string;
+        shared?: boolean | undefined;
+        tier?: string | undefined;
+        windowId?: string | undefined;
+    };
+    status?: "exhausted" | "ok" | "unknown" | "warning" | undefined;
+    window?: {
+        durationMs?: number | undefined;
+        id: string;
+        label: string;
+        resetLabel?: string | undefined;
+        resetsAt?: number | undefined;
+    } | undefined;
+}>;
+export declare const usageResetCreditDetailSchema: import("@linxiraos/pi-omptype").FluentType<{
+    expiresAt?: string | undefined;
+    grantedAt?: string | undefined;
+    status?: string | undefined;
+}, {
+    expiresAt?: string | undefined;
+    grantedAt?: string | undefined;
+    status?: string | undefined;
+}>;
+export declare const usageResetCreditsSchema: import("@linxiraos/pi-omptype").FluentType<{
+    availableCount: number;
+    credits?: {
+        expiresAt?: string | undefined;
+        grantedAt?: string | undefined;
+        status?: string | undefined;
+    }[] | undefined;
+}, {
+    availableCount: number;
+    credits?: {
+        expiresAt?: string | undefined;
+        grantedAt?: string | undefined;
+        status?: string | undefined;
+    }[] | undefined;
+}>;
+export declare const usageReportSchema: import("@linxiraos/pi-omptype").FluentType<{
+    fetchedAt: number;
+    limits: {
+        amount: {
+            limit?: number | undefined;
+            remaining?: number | undefined;
+            remainingFraction?: number | undefined;
+            unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
+            used?: number | undefined;
+            usedFraction?: number | undefined;
+        };
+        id: string;
+        label: string;
+        notes?: string[] | undefined;
+        scope: {
+            accountId?: string | undefined;
+            modelId?: string | undefined;
+            orgId?: string | undefined;
+            projectId?: string | undefined;
+            provider: string;
+            shared?: boolean | undefined;
+            tier?: string | undefined;
+            windowId?: string | undefined;
+        };
+        status?: "exhausted" | "ok" | "unknown" | "warning" | undefined;
+        window?: {
+            durationMs?: number | undefined;
+            id: string;
+            label: string;
+            resetLabel?: string | undefined;
+            resetsAt?: number | undefined;
+        } | undefined;
+    }[];
+    metadata?: Record<string, unknown> | undefined;
+    notes?: string[] | undefined;
+    provider: string;
+    raw?: unknown;
+    resetCredits?: {
+        availableCount: number;
+        credits?: {
+            expiresAt?: string | undefined;
+            grantedAt?: string | undefined;
+            status?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+}, {
+    fetchedAt: number;
+    limits: {
+        amount: {
+            limit?: number | undefined;
+            remaining?: number | undefined;
+            remainingFraction?: number | undefined;
+            unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
+            used?: number | undefined;
+            usedFraction?: number | undefined;
+        };
+        id: string;
+        label: string;
+        notes?: string[] | undefined;
+        scope: {
+            accountId?: string | undefined;
+            modelId?: string | undefined;
+            orgId?: string | undefined;
+            projectId?: string | undefined;
+            provider: string;
+            shared?: boolean | undefined;
+            tier?: string | undefined;
+            windowId?: string | undefined;
+        };
+        status?: "exhausted" | "ok" | "unknown" | "warning" | undefined;
+        window?: {
+            durationMs?: number | undefined;
+            id: string;
+            label: string;
+            resetLabel?: string | undefined;
+            resetsAt?: number | undefined;
+        } | undefined;
+    }[];
+    metadata?: Record<string, unknown> | undefined;
+    notes?: string[] | undefined;
+    provider: string;
+    raw?: unknown;
+    resetCredits?: {
+        availableCount: number;
+        credits?: {
+            expiresAt?: string | undefined;
+            grantedAt?: string | undefined;
+            status?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+}>;
+/** Optional logger for usage fetchers. */
+export interface UsageLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+}
+/** Credential bundle for usage endpoints. */
+export interface UsageCredential {
+    type: "api_key" | "oauth";
+    apiKey?: string;
+    accessToken?: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    accountId?: string;
+    projectId?: string;
+    email?: string;
+    /** Organization/workspace the credential is scoped to (see OAuthCredentials.orgId). */
+    orgId?: string;
+    /** Human-readable organization name for display. */
+    orgName?: string;
+    enterpriseUrl?: string;
+    metadata?: Record<string, unknown>;
+    apiEndpoint?: string;
+}
+/** Parameters provided to a usage fetcher. */
+export interface UsageFetchParams {
+    provider: Provider;
+    credential: UsageCredential;
+    /** Stable credential identity key derived by the auth storage layer. */
+    accountKey?: string;
+    baseUrl?: string;
+    signal?: AbortSignal;
+}
+/** Shared runtime utilities for fetchers. */
+export interface UsageFetchContext {
+    fetch: FetchImpl;
+    logger?: UsageLogger;
+    retryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+    /** Observed request-cost history for providers without upstream usage APIs. */
+    listUsageCosts?: (query?: UsageCostHistoryQuery) => UsageCostHistoryEntry[];
+}
+/** Provider implementation for fetching usage information. */
+export interface UsageProvider {
+    id: Provider;
+    fetchUsage(params: UsageFetchParams, ctx: UsageFetchContext): Promise<UsageReport | null>;
+    /** Parse provider rate-limit response headers (lowercased keys) into a usage report, if supported. */
+    parseRateLimitHeaders?(headers: Record<string, string>, now?: number): UsageReport | null;
+    supports?(params: UsageFetchParams): boolean;
+    /** True when fetchUsage contacts upstream and can authenticate the credential for health checks. */
+    validatesCredentials?: boolean;
+    /** Whether a failed refresh may serve the previous successful report. Defaults to true. */
+    retainLastGoodOnFailure?: boolean;
+}
+/** Request context used when ranking usage for a specific model. */
+export interface CredentialRankingContext {
+    /** Provider model id, when the caller is selecting a credential for one model. */
+    modelId?: string;
+}
+/** Strategy for usage-based credential ranking. Providers implement this to opt into smart credential selection. */
+export interface CredentialRankingStrategy {
+    /** Extract the primary (short) and secondary (long) window limits from a usage report. */
+    findWindowLimits(report: UsageReport, context?: CredentialRankingContext): {
+        primary?: UsageLimit;
+        secondary?: UsageLimit;
+    };
+    /**
+     * Restrict limits to the ones relevant for the requested model before
+     * credential-wide exhaustion checks and ranking. Providers with shared
+     * account-wide quotas can omit this and use all limits.
+     */
+    scopeLimits?(report: UsageReport, context?: CredentialRankingContext): UsageLimit[];
+    /**
+     * Return a provider-local backoff scope for the requested model. Providers
+     * with backend-specific quotas use this so one exhausted model family does
+     * not block unrelated families on the same OAuth credential.
+     */
+    blockScope?(context?: CredentialRankingContext): string | undefined;
+    /**
+     * Scopes that apply to a request, most specific first. With a context, the
+     * request's own scope plus any legacy catch-all scope whose blocks still
+     * apply to everything. Without one — reconciliation runs with no request —
+     * every scope whose blocks must be healed.
+     *
+     * A provider that scopes backoff by model family must implement this, or a
+     * block written under one scope is invisible to requests and to healing.
+     */
+    blockScopes?(context?: CredentialRankingContext): string[];
+    /** Fallback window durations (ms) when limits don't specify durationMs. */
+    windowDefaults: {
+        primaryMs: number;
+        secondaryMs: number;
+    };
+    /** Optional: priority boost for specific credential states (e.g., fresh 5h ticker start). */
+    hasPriorityBoost?(primary: UsageLimit | undefined): boolean;
+}

package/dist/types/utils/abort.d.ts

@@ -0,0 +1,25 @@
+export interface AbortSourceTracker {
+    requestAbortController: AbortController;
+    requestSignal: AbortSignal;
+    abortLocally(reason: Error): Error;
+    getLocalAbortReason(): Error | undefined;
+    wasCallerAbort(): boolean;
+}
+/**
+ * Tracks whether a merged request signal was aborted by the caller or by provider-local logic.
+ *
+ * Caller aborts always take priority. When both the caller and a local watchdog fire near
+ * each other, the merged `requestSignal.reason` reflects whichever AbortController called
+ * `.abort()` first — but ordering is racy and not meaningful for upstream consumers. What
+ * matters is intent: if the caller's signal aborted, the request was cancelled by the
+ * caller, and any local watchdog reason is incidental and **MUST NOT** be surfaced as a
+ * retryable transient error (which would cause auto-retry to re-enter streaming and leave
+ * the UI showing a spinner the user already tried to cancel).
+ */
+export declare function createAbortSourceTracker(callerSignal?: AbortSignal): AbortSourceTracker;
+/**
+ * Race a shared promise against a caller's AbortSignal without coupling the
+ * underlying work to that signal. The shared promise keeps running (and caches
+ * its result) even when an individual caller bails out.
+ */
+export declare function raceWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;

package/dist/types/utils/anthropic-auth.d.ts

@@ -0,0 +1,35 @@
+/** Auth configuration for Anthropic */
+export interface AnthropicAuthConfig {
+    apiKey: string;
+    baseUrl: string;
+    isOAuth: boolean;
+}
+export declare function resolveAnthropicBaseUrlFromEnv(): string | undefined;
+/**
+ * Checks if a token is an OAuth token by looking for sk-ant-oat prefix.
+ */
+export declare function isOAuthToken(apiKey: string): boolean;
+/**
+ * Build an {@link AnthropicAuthConfig} from an already-resolved API key.
+ *
+ * `apiKey` is whatever the caller chose for `Authorization`/`x-api-key` —
+ * usually `authStorage.getApiKey("anthropic")`. `baseUrl` overrides the
+ * env-derived base; pass `undefined` to fall back to FOUNDRY/ANTHROPIC env
+ * resolution and finally `DEFAULT_BASE_URL`.
+ *
+ * `isOAuth` is derived from the token prefix so the helper stays pure: callers
+ * never have to thread the OAuth flag through their own resolution logic.
+ */
+export declare function buildAnthropicAuthConfig(apiKey: string, baseUrl?: string): AnthropicAuthConfig;
+/**
+ * Builds HTTP headers for Anthropic API requests (search variant).
+ *
+ * Forwards `ANTHROPIC_CUSTOM_HEADERS` when the resolver deems them applicable
+ * (Foundry mode, or a non-Anthropic base URL — typically an enterprise
+ * gateway), matching the streaming path so web search behaves identically.
+ */
+export declare function buildAnthropicSearchHeaders(auth: AnthropicAuthConfig): Record<string, string>;
+/**
+ * Builds the full API URL for Anthropic messages endpoint.
+ */
+export declare function buildAnthropicUrl(auth: AnthropicAuthConfig): string;

package/dist/types/utils/aws-profile.d.ts

@@ -0,0 +1,17 @@
+/** INI sections with `profile ` / `sso-session ` prefixes normalized. */
+export type AwsIniFile = Record<string, Record<string, string>>;
+export declare function parseAwsIni(text: string): AwsIniFile;
+/** Resolve the selected shared-credentials profile. */
+export declare function resolveAwsProfile(profile?: string): string;
+/**
+ * Whether the shared config file participates in profile/region resolution.
+ * Explicit profile selection enables it; the implicit default profile follows
+ * the AWS SDK's `AWS_SDK_LOAD_CONFIG` opt-in.
+ */
+export declare function shouldLoadAwsSharedConfig(profile?: string): boolean;
+export declare function resolveAwsProfileRegion(profile?: string): string | undefined;
+/** Region selected by the environment or active shared-config profile. */
+export declare function resolveAwsAmbientRegion(profile?: string): string | undefined;
+/** Resolve the region precedence shared by AWS transports and credential exchanges. */
+export declare function resolveAwsRegion(explicitRegion?: string, profile?: string): string;
+export declare function hasConfiguredAwsProfile(profile?: string): boolean;

package/dist/types/utils/block-symbols.d.ts

@@ -0,0 +1,62 @@
+/** Stores streamed tool-call argument JSON for live renderers and parser recovery. */
+export declare const kStreamingPartialJson: unique symbol;
+/** Carries streamed tool-call argument JSON without exposing a string-keyed property. */
+export type StreamingPartialJsonCarrier = object & {
+    [kStreamingPartialJson]?: string;
+};
+/** Reads streamed tool-call argument JSON from a block or event snapshot. */
+export declare function getStreamingPartialJson(block: StreamingPartialJsonCarrier | null | undefined): string | undefined;
+/** Writes streamed tool-call argument JSON to a block or clears it with `undefined`. */
+export declare function setStreamingPartialJson(block: StreamingPartialJsonCarrier, value: string | undefined): void;
+/** Clears streamed tool-call argument JSON without deleting or changing object shape. */
+export declare function clearStreamingPartialJson(block: StreamingPartialJsonCarrier): void;
+/** Stores a provider-local stream block index without exposing a string-keyed property. */
+export declare const kStreamingBlockIndex: unique symbol;
+/** Stores the last parsed argument prefix length for throttled streaming JSON parsing. */
+export declare const kStreamingLastParseLen: unique symbol;
+/**
+ * The Cursor interaction envelope's `call_id` for a streamed tool-call block.
+ *
+ * Tracked separately from the block's own `id` because they are NOT the same
+ * key: MCP and Pi blocks are filed under the id inside the call's `args`, which
+ * is what the exec channel pairs its result under, while every streamed
+ * `ToolCall*Update` correlates on the envelope's `call_id`. Matching
+ * completions against the block id would mis-route every call whose args carry
+ * their own id.
+ */
+export declare const kStreamingEnvelopeId: unique symbol;
+/** Marks streamed tool-call arguments that already received an authoritative done payload. */
+export declare const kStreamingArgumentsDone: unique symbol;
+/** Classifies Cursor's in-flight tool-call kind without leaking provider-private state. */
+export declare const kStreamingBlockKind: unique symbol;
+/**
+ * Marks a `toolCall` content block that Cursor's exec channel already
+ * executed server-side (via the coding-agent bridge) and whose result is
+ * buffered separately for emission via the assistant-loop stream.
+ *
+ * `agent-loop.ts` MUST skip execution of blocks carrying this marker —
+ * treating them as a fresh runnable tool call would run the same
+ * side-effecting tool (bash, write, delete, …) a second time. Symbol-keyed
+ * so it never persists across the JSONL round-trip, where rebuild instead
+ * pairs the block with its already-persisted `toolResult` message by id.
+ */
+export declare const kCursorExecResolved: unique symbol;
+/** Carries the resolved marker without exposing a string-keyed property. */
+export type CursorExecResolvedCarrier = object & {
+    [kCursorExecResolved]?: true;
+};
+/**
+ * Marks a text block synthesized by cross-model thinking demotion in
+ * `transformMessages`. Converters that flatten adjacent text blocks into one
+ * string (openai-completions) insert a paragraph separator after marked
+ * blocks; unmarked adjacent blocks keep their original byte sequence.
+ * Symbol-keyed so the marker never persists across the JSONL round-trip and
+ * never reaches the wire.
+ */
+export declare const kDemotedThinking: unique symbol;
+/** Carries the demoted-thinking marker without exposing a string-keyed property. */
+export type DemotedThinkingCarrier = object & {
+    [kDemotedThinking]?: boolean;
+};
+/** True for text blocks synthesized by cross-model thinking demotion. */
+export declare function isDemotedThinking(block: DemotedThinkingCarrier | null | undefined): boolean;

package/dist/types/utils/deterministic-id.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A UUID-shaped string: five hex groups in the canonical 8-4-4-4-12 layout.
+ *
+ * NOT a spec-compliant RFC 4122 UUID — the version/variant nibbles are left as
+ * raw hash output — but the shape passes everywhere a UUID string is expected.
+ */
+export type DeterministicUuid = `${string}-${string}-${string}-${string}-${string}`;
+/**
+ * Format the leading 128 bits of `seed`'s SHA-256 digest as a v4-shape UUID
+ * (8-4-4-4-12 hex groups).
+ *
+ * Deterministic: identical seeds always map to the same id, so callers get
+ * stable ids across requests / conversation turns (reusing message-blob ids,
+ * keying prompt caches) without persisting a seed→id mapping.
+ */
+export declare function deterministicUuid(seed: string): DeterministicUuid;