@irogane/kaji 0.2.0-beta.11

package/dist/index.d.ts

@@ -0,0 +1,1560 @@
+import { N as NewKajiEvent, S as StoredKajiEvent, K as KajiEvent, M as MetricsSink, C as ContextWindow, a as SessionState, b as ContextBuildResult, T as ToolRisk, c as ToolCall, d as ToolExecutionContext, e as TimerScheduler, f as TraceSink, g as ToolSpec, I as IdFactory, h as Clock, R as RetryOptions, i as ModelProvider, P as ProviderMessage, j as ModelProviderOptions, k as ModelResponse, l as ModelResponseChunk, m as ToolHandler, n as ToolRegistry, o as ToolMeta, J as JSONSchema, p as CancellationTokenLike, q as TurnContext, r as ContextDiagnostics, s as CancellationToken, t as TokenUsage } from './context-C-YPY-GS.js';
+export { A as AgentTurnFailed, u as ApprovalFailureCode, v as ApprovalKey, B as BaseEvent, w as CancellationError, x as ContextIntegrityError, y as ContextWindowOverflowError, D as DEFAULT_CONTEXT_WINDOW, z as DEFAULT_PROVIDER_RESPONSE_LIMITS, E as IdScope, F as JournalStage, G as KajiEventInput, L as ListToolSpecsOptions, H as METRIC_NAMES, O as Message, Q as MetricLabels, U as MetricMeasurement, V as MetricName, W as MissingToolIdentityError, X as NOOP_METRICS, Y as NOOP_TRACE, Z as ProviderFamily, _ as ProviderResponseLimits, $ as ProviderStatus, a0 as SessionCreated, a1 as SessionTokens, a2 as SpanName, a3 as SubscriberStage, a4 as TimerHandle, a5 as ToolArgumentValidationError, a6 as ToolExecutionOutcome, a7 as ToolMetricOutcome, a8 as ToolParameters, a9 as ToolSchemaValidationError, aa as ToolSchemaValidator, ab as ToolValidationCode, ac as ToolValidationError, ad as TraceAttributeName, ae as TraceAttributeValue, af as TraceAttributes, ag as TraceSpan, ah as TurnOutcome, ai as UnclassifiedToolRiskError, aj as UnknownToolError, ak as UuidFactory, al as applyEvent, am as approvalKey, an as deadlineAfter, ao as executeTool, ap as listToolSpecs, aq as providerFamily, ar as recordMetric, as as registerTool, at as replaySession, au as resolveProviderResponseLimits, av as startSpan, aw as throwIfCancellationRequested, ax as toolSpecFromSchema, ay as validateNewEvent, az as validateStoredEvent } from './context-C-YPY-GS.js';
+import * as z from 'zod';
+import 'ajv/dist/2020.js';
+
+/**
+ * Event type discriminants. String values are the wire format and must match
+ * the Python SDK (`kaji.infra.events.types.EventType`) byte for byte.
+ */
+declare const EventType: {
+    readonly SESSION_CREATED: "session.created";
+    readonly SESSION_CLOSED: "session.closed";
+    readonly USER_MESSAGE: "user.message";
+    readonly USER_AUDIO_CHUNK: "user.audio.chunk";
+    readonly TRANSCRIPT_PARTIAL: "transcript.partial";
+    readonly TRANSCRIPT_FINAL: "transcript.final";
+    readonly MEMORY_RETRIEVAL_STARTED: "memory.retrieval.started";
+    readonly MEMORY_RETRIEVAL_COMPLETED: "memory.retrieval.completed";
+    readonly AGENT_REASONING_STARTED: "agent.reasoning.started";
+    readonly AGENT_MESSAGE_DELTA: "agent.message.delta";
+    readonly AGENT_MESSAGE_COMPLETED: "agent.message.completed";
+    readonly AGENT_TURN_EXHAUSTED: "agent.turn.exhausted";
+    readonly AGENT_TURN_FAILED: "agent.turn.failed";
+    readonly TOOL_CALL_REQUESTED: "tool.call.requested";
+    readonly TOOL_CALL_STARTED: "tool.call.started";
+    readonly TOOL_CALL_COMPLETED: "tool.call.completed";
+    readonly TOOL_CALL_FAILED: "tool.call.failed";
+    readonly TOOL_APPROVAL_REQUESTED: "tool.approval.requested";
+    readonly TOOL_APPROVAL_APPROVED: "tool.approval.approved";
+    readonly TOOL_APPROVAL_REJECTED: "tool.approval.rejected";
+    readonly WORKFLOW_STARTED: "workflow.started";
+    readonly WORKFLOW_COMPLETED: "workflow.completed";
+    readonly WORKFLOW_FAILED: "workflow.failed";
+    readonly CANCELLATION_REQUESTED: "cancellation.requested";
+    readonly CANCELLATION_COMPLETED: "cancellation.completed";
+};
+type EventType = (typeof EventType)[keyof typeof EventType];
+
+type DurableJsonSubject = "tool_result" | "workflow_result" | "event_metadata" | "memory_document" | "pending_tool_call" | "event";
+declare class InvalidDurableValueError extends Error {
+    readonly subject: DurableJsonSubject;
+    readonly code: "INVALID_DURABLE_VALUE";
+    constructor(subject: DurableJsonSubject);
+}
+declare class DurableJsonLimitError extends Error {
+    readonly subject: DurableJsonSubject;
+    readonly maxBytes: number;
+    readonly code: "EVENT_PAYLOAD_TOO_LARGE";
+    constructor(subject: DurableJsonSubject, maxBytes: number);
+}
+declare class EventSchemaIncompatibleError extends Error {
+    readonly path: string;
+    readonly code = "EVENT_SCHEMA_INCOMPATIBLE";
+    constructor(path: string);
+}
+declare class EventIdConflictError extends Error {
+    readonly eventId: string;
+    readonly code = "EVENT_ID_CONFLICT";
+    constructor(eventId: string);
+}
+declare class EventStoreCapacityError extends Error {
+    readonly sessionId: string;
+    readonly code = "EVENT_STORE_CAPACITY_EXCEEDED";
+    constructor(sessionId: string, message: string);
+}
+type SessionPurgeComponent = "event_store" | "event_delivery" | "tool_idempotency_ledger";
+declare class SessionPurgeBusyError extends Error {
+    readonly sessionId: string;
+    readonly code: "SESSION_PURGE_BUSY";
+    constructor(sessionId: string);
+}
+declare class SessionPurgeUnsupportedError extends Error {
+    readonly sessionId: string;
+    readonly component: SessionPurgeComponent;
+    readonly code: "SESSION_PURGE_UNSUPPORTED";
+    constructor(sessionId: string, component?: SessionPurgeComponent);
+}
+declare class EventBufferOverflowError extends Error {
+    readonly lastSequence: number;
+    readonly latestSequence: number;
+    readonly code = "EVENT_BUFFER_OVERFLOW";
+    constructor(lastSequence: number, latestSequence: number);
+}
+type EventDeliveryPhase = "append" | "publish";
+declare class EventDeliveryError extends Error {
+    readonly phase: EventDeliveryPhase;
+    readonly eventId: string;
+    readonly persisted: boolean;
+    readonly code: "EVENT_APPEND_FAILED" | "EVENT_PUBLISH_FAILED";
+    constructor(phase: EventDeliveryPhase, eventId: string, persisted: boolean, options?: ErrorOptions);
+}
+
+/** Internal physical-delete capability; intentionally absent from public barrels. */
+declare const coordinatedSessionPurge: unique symbol;
+/** Internal listener-detach capability; intentionally absent from public barrels. */
+declare const authorizedListenerTeardown: unique symbol;
+declare class SessionPurgeAuthorization {
+}
+
+interface AppendResult {
+    event: StoredKajiEvent;
+    inserted: boolean;
+}
+interface EventStore {
+    /** Optional retained-session bound used to align runtime projection caches. */
+    readonly maxSessions?: number;
+    append(event: NewKajiEvent): Promise<AppendResult>;
+    getEvents(sessionId: string, options?: {
+        afterSequence?: number;
+        limit?: number;
+    }): Promise<StoredKajiEvent[]>;
+    lastSequence(sessionId: string): Promise<number>;
+}
+interface PurgeableEventStore extends EventStore {
+    purgeSession(sessionId: string): Promise<boolean>;
+}
+declare function supportsSessionPurge(store: EventStore): store is PurgeableEventStore;
+type SessionEventListener = (event: StoredKajiEvent) => boolean;
+interface EventStoreSession {
+    appendLocked(event: NewKajiEvent): Promise<AppendResult>;
+    getEventsLocked(options?: {
+        afterSequence?: number;
+        limit?: number;
+    }): StoredKajiEvent[];
+    lastSequenceLocked(): number;
+    attachListenerLocked(listener: SessionEventListener): void;
+    detachListenerLocked(listener: SessionEventListener): void;
+}
+interface InMemoryEventStoreOptions {
+    maxSessions?: number;
+    maxEventsPerSession?: number;
+}
+declare class InMemoryEventStore implements PurgeableEventStore {
+    private readonly sessions;
+    private readonly eventsById;
+    private readonly idReservations;
+    private readonly listeners;
+    private readonly lanes;
+    readonly maxSessions: number;
+    private readonly maxEventsPerSession;
+    constructor(options?: InMemoryEventStoreOptions);
+    get sessionTransactionsEnabled(): boolean;
+    /** @internal Diagnostics for deterministic leak tests. */
+    get activeSessionLaneCount(): number;
+    /** @internal Diagnostics for deterministic leak tests. */
+    get activeIdReservationCount(): number;
+    /** @internal Diagnostics for deterministic leak tests. */
+    get activeListenerCount(): number;
+    sessionTransaction<T>(sessionId: string, operation: (transaction: EventStoreSession) => Promise<T>): Promise<T>;
+    append(input: NewKajiEvent): Promise<AppendResult>;
+    private claimId;
+    private finishReservation;
+    private appendTransaction;
+    protected insertReserved(event: NewKajiEvent): Promise<AppendResult>;
+    private fanoutSnapshot;
+    private attachListenerLocked;
+    private detachListenerLocked;
+    getEvents(sessionId: string, options?: {
+        afterSequence?: number;
+        limit?: number;
+    }): Promise<StoredKajiEvent[]>;
+    private getEventsLocked;
+    lastSequence(sessionId: string): Promise<number>;
+    purgeSession(sessionId: string): Promise<boolean>;
+    [coordinatedSessionPurge](sessionId: string, authorization: SessionPurgeAuthorization): Promise<boolean>;
+    [authorizedListenerTeardown](sessionId: string, listeners: readonly object[], authorization: SessionPurgeAuthorization): Promise<void>;
+    private lastSequenceLocked;
+    private admitSession;
+}
+
+interface EventBusSubscribeOptions {
+    afterSequence?: number;
+}
+interface EventBusProtocol<TEvent extends {
+    readonly session_id: string;
+} = KajiEvent> {
+    publish(event: TEvent): Promise<void | string>;
+    /**
+     * Return an iterator that cannot miss events published after `afterSequence`.
+     * Implementations must either attach synchronously before returning or retain
+     * cursor-addressable history that a lazy iterator reads when iteration starts.
+     */
+    subscribe(sessionId: string, options?: EventBusSubscribeOptions): AsyncIterableIterator<TEvent>;
+    close(): void | Promise<void>;
+}
+interface EventCommitter {
+    readonly store: EventStore;
+    commit(event: NewKajiEvent): Promise<StoredKajiEvent>;
+    subscribe(sessionId: string, options?: {
+        afterSequence?: number;
+    }): AsyncIterableIterator<StoredKajiEvent>;
+}
+
+declare class EventBus<TEvent extends {
+    readonly session_id: string;
+} = KajiEvent> implements EventBusProtocol<TEvent> {
+    private readonly subscriberCapacity;
+    private readonly metrics;
+    private readonly subscribers;
+    constructor(subscriberCapacity?: number, metrics?: MetricsSink);
+    publish(event: TEvent): Promise<void>;
+    subscribe(sessionId: string, options?: EventBusSubscribeOptions): AsyncIterableIterator<TEvent>;
+    close(): void;
+}
+
+interface InMemoryEventCommitterOptions {
+    subscriberCapacity?: number;
+    metricsSink?: MetricsSink;
+}
+interface SplitEventCommitterOptions {
+    subscriberCapacity?: number;
+    maxPendingEvents?: number;
+    metricsSink?: MetricsSink;
+}
+/** Stable single-process append + fanout boundary. */
+declare class InMemoryEventCommitter implements EventCommitter {
+    readonly store: EventStore;
+    private readonly serial;
+    private readonly subscribers;
+    private readonly subscriberCapacity;
+    private readonly metrics;
+    private readonly transactionalStore;
+    private readonly subscriptions;
+    constructor(store?: EventStore, options?: InMemoryEventCommitterOptions);
+    commit(event: NewKajiEvent): Promise<StoredKajiEvent>;
+    private commitWith;
+    subscribe(sessionId: string, options?: {
+        afterSequence?: number;
+    }): AsyncIterableIterator<StoredKajiEvent>;
+    closeSessionSubscriptions(sessionId: string, authorization: SessionPurgeAuthorization): Promise<void>;
+    close(): Promise<void>;
+}
+/** Experimental adapter for stores and buses that cannot share one atomic boundary. */
+declare class SplitEventCommitter implements EventCommitter {
+    readonly store: EventStore;
+    readonly bus: EventBusProtocol<KajiEvent | StoredKajiEvent>;
+    private readonly serial;
+    private readonly pending;
+    private readonly subscriberCapacity;
+    private readonly metrics;
+    private readonly transactionalStore;
+    private pendingReservations;
+    private subscriptionCreations;
+    private readonly subscriptions;
+    private readonly orphanSubscriptionTeardowns;
+    private closed;
+    private readonly unregisterPurgeBlocker;
+    readonly sessionPurgeComponent: "event_delivery";
+    readonly maxPendingEvents: number;
+    constructor(store: EventStore, bus: EventBusProtocol<KajiEvent | StoredKajiEvent>, options?: SplitEventCommitterOptions);
+    close(): void;
+    private retainOrphanSubscription;
+    private startOrphanSubscriptionTeardown;
+    commit(input: NewKajiEvent): Promise<StoredKajiEvent>;
+    private reservePendingSlot;
+    private releasePendingSlot;
+    private promotePendingSlot;
+    private commitUnlocked;
+    retryPublish(eventId: string): Promise<StoredKajiEvent>;
+    private publishPendingUnlocked;
+    private hasPendingForSession;
+    retry(eventId: string): Promise<StoredKajiEvent>;
+    subscribe(sessionId: string, options?: {
+        afterSequence?: number;
+    }): AsyncIterableIterator<StoredKajiEvent>;
+    pendingEventIds(): string[];
+}
+
+interface ContextIndexStats {
+    readonly fullColdBuilds: number;
+    readonly coldEvents: number;
+    readonly incrementalEvents: number;
+    readonly suffixCalls: number;
+    readonly maxVisitedTurnEntries: number;
+    readonly copiedOutputMessages: number;
+    readonly persistentCopiedPayloadBytes: number;
+    readonly retainedTurns: number;
+    readonly turnEntries: number;
+    readonly sentinelEntries: number;
+    readonly totalEntries: number;
+    readonly latestUserAccesses: number;
+    readonly scannedToolCalls: number;
+    readonly scannedToolArgumentBytes: number;
+}
+
+/** Incremental projection that owns one session-local sequence cursor. */
+declare class SessionProjector {
+    readonly sessionId: string;
+    private readonly metrics;
+    private readonly projectionState;
+    private readonly contextIndex;
+    lastSequence: number;
+    appliedEvents: number;
+    initialized: boolean;
+    constructor(sessionId: string, metrics?: MetricsSink, contextWindow?: Readonly<ContextWindow>);
+    /** Return a deep snapshot; projection state remains privately owned. */
+    get state(): SessionState;
+    apply(event: StoredKajiEvent): void;
+    private applyValidated;
+    sync(store: EventStore, onApplied?: (event: StoredKajiEvent) => void): Promise<number>;
+    get contextIndexStats(): Readonly<ContextIndexStats>;
+    buildProjectedContext(systemPrompt?: string, window?: ContextWindow): ContextBuildResult;
+    latestUserContent(): string | undefined;
+}
+
+interface SessionRecord {
+    sessionId: string;
+    userId: string;
+    createdAt: number;
+    title: string;
+}
+interface SessionStore {
+    recordSession(record: SessionRecord): Promise<void>;
+    listSessions(userId: string): Promise<SessionRecord[]>;
+}
+declare class InMemorySessionStore implements SessionStore {
+    private readonly records;
+    recordSession(record: SessionRecord): Promise<void>;
+    listSessions(userId: string): Promise<SessionRecord[]>;
+}
+
+declare class SessionManager {
+    private readonly _store;
+    private readonly _sessionStore?;
+    constructor(store: EventStore, sessionStore?: SessionStore);
+    getState(sessionId: string): Promise<SessionState>;
+    recordSession(sessionId: string, userId: string, title?: string): Promise<void>;
+    listActive(userId: string): Promise<Array<{
+        sessionId: string;
+        userId: string;
+        createdAt: number;
+        title: string;
+    }>>;
+}
+
+/**
+ * Tool policy enforcement, mirroring `kaji.runtime.tools.policies`.
+ * Controls which tools may run and which require explicit approval before
+ * execution, keyed on tool name and risk classification.
+ */
+
+/** Thrown by `ToolPolicy.enforce` when a tool call is not permitted. */
+declare class ToolPolicyViolation extends Error {
+    constructor(toolName: string);
+}
+interface ToolPolicyOptions {
+    /** Explicit allowlist. When undefined, all tools not in `denied` are allowed. */
+    allowed?: ReadonlySet<string>;
+    /** Tools that are always blocked, even if in `allowed`. */
+    denied?: ReadonlySet<string>;
+    /** Risk levels that require explicit approval before the tool runs. */
+    requireApprovalFor?: ReadonlySet<ToolRisk>;
+}
+declare class ToolPolicy {
+    private readonly allowed;
+    private readonly denied;
+    readonly requireApprovalFor: ReadonlySet<ToolRisk>;
+    constructor(opts?: ToolPolicyOptions);
+    /** Returns true when the tool is not denied and (if an allowlist exists) is in it. */
+    isAllowed(toolName: string): boolean;
+    isAllowedAny(toolNames: Iterable<string>): boolean;
+    /** Throws `ToolPolicyViolation` if the tool is not allowed. */
+    enforce(toolName: string): void;
+    enforceAny(toolName: string, aliases?: Iterable<string>): void;
+    /**
+     * Returns true when the tool's effective risk level is at or above the
+     * minimum rank in `requireApprovalFor`. So `requireApprovalFor: {"destructive"}`
+     * also catches `"admin"`. Enabled tools must carry a known risk; missing
+     * and unknown classifications fail instead of defaulting to `read`.
+     */
+    requiresApproval(_toolName: string, risk: ToolRisk | undefined): boolean;
+}
+
+/** Typed approval decisions and the canonical runtime request context. */
+
+type ApprovalRejectionCode = "rejected" | "timeout" | "turn_timeout" | "cancelled" | "unavailable";
+type ApprovalDeadlineSource = "approval" | "turn";
+type ApprovalDecision = Readonly<{
+    granted: true;
+    code: "approved";
+    recorded?: boolean;
+}> | Readonly<{
+    granted: false;
+    code: ApprovalRejectionCode;
+    reason: string;
+    recorded?: boolean;
+}>;
+/**
+ * Runtime-owned approval boundary. `committer` is used only to subscribe;
+ * `emit` is the canonical runtime write path so projection and turn collection
+ * stay coherent.
+ */
+interface ApprovalRequestContext {
+    readonly execution: ToolExecutionContext;
+    readonly toolName: string;
+    readonly risk: ToolRisk;
+    readonly arguments: Readonly<Record<string, unknown>>;
+    readonly committer: EventCommitter;
+    readonly emit: (event: KajiEvent) => Promise<StoredKajiEvent>;
+    readonly deadlineMonotonicMs: number;
+    readonly deadlineSource: ApprovalDeadlineSource;
+    /** Runtime clock paired with `deadlineMonotonicMs`; custom contexts may omit it. */
+    readonly nowMonotonic?: () => number;
+    readonly timerScheduler: TimerScheduler;
+}
+interface TypedApprovalHandler {
+    request(call: ToolCall, context: ApprovalRequestContext): Promise<ApprovalDecision>;
+}
+/** Dedicated marker for the one handler that owns approval-request emission. */
+interface EventBackedApprovalHandler extends TypedApprovalHandler {
+    readonly approvalRequestOwner: "handler";
+}
+
+/** Closed, redaction-safe recovery metadata shared by errors and renderers. */
+type IntegrationRecoveryReason = "github_token_missing" | "gmail_grant_missing" | "keychain_missing" | "keychain_locked" | "keychain_corrupt" | "keychain_unsupported" | "gmail_scope_drift" | "policy_rejected" | "api_rejected" | "transient_read_failed" | "rate_limited" | "redirect_rejected" | "response_limit_exceeded" | "github_mutation_unknown" | "gmail_mutation_unknown";
+interface IntegrationRecoveryFields {
+    readonly reason_code: IntegrationRecoveryReason;
+    readonly recovery_code: string;
+    readonly doc_url: string;
+}
+
+type ToolFailureOutcome = "not_started" | "failed" | "unknown";
+interface ToolFailureFields {
+    readonly error_code: string;
+    readonly retryable: boolean;
+    readonly outcome: ToolFailureOutcome;
+    readonly reason_code?: IntegrationRecoveryReason;
+    readonly recovery_code?: string;
+    readonly doc_url?: string;
+}
+/** Stable public tool failure without retaining the originating exception. */
+declare class ToolExecutionError extends Error implements ToolFailureFields {
+    readonly error_code: string;
+    readonly retryable: boolean;
+    readonly outcome: ToolFailureOutcome;
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string, error_code: string, retryable: boolean, outcome: ToolFailureOutcome, recovery?: IntegrationRecoveryFields);
+    readonly reason_code?: IntegrationRecoveryReason;
+    readonly recovery_code?: string;
+    readonly doc_url?: string;
+}
+declare class IdempotencyCapacityError extends ToolExecutionError {
+    constructor();
+}
+declare class IdempotencyConflictError extends ToolExecutionError {
+    constructor();
+}
+
+type ToolLedgerOutcome = {
+    readonly status: "completed";
+    readonly result: unknown;
+} | {
+    readonly status: "failed";
+    readonly error: ToolExecutionError;
+};
+interface ToolIdempotencyClaim {
+    readonly sessionId: string;
+    readonly toolCallId: string;
+    readonly fingerprint: string;
+}
+type ToolClaimResult = {
+    readonly status: "owner";
+    readonly claim: ToolIdempotencyClaim;
+} | {
+    readonly status: "running";
+    readonly outcome: Promise<ToolLedgerOutcome>;
+} | {
+    readonly status: "completed";
+    readonly result: unknown;
+} | {
+    readonly status: "unknown";
+    readonly error: ToolExecutionError;
+};
+/** Replaceable persistence boundary for exact tool-call idempotency. */
+interface ToolIdempotencyLedger {
+    claim(sessionId: string, toolCallId: string, fingerprint: string): Promise<ToolClaimResult>;
+    complete(claim: ToolIdempotencyClaim, result: unknown): Promise<void>;
+    retryableFailure(claim: ToolIdempotencyClaim, error: ToolExecutionError): Promise<void>;
+    unknownOutcome(claim: ToolIdempotencyClaim, error: ToolExecutionError): Promise<void>;
+    releaseCompleted(sessionId: string): Promise<number>;
+    /** Remove completed and unknown entries, but never an in-flight claim. */
+    releaseSettled?(sessionId: string): Promise<number>;
+}
+interface InMemoryToolIdempotencyLedgerOptions {
+    capacity?: number;
+    completedTtlMs?: number;
+    now?: () => number;
+}
+/** Process-local bounded ledger. Running and unknown entries are never evicted. */
+declare class InMemoryToolIdempotencyLedger implements ToolIdempotencyLedger {
+    private readonly entries;
+    private readonly capacity;
+    private readonly completedTtlMs;
+    private readonly now;
+    constructor(options?: InMemoryToolIdempotencyLedgerOptions);
+    claim(sessionId: string, toolCallId: string, fingerprint: string): Promise<ToolClaimResult>;
+    complete(claim: ToolIdempotencyClaim, result: unknown): Promise<void>;
+    retryableFailure(claim: ToolIdempotencyClaim, error: ToolExecutionError): Promise<void>;
+    unknownOutcome(claim: ToolIdempotencyClaim, error: ToolExecutionError): Promise<void>;
+    releaseCompleted(sessionId: string): Promise<number>;
+    releaseSettled(sessionId: string): Promise<number>;
+    private runningEntry;
+    private evictCompletedForCapacity;
+}
+
+interface ToolExecutionLimits {
+    readonly maxParallel: number;
+    readonly timeoutMs: number | null;
+    readonly approvalTimeoutMs: number;
+}
+declare const DEFAULT_TOOL_EXECUTION_LIMITS: Readonly<ToolExecutionLimits>;
+type ToolExecutionControllerOutcome = {
+    readonly status: "completed";
+    readonly result: unknown;
+} | {
+    readonly status: "failed";
+    readonly error: ToolExecutionError;
+    /** True only for a deadline observed by this invocation, never a ledger replay. */
+    readonly turnTimeout?: true;
+};
+interface ToolExecutionRequest {
+    readonly name: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly context: ToolExecutionContext;
+    readonly timeoutMs?: number;
+    readonly exclusive: boolean;
+    /**
+     * Persist the start acknowledgement and settle when the append is no longer active.
+     * Implementations must observe `signal`; otherwise the claim and permit remain owned,
+     * `drain()` reports the call, and the process must be restarted if it never settles.
+     */
+    readonly onStarted: (signal: AbortSignal) => Promise<void>;
+    readonly execute: (context: ToolExecutionContext) => Promise<unknown>;
+}
+interface ToolExecutionControllerOptions {
+    limits?: Partial<ToolExecutionLimits>;
+    ledger?: ToolIdempotencyLedger;
+    now?: () => number;
+    monotonicNow?: () => number;
+    timerScheduler?: TimerScheduler;
+    metricsSink?: MetricsSink;
+    traceSink?: TraceSink;
+}
+/** Runtime-lifetime bounded tool execution and idempotency controller. */
+declare class ToolExecutionController {
+    readonly limits: Readonly<ToolExecutionLimits>;
+    readonly ledger: ToolIdempotencyLedger;
+    private readonly permits;
+    private readonly monotonicNow;
+    private readonly timerScheduler;
+    private readonly metrics;
+    private readonly trace;
+    private readonly active;
+    private readonly pendingStarts;
+    private readonly claimCleanups;
+    private readonly pendingApprovals;
+    constructor(options?: ToolExecutionControllerOptions);
+    execute(request: ToolExecutionRequest): Promise<ToolExecutionControllerOutcome>;
+    private executeBounded;
+    /** Wait for real start/handler settlement; report calls still owned at the deadline. */
+    drain(timeoutMs: number): Promise<readonly string[]>;
+    /** @internal Whether start recording or handler code still owns this session. */
+    hasActiveSession(sessionId: string): boolean;
+    /** @internal Retain approval ownership after a timeout/cancellation race. */
+    trackApproval<T>(sessionId: string, callId: string, operation: Promise<T>): Promise<T>;
+    private trackPendingStart;
+    private finishPendingStart;
+    private abortOutcome;
+    private waitForRunningOutcome;
+    private scheduleLateClaimCleanup;
+    private linkedSignal;
+}
+
+/** Bounded, ordered planning and execution of provider tool calls. */
+
+/** A single tool call instruction from the LLM. */
+interface ToolCallInstruction {
+    id?: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** Result of a single tool call execution. */
+type ToolCallResult = {
+    id: string;
+    name: string;
+    result: unknown;
+} | {
+    id: string;
+    name: string;
+    error: string;
+    error_code?: string;
+    error_path?: string;
+    retryable?: boolean;
+    outcome?: "not_started" | "failed" | "unknown";
+    reason_code?: IntegrationRecoveryReason;
+    recovery_code?: string;
+    doc_url?: string;
+};
+type ToolExecutor = (name: string, args: Readonly<Record<string, unknown>>, context: ToolExecutionContext) => Promise<unknown>;
+/** Start acknowledgements receive `signal`; custom emitters must settle when it aborts. */
+type EmitFn = (event: KajiEvent, signal?: AbortSignal) => Promise<StoredKajiEvent | void>;
+interface ToolPlannerOptions {
+    executor: ToolExecutor;
+    policy?: ToolPolicy;
+    approvalHandler?: TypedApprovalHandler;
+    specs?: ReadonlyMap<string, ToolSpec>;
+    idFactory?: IdFactory;
+    clock?: Clock;
+    executionController?: ToolExecutionController;
+    executionLimits?: Partial<ToolExecutionLimits>;
+    idempotencyLedger?: ToolIdempotencyLedger;
+    /** Canonical runtime committer used by event-backed approval waiters. */
+    approvalCommitter?: EventCommitter;
+    /** Monotonic clock source used to derive the absolute approval deadline. */
+    now?: () => number;
+    metricsSink?: MetricsSink;
+    traceSink?: TraceSink;
+    timerScheduler?: TimerScheduler;
+}
+declare class ToolPlanner {
+    private readonly executor;
+    private readonly policy;
+    private readonly approvalHandler;
+    readonly approvalCommitter: EventCommitter | undefined;
+    private readonly specs;
+    private readonly schemaValidator;
+    private readonly idFactory;
+    private readonly clock;
+    private readonly now;
+    private readonly timerScheduler;
+    readonly executionController: ToolExecutionController;
+    /** Canonical emitter for standalone planner usage. */
+    static committerEmitter(committer: EventCommitter): EmitFn;
+    constructor(opts: ToolPlannerOptions);
+    /**
+     * Execute one provider batch with bounded parallelism and provider-order
+     * request/result/terminal semantics. Explicitly parallel-safe runs overlap;
+     * every unmarked tool is an exclusive barrier.
+     */
+    executeBatch(sessionId: string, toolCalls: ToolCallInstruction[], emit: EmitFn, turnId?: string, turnContext?: {
+        readonly principalId?: string;
+        readonly requestId?: string;
+        readonly traceId?: string;
+        readonly deadlineMonotonicMs?: number;
+        readonly db?: unknown;
+        readonly metadata?: Readonly<Record<string, unknown>>;
+    }, signal?: AbortSignal): Promise<ToolCallResult[]>;
+    private executeParallelGroup;
+    private normalizeCalls;
+    private requestedEvent;
+    private preflight;
+    private authoritativeApprovalDecision;
+    private raceApprovalDecision;
+    private executePrepared;
+    private terminalEvent;
+    private event;
+}
+
+interface CliApprovalInput {
+    readonly readableEnded?: boolean;
+    readonly destroyed?: boolean;
+    on(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    once(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    removeListener(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    pause(): this;
+    resume(): this;
+}
+interface CliApprovalOutput {
+    write(chunk: string): boolean;
+}
+interface CliApprovalOptions {
+    /** Defaults to process.stdin. Override in tests with a readable input. */
+    input?: CliApprovalInput;
+    /** Defaults to process.stdout. Override in tests with a writable output. */
+    output?: CliApprovalOutput;
+    /**
+     * Optional label printed in the prompt header to disambiguate concurrent
+     * agents (e.g. `"agent-a"`, `"session-c1"`). Defaults to empty.
+     */
+    label?: string;
+}
+declare function cliApprovalHandler(opts?: CliApprovalOptions): TypedApprovalHandler;
+
+interface OpenAIProviderOptions {
+    apiKey: string;
+    model?: string;
+    baseURL?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Per-request timeout in milliseconds. Must be a positive finite integer. */
+    requestTimeoutMs?: number;
+    /** Extra HTTP headers to send with every request. Used by OpenAI-compatible
+     * gateways (OpenRouter, Together, Groq) to attach attribution or routing
+     * metadata. Ignored when the value is empty. */
+    defaultHeaders?: Record<string, string>;
+    /** Rate-limit retry configuration. */
+    retry?: RetryOptions;
+}
+declare class OpenAIProvider implements ModelProvider {
+    readonly providerFamily: "openai";
+    private readonly opts;
+    private client;
+    constructor(opts: OpenAIProviderOptions);
+    /** Expose the model name for downstream cost calculation. */
+    get model(): string;
+    protected createClient(): Promise<object>;
+    private getClient;
+    generate(messages: ProviderMessage[], tools: ToolSpec[], options?: ModelProviderOptions): Promise<ModelResponse>;
+    generateStream(messages: ProviderMessage[], tools: ToolSpec[], options?: ModelProviderOptions): AsyncGenerator<ModelResponseChunk>;
+}
+
+interface AnthropicProviderOptions {
+    apiKey: string;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Per-request timeout in milliseconds. Must be a positive finite integer. */
+    requestTimeoutMs?: number;
+    /** Rate-limit retry configuration. */
+    retry?: RetryOptions;
+}
+declare class AnthropicProvider implements ModelProvider {
+    readonly providerFamily: "anthropic";
+    private readonly opts;
+    private client;
+    constructor(opts: AnthropicProviderOptions);
+    get model(): string;
+    protected createClient(): Promise<object>;
+    private getClient;
+    generate(messages: ProviderMessage[], tools: ToolSpec[], options?: ModelProviderOptions): Promise<ModelResponse>;
+    generateStream(messages: ProviderMessage[], tools: ToolSpec[], options?: ModelProviderOptions): AsyncGenerator<ModelResponseChunk>;
+}
+
+interface ProviderErrorOptions {
+    service?: string;
+    action?: string;
+    statusCode?: number;
+}
+declare class ProviderError extends Error {
+    readonly service: string;
+    readonly action: string;
+    readonly statusCode?: number;
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string, options?: ProviderErrorOptions);
+}
+declare class ProviderConfigError extends ProviderError {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string, options?: Omit<ProviderErrorOptions, "action">);
+}
+declare class ProviderAPIError extends ProviderError {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string, options?: ProviderErrorOptions);
+}
+declare class ProviderConnectionError extends ProviderError {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string, options?: ProviderErrorOptions);
+}
+declare class ProviderRateLimitedError extends ProviderError {
+    readonly retryAfterMs: number;
+    readonly attempts: number;
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string, options: Omit<ProviderErrorOptions, "action"> & {
+        retryAfterMs: number;
+        attempts: number;
+    });
+}
+type ProviderOutputDimension = "text" | "tool_arguments" | "total_response" | "tool_calls";
+declare class ProviderOutputLimitError extends Error {
+    readonly dimension: ProviderOutputDimension;
+    readonly limit: number;
+    readonly code: "PROVIDER_OUTPUT_LIMIT";
+    readonly phase: "provider_stream";
+    readonly retryable: false;
+    readonly outcome: "unknown";
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(dimension: ProviderOutputDimension, limit: number);
+}
+interface NormalizedProviderError {
+    type: "api" | "auth" | "config" | "network" | "rate_limit";
+    code: "PROVIDER_API_ERROR" | "PROVIDER_AUTH_ERROR" | "PROVIDER_CONFIG_ERROR" | "PROVIDER_NETWORK_ERROR" | "PROVIDER_RATE_LIMITED";
+    service: string;
+    action: string;
+    status: number | null;
+    retryable: boolean;
+}
+declare function normalizeProviderError(error: ProviderError): NormalizedProviderError;
+
+/**
+ * Per-model $/1M token cost table. Updated quarterly.
+ * All rates are USD per 1,000,000 tokens.
+ */
+interface ModelCostEntry {
+    /** Cost in USD per 1M input tokens. */
+    inputPer1M: number;
+    /** Cost in USD per 1M output tokens. */
+    outputPer1M: number;
+}
+/**
+ * Look up cost for an exact supported model or a provider snapshot suffix.
+ * Returns `undefined` rather than guessing for unknown or routed models.
+ */
+declare function lookupCost(model: string): ModelCostEntry | undefined;
+/**
+ * Calculate cost in USD for a given token count and model.
+ * Returns 0 if the model is not in the cost table.
+ */
+declare function calculateCostUsd(model: string, inputTokens: number, outputTokens: number): number;
+
+/**
+ * Provider registry: a process-level map from name to `ModelProvider`.
+ * Mirrors `kaji.runtime.providers.registry`.
+ */
+
+/** Register a provider under a name. Throws on duplicate. */
+declare function registerProvider(name: string, provider: ModelProvider): void;
+/** Retrieve a registered provider. Throws if not found. */
+declare function getProvider(name: string): ModelProvider;
+
+/**
+ * Function-style provider factories.
+ *
+ * Convenience wrappers so callers can write `openai("gpt-5.4-mini")` instead of
+ * `new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, model: "gpt-5.4-mini" })`.
+ * Reads the conventional environment variable when no apiKey is given.
+ *
+ *   import { openai, anthropic, generateText } from "@irogane/kaji";
+ *   const { text } = await generateText({
+ *     provider: openai("gpt-5.4-mini"),
+ *     messages: [{ role: "user", content: "Hello" }],
+ *   });
+ */
+
+type ModelOrOptions<TOpts> = string | (Omit<TOpts, "apiKey"> & {
+    apiKey?: string;
+});
+/** Create an OpenAI provider. Reads `OPENAI_API_KEY` from the environment when no `apiKey` is passed. */
+declare function openai(arg?: ModelOrOptions<OpenAIProviderOptions>): OpenAIProvider;
+/** Create an Anthropic provider. Reads `ANTHROPIC_API_KEY` from the environment when no `apiKey` is passed. */
+declare function anthropic(arg?: ModelOrOptions<AnthropicProviderOptions>): AnthropicProvider;
+/** Optional OpenRouter-specific options for routing and attribution. */
+interface OpenRouterFactoryOptions extends Omit<OpenAIProviderOptions, "apiKey" | "baseURL"> {
+    apiKey?: string;
+    /** Sent as `HTTP-Referer`. OpenRouter shows the app on its leaderboard. */
+    httpReferer?: string;
+    /** Sent as `X-OpenRouter-Title`. Human-readable app name on the OpenRouter dashboard. */
+    appTitle?: string;
+}
+declare function openrouter(arg?: string | OpenRouterFactoryOptions): OpenAIProvider;
+declare function kimi(arg?: string | OpenRouterFactoryOptions): OpenAIProvider;
+/** Optional Gemini factory options. Mirrors the OpenAI/anthropic shape. */
+interface GeminiFactoryOptions extends Omit<OpenAIProviderOptions, "apiKey" | "baseURL"> {
+    apiKey?: string;
+}
+declare function gemini(arg?: string | GeminiFactoryOptions): OpenAIProvider;
+
+/** Interface for reading secrets at runtime. v1 default: env-only. */
+interface SecretSource {
+    get(key: string): Promise<string | undefined>;
+}
+/**
+ * Reads secrets from process.env. Default for all v1 integrations.
+ * v1.1 will add VaultSecretSource, DopplerSecretSource, AWSSecretsSource.
+ */
+declare class EnvSecretSource implements SecretSource {
+    get(key: string): Promise<string | undefined>;
+}
+
+/**
+ * Integration abstract base class: namespace-scoped tool bundle.
+ * Mirrors `kaji.runtime.integrations.base.Integration`.
+ */
+
+/**
+ * Mark a handler function as a tool with the given metadata.
+ *
+ * Usage on an Integration subclass:
+ *
+ *   readonly retrieveCharge = tool(
+ *     { description: "Retrieve a charge", parameters: {...}, risk: "read" },
+ *     async (ctx, args) => { ... },
+ *   );
+ *
+ * `Integration.tools()` will auto-discover all own properties that are
+ * handlers marked this way.
+ */
+declare function tool(meta: ToolMeta, handler: ToolHandler): ToolHandler;
+declare abstract class Integration {
+    /** The namespace prefix applied to all tools in this integration. */
+    abstract readonly namespace: string;
+    /** Return all [spec, handler] pairs for this integration.
+     *
+     * The default implementation scans own instance properties for handlers
+     * marked with `tool(meta, fn)`. Override to return tuples manually.
+     */
+    tools(): [ToolSpec, ToolHandler][];
+    /** Register all tools into the given registry, namespace-prefixed. */
+    register(registry: ToolRegistry): void;
+}
+
+/**
+ * Function-level `functionTool` for one-off tools without an `Integration` subclass.
+ * Mirrors `kaji.runtime.integrations.functional`.
+ *
+ * The class-based `Integration` path remains the right shape for namespaced,
+ * multi-tool bundles. This module adds a lightweight alternative for the common
+ * case of "I have one async function; expose it as a tool."
+ *
+ *   const getWeather = functionTool(
+ *     { description: "Return weather.", parameters: z.object({ city: z.string() }) },
+ *     async ({ city }) => ({ city, tempF: 68 }),
+ *   );
+ *
+ *   const runtime = new AgentBuilder().provider(p).tool(getWeather).build();
+ */
+
+type ArgsOf<P> = P extends z.ZodType ? z.input<P> : Record<string, unknown>;
+/** Signature accepted by `functionTool`. Zod validates the provider arguments,
+ * but its defaults, coercions, and transformations are deliberately discarded.
+ * The second context parameter may be ignored and matches registry handlers. */
+type FunctionToolHandler<P> = (args: ArgsOf<P>, context: ToolExecutionContext) => Promise<unknown>;
+/** Tool packaged with its spec + adapter handler, registrable like an Integration. */
+declare class BoundTool {
+    readonly spec: ToolSpec;
+    readonly handler: ToolHandler;
+    readonly namespace: string;
+    constructor(spec: ToolSpec, handler: ToolHandler, namespace?: string);
+    register(registry: ToolRegistry): void;
+}
+interface FunctionToolMeta<P> extends Omit<ToolMeta, "parameters"> {
+    /** Tool name. Defaults to the handler's `.name` if available. */
+    name?: string;
+    /** Zod schema or JSON Schema describing the arguments. */
+    parameters: P;
+    /** Namespace prefix (defaults to "fn"). */
+    namespace?: string;
+}
+/**
+ * Build a single tool from a meta + handler pair. The handler receives the
+ * a byte-equivalent isolated clone after validation succeeds.
+ */
+declare function functionTool<P extends z.ZodType | Record<string, unknown>>(meta: FunctionToolMeta<P>, handler: FunctionToolHandler<P>): BoundTool;
+
+type IntegrationValidationCode = "INTEGRATION_SCHEMA_INVALID";
+type IntegrationStability = "experimental" | "beta";
+type IntegrationRuntime = "python" | "typescript";
+type IntegrationToolRisk = ToolRisk;
+interface NormalizedIntegrationValidationError {
+    code: IntegrationValidationCode;
+    path: string;
+}
+declare abstract class IntegrationValidationError extends Error {
+    readonly code: IntegrationValidationCode;
+    readonly path: string;
+    protected constructor(code: IntegrationValidationCode, path: string, message: string);
+    normalized(): NormalizedIntegrationValidationError;
+}
+declare class ManifestValidationError extends IntegrationValidationError {
+    constructor(path: string, message: string);
+}
+declare class IndexValidationError extends IntegrationValidationError {
+    constructor(path: string, message: string);
+}
+declare class IntegrationExperimentalError extends Error {
+    readonly integrationName: string;
+    readonly code: "INTEGRATION_EXPERIMENTAL";
+    readonly path: string;
+    constructor(integrationName: string);
+    normalized(): {
+        code: "INTEGRATION_EXPERIMENTAL";
+        path: string;
+    };
+}
+declare class IntegrationNotFoundError extends Error {
+    readonly integrationName: string;
+    constructor(integrationName: string);
+}
+interface RegistryIndexEntry {
+    manifest: string;
+    stability: IntegrationStability;
+    runtimes: IntegrationRuntime[];
+}
+interface RegistryIndexDocument {
+    $schema: "./index.schema.json";
+    version: string;
+    integrations: Record<string, RegistryIndexEntry>;
+}
+type IntegrationAuth = Readonly<{
+    kind: "none";
+}> | Readonly<{
+    kind: "env";
+    env: string;
+    optional?: boolean;
+    docs?: string;
+}> | Readonly<{
+    kind: "oauth";
+    provider: "google";
+    clientIdEnv: string;
+    clientSecretEnv?: string;
+    scopes: readonly string[];
+    docs?: string;
+}>;
+interface IntegrationManifestTool {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: JSONSchema;
+    readonly risk: IntegrationToolRisk;
+    readonly parallel_safe: boolean;
+    readonly timeout_ms?: number;
+}
+interface IntegrationManifestDocument {
+    name: string;
+    version: string;
+    namespace: string;
+    description: string;
+    auth: IntegrationAuth;
+    files: string[];
+    tools: IntegrationManifestTool[];
+    extras?: string[];
+    peerDeps?: Record<string, string>;
+}
+interface LoadedIntegrationManifest extends IntegrationManifestDocument {
+    stability: IntegrationStability;
+    runtimes: IntegrationRuntime[];
+    /** Absolute path to manifest.json. */
+    path: string;
+    /** Absolute directory containing manifest.json. */
+    root: string;
+}
+interface RegistryLoaderOptions {
+    /** Directory containing schema.json and index.schema.json. Defaults to registryRoot. */
+    schemaRoot?: string;
+    /** Reuse an already validated index when loading several manifests. */
+    index?: RegistryIndexDocument;
+}
+declare function validateManifestDocument(document: unknown, options: {
+    schemaRoot: string;
+}): Promise<IntegrationManifestDocument>;
+declare function validateIndexDocument(document: unknown, options: {
+    schemaRoot: string;
+}): Promise<RegistryIndexDocument>;
+declare function loadRegistryIndex(registryRoot: string, options?: RegistryLoaderOptions): Promise<RegistryIndexDocument>;
+declare function loadManifest(registryRoot: string, name: string, options?: RegistryLoaderOptions): Promise<LoadedIntegrationManifest>;
+declare function formatIntegrationError(error: unknown): string;
+
+interface SafeFetchPolicy {
+    readonly allowedHosts: readonly string[];
+    readonly allowPublicInternet?: boolean;
+    readonly allowHttp?: boolean;
+    readonly timeoutMs?: number;
+    readonly maxResponseBytes?: number;
+    readonly maxRedirects?: number;
+    /** Additional credential-bearing request headers to remove on cross-origin redirects. */
+    readonly sensitiveHeaders?: readonly string[];
+}
+interface BoundNetworkTransport {
+    request(target: {
+        readonly url: URL;
+        readonly validatedAddresses: readonly string[];
+    }, init: RequestInit & {
+        readonly signal: AbortSignal;
+    }): Promise<Response>;
+}
+interface BoundedResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly bytes: Uint8Array;
+}
+/** Injectable only so registry tests and application egress adapters never need public DNS. */
+type AddressResolver = (hostname: string) => Promise<readonly string[]>;
+/**
+ * Execute one bounded request through an address-pinning application transport.
+ * The optional resolver argument is intentionally not re-exported from the beta root.
+ */
+declare function safeRequest(input: URL, init: RequestInit, context: ToolExecutionContext, policy: SafeFetchPolicy, transport: BoundNetworkTransport, resolver?: AddressResolver): Promise<BoundedResponse>;
+
+/** Whole-turn execution limits and stable timeout errors. */
+type TurnPhase = "queue" | "provider_open" | "provider_stream" | "approval" | "tool";
+type TurnOutcome = "not_started" | "failed" | "unknown";
+interface TurnExecutionLimits {
+    readonly turnTimeoutMs: number;
+    readonly providerCancellationGraceMs: number;
+    readonly providerTextMaxBytes: number;
+    readonly providerToolArgumentsMaxBytes: number;
+    readonly providerResponseMaxBytes: number;
+    readonly providerToolCallsMax: number;
+}
+declare const DEFAULT_TURN_EXECUTION_LIMITS: Readonly<TurnExecutionLimits>;
+declare class TurnTimeoutError extends Error {
+    readonly phase: TurnPhase;
+    readonly retryable: boolean;
+    readonly outcome: TurnOutcome;
+    readonly code: "TURN_TIMEOUT";
+    constructor(phase: TurnPhase, retryable: boolean, outcome: TurnOutcome);
+}
+declare class ProviderCancellationContractViolation extends Error {
+    readonly phase: Extract<TurnPhase, "provider_open" | "provider_stream">;
+    readonly code: "PROVIDER_CANCELLATION_CONTRACT_VIOLATION";
+    readonly retryable = false;
+    readonly outcome: "unknown";
+    constructor(phase?: Extract<TurnPhase, "provider_open" | "provider_stream">);
+}
+
+/** Cancellation token whose state changes can be observed while queued. */
+interface ObservableCancellationToken extends CancellationTokenLike {
+    readonly signal: AbortSignal;
+}
+/** Process-local serialization boundary for turns that share a session. */
+interface SessionTurnCoordinator {
+    acquire(sessionId: string, token?: ObservableCancellationToken, options?: TurnLeaseOptions): Promise<SessionTurnLease>;
+    quarantine(sessionId: string): void | Promise<void>;
+    clearQuarantine(sessionId: string): void | Promise<void>;
+    runExclusive<T>(sessionId: string, token: ObservableCancellationToken | undefined, operation: () => Promise<T>): Promise<T>;
+}
+interface TurnLeaseOptions {
+    readonly deadlineMonotonicMs?: number;
+    readonly clock?: Clock;
+    readonly scheduler?: TimerScheduler;
+}
+/** Exclusive ownership that may be transferred to runtime quarantine. */
+interface SessionTurnLease {
+    transfer(): SessionTurnLease;
+    release(): void | Promise<void>;
+}
+/**
+ * FIFO keyed coordinator for one process. Different session IDs never share a
+ * queue; callers that need cross-process serialization must inject another
+ * implementation.
+ */
+declare class InMemorySessionTurnCoordinator implements SessionTurnCoordinator {
+    private readonly entries;
+    /** Number of session queues currently held or waiting. */
+    get entryCount(): number;
+    /** Total actively linked waiters across session queues. */
+    get waitingCount(): number;
+    runExclusive<T>(sessionId: string, token: ObservableCancellationToken | undefined, operation: () => Promise<T>): Promise<T>;
+    acquire(sessionId: string, token?: ObservableCancellationToken, options?: TurnLeaseOptions): Promise<SessionTurnLease>;
+    quarantine(sessionId: string): void;
+    clearQuarantine(sessionId: string): void;
+    private lease;
+    private enqueue;
+    private unlink;
+    private release;
+}
+
+interface StreamDiagnostics {
+    readonly inputFragments: number;
+    readonly durableDeltaEvents: number;
+    readonly deltaJoinOperations: number;
+    readonly responseJoinOperations: number;
+    readonly textBytes: number;
+    readonly totalResponseBytes: number;
+    readonly toolCalls: number;
+    readonly rawFragments: number;
+    readonly toolArgumentJoinOperations: number;
+}
+
+/**
+ * Agent runtime: the ReAct tool-using loop, mirroring
+ * `kaji.runtime.agents.runtime.AgentRuntime`.
+ *
+ * runTurn: replay state -> build messages -> stream from provider -> emit
+ * events -> execute a bounded tool batch -> loop until the
+ * provider returns no tool calls -> emit AgentMessageCompleted.
+ */
+
+/** Tuning parameters for the ReAct loop, mirroring Python `AgentStrategy`. */
+interface AgentStrategy {
+    /** Maximum tool-call iterations before the loop terminates. Default: 5. */
+    maxToolIterations?: number;
+    /**
+     * When `false`, the loop breaks after the first provider response even if
+     * it requested tool calls (the calls are never executed). Default: `true`.
+     */
+    allowToolCalls?: boolean;
+}
+interface AgentRuntimeOptions {
+    provider: ModelProvider;
+    store: EventStore;
+    /** Canonical append + subscription boundary. */
+    committer: EventCommitter;
+    systemPrompt?: string;
+    strategy?: AgentStrategy;
+    /**
+     * Tool specs to surface to the provider each turn. When provided, only
+     * these tools are offered (scoped registry). When omitted, falls back to
+     * `listToolSpecs()` from the global registry.
+     */
+    tools?: ToolSpec[];
+    /**
+     * Optional tool policy. When provided, tool calls whose risk level is in
+     * `policy.requireApprovalFor` require an `approvalHandler` before execution.
+     */
+    policy?: ToolPolicy;
+    /**
+     * Optional approval handler for tools that require explicit approval.
+     * Wired into the default `ToolPlanner` when `planner` is not provided.
+     */
+    approvalHandler?: TypedApprovalHandler;
+    /**
+     * Tool execution planner. When omitted, a default planner is constructed from
+     * `toolExecutor`, `policy`, `approvalHandler`, and `tools`.
+     */
+    planner?: ToolPlanner;
+    /**
+     * Scoped tool executor. Used by the default planner when `planner` is omitted.
+     * Falls back to the global `executeTool` registry.
+     */
+    toolExecutor?: ToolExecutor;
+    /** Runtime-lifetime tool execution bounds used by every dynamic planner. */
+    toolExecutionLimits?: Partial<ToolExecutionLimits>;
+    /** Replace the process-local tool idempotency ledger. */
+    toolIdempotencyLedger?: ToolIdempotencyLedger;
+    /** Whole-turn deadline and provider response bounds. */
+    turnExecutionLimits?: Partial<TurnExecutionLimits>;
+    /** Explicit defaults for a single-tenant application. */
+    defaultContext?: TurnContext;
+    /**
+     * Defaults to one process-local coordinator per store object. Inject a
+     * distributed implementation when runtimes span processes.
+     */
+    turnCoordinator?: SessionTurnCoordinator;
+    /** Complete-turn provider-history bounds. Defaults to 32 turns / 100,000 characters. */
+    contextWindow?: ContextWindow;
+    /** Dependency-free recording sink; defaults to a no-op. */
+    metricsSink?: MetricsSink;
+    /** Privileged trace sink; defaults to a no-op. */
+    traceSink?: TraceSink;
+    /** Scoped identifier source used for every runtime and event identifier. */
+    idFactory?: IdFactory;
+    /** Wall and monotonic clock used by runtime events and timing. */
+    clock?: Clock;
+    /** Disposable one-shot timers used for deterministic deadline races. */
+    timerScheduler?: TimerScheduler;
+}
+/** Immutable snapshot of the resolved limits used by one runtime instance. */
+interface EffectiveRuntimeLimits {
+    readonly maxToolIterations: number;
+    readonly contextWindowTurns: number | null;
+    readonly contextWindowCharacters: number | null;
+    readonly toolMaxParallel: number;
+    readonly toolTimeoutMs: number | null;
+    readonly approvalTimeoutMs: number;
+    readonly turnTimeoutMs: number;
+    readonly providerCancellationGraceMs: number;
+    readonly providerTextMaxBytes: number;
+    readonly providerToolArgumentsMaxBytes: number;
+    readonly providerResponseMaxBytes: number;
+    readonly providerToolCallsMax: number;
+}
+interface RunTurnOptions {
+    cancellationToken?: CancellationToken;
+    context?: TurnContext;
+}
+interface TurnOptions {
+    /** Existing session to reuse; a fresh UUID is generated when omitted. */
+    sessionId?: string;
+    cancellationToken?: CancellationToken;
+    context?: TurnContext;
+}
+/**
+ * Result of one `AgentRuntime.turn` call.
+ *
+ * - `text` is built from `AGENT_MESSAGE_COMPLETED` content joined across
+ *   iterations, not delta accumulation. It may be empty when the provider keeps
+ *   returning tool calls; inspect `events` for `AGENT_TURN_EXHAUSTED`.
+ * - `toolCallEvents` are `KajiEvent`s of type `TOOL_CALL_REQUESTED`, not
+ *   provider-neutral `ToolCall` payloads. The name reflects the type.
+ * - `events` contains persisted events after this call's starting cursor.
+ * - `accounting` covers completed provider iterations, including iterations
+ *   with no durable assistant completion event.
+ */
+interface TurnResult {
+    text: string;
+    sessionId: string;
+    turnId: string;
+    toolCallEvents: StoredKajiEvent[];
+    events: StoredKajiEvent[];
+    accounting: TurnAccounting;
+}
+/** Immutable provider usage and cost totals for one successful turn. */
+interface TurnAccounting {
+    readonly providerIterations: number;
+    readonly usage: Readonly<TokenUsage> | null;
+    readonly usageComplete: boolean;
+    readonly costUsd: number | null;
+    readonly costComplete: boolean;
+}
+declare class AgentRuntime {
+    private readonly provider;
+    private readonly store;
+    private readonly committer;
+    private readonly systemPrompt?;
+    private readonly maxToolIterations;
+    private readonly allowToolCalls;
+    private readonly fixedTools;
+    private readonly toolExecutor;
+    private readonly policy;
+    private readonly approvalHandler;
+    private readonly defaultContext;
+    private readonly turnCoordinator;
+    private readonly contextWindow;
+    private readonly projectionCacheCapacity;
+    private readonly projectors;
+    private readonly projectionTails;
+    private readonly activeProjectionSessions;
+    private readonly turnEventCollectors;
+    private readonly contextDiagnosticsBySession;
+    private readonly streamDiagnosticsBySession;
+    private readonly toolExecutionController;
+    private readonly metrics;
+    private readonly trace;
+    private readonly idFactory;
+    private readonly clock;
+    private readonly turnLimits;
+    private readonly providerResponseLimits;
+    private readonly timerScheduler;
+    private readonly providerQuarantine;
+    private readonly storeRuntimeOwner;
+    private closed;
+    /**
+     * Resolved planner: explicit if caller provided one, cached when the tool
+     * set is fixed at construction, `null` when the runtime must rebuild a
+     * planner per turn from the dynamic global registry.
+     */
+    private readonly planner;
+    constructor(options: AgentRuntimeOptions);
+    private buildPlanner;
+    private resolvePlanner;
+    /** Drain actual tool handler settlement without claiming cancellation stopped work. */
+    drainTools(timeoutMs: number): Promise<readonly string[]>;
+    drainProviders(timeoutMs: number): Promise<readonly string[]>;
+    /**
+     * Deterministically remove one settled session from the store and every
+     * runtime-owned cache. Applications should shut down in this order:
+     *
+     * ```ts
+     * await runtime.drainTools(graceMs);
+     * await runtime.drainProviders(graceMs);
+     * await runtime.purgeSession(sessionId);
+     * runtime.close();
+     * ```
+     */
+    purgeSession(sessionId: string): Promise<boolean>;
+    private finishIrreversiblePurge;
+    private sessionPurgeUnsupportedComponent;
+    private closeSessionSubscriptions;
+    close(): void;
+    private hasBusySessionState;
+    private clearSessionCaches;
+    private releaseSettledSession;
+    private ensureOpen;
+    /** Return an immutable snapshot of the limits this runtime will use. */
+    effectiveLimits(): Readonly<EffectiveRuntimeLimits>;
+    private resolveTurnContext;
+    private event;
+    /** Canonical application write path for event drafts. */
+    appendEvent(event: NewKajiEvent): Promise<StoredKajiEvent>;
+    private projectorFor;
+    private withProjectionSession;
+    private trimProjectionCache;
+    get projectionCacheSize(): number;
+    private withProjectionLock;
+    private syncProjection;
+    /** Diagnostics from the latest provider context built for a session. */
+    contextDiagnostics(sessionId: string): ContextDiagnostics | undefined;
+    /** Immutable counters from the latest provider call for a session. */
+    streamDiagnostics(sessionId: string): StreamDiagnostics | undefined;
+    /** Read index counters without creating a session projector. */
+    contextIndexStats(sessionId: string): Readonly<ContextIndexStats> | undefined;
+    private runCoordinated;
+    /**
+     * Run one full agent turn and return a structured result.
+     *
+     * Wraps the ceremony of bootstrapping a session, sending the prompt,
+     * running the ReAct loop, and slicing the new events out of the store.
+     * Errors from the underlying loop propagate unchanged.
+     */
+    turn(prompt: string, options?: TurnOptions): Promise<TurnResult>;
+    /**
+     * Append a user message and immediately run the agent turn.
+     *
+     * This is the idiomatic one-shot call:
+     *   await runtime.send("s1", "What time is it?");
+     *
+     * For more control (batch-append, replay, pre-seeding), call `appendEvent()`
+     * and then `runTurn()` separately.
+     */
+    send(sessionId: string, content: string, options?: RunTurnOptions): Promise<void>;
+    private sendUnlocked;
+    /**
+     * Return a cursor page of persisted events for `sessionId` in append order.
+     */
+    history(sessionId: string, options?: {
+        afterSequence?: number;
+        limit?: number;
+    }): Promise<StoredKajiEvent[]>;
+    runTurn(sessionId: string, options?: RunTurnOptions): Promise<void>;
+    private runTurnUnlocked;
+    private recordTurnFailure;
+}
+
+/**
+ * AgentBuilder: fluent builder for AgentRuntime.
+ * Mirrors `kaji.runtime.agents.builder.AgentBuilder`.
+ */
+
+/** Anything with a register(registry: ToolRegistry) method. */
+interface Integrable {
+    register(registry: ToolRegistry): void;
+}
+interface AgentBuilderBuildOptions {
+    /** Canonical append + subscription boundary. */
+    committer?: EventCommitter;
+    /** Defaults to the injected committer's store, otherwise a fresh in-memory store. */
+    store?: EventStore;
+    /** Defaults to the process-local coordinator shared by this store object. */
+    turnCoordinator?: SessionTurnCoordinator;
+}
+declare class AgentBuilder {
+    private _provider;
+    private readonly _integrations;
+    private _policy;
+    private _approvalHandler;
+    private _systemPrompt;
+    private _strategy;
+    private _contextWindow;
+    private _defaultContext;
+    private _toolExecutionLimits;
+    private _turnExecutionLimits;
+    private _toolIdempotencyLedger;
+    private _metricsSink;
+    private _traceSink;
+    private _idFactory;
+    private _clock;
+    private _timerScheduler;
+    provider(p: ModelProvider): this;
+    integration(i: Integrable): this;
+    /** Add a function-level tool created by `functionTool({...}, handler)`. */
+    tool(bound: Integrable): this;
+    policy(p: ToolPolicy): this;
+    approvalHandler(handler: TypedApprovalHandler): this;
+    systemPrompt(prompt: string): this;
+    strategy(s: AgentStrategy): this;
+    contextWindow(window: ContextWindow): this;
+    /** Configure explicit defaults for a single-tenant application. */
+    defaultContext(context: TurnContext): this;
+    toolExecutionLimits(limits: Partial<ToolExecutionLimits>): this;
+    turnExecutionLimits(limits: Partial<TurnExecutionLimits>): this;
+    toolIdempotencyLedger(ledger: ToolIdempotencyLedger): this;
+    metricsSink(sink: MetricsSink): this;
+    traceSink(sink: TraceSink): this;
+    idFactory(factory: IdFactory): this;
+    clock(clock: Clock): this;
+    timerScheduler(scheduler: TimerScheduler): this;
+    build(opts?: AgentBuilderBuildOptions): AgentRuntime;
+}
+
+/**
+ * One-shot helpers: call a provider without spinning up the full
+ * event-sourced runtime. Use when you just want one model response.
+ *
+ *   const { text } = await generateText({
+ *     provider: openai("gpt-5.4-mini"),
+ *     messages: [{ role: "user", content: "Hello" }],
+ *   });
+ *
+ * For tool-using ReAct loops, durable replay, batched tools, or policy
+ * gating, build an `AgentRuntime`/`AgentBuilder` instead.
+ */
+
+interface GenerateTextOptions extends ModelProviderOptions {
+    provider: ModelProvider;
+    messages: ProviderMessage[];
+    /** Optional tool specs to surface to the model. */
+    tools?: ToolSpec[];
+}
+/**
+ * Single-call wrapper around `provider.generate`. Returns the full text and
+ * any tool calls the model produced. Does not execute tool calls; the caller
+ * decides what to do with them.
+ */
+declare function generateText(options: GenerateTextOptions): Promise<ModelResponse>;
+interface StreamTextResult {
+    /**
+     * Async-iterable of text deltas as they arrive from the provider.
+     *
+     * Each of `textStream`, `text`, and `toolCalls` is independently
+     * consumable; awaiting any one of them does not require iterating
+     * any of the others. All three reject if the source stream errors.
+     */
+    textStream: AsyncIterable<string>;
+    /** Resolves to the concatenated text once the source stream finishes. */
+    text: Promise<string>;
+    /** Resolves to the tool calls the model emitted, if any. */
+    toolCalls: Promise<ModelResponse["toolCalls"]>;
+}
+/**
+ * Stream a single provider call. All three result handles
+ * (`textStream`, `text`, `toolCalls`) are independent: the source stream
+ * is drained eagerly in the background so awaiting any one of them is
+ * sufficient. All three reject if the source errors.
+ *
+ *   const { textStream, text } = streamText({ provider: openai("gpt-5.4-mini"), messages });
+ *   for await (const chunk of textStream) process.stdout.write(chunk);
+ *   console.log("\nfinal:", await text);
+ *
+ * For a non-streaming one-shot, use `generateText`.
+ */
+declare function streamText(options: GenerateTextOptions): StreamTextResult;
+
+interface EventApprovalHandlerOptions {
+    /** Monotonic clock source for approval deadlines. */
+    now?: () => number;
+    idFactory?: IdFactory;
+    clock?: Clock;
+}
+declare class EventApprovalHandler implements EventBackedApprovalHandler {
+    readonly approvalRequestOwner: "handler";
+    private readonly now;
+    private readonly idFactory;
+    private readonly clock;
+    constructor(options?: EventApprovalHandlerOptions);
+    request(call: ToolCall, context: ApprovalRequestContext): Promise<ApprovalDecision>;
+}
+
+/**
+ * Policy-driven approval handler that resolves decisions synchronously
+ * without any I/O. Useful for testing, sandboxed environments, or as a
+ * safe default that denies everything not explicitly listed.
+ */
+
+interface AutoApprovalPolicy {
+    /** Tool names to always allow, regardless of `allowAll`. */
+    allow: string[];
+    /** Tool names to always deny (checked before `allow`). */
+    deny: string[];
+    /** When `true`, allow any tool that is not in `deny`. Defaults to `false`. */
+    allowAll?: boolean;
+}
+declare class AutoApprovalHandler implements TypedApprovalHandler {
+    private readonly policy;
+    constructor(policy: AutoApprovalPolicy);
+    request(call: ToolCall, _context: ApprovalRequestContext): Promise<ApprovalDecision>;
+}
+
+/**
+ * Kaji: build agents in TypeScript.
+ *
+ * Infra-free core, mirroring the Python `kaji` SDK's public surface:
+ * event-sourced building blocks (events, bus, store, replay) and a tool
+ * registry. Import what you need and compose it; nothing here requires a
+ * database, server, or any environment configured.
+ *
+ * Implementation helpers (test resets, internal symbols, low-level Zod/JSON
+ * Schema converters, the planner's `EmitFn`/`buildMessages`) deliberately are
+ * not re-exported here; reach into the submodule path when you need them.
+ */
+declare const VERSION = "0.2.0-beta.11";
+
+export { AgentBuilder, type AgentBuilderBuildOptions, AgentRuntime, type AgentRuntimeOptions, type AgentStrategy, AnthropicProvider, type AnthropicProviderOptions, type ApprovalDeadlineSource, type ApprovalDecision, type ApprovalRejectionCode, type ApprovalRequestContext, AutoApprovalHandler, type AutoApprovalPolicy, type BoundNetworkTransport, BoundTool, type BoundedResponse, CancellationToken, CancellationTokenLike, type CliApprovalInput, type CliApprovalOptions, type CliApprovalOutput, Clock, ContextDiagnostics, ContextWindow, DEFAULT_TOOL_EXECUTION_LIMITS, DEFAULT_TURN_EXECUTION_LIMITS, DurableJsonLimitError, type EffectiveRuntimeLimits, EnvSecretSource, EventApprovalHandler, type EventApprovalHandlerOptions, type EventBackedApprovalHandler, EventBufferOverflowError, EventBus, type EventBusProtocol, type EventCommitter, EventDeliveryError, EventIdConflictError, EventSchemaIncompatibleError, type EventStore, EventStoreCapacityError, EventType, type FunctionToolHandler, type FunctionToolMeta, type GeminiFactoryOptions, type GenerateTextOptions, IdFactory, IdempotencyCapacityError, IdempotencyConflictError, InMemoryEventCommitter, type InMemoryEventCommitterOptions, InMemoryEventStore, InMemorySessionStore, InMemorySessionTurnCoordinator, InMemoryToolIdempotencyLedger, type InMemoryToolIdempotencyLedgerOptions, IndexValidationError, type Integrable, Integration, type IntegrationAuth, IntegrationExperimentalError, type IntegrationManifestDocument, type IntegrationManifestTool, IntegrationNotFoundError, type IntegrationRuntime, type IntegrationStability, type IntegrationToolRisk, type IntegrationValidationCode, IntegrationValidationError, InvalidDurableValueError, JSONSchema, KajiEvent, type LoadedIntegrationManifest, ManifestValidationError, MetricsSink, type ModelCostEntry, ModelProvider, ModelProviderOptions, ModelResponse, ModelResponseChunk, NewKajiEvent, type NormalizedIntegrationValidationError, type NormalizedProviderError, type ObservableCancellationToken, OpenAIProvider, type OpenAIProviderOptions, type OpenRouterFactoryOptions, ProviderAPIError, ProviderCancellationContractViolation, ProviderConfigError, ProviderConnectionError, ProviderError, ProviderMessage, type ProviderOutputDimension, ProviderOutputLimitError, ProviderRateLimitedError, type PurgeableEventStore, type RegistryIndexDocument, type RegistryIndexEntry, type RegistryLoaderOptions, RetryOptions, type RunTurnOptions, type SafeFetchPolicy, type SecretSource, SessionManager, SessionProjector, SessionPurgeBusyError, SessionPurgeUnsupportedError, type SessionRecord, SessionState, type SessionStore, type SessionTurnCoordinator, type SessionTurnLease, SplitEventCommitter, type SplitEventCommitterOptions, StoredKajiEvent, type StreamTextResult, TimerScheduler, TokenUsage, ToolCall, type ToolCallInstruction, type ToolCallResult, type ToolClaimResult, ToolExecutionContext, ToolExecutionController, type ToolExecutionControllerOptions, type ToolExecutionControllerOutcome, ToolExecutionError, type ToolExecutionLimits, type ToolExecutionRequest, type ToolExecutor, type ToolFailureFields, type ToolFailureOutcome, ToolHandler, type ToolIdempotencyClaim, type ToolIdempotencyLedger, type ToolLedgerOutcome, ToolPlanner, type ToolPlannerOptions, ToolPolicy, type ToolPolicyOptions, ToolPolicyViolation, ToolRegistry, ToolRisk, ToolSpec, TraceSink, type TurnAccounting, TurnContext, type TurnOutcome as TurnDeadlineOutcome, type TurnExecutionLimits, type TurnLeaseOptions, type TurnOptions, type TurnPhase, type TurnResult, TurnTimeoutError, type TypedApprovalHandler, VERSION, anthropic, calculateCostUsd, cliApprovalHandler, formatIntegrationError, functionTool, gemini, generateText, getProvider, kimi, loadManifest, loadRegistryIndex, lookupCost, normalizeProviderError, openai, openrouter, registerProvider, safeRequest, streamText, supportsSessionPurge, tool, validateIndexDocument, validateManifestDocument };