@kodax-ai/kodax 0.7.96 → 0.7.97-alpha.2

package/dist/types-chunks/client-contract-A1jdk6xz.d.ts

@@ -0,0 +1,1993 @@
+import { ai as KodaXJsonValue, ab as KodaXExtensionSessionState, aa as KodaXExtensionSessionRecord, ao as KodaXSessionArtifactLedgerEntry, bB as SessionErrorMetadata, aQ as MemoryActionProposal, aT as MemoryApplyResult, bh as MemoryRejectResult, bf as MemoryRefFilter, b6 as MemoryItemRef, aY as MemoryBodySnapshot, bi as MemoryRememberInput, bj as MemoryRememberResult, b8 as MemoryLifecycleOperationResult, by as PendingEpisodeReviewSummary, af as KodaXGoalState, at as KodaXSessionEntry, N as AgentTreeSnapshot, s as AgentDetail, M as AgentSpawnInput, Q as AgentTurnRef, r as AgentDataClassification, y as AgentFollowupResult, I as AgentOutput, t as AgentEvent } from './review-inbox.d-BeaLRNHx.js';
+import { P as ProviderRequestObservation } from './provider-request-observation.d-jL8T6wVO.js';
+import { b8 as WorkflowIsolation, aN as LearningQuery, aM as LearningPage, ax as LearnedCapabilityRecord, aP as LearningSurfaceSnapshot, aI as LearningEvent, aO as LearningSubscribeOptions, a4 as CompactionReport, bt as WorkflowProcessSnapshot, _ as AskUserQuestionOptions, Y as AskUserMultiOptions, am as KodaXInputArtifact, aW as ManagedWorkflowStatus, bm as WorkflowProcessEvent, W as AskUserAnswer, ah as ExternalAgentRegistrationSummary, ag as ExternalAgentRegistration, J as AgentRegistrationMutationOptions, I as AgentRegistrationEnabledMutationOptions } from './types.d-o7t9dds4.js';
+import { k as KodaXMessage, W as KodaXTaskRoutingDecision, X as KodaXTaskType, Y as KodaXTaskWorkIntent, S as KodaXTaskComplexity, N as KodaXRiskLevel, h as KodaXHarnessProfile, f as KodaXExecutionMode, b as KodaXChildFanoutClass, ab as KodaXWireReasoningEffort, a2 as KodaXTokenUsage } from './types.d-BjOq57-z.js';
+
+interface CircuitBreaker {
+    readonly timestamps: readonly number[];
+}
+
+interface DenialTracker {
+    readonly consecutive: number;
+    /** Lifetime diagnostic only; never trips the breaker by itself. */
+    readonly cumulative: number;
+    /** Bounded completed-review window. `true` means the reviewer denied. */
+    readonly recent?: readonly boolean[];
+}
+
+/**
+ * KodaX Provider Resilience Types (Feature 045)
+ *
+ * Defines the type system for failure taxonomy, recovery ladder,
+ * and execution state tracking used by the resilience module.
+ */
+/**
+ * Fine-grained error classification beyond the basic ErrorCategory.
+ * Each class maps to a distinct recovery strategy.
+ */
+type ResilienceErrorClass = 'rate_limit' | 'provider_overloaded' | 'request_timeout' | 'stream_idle_timeout' | 'chunk_timeout' | 'connection_failure' | 'incomplete_stream' | 'user_abort' | 'non_retryable_provider_error' | 'reasoning_content_required';
+/**
+ * The stage of the provider request lifecycle when the failure occurred.
+ * Determines the stable boundary and recovery strategy.
+ */
+type FailureStage = 'before_request_accepted' | 'before_first_delta' | 'mid_stream_text' | 'mid_stream_thinking' | 'mid_stream_tool_input' | 'post_tool_execution_pre_assistant_close';
+
+type RuntimeContextOptimizationProfile = 'off' | 'report_only' | 'balanced' | 'small_window' | 'aggressive';
+type RuntimeContextPressure = 'low' | 'medium' | 'high' | 'critical';
+interface RuntimeContextBudgetBreakdown {
+    readonly systemPrompt: number;
+    readonly toolSchemas: number;
+    readonly skillCatalog: number;
+    readonly mcpCatalog: number;
+    readonly transcript: number;
+    readonly pendingInput: number;
+    readonly recentToolResults: number;
+    readonly reservedResponse: number;
+    readonly total: number;
+}
+interface RuntimeContextBudgetSnapshot {
+    /** The policy used by the execution owner, including its actual physical reserves. */
+    readonly compactionBudget?: {
+        readonly triggerPercent: number;
+        readonly absoluteTriggerTokens?: number;
+        readonly triggerTokens: number;
+        readonly physicalCapacityTokens: number;
+        readonly reservedResponseTokens: number;
+        readonly reservedMemoryTokens: number;
+    };
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly turnId?: string;
+    readonly contextId?: string;
+    readonly contextKind?: 'root' | 'child';
+    readonly parentContextId?: string;
+    readonly agentId?: string;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly profile: RuntimeContextOptimizationProfile;
+    readonly contextWindow: number;
+    readonly smallWindow: boolean;
+    readonly pressure: RuntimeContextPressure;
+    readonly tokenBreakdown: RuntimeContextBudgetBreakdown;
+    readonly usedTokens: number;
+    /** Diagnostic slack for the existing snapshot; never an append budget. */
+    readonly availableTokens: number;
+    readonly usedRatio: number;
+    readonly toolSchemaRatio: number;
+    readonly recommendations: readonly RuntimeContextBudgetRecommendation[];
+    readonly createdAt: string;
+}
+type RuntimeContextBudgetRecommendation = 'prefer_progressive_tool_exposure' | 'compact_or_summarize_history' | 'trim_recent_tool_results' | 'reserve_response_budget';
+
+type KodaXShellSandboxBackend = 'windows-restricted-user' | 'macos-seatbelt' | 'linux-bubblewrap' | 'unsupported';
+type KodaXShellSandboxObservation = {
+    readonly version: 1;
+    readonly state: 'applied';
+    readonly backend: KodaXShellSandboxBackend;
+    readonly policyId: 'kodax-workspace-shell-v1';
+} | {
+    readonly version: 1;
+    readonly state: 'fallback';
+    readonly reason: 'not_ready' | 'prepare_failed' | 'backend_failed' | 'session_reset_pending' | 'acl_transition_pending';
+    readonly execution: 'normal_permission_policy';
+} | {
+    readonly version: 1;
+    readonly state: 'not_selected';
+};
+interface KodaXTodoDriftWarningEvent {
+    readonly kind: 'work_started_without_claimed_todo';
+    readonly toolName: string;
+    readonly toolCallId?: string;
+    readonly count: number;
+    readonly pendingCount: number;
+    readonly openCount: number;
+    readonly firstPendingTodoId?: string;
+    readonly firstPendingTodoSubject?: string;
+}
+interface KodaXContextTokenSnapshot {
+    /** Request-local ceiling learned from rejection; cleared by new usage. */
+    capacityWindow?: number;
+    /** Current best-known token count for the full conversation context. */
+    currentTokens: number;
+    /** Local estimate for the same message set, used to adjust later message deltas. */
+    baselineEstimatedTokens: number;
+    /** Whether the snapshot is based on provider/API usage or local estimation. */
+    source: 'api' | 'estimate';
+    /** Optional turn usage from the latest provider response. */
+    usage?: KodaXTokenUsage;
+}
+interface KodaXTaskCapabilityHint {
+    kind: 'skill' | 'tool' | 'command' | 'workflow';
+    name: string;
+    details?: string;
+}
+interface KodaXTaskVerificationCriterion {
+    id: string;
+    label: string;
+    description: string;
+    threshold: number;
+    weight: number;
+    requiredEvidence?: string[];
+}
+interface KodaXRuntimeVerificationContract {
+    startupCommand?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    readySignal?: string;
+    baseUrl?: string;
+    uiFlows?: string[];
+    apiChecks?: string[];
+    dbChecks?: string[];
+    fixtures?: string[];
+}
+interface KodaXTaskVerificationContract {
+    summary?: string;
+    instructions?: string[];
+    requiredEvidence?: string[];
+    requiredChecks?: string[];
+    capabilityHints?: KodaXTaskCapabilityHint[];
+    rubricFamily?: 'code-review' | 'frontend' | 'product-completeness' | 'functionality' | 'code-quality' | 'partner-research';
+    criteria?: KodaXTaskVerificationCriterion[];
+    runtime?: KodaXRuntimeVerificationContract;
+}
+/**
+ * FEATURE_247 — SDK-consumer agent profile identity (e.g. KodaX-Space Partner).
+ *
+ * The SDK core treats this as OPAQUE attribution: it is echoed onto results,
+ * events, the effective-config snapshot, session runtimeInfo, and tool context
+ * so an embedder can confirm which profile actually ran and can attribute
+ * concurrent Partner/Coder sessions. Absent ⇒ the default Coding Agent, with no
+ * behavioral change anywhere.
+ *
+ * Only two fields carry behavior, both additive and gated on their own presence:
+ *   - `instructions` — on the SA path the embedder sets
+ *     `context.systemPromptOverride`; the AMA/AMAW path builds role prompts
+ *     internally, so when this is set the Worker role prompt PREPENDS this block
+ *     (absent ⇒ byte-identical default coding role prompt).
+ *   - `verification` — a profile-default verifier standard the Sidecar Verifier
+ *     applies; per-task `context.taskVerification` still overrides/augments it.
+ *
+ * Everything else (`surface`/`id`/`version`/`name`) is pure identity passthrough.
+ */
+interface KodaXAgentProfile {
+    /** Surface/profile label, e.g. `'code'` | `'partner'`. Opaque to the core. */
+    readonly surface?: string;
+    /** Stable profile id (UUID or stable name). Opaque to the core. */
+    readonly id?: string;
+    /** Profile version. Opaque to the core. */
+    readonly version?: string;
+    /** Human-facing display name. Opaque to the core. */
+    readonly name?: string;
+    /**
+     * Partner behavior instructions injected into the AMA/AMAW Worker role prompt
+     * (prepended). The SA path uses `context.systemPromptOverride` instead — this
+     * field is the AMA-path equivalent so a Partner profile behaves consistently
+     * across both execution modes.
+     */
+    readonly instructions?: string;
+    /**
+     * Profile-default verification standard. Merged with per-task
+     * `context.taskVerification` (per-task fields win) before reaching the Sidecar
+     * Verifier.
+     */
+    readonly verification?: KodaXTaskVerificationContract;
+}
+interface KodaXTaskToolPolicy {
+    summary: string;
+    allowedTools?: string[];
+    blockedTools?: string[];
+    allowedShellPatterns?: string[];
+    allowedWritePathPatterns?: string[];
+}
+interface KodaXChildContextBundle {
+    id: string;
+    fanoutClass: KodaXChildFanoutClass;
+    objective: string;
+    scopeSummary?: string;
+    evidenceRefs: string[];
+    constraints: string[];
+    readOnly: boolean;
+    /**
+     * FEATURE_102 / FEATURE_259 — semantic model tier intent. The runtime maps
+     * configured `fast`/`deep` tiers to concrete routes and safely inherits the
+     * parent when a tier is unavailable or ineligible.
+     */
+    modelHint?: KodaXChildModelHint;
+    /**
+     * FEATURE_217 (v0.7.49): workflow-level child isolation hint. Default is
+     * shared parent cwd; `worktree` is opt-in and parent-managed.
+     */
+    isolation?: WorkflowIsolation;
+    /**
+     * FEATURE_191 — optional registered specialist agent name. When set,
+     * the child is dispatched with that agent's `instructions` /
+     * `tools` / `reasoning` / `guardrails` instead of the stock Worker
+     * bundle. Resolved via `resolveConstructedAgent(name)` at dispatch
+     * time; unknown names are rejected by `toolDispatchChildTask` with
+     * a tool-result error (not throw) before the bundle reaches
+     * `executeReadChild` / `executeWriteChild`. Optional — omitting
+     * preserves byte-identical v0.7.42 baseline dispatch behavior.
+     */
+    specialistName?: string;
+    /**
+     * FEATURE_102 Phase 2 (v0.7.45) — explicit per-dispatch provider/model the
+     * dispatching agent chose for this child (e.g. a cross-family second review).
+     * Priority in child-executor: `bundle.provider/model` > specialist's declared
+     * model > parent default. Omitting both inherits the parent (byte-identical).
+     */
+    provider?: string;
+    model?: string;
+    /** Optional per-dispatch reasoning effort. Omit to inherit the parent effort. */
+    effort?: KodaXWireReasoningEffort;
+    /**
+     * FEATURE_246 Part B — optional JSON Schema (opaque) for the child's
+     * structured output. When set, the child briefing asks for a fenced JSON
+     * block matching it; the child executor parses + validates the result (with
+     * one bounded repair turn) and surfaces it on `KodaXChildAgentResult.structured`.
+     */
+    outputSchema?: unknown;
+    /**
+     * Runtime-only fixed AMA result contract. Unlike Workflow outputSchema,
+     * invalid output is parse-only and never starts a repair model turn.
+     */
+    structuredOutputContract?: 'pattern-disposition-parse-only';
+    /** Trusted host provenance plus the generated script's terse-result declaration. */
+    workflowOutputContract?: {
+        readonly kodaxAuthored: boolean;
+        readonly terseResult: boolean;
+    };
+}
+/**
+ * FEATURE_120 v0.7.39 Phase 4 — model tier hint. Tier semantics:
+ *   - `'fast'` — short lookups (read 1-2 files, simple grep).
+ *   - `'balanced'` — normal subtasks (default behavior; same as omit).
+ *   - `'deep'` — heavy reasoning (multi-file analysis, complex audit).
+ *
+ * `omit` ≡ `'balanced'` so the absent case maps to "default routing".
+ * Validators MUST reject other strings (the dispatch tool drops
+ * unknown values silently with a tolerant fallback to `undefined`).
+ */
+type KodaXChildModelHint = 'fast' | 'balanced' | 'deep';
+type KodaXChildTierOutcome = 'applied' | 'balanced-parent' | 'fast-write-ineligible' | 'unconfigured' | 'shadowed-by-selector' | 'inherited';
+type KodaXChildRouteSource = 'explicit' | 'specialist' | 'tier' | 'parent' | 'default';
+interface KodaXChildRouteFacts {
+    readonly requestedTier: KodaXChildModelHint | 'inherited';
+    readonly tierOutcome: KodaXChildTierOutcome;
+    readonly providerSource: KodaXChildRouteSource;
+    readonly modelSource?: Exclude<KodaXChildRouteSource, 'default'>;
+    readonly initialProvider?: string;
+    readonly initialModel?: string;
+    readonly finalProvider?: string;
+    readonly finalModel?: string;
+    readonly resolvedEffort?: string;
+    readonly fallbackReason?: string;
+    readonly iterations?: number;
+    readonly inputTokens?: number;
+    readonly cacheReadTokens?: number;
+    readonly outputTokens?: number;
+    readonly digestTokens?: number;
+    readonly durationMs?: number;
+}
+/**
+ * Bounded terminal execution failure facts. Provider failures use only safe
+ * structured facts, never raw upstream messages or bodies. Local exceptions
+ * retain a bounded diagnostic with scoped Provider credentials redacted.
+ */
+interface KodaXExecutionFailure {
+    readonly source?: 'provider' | 'local';
+    /** Bounded diagnostic, independent of any assistant reply. */
+    readonly message: string;
+    readonly safeMessage: string;
+    readonly errorName?: string;
+    readonly errorClass: ResilienceErrorClass | 'local_execution_error';
+    /** Most specific safe upstream or KodaX failure code available. */
+    readonly code?: string;
+    readonly failureCode?: 'provider_not_registered' | 'request_build_failed' | 'protocol_mismatch' | 'response_stream_error';
+    readonly provider?: string;
+    readonly model?: string;
+    readonly requestPhase: FailureStage | 'local_execution';
+    readonly providerStage?: 'catalog' | 'request_build' | 'transport' | 'response_stream';
+    readonly httpStatus?: number;
+    readonly upstreamCode?: string;
+    readonly requestId?: string;
+    readonly retryAfterMs?: number;
+    readonly elapsedMs?: number;
+}
+interface KodaXChildAgentResult {
+    readonly iteration?: {
+        readonly current: number;
+        readonly max: number;
+    };
+    childId: string;
+    fanoutClass: KodaXChildFanoutClass;
+    status: 'completed' | 'blocked' | 'failed';
+    disposition: 'candidate' | 'valid' | 'false-positive' | 'needs-more-evidence';
+    summary: string;
+    evidenceRefs: string[];
+    contradictions: string[];
+    artifactPaths?: string[];
+    sessionId?: string;
+    /** Bounded workflow transcript digest. Full `summary` remains the synthesis/audit source. */
+    digest?: string;
+    /** True when a workflow child digest was attempted but failed (error/timeout/empty distillation). */
+    digestFailed?: boolean;
+    /** True when a workflow child digest is running asynchronously and may arrive later. */
+    digestPending?: boolean;
+    /** Actual provider/model selected for this child run, when known. */
+    provider?: string;
+    model?: string;
+    /** Terminal execution failure, independent of assistant text. */
+    failure?: KodaXExecutionFailure;
+    /** Actual iterations consumed by this child agent. */
+    actualIterations?: number;
+    /** Best-known token usage for this child run. Used by workflow budget accounting. */
+    totalTokensUsed?: number;
+    /** Token usage attributable only to the optional presentation digest call. */
+    digestTokensUsed?: number;
+    /** Provider-reported usage for the optional digest call (diagnostic subset of totalTokensUsed). */
+    digestUsage?: {
+        readonly inputTokens?: number;
+        readonly outputTokens?: number;
+        readonly totalTokens?: number;
+        readonly cacheReadTokens?: number;
+    };
+    /** Correlated model-tier and fallback facts for cost/quality reporting. */
+    routeFacts?: KodaXChildRouteFacts;
+    /** True when the child exhausted its iteration budget before completing. */
+    limitReached?: boolean;
+    /**
+     * True when the child's `runKodaX` exited via CAP-083 AbortError silent
+     * terminal (`KodaXResult.interrupted === true`). Surfaces the
+     * "success but empty lastText" path that produces empty
+     * `<task-completed task_id="X"></task-completed>` banners.
+     * Diagnostic field — populated by child-executor on the success branch
+     * and consumed by dispatch-child-tasks' empty-summary fallback.
+     */
+    interrupted?: boolean;
+    /**
+     * FEATURE_246 Part B — schema-validated structured output parsed from the
+     * child's final text (present only when the bundle carried `outputSchema`
+     * and a JSON value was parseable). Surfaced to the workflow runtime as
+     * `WorkflowTaskResult.structured`.
+     */
+    structured?: unknown;
+}
+interface KodaXParentReductionContract {
+    owner: 'parent';
+    strategy: 'direct-parent' | 'evaluator-assisted' | 'reducer-child';
+    collapseChildTranscripts: boolean;
+    summary: string;
+    requiredArtifacts: string[];
+}
+type KodaXMemoryStrategy = 'continuous' | 'compact' | 'reset-handoff';
+type KodaXBudgetDisclosureZone = 'green' | 'yellow' | 'orange' | 'red';
+interface KodaXManagedTaskHarnessTransition {
+    from: KodaXHarnessProfile;
+    to: KodaXHarnessProfile;
+    round: number;
+    source: 'scout' | 'evaluator';
+    reason?: string;
+    approved: boolean;
+    denialReason?: string;
+}
+type KodaXManagedTaskPhase = 'starting' | 'routing' | 'preflight' | 'round' | 'worker' | 'upgrade' | 'verifying' | 'completed';
+type KodaXManagedLiveEventPresentation = 'status' | 'assistant' | 'thinking';
+interface KodaXManagedLiveEvent {
+    key: string;
+    kind: 'progress' | 'completed' | 'notification' | 'warning';
+    presentation?: KodaXManagedLiveEventPresentation;
+    phase?: KodaXManagedTaskPhase;
+    workerId?: string;
+    workerTitle?: string;
+    summary: string;
+    detail?: string;
+    persistToHistory?: boolean;
+}
+interface KodaXVerificationScorecardCriterion {
+    id: string;
+    label: string;
+    threshold: number;
+    score: number;
+    passed: boolean;
+    weight: number;
+    requiredEvidence?: string[];
+    evidence?: string[];
+    reason?: string;
+}
+interface KodaXVerificationScorecard {
+    rubricFamily?: KodaXTaskVerificationContract['rubricFamily'];
+    overallScore: number;
+    verdict: 'accept' | 'revise' | 'blocked';
+    criteria: KodaXVerificationScorecardCriterion[];
+    trend?: 'improving' | 'flat' | 'regressing';
+    summary?: string;
+}
+interface KodaXRoleRoundSummary {
+    role: KodaXTaskRole;
+    round: number;
+    objective: string;
+    confirmedConclusions: string[];
+    unresolvedQuestions: string[];
+    nextFocus: string[];
+    summary: string;
+    sourceWorkerId?: string;
+    updatedAt: string;
+}
+interface KodaXManagedBudgetSnapshot {
+    totalBudget: number;
+    reserveBudget: number;
+    reserveRemaining: number;
+    upgradeReserveBudget?: number;
+    upgradeReserveRemaining?: number;
+    plannedRounds: number;
+    currentRound: number;
+    spentBudget: number;
+    remainingBudget: number;
+    workerId?: string;
+    role?: KodaXTaskRole;
+    currentHarness?: KodaXHarnessProfile;
+    upgradeCeiling?: KodaXHarnessProfile;
+    zone?: KodaXBudgetDisclosureZone;
+    showExactRoundCounter?: boolean;
+    allowExtensionRequest?: boolean;
+    mustConverge?: boolean;
+    softMaxIter?: number;
+    hardMaxIter?: number;
+    extensionGrantedIters?: number;
+    extensionDenied?: boolean;
+    extensionReason?: string;
+}
+type KodaXTaskSurface = 'cli' | 'repl' | 'plan';
+type KodaXTaskStatus = 'planned' | 'running' | 'blocked' | 'failed' | 'completed';
+type KodaXTaskRole = 'direct' | 'scout' | 'planner' | 'generator' | 'evaluator' | 'worker';
+interface KodaXTaskContract {
+    taskId: string;
+    surface: KodaXTaskSurface;
+    objective: string;
+    createdAt: string;
+    updatedAt: string;
+    status: KodaXTaskStatus;
+    primaryTask: KodaXTaskType;
+    workIntent: KodaXTaskWorkIntent;
+    complexity: KodaXTaskComplexity;
+    riskLevel: KodaXRiskLevel;
+    harnessProfile: KodaXHarnessProfile;
+    recommendedMode: KodaXExecutionMode;
+    requiresBrainstorm: boolean;
+    reason: string;
+    contractSummary?: string;
+    successCriteria: string[];
+    requiredEvidence: string[];
+    constraints: string[];
+    contractCreatedByAssignmentId?: string;
+    contractUpdatedAt?: string;
+    metadata?: Record<string, KodaXJsonValue>;
+    verification?: KodaXTaskVerificationContract;
+}
+interface KodaXTaskRoleAssignment {
+    id: string;
+    role: KodaXTaskRole;
+    title: string;
+    dependsOn: string[];
+    status: KodaXTaskStatus;
+    agent?: string;
+    toolPolicy?: KodaXTaskToolPolicy;
+    summary?: string;
+    sessionId?: string;
+}
+interface KodaXTaskWorkItem {
+    id: string;
+    assignmentId: string;
+    description: string;
+    execution: 'serial' | 'parallel';
+}
+interface KodaXTaskEvidenceArtifact {
+    kind: 'json' | 'text' | 'markdown' | 'image';
+    path: string;
+    description?: string;
+}
+interface KodaXTaskEvidenceEntry {
+    assignmentId: string;
+    role: KodaXTaskRole;
+    status: KodaXTaskStatus;
+    title?: string;
+    round?: number;
+    summary?: string;
+    output?: string;
+    sessionId?: string;
+    signal?: 'COMPLETE' | 'BLOCKED' | 'DECIDE';
+    signalReason?: string;
+}
+interface KodaXTaskEvidenceBundle {
+    workspaceDir: string;
+    runId?: string;
+    artifacts: KodaXTaskEvidenceArtifact[];
+    entries: KodaXTaskEvidenceEntry[];
+    routingNotes: string[];
+}
+interface KodaXOrchestrationVerdict {
+    status: KodaXTaskStatus;
+    decidedByAssignmentId: string;
+    summary: string;
+    signal?: 'COMPLETE' | 'BLOCKED' | 'DECIDE';
+    signalReason?: string;
+    signalDebugReason?: string;
+    disposition?: 'complete' | 'blocked' | 'needs_continuation';
+}
+interface KodaXManagedTaskRuntimeState {
+    childContextBundles?: KodaXChildContextBundle[];
+    childAgentResults?: KodaXChildAgentResult[];
+    parentReductionContract?: KodaXParentReductionContract;
+    budget?: KodaXManagedBudgetSnapshot;
+    scorecard?: KodaXVerificationScorecard;
+    qualityAssuranceMode?: 'required' | 'optional';
+    memoryStrategies?: Record<string, KodaXMemoryStrategy>;
+    memoryNotes?: Record<string, string>;
+    roleRoundSummaries?: Partial<Record<KodaXTaskRole, KodaXRoleRoundSummary>>;
+    routingAttempts?: number;
+    routingSource?: KodaXTaskRoutingDecision['routingSource'];
+    currentHarness?: KodaXHarnessProfile;
+    upgradeCeiling?: KodaXHarnessProfile;
+    harnessTransitions?: KodaXManagedTaskHarnessTransition[];
+    completionContractStatus?: Record<string, 'ready' | 'incomplete' | 'blocked' | 'missing'>;
+    rawRoutingDecision?: KodaXTaskRoutingDecision;
+    finalRoutingDecision?: KodaXTaskRoutingDecision;
+    routingOverrideReason?: string;
+    providerRuntimeBehavior?: {
+        downgraded?: boolean;
+        reasons: string[];
+    };
+    degradedVerification?: {
+        fallbackWorkerId?: string;
+        reason: string;
+        debugReason?: string;
+    };
+    degradedContinue?: boolean;
+    reviewFilesOrAreas?: string[];
+    toolOutputTruncated?: boolean;
+    toolOutputTruncationNotes?: string[];
+    /**
+     * Warn-only todo hygiene telemetry: successful real work started while
+     * pending todos existed and no item was marked in_progress. The runner
+     * never mutates todo state from this signal.
+     */
+    todoDriftWarnings?: KodaXTodoDriftWarningEvent[];
+    managedTimeline?: KodaXManagedLiveEvent[];
+    evidenceAcquisitionMode?: 'overview' | 'diff-bundle' | 'diff-slice' | 'file-read';
+    consecutiveEvidenceOnlyIterations?: number;
+    globalWorkBudget?: number;
+    budgetUsage?: number;
+    budgetApprovalRequired?: boolean;
+    /** FEATURE_067: Evaluator review prompt for write fan-out diffs. */
+    childWriteReviewPrompt?: string;
+    /** FEATURE_067: Number of write child diffs pending evaluator review. */
+    childWriteDiffCount?: number;
+}
+interface KodaXManagedTask {
+    contract: KodaXTaskContract;
+    roleAssignments: KodaXTaskRoleAssignment[];
+    workItems: KodaXTaskWorkItem[];
+    evidence: KodaXTaskEvidenceBundle;
+    verdict: KodaXOrchestrationVerdict;
+    runtime?: KodaXManagedTaskRuntimeState;
+}
+interface KodaXManagedVerdictPayload {
+    /** FEATURE_184 (v0.7.45): `'sidecar'` is the new architectural source —   *  Sidecar Verifier replaces the in-chain Evaluator role. `'evaluator'`
+     *  / `'worker'` are retained for backward-compat reads of session jsonl
+     *  written before v0.7.45. New writes use `'sidecar'`. */
+    source: 'evaluator' | 'worker' | 'sidecar';
+    status: 'accept' | 'revise' | 'blocked';
+    reason?: string;
+    debugReason?: string;
+    followups: string[];
+    userFacingText: string;
+    userAnswer?: string;
+    artifactPath?: string;
+    rawArtifactPath?: string;
+    rawResponseText?: string;
+    nextHarness?: KodaXTaskRoutingDecision['harnessProfile'];
+    protocolParseFailed?: boolean;
+    verificationDegraded?: boolean;
+    strategyReasonCode?: 'missing_requirement' | 'contradicted_evidence' | 'unsupported_claim' | 'unresolved_high_risk' | 'verification_degraded';
+    recommendedPattern?: 'classify-and-act' | 'fan-out-and-synthesize' | 'adversarial-verification' | 'generate-and-filter' | 'tournament' | 'loop-until-done';
+    targetEvidenceRefs?: string[];
+    preferredFallbackWorkerId?: string;
+    /**
+     * v0.7.26 Risk-3 fix — Evaluator explicit budget-extension request.
+     * When present, the Runner-driven `wrapEmitterWithRecorder` fires the
+     * budget-extension dialog regardless of the 90% threshold, using this
+     * string as the user-visible summary. Mirrors legacy Evaluator's
+     * `budgetRequest` field which was parsed from the fenced-block
+     * `kodax-budget-request` payload in v0.7.22.
+     */
+    budgetRequest?: string;
+}
+interface KodaXManagedProtocolPayload {
+    verdict?: KodaXManagedVerdictPayload;
+}
+interface KodaXRuntimeSessionSnapshot {
+    extensionState?: KodaXExtensionSessionState;
+    extensionRecords?: KodaXExtensionSessionRecord[];
+}
+interface KodaXWrittenFile {
+    readonly path: string;
+    /** Retains a successful Skill promotion even if a later edit changes the file. */
+    readonly sourceTool: 'write' | 'edit' | 'multi_edit' | 'insert_after_anchor' | 'run_skill_script';
+}
+interface KodaXResult {
+    success: boolean;
+    lastText: string;
+    signal?: 'COMPLETE' | 'BLOCKED' | 'DECIDE';
+    signalReason?: string;
+    signalDebugReason?: string;
+    messages: KodaXMessage[];
+    sessionId: string;
+    /**
+     * FEATURE_247 — the agent profile this run executed under, echoed verbatim from
+     * `options.context.agentProfile`. Lets an embedder confirm the running profile
+     * was Partner (not the default Coding Agent). Absent ⇒ default Coding Agent.
+     */
+    agentProfile?: KodaXAgentProfile;
+    /** Internal raw protocol output retained for artifact persistence after compacting visible failure text. */
+    protocolRawText?: string;
+    /** Structured managed-task protocol payload separated from visible text. */
+    managedProtocolPayload?: KodaXManagedProtocolPayload;
+    /** Final visible routing decision for this run, including harness and work intent. */
+    routingDecision?: KodaXTaskRoutingDecision;
+    /** Managed task summary produced by the task engine for this run. */
+    managedTask?: KodaXManagedTask;
+    /** Best-known token snapshot after the round completes. */
+    contextTokenSnapshot?: KodaXContextTokenSnapshot;
+    /** Latest provider usage when the caller has it directly. */
+    usage?: KodaXTokenUsage;
+    /** Serializable runtime-owned session state for host-owned persistence. */
+    runtimeSessionSnapshot?: KodaXRuntimeSessionSnapshot;
+    /**
+     * FEATURE_076: artifact ledger pre-extracted before round-boundary reshape.
+     * Populated when the reshape replaces `messages` with a clean {user, assistant}
+     * dialog — tool_result blocks (the source of artifact ledger entries) no
+     * longer live in `messages` after reshape. REPL consumers should read this
+     * field first, falling back to `extractArtifactLedger(messages)` for
+     * backward compatibility on code paths that have not yet been updated.
+     */
+    artifactLedger?: readonly KodaXSessionArtifactLedgerEntry[];
+    /** Successful writes in this invocation; candidates, not permission to publish files.
+     * Unlike the compaction ledger, this list is not truncated with conversation history.
+     * An empty list is authoritative; undefined supports older/custom executors.
+     */
+    writtenFiles?: readonly KodaXWrittenFile[];
+    /** 是否被用户中断 (Ctrl+C) */
+    interrupted?: boolean;
+    /** 是否达到迭代上限 */
+    limitReached?: boolean;
+    /** Error metadata for recovery - 错误元数据用于恢复 */
+    errorMetadata?: SessionErrorMetadata;
+    /** Terminal execution failure, independent of assistant text. */
+    failure?: KodaXExecutionFailure;
+}
+
+/** Existing product domain operations. This module has no Host or UI dependencies. */
+
+interface ClientCompactSessionResult {
+    readonly compacted: boolean;
+    readonly tokensBefore: number;
+    readonly tokensAfter: number;
+    /** Host-committed context, or the unchanged context for a no-op. */
+    readonly messages: KodaXMessage[];
+    readonly report?: CompactionReport;
+    /** A no-op or failure explanation; a lost reply never implies success. */
+    readonly reason?: string;
+}
+/** Preview revision accompanies fingerprints so a second UI need not recreate it. */
+interface ClientMemoryProposal extends MemoryActionProposal {
+    readonly revision: string;
+}
+interface ClientMemoryController {
+    listInbox(): Promise<readonly ClientMemoryProposal[]>;
+    showProposal(id: string): Promise<ClientMemoryProposal | undefined>;
+    approveProposal(id: string, expectedFingerprints: Readonly<Record<string, string>>, expectedRevision?: string): Promise<MemoryApplyResult>;
+    rejectProposal(id: string, reason?: string, expectedRevision?: string): Promise<MemoryRejectResult>;
+    listRefs(filter?: MemoryRefFilter): Promise<readonly MemoryItemRef[]>;
+    /** Host resolves the exact ref ID; a supplied storage path is never write authority. */
+    readRef(ref: MemoryItemRef): Promise<MemoryBodySnapshot>;
+    remember(input: MemoryRememberInput): Promise<MemoryRememberResult>;
+    forgetRef(id: string, expectedBodyFingerprint?: string): Promise<MemoryLifecycleOperationResult>;
+}
+interface ClientMemoryRebuildResult {
+    readonly status: 'missing-dir' | 'no-topics' | 'rebuilt';
+    readonly memoryRoot: string;
+    readonly entrypointPath: string;
+    readonly entryCount: number;
+    readonly malformedFiles: readonly string[];
+    readonly warnings: readonly string[];
+}
+interface ClientMemoryPlane {
+    readonly controller: ClientMemoryController;
+    readonly memoryRoot: string;
+    readonly entrypointPath: string;
+    listReviews(): Promise<readonly PendingEpisodeReviewSummary[]>;
+    reviewerProviderConfigured(): boolean;
+    rebuild(): Promise<ClientMemoryRebuildResult>;
+    /** Validate containment and required directories; the UI launches its own editor. */
+    ensureOpenTarget(targetPath: string): Promise<string>;
+}
+interface ClientMemoryService {
+    /** Host derives the project identity and rechecks authorization for each operation. */
+    forProject(projectRoot: string): Promise<ClientMemoryPlane>;
+}
+/** Learning notifications belong to the authenticated client; governance is shared. */
+interface ClientLearningSubscription extends AsyncIterableIterator<LearningEvent> {
+    /** Registration only; read a snapshot after awaiting ready. */
+    readonly ready: Promise<void>;
+}
+interface ClientLearningService {
+    list(query?: LearningQuery): Promise<LearningPage>;
+    get(nameOrSlugOrId: string): Promise<LearnedCapabilityRecord>;
+    getSnapshot(): Promise<LearningSurfaceSnapshot>;
+    events(afterRevision?: number): Promise<readonly LearningEvent[]>;
+    subscribe(options?: LearningSubscribeOptions): ClientLearningSubscription;
+    acknowledge(nameOrSlugOrId: string): Promise<void>;
+    snooze(nameOrSlugOrId: string, until: string): Promise<void>;
+    reject(nameOrSlugOrId: string): Promise<void>;
+    disable(nameOrSlugOrId: string): Promise<void>;
+    rollback(nameOrSlugOrId: string): Promise<void>;
+    promote(nameOrSlugOrId: string, scope: 'user'): Promise<void>;
+    review(nameOrSlugOrId: string): Promise<void>;
+    trust(nameOrSlugOrId: string): Promise<void>;
+}
+interface ClientCommandInput {
+    readonly sessionId: string;
+    readonly inputId: string;
+    readonly name: string;
+    readonly args?: readonly string[];
+}
+type ClientCommandResult = {
+    readonly kind: 'completed';
+    readonly success: boolean;
+    readonly message?: string;
+} | {
+    readonly kind: 'started';
+    readonly runId: string;
+    readonly message?: string;
+};
+interface ClientReviewInput {
+    readonly sessionId: string;
+    readonly inputId: string;
+    readonly args?: readonly string[];
+}
+interface ClientReviewService {
+    start(input: ClientReviewInput): Promise<ClientCommandResult>;
+}
+interface ClientCommandService {
+    /** Plain editable text only. Reading or cancelling a draft has no execution effects. */
+    readPrompt(input: Omit<ClientCommandInput, 'inputId'>): Promise<{
+        readonly title: string;
+        readonly text: string;
+    } | null>;
+    /** Execute an existing registered command. Never automatically replay a lost reply. */
+    execute(input: ClientCommandInput): Promise<ClientCommandResult>;
+}
+
+/** Display facts only; extension handlers and Host execution types stay private. */
+interface ClientLoadedExtension {
+    readonly path: string;
+    readonly label: string;
+    readonly loadSource: string;
+}
+interface ClientExtensionSource {
+    readonly kind: string;
+    readonly id?: string;
+    readonly label?: string;
+}
+interface ClientExtensionDiagnostics {
+    readonly loadedExtensions: readonly ClientLoadedExtension[];
+    readonly capabilityProviders: readonly {
+        readonly id: string;
+        readonly kinds: readonly string[];
+        readonly metadata?: Record<string, unknown>;
+    }[];
+    readonly commands: readonly {
+        readonly name: string;
+        readonly aliases?: readonly string[];
+        readonly description: string;
+    }[];
+    readonly tools: readonly {
+        readonly name: string;
+        readonly source: ClientExtensionSource;
+        readonly shadowedSources: readonly ClientExtensionSource[];
+    }[];
+    readonly hooks: readonly {
+        readonly hook: string;
+        readonly order: number;
+        readonly source: ClientExtensionSource;
+    }[];
+    readonly failures: readonly {
+        readonly stage: string;
+        readonly target: string;
+        readonly message: string;
+        readonly source: ClientExtensionSource;
+    }[];
+    readonly defaults: {
+        readonly activeTools?: readonly string[];
+        readonly modelSelection: {
+            readonly provider?: string;
+            readonly model?: string;
+        };
+        readonly thinkingLevel?: string;
+    };
+}
+interface ClientSession {
+    readonly executionCwd?: string;
+    /** Active conversation messages, when supplied by a Host read. */
+    readonly msgCount?: number;
+    readonly id: string;
+    readonly archived?: boolean;
+    readonly title: string;
+    readonly tag?: string;
+    readonly gitRoot?: string;
+    readonly workspaceRoot?: string;
+    readonly branch?: string;
+    readonly workspaceKind?: 'detected' | 'managed';
+    readonly surface?: string;
+    readonly profileId?: string;
+    readonly createdAt?: string;
+}
+interface ClientSessionSummary extends ClientSession {
+    /** Opaque continuation token for list pagination. */
+    readonly cursor?: string;
+    readonly msgCount: number;
+    readonly tag?: string;
+    readonly projectKey?: string;
+    readonly archived?: boolean;
+}
+interface ClientSessionFilter {
+    readonly projectRoot?: string;
+    readonly scope?: 'user' | 'managed-task-worker' | 'all';
+    readonly includeArchived?: boolean;
+    readonly limit?: number;
+    readonly before?: string;
+    readonly tag?: string;
+    readonly surface?: string;
+    readonly cursor?: string;
+}
+interface KodaXProductClient {
+    readonly lifecycle: ClientLifecycleService;
+    readonly statistics: ClientStatisticsService;
+    readonly commands: ClientCommandService;
+    readonly review: ClientReviewService;
+    readonly memory: ClientMemoryService;
+    readonly learning: ClientLearningService;
+    readonly host: {
+        /** Request an idle Host to shut down. Acceptance does not prove cleanup has completed. */
+        shutdown(): Promise<{
+            readonly accepted: true;
+        }>;
+    };
+    readonly sessions: {
+        cancel(input: ClientSessionCancelInput): Promise<ClientSessionCancelReceipt>;
+        compact(sessionId: string, input?: {
+            readonly customInstructions?: string;
+        }): Promise<ClientCompactSessionResult>;
+        create(input?: ClientCreateSessionInput): Promise<ClientSession>;
+        list(filter?: ClientSessionFilter): Promise<readonly ClientSessionSummary[]>;
+        read(sessionId: string): Promise<ClientSession>;
+        delete(sessionId: string): Promise<void>;
+        archive(sessionId: string): Promise<void>;
+        unarchive(sessionId: string): Promise<void>;
+        getSettings(sessionId: string): Promise<ClientSessionSettings>;
+        /** Read the Host's existing settings revision for a conditional edit or restoration. */
+        getSettingsVersioned(sessionId: string): Promise<ClientSessionSettingsSnapshot>;
+        /** Reject with conflict if another settings edit has occurred since expectedRevision. */
+        updateSettingsVersioned(sessionId: string, patch: ClientSessionSettingsPatch, options: {
+            readonly expectedRevision: number;
+        }): Promise<ClientSessionSettingsSnapshot>;
+        /** Existing Host Auto reviewer diagnostics; undefined when Auto mode is not selected. */
+        getAutoModeStats(sessionId: string): Promise<ClientAutoModeStats | undefined>;
+        /** Change this Session only. The next physical request uses the updated selection. */
+        updateSettings(sessionId: string, patch: ClientSessionSettingsPatch): Promise<ClientSessionSettings>;
+        /** Delivers the current view first, then replacements; no event cursor is needed. */
+        observe(sessionId: string, onView: (view: ClientSessionView) => void, options?: ClientObserveOptions): Promise<ClientObservation>;
+        /** Read the original content behind a bounded display item. Offsets are UTF-16 characters. */
+        readItem(sessionId: string, itemId: string, options?: ClientItemReadOptions): Promise<ClientItemContent | null>;
+        /** Newest page of the canonical conversation first; older pages via nextCursor. */
+        readHistory(sessionId: string, options?: ClientHistoryReadOptions): Promise<ClientHistoryPage>;
+        /** Full body behind one oversized history entry, chunked like readItem. */
+        readHistoryEntry(sessionId: string, itemId: string, options?: ClientItemReadOptions): Promise<ClientItemContent | null>;
+        /** Search the whole Session history; entryIndex values are stable within the returned revision. */
+        searchHistory(sessionId: string, input: ClientHistorySearchInput): Promise<ClientHistorySearchResult>;
+        /** Persistent session goal owned by the Host; every client reads the same state. */
+        readGoal(sessionId: string): Promise<ClientSessionGoal | null>;
+        /** Create a goal; conflicts while a non-complete goal is active. Budget rules are the domain's. */
+        createGoal(sessionId: string, input: ClientGoalCreateInput): Promise<ClientSessionGoal>;
+        /** Pause an active goal; conflicts from any other status. */
+        pauseGoal(sessionId: string): Promise<ClientSessionGoal>;
+        /** Resume a paused goal; conflicts from any other status. */
+        resumeGoal(sessionId: string): Promise<ClientSessionGoal>;
+        /** Clear the current goal; conflicts when no goal exists. */
+        clearGoal(sessionId: string): Promise<void>;
+        /** Host-owned notice append; UIs never write lineage or session files directly. */
+        appendNotice(sessionId: string, input: {
+            readonly content: string;
+            readonly source?: string;
+        }): Promise<void>;
+        /** Branch structure owned by the Host; both clients see the same head. Null when the session predates lineage. */
+        readLineage(sessionId: string): Promise<ClientLineageSummary | null>;
+        /** Label (or unlabel when `label` is omitted) one entry by id or existing label; unknown selectors conflict. */
+        labelEntry(sessionId: string, input: ClientLineageLabelInput): Promise<ClientLineageSummary>;
+        /** Move the active head to an entry by id or label; stale selectors conflict, never silently no-op. */
+        selectBranch(sessionId: string, selector: string, options?: {
+            readonly summarizeCurrentBranch?: boolean;
+        }): Promise<ClientSession>;
+        /** Move the head back to an entry; idle sessions only, and file effects are never rolled back. */
+        rewindSession(sessionId: string, input: {
+            readonly selector?: string;
+            readonly historyBoundary?: ClientHistoryBoundary;
+            readonly expectedHead: string | null;
+        }): Promise<ClientSession>;
+        /** Derive a new Session from this idle session's history; the source stays unchanged. */
+        forkSession(sessionId: string, input?: ClientSessionForkInput): Promise<ClientSession>;
+        /** Derive a new Session from a deterministic recovery seed (no LLM call); continue with a normal input submit. */
+        recoverSession(sessionId: string, input?: ClientSessionRecoverInput): Promise<ClientSession>;
+    };
+    readonly inputs: {
+        submit(input: ClientSubmitInput): Promise<ClientInputAcceptance>;
+        read(sessionId: string, inputId: string): Promise<ClientInputAcceptance | null>;
+        withdraw(sessionId: string, inputId: string): Promise<ClientSubmitInput>;
+    };
+    readonly runs: {
+        /** Explicit tool execution through the Host's ordinary tool gates, without a model prompt. */
+        startTool(input: ClientToolInvocationInput): Promise<{
+            readonly runId: string;
+            readonly sessionId: string;
+        }>;
+        /** Current lifecycle facts of one Run; internal stages stay internal. */
+        read(runId: string): Promise<ClientRunStatus>;
+        /** Request a stop; accepted only means the durable Stop request was created. */
+        stop(runId: string): Promise<ClientRunStopReceipt>;
+        /** Resolve at a terminal phase; `unknown` means the outcome could not be confirmed, never success. */
+        await(runId: string): Promise<ClientRunOutcome>;
+    };
+    /**
+     * FEATURE_298 T22 — Host-owned workflow control. `start` takes a declarative
+     * source (validated/resolved inside the Host, never a prepared module), so
+     * every client of the same Host observes and controls the same work.
+     */
+    readonly workflows: {
+        start(input: ClientWorkflowStartInput): Promise<ClientWorkflowStartResult>;
+        list(filter?: {
+            readonly runId?: string;
+            readonly limit?: number;
+        }): Promise<readonly ClientWorkflowRun[]>;
+        get(runId: string): Promise<ClientWorkflowProcess | undefined>;
+        /** Existing Host process events; subscriptions carry facts, never executable workflow modules. */
+        /** Terminates on transport failure; rebuild, await ready, then read a snapshot. */
+        subscribe(filter: {
+            readonly runId?: string;
+        }, listener: (event: ClientWorkflowEvent) => void, onError?: (error: unknown) => void): {
+            readonly ready: Promise<void>;
+            close(): void;
+        };
+        pause(runId: string): Promise<boolean>;
+        resume(runId: string): Promise<boolean>;
+        stop(runId: string, options?: {
+            readonly sessionId: string;
+        }): Promise<boolean>;
+    };
+    readonly interactions: {
+        /** Answers the Host is currently waiting for. */
+        list(filter?: {
+            readonly sessionId?: string;
+        }): Promise<readonly ClientInteraction[]>;
+        /** Precise request ID + typed response; only the first valid answer counts. */
+        respond(requestId: string, response: ClientInteractionResponse): Promise<ClientInteractionResult>;
+    };
+    readonly permissions: {
+        /** Effective explicit grants; every client sees the same revision. */
+        listGrants(): Promise<ClientPermissionGrants>;
+        /** Revoke exactly one grant by its domain identity; the revision must match. */
+        revokeGrant(grantId: string, expectedRevision: number): Promise<boolean>;
+    };
+    /**
+     * FEATURE_298 T30 — Host-owned external Agent registry. Mutations use the
+     * registry's own domain identity (configuration revision CAS, management
+     * ownership), never a generic operation envelope.
+     */
+    readonly registrations: {
+        list(): Promise<readonly ExternalAgentRegistrationSummary[]>;
+        upsert(registration: ExternalAgentRegistration, options?: AgentRegistrationMutationOptions): Promise<ExternalAgentRegistrationSummary>;
+        setEnabled(agentId: string, enabled: boolean, options?: AgentRegistrationEnabledMutationOptions): Promise<ExternalAgentRegistrationSummary | undefined>;
+        remove(agentId: string, options?: AgentRegistrationMutationOptions): Promise<boolean>;
+    };
+    /**
+     * FEATURE_298 T30 — collaboration control over the Host's Session Actors.
+     * Reads return the actual domain objects; `wait` resolves one Agent event.
+     */
+    readonly agents: {
+        reviewLean(input: Omit<ClientReviewInput, 'args'>): Promise<ClientCommandResult>;
+        tree(sessionId: string): Promise<AgentTreeSnapshot>;
+        detail(sessionId: string, actorPath: string): Promise<AgentDetail>;
+        spawn(sessionId: string, input: AgentSpawnInput): Promise<AgentTurnRef>;
+        send(sessionId: string, actorPath: string, content: string, classification?: AgentDataClassification): Promise<void>;
+        followup(sessionId: string, actorPath: string, objective: string, options?: {
+            readonly expectedRevision?: number;
+        }): Promise<AgentFollowupResult>;
+        interrupt(sessionId: string, actorPath: string, reason?: string): Promise<void>;
+        output(sessionId: string, actorPath: string, turnId?: string): Promise<AgentOutput>;
+        wait(sessionId: string, afterSequence?: number, timeoutMs?: number, options?: {
+            readonly signal?: AbortSignal;
+        }): Promise<AgentEvent | undefined>;
+    };
+    readonly config: {
+        /** Saved user defaults. Session overrides remain independent. */
+        read(): Promise<ClientConfig>;
+        /** Live execution controls only; never exposes credentials or arbitrary environment. */
+        readEffective(): Promise<ClientEffectiveExecutionConfig>;
+        /** Omitted keys stay unchanged; null clears a saved default. */
+        patch(patch: {
+            [K in keyof ClientConfig]?: ClientConfig[K] | null;
+        }): Promise<ClientConfig>;
+        reload(): Promise<{
+            readonly ok: true;
+            readonly config: ClientConfig;
+        }>;
+    };
+    readonly catalog: {
+        extensions(): Promise<{
+            readonly active: boolean;
+            readonly extensions: readonly ClientLoadedExtension[];
+            readonly diagnostics?: ClientExtensionDiagnostics;
+        }>;
+        providers(): Promise<readonly ClientProviderInfo[]>;
+        models(filter?: {
+            readonly provider?: string;
+        }): Promise<readonly ClientModelCatalog[]>;
+        reasoningEfforts(input: ClientModelSelection): Promise<readonly string[]>;
+        /** Explicitly sends minimal Provider requests; never runs during connect or discovery. */
+        probeReasoningEfforts(input: ClientModelSelection & {
+            readonly efforts: readonly string[];
+        }): Promise<readonly ClientCapabilityProbeResult[]>;
+        forgetCapabilities(input?: {
+            readonly provider?: string;
+            readonly model?: string;
+        }): Promise<void>;
+        /**
+         * Slash commands visible for a workspace. `source` is where the Host
+         * resolved the command from — one of the registry origins ("builtin",
+         * "user", "project", "learned", "extension") — reported as a string so
+         * the contract stays forward-compatible with new origins.
+         */
+        commands(workspaceRoot: string): Promise<readonly ClientCommandInfo[]>;
+        /**
+         * Skills the Host can invoke. `source` uses the same registry-origin
+         * vocabulary as `commands`; see {@link ClientSkillInfo}.
+         */
+        skills(input?: {
+            readonly userInvocableOnly?: boolean;
+        }): Promise<readonly ClientSkillInfo[]>;
+    };
+    readonly mcp: {
+        /** Current Host diagnostics; never connects or refreshes a server. */
+        status(): Promise<readonly ClientMcpServerStatus[]>;
+        listServers(): Promise<Readonly<Record<string, ClientMcpServerConfig>>>;
+        getServer(name: string): Promise<ClientMcpServerConfig | undefined>;
+        validateServer(name: string, config: unknown): Promise<{
+            readonly ok: true;
+            readonly config: ClientMcpServerConfig;
+        } | {
+            readonly ok: false;
+            readonly error: string;
+        }>;
+        upsertServer(name: string, config: ClientMcpServerConfig): Promise<ClientMcpServerConfig>;
+        deleteServer(name: string): Promise<boolean>;
+        reloadServers(): Promise<{
+            readonly ok: true;
+            readonly servers: readonly ClientMcpServerStatus[];
+        }>;
+        listTools(filter?: {
+            readonly server?: string;
+            readonly forceRefresh?: boolean;
+        }): Promise<readonly {
+            readonly serverId: string;
+            readonly tools: readonly ClientMcpTool[];
+            readonly cachedAt?: string;
+        }[]>;
+    };
+    /** Release this connection. The Host and its work retain their own lifetime. */
+    disconnect(): Promise<void>;
+}
+interface ClientObservation {
+    close(): void;
+}
+type ClientObservationStatus = {
+    readonly state: 'live';
+} | {
+    readonly state: 'interrupted';
+    readonly message?: string;
+} | {
+    readonly state: 'closed';
+    readonly reason: 'client' | 'unavailable';
+    readonly message?: string;
+};
+interface ClientObserveOptions {
+    /** Live is emitted only after delivery of a complete current view. */
+    readonly onStatus?: (status: ClientObservationStatus) => void;
+}
+interface ClientModelSelection {
+    readonly provider: string;
+    readonly model?: string;
+}
+interface ClientModelCatalog {
+    readonly provider: string;
+    readonly models: readonly string[];
+}
+/** `source`: registry origin — "builtin" | "user" | "project" | "learned" | "extension". */
+interface ClientCommandInfo {
+    readonly name: string;
+    readonly aliases?: readonly string[];
+    readonly description: string;
+    /** Where the Host discovered the command (builtin/project/extension/...). */
+    readonly source: string;
+    readonly userInvocable?: boolean;
+}
+/** `source`: same registry-origin vocabulary as ClientCommandInfo. */
+interface ClientSkillInfo {
+    readonly name: string;
+    readonly description: string;
+    readonly userInvocable: boolean;
+    readonly path: string;
+    /** Where the Host discovered the Skill (builtin/user/project/...). */
+    readonly source: string;
+}
+interface ClientProviderInfo {
+    readonly name: string;
+    readonly model: string;
+    readonly models: readonly string[];
+    readonly configured: boolean;
+    readonly source: 'builtin' | 'config' | 'runtime';
+    readonly reasoningCapability: string;
+    readonly capabilityProfile: {
+        readonly transport: 'native-api' | 'cli-bridge';
+        readonly conversationSemantics: 'full-history' | 'last-user-message';
+        readonly mcpSupport: 'native' | 'none';
+        readonly contextFidelity?: 'full' | 'partial' | 'lossy';
+        readonly toolCallingFidelity?: 'full' | 'limited' | 'none';
+        readonly sessionSupport?: 'full' | 'limited' | 'stateless';
+        readonly longRunningSupport?: 'full' | 'limited' | 'none';
+        readonly multimodalSupport?: 'none' | 'image-input' | 'full';
+        readonly evidenceSupport?: 'full' | 'limited' | 'none';
+    };
+}
+interface ClientMcpTool {
+    readonly id: string;
+    readonly serverId: string;
+    readonly name: string;
+    readonly title?: string;
+    readonly summary: string;
+    readonly cachedAt: string;
+    readonly inputSchema?: unknown;
+    readonly outputSchema?: unknown;
+    readonly annotations?: Readonly<Record<string, unknown>>;
+    readonly risk?: 'read' | 'write' | 'network' | 'exec';
+    readonly taskSupport?: 'forbidden' | 'optional' | 'required';
+}
+interface ClientCapabilityProbeResult {
+    readonly effort: string;
+    readonly status: 'accepted' | 'rejected' | 'error';
+    readonly error?: string;
+}
+interface ClientItemReadOptions {
+    readonly offset?: number;
+    readonly part?: 'text' | 'input';
+}
+/** Paging over a Session's canonical conversation history. */
+interface ClientHistoryReadOptions {
+    /** Cursor from a previous page's nextCursor; omit to read the newest page. */
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+interface ClientHistoryPage {
+    /** This page's entries projected like view items, oldest first. */
+    readonly items: readonly ClientViewItem[];
+    /** Conversation revision this page was read at. */
+    readonly revision: string;
+    /** Canonical storage revision used by operation boundaries; distinct from the page revision. */
+    readonly sourceRevision: string;
+    readonly status: 'resolved' | 'partial' | 'ambiguous';
+    readonly issues: readonly ClientHistoryIssue[];
+    /** Cursor of the next older page; absent when this is the oldest page. */
+    readonly nextCursor?: string;
+    /**
+     * Entries too large to inline as items. Read the full body by itemId with
+     * readHistoryEntry; the page never substitutes a truncated preview.
+     */
+    readonly oversized: readonly {
+        readonly itemId: string;
+        readonly byteLength: number;
+    }[];
+}
+/** Durable, client-scoped exit control; receipt acceptance is separate from verified outcomes. */
+interface ClientLifecycleService {
+    requestExit(input: {
+        readonly requestId: string;
+        readonly shutdownHost?: boolean;
+    }): Promise<ClientExitReceipt>;
+    readExit(requestId: string): Promise<ClientExitReceipt | null>;
+    listPendingExits(): Promise<readonly ClientExitReceipt[]>;
+}
+type ClientExecutionTarget = {
+    readonly kind: 'run';
+    readonly runId: string;
+} | {
+    readonly kind: 'actor_turn';
+    readonly actorPath: string;
+    readonly turnId: string;
+    readonly parentRunId?: string;
+} | {
+    readonly kind: 'operation';
+    readonly operationId: string;
+    readonly operation: 'session.compact';
+};
+interface ClientUsageTotals {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    readonly thoughtTokens: number;
+}
+interface ClientProviderRequestFact extends Omit<ProviderRequestObservation, 'state'> {
+    readonly state: ProviderRequestObservation['state'] | 'unknown';
+    readonly revision: number;
+    readonly sessionId: string;
+    readonly runtimeId: string;
+    readonly target: ClientExecutionTarget;
+    readonly previousRequestId?: string;
+    readonly fallback: boolean;
+    /** Restart recovery only marks an unfinished request unknown; it never invents usage. */
+    readonly recovery?: 'outcome_unknown';
+}
+interface ClientToolExecutionFact {
+    readonly id: string;
+    readonly revision: number;
+    readonly toolId: string;
+    readonly name: string;
+    readonly sessionId: string;
+    readonly runtimeId: string;
+    readonly target: ClientExecutionTarget;
+    readonly state: 'prepared' | 'executing' | 'completed' | 'not_executed' | 'unknown';
+    readonly result?: 'succeeded' | 'failed' | 'cancelled';
+    readonly updatedAt: string;
+    /** Actual adapter observations, in order. Empty means the backend was not reported. */
+    readonly sandbox: readonly KodaXShellSandboxObservation[];
+}
+interface ClientExecutionFactsPage<T> {
+    readonly revision: number;
+    readonly items: readonly T[];
+    readonly nextCursor?: string;
+}
+/** Last request-preparation estimate for a context, retained across disconnect and restart. */
+interface ClientContextBudgetFact extends RuntimeContextBudgetSnapshot {
+    readonly runtimeId: string;
+    readonly revision: number;
+    readonly target: ClientExecutionTarget;
+    readonly contextRevision?: number;
+}
+interface ClientStatisticsService {
+    read(sessionId: string): Promise<{
+        readonly sessionId: string;
+        readonly revision: number;
+        readonly coverage: 'complete' | 'partial';
+        readonly issues: readonly string[];
+        readonly usage: ClientUsageTotals;
+        readonly requestCount: number;
+        readonly requestsWithoutUsage: number;
+        readonly physicalRequestCount: number;
+        readonly operationCount: number;
+        readonly contexts: readonly ClientContextBudgetFact[];
+    }>;
+    readRequests(sessionId: string, options?: {
+        readonly cursor?: string;
+        readonly limit?: number;
+    }): Promise<ClientExecutionFactsPage<ClientProviderRequestFact>>;
+    readTools(sessionId: string, options?: {
+        readonly cursor?: string;
+        readonly limit?: number;
+    }): Promise<ClientExecutionFactsPage<ClientToolExecutionFact>>;
+}
+interface ClientExitReceipt {
+    readonly requestId: string;
+    readonly clientId: string;
+    readonly runtimeId: string;
+    readonly accepted: true;
+    readonly requestedAt: string;
+    readonly updatedAt: string;
+    readonly cleanup: {
+        readonly actorTurns: readonly {
+            readonly actorPath: string;
+            readonly turnId: string;
+        }[];
+        readonly operationIds: readonly string[];
+        readonly state: 'pending' | 'succeeded' | 'unknown' | 'failed';
+        readonly runIds: readonly string[];
+        readonly withdrawnInputs: readonly {
+            readonly sessionId: string;
+            readonly inputId: string;
+        }[];
+        readonly issues: readonly string[];
+    };
+    readonly host: {
+        readonly requested: boolean;
+        readonly state: 'not_requested' | 'pending' | 'protected' | 'accepted' | 'succeeded' | 'failed' | 'unknown';
+        readonly owner: {
+            readonly runtimeId: string;
+            readonly pid: number;
+            readonly kind?: 'daemon' | 'inline';
+            readonly processStartIdentity?: string;
+            readonly processContainment?: 'windows-job';
+            readonly supervisorPid?: number;
+            readonly supervisorProcessStartIdentity?: string;
+        };
+        readonly cleanup?: 'succeeded' | 'failed';
+        readonly message?: string;
+        readonly replacementRunning?: boolean;
+    };
+}
+/** Host-issued canonical boundary. Pass it back unchanged; never derive it from an item ID. */
+interface ClientHistoryBoundary {
+    readonly entryId: string;
+    readonly sourceRevision: string;
+}
+interface ClientHistoryIssue {
+    readonly code: string;
+    readonly message: string;
+    readonly occurrenceCount: number;
+    readonly entryCount: number;
+    readonly entryIds: readonly string[];
+}
+interface ClientHistorySearchInput {
+    readonly query: string;
+    readonly limit?: number;
+    readonly role?: 'user' | 'assistant';
+    /** 'all' (default) searches active and compacted history; 'compacted' only the compacted tail. */
+    readonly scope?: 'all' | 'compacted';
+}
+/** The domain's persistent goal state, written only by Host commands. */
+type ClientSessionGoal = KodaXGoalState;
+interface ClientGoalCreateInput {
+    readonly objective: string;
+    /** Optional hard token ceiling; the domain validates positive integers. */
+    readonly tokenBudget?: number;
+}
+/** Lineage facts with a bounded text preview; raw messages stay in the Host. */
+interface ClientLineageEntry {
+    readonly id: string;
+    readonly parentId: string | null;
+    readonly type: KodaXSessionEntry['type'];
+    readonly timestamp: string;
+    readonly role?: 'user' | 'assistant' | 'system' | 'tool';
+    /** Bounded content hint, never a substitute for history/readItem. */
+    readonly preview?: string;
+    /** Present on label entries: the labeled target entry. */
+    readonly targetId?: string;
+    /** Present on label entries; absent means the label was removed. */
+    readonly label?: string;
+    /** Present on rewind markers: how many entries left the active branch. */
+    readonly truncatedCount?: number;
+}
+interface ClientLineageSummary {
+    readonly activeEntryId: string | null;
+    readonly entries: readonly ClientLineageEntry[];
+}
+interface ClientLineageLabelInput {
+    /** Entry id or an existing label name. */
+    readonly selector: string;
+    /** Omit to remove the target's label. */
+    readonly label?: string;
+}
+interface ClientSessionForkInput {
+    /** Exclude the boundary message when deriving Retry; requires historyBoundary. */
+    readonly before?: boolean;
+    /** Entry id or label naming the boundary; defaults to the active head. */
+    readonly selector?: string;
+    /** Explicit conversation-history boundary; stale revisions surface as resync_required. */
+    readonly historyBoundary?: ClientHistoryBoundary;
+    readonly title?: string;
+}
+interface ClientSessionRecoverInput {
+    readonly title?: string;
+    /** Free-form reason recorded in the seed header. */
+    readonly reason?: string;
+}
+interface ClientHistorySearchResult {
+    readonly revision: string;
+    readonly hits: readonly {
+        /** Opaque reference readable through readHistoryEntry; expired snapshots require a new search. */
+        readonly itemId: string;
+        /** Stable within this revision; indexes the transcript at that revision. */
+        readonly entryIndex: number;
+        readonly role: 'user' | 'assistant';
+        readonly timestamp?: string;
+        readonly snippet: string;
+    }[];
+}
+interface ClientItemContent {
+    readonly outputState?: 'draft' | 'committed';
+    /** Same revision and outputState as the observed item, for frozen reads. */
+    readonly textRevision?: number;
+    readonly id: string;
+    readonly text: string;
+    readonly offset: number;
+    readonly totalLength: number;
+    readonly nextOffset?: number;
+}
+interface ClientSessionView {
+    /** Effective configuration for the current parent selection; not a physical request receipt. */
+    readonly contextBudget?: ClientContextBudget;
+    /** Host estimate of the saved parent context, available without a live Run. */
+    readonly parentContextTokens?: number;
+    readonly activity?: ClientSessionActivity;
+    readonly queue: readonly ClientQueuedInput[];
+    readonly session: ClientSession;
+    readonly items: readonly ClientViewItem[];
+    /** Effective Host profile values plus Session overrides; getSettings/updateSettings retain raw overrides. */
+    readonly settings: ClientSessionSettings;
+    /** Pending answers in this Session; all observers see the same identities. */
+    readonly interactions: readonly ClientInteraction[];
+    readonly runs: readonly {
+        readonly runId: string;
+        readonly phase: string;
+        readonly provider: string;
+        readonly model?: string;
+        readonly error?: string;
+    }[];
+}
+interface ClientContextBudget {
+    readonly scope: 'parent' | 'worker';
+    readonly provider: string;
+    readonly model: string;
+    readonly contextWindow: number;
+    readonly reservedResponseTokens: number;
+    readonly reservedMemoryTokens?: number;
+    readonly contextId?: string;
+    readonly compaction: {
+        readonly enabled: true;
+        readonly triggerPercent: number;
+        readonly absoluteTriggerTokens?: number;
+        /** Present only when execution has supplied its Memory and provider-envelope capacity. */
+        readonly triggerTokens?: number;
+        readonly physicalCapacityTokens?: number;
+    };
+}
+/** Display facts for the latest Run; worker context is distinct from parent context. */
+interface ClientSessionActivity {
+    /** Transient request progress; never saved as conversation history or partial tool arguments. */
+    readonly streaming?: {
+        readonly kind: 'thinking';
+        readonly providerRequestId: string;
+        readonly itemId: string;
+        readonly charCount: number;
+        /** Host estimate for the current request's visible thinking, not Provider usage. */
+        readonly estimatedTokenCount?: number;
+    } | {
+        readonly kind: 'tool-input';
+        readonly providerRequestId: string;
+        readonly toolName: string;
+        readonly callId?: string;
+        /** Cumulative characters for this call; absent when the Provider supplied no call identity. */
+        readonly charCount?: number;
+    };
+    readonly workflow?: ClientWorkflowProcess;
+    /** Latest execution budget, whose model and scope may differ from the current Session selection. */
+    readonly contextBudget?: ClientContextBudget;
+    readonly runId: string;
+    readonly costReport?: string;
+    readonly children?: readonly {
+        readonly id: string;
+        readonly label: string;
+        readonly source: 'workflow' | 'normal';
+        readonly kind: 'assistant' | 'thinking' | 'tool' | 'progress' | 'prompt' | 'stream';
+        readonly detail: string;
+        readonly status: 'running' | 'completed';
+        readonly startedAt: number;
+    }[];
+    readonly managedTask?: {
+        readonly childFanoutClass?: 'finding-validation' | 'module-triage' | 'evidence-scan' | 'hypothesis-check';
+        readonly harnessProfile?: string;
+        readonly globalWorkBudget?: number;
+        readonly budgetUsage?: number;
+        readonly budgetApprovalRequired?: boolean;
+        readonly phase?: string;
+        readonly workerId?: string;
+        readonly workerTitle?: string;
+        readonly breadcrumb?: string;
+        readonly expandedBreadcrumb?: string;
+        readonly round?: number;
+        readonly maximumRounds?: number;
+        readonly idleWaiting: boolean;
+        readonly pendingChildren?: number;
+        readonly fanoutCount?: number;
+    };
+    readonly compacting?: boolean;
+    readonly iteration?: {
+        readonly current: number;
+        readonly maximum: number;
+    };
+    readonly context?: {
+        readonly tokenCount: number;
+        readonly tokenSource: 'api' | 'estimate';
+        readonly scope: 'parent' | 'worker';
+    };
+    /** Latest root iteration/compaction fact; child events never overwrite it. */
+    readonly parentContextTokens?: number;
+    readonly usage?: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly totalTokens: number;
+        readonly cacheReadTokens?: number;
+        readonly cacheWriteTokens?: number;
+        readonly thoughtTokens?: number;
+    };
+    readonly todos?: readonly {
+        readonly id: string;
+        readonly subject: string;
+        readonly status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped' | 'cancelled';
+        readonly description?: string;
+        readonly owner?: string;
+        readonly note?: string;
+        readonly activeForm?: string;
+    }[];
+}
+interface ClientViewItem {
+    /** Image references proven by canonical user/tool content; does not include file bytes. */
+    readonly attachments?: readonly {
+        readonly kind: 'image';
+        readonly path: string;
+        readonly mediaType?: string;
+    }[];
+    /** Boundary after the complete canonical message, shared by all its display blocks. */
+    readonly historyBoundary?: ClientHistoryBoundary;
+    /** Host checkpoint provenance for retained output and tool evidence. */
+    readonly sourceRunId?: string;
+    readonly sourceTurnId?: string;
+    /** One generated assistant message, shared by its draft and canonical items. */
+    readonly outputId?: string;
+    readonly outputState?: 'draft' | 'committed';
+    /** Draft revision changes on replacement, never append; immutable committed output uses 0. Compare with outputState. */
+    readonly textRevision?: number;
+    /** Host recovery metadata; clients render the supplied item order. */
+    readonly afterInputId?: string;
+    readonly id: string;
+    /** Accepted input identity of a canonical user message; absent on legacy history. */
+    readonly inputId?: string;
+    readonly type: 'user' | 'assistant' | 'thinking' | 'info' | 'error' | 'event' | 'hint' | 'sidecar' | 'system' | 'tool';
+    readonly text: string;
+    /** Present when text is a bounded suffix; readItem retains the complete original. */
+    readonly textOffset?: number;
+    readonly totalTextLength?: number;
+    readonly timestamp?: number;
+    readonly icon?: string;
+    readonly compactText?: string;
+    /** Verifier facts, independent of the consumer's label, icon or color. */
+    readonly sidecar?: {
+        readonly verdict?: 'revise' | 'blocked';
+        readonly delivery?: 'synthetic-user-message' | 'budget-exhausted' | 'terminal-block';
+    };
+    readonly tool?: {
+        readonly assistantOutputId?: string;
+        readonly executionBegan?: true;
+        readonly resultRecorded?: true;
+        readonly callId: string;
+        readonly name: string;
+        readonly status: 'running' | 'success' | 'error' | 'cancelled' | 'awaiting_approval';
+        readonly inputText?: string;
+        readonly totalInputLength?: number;
+        readonly progress?: string;
+        readonly startedAt?: number;
+        readonly endedAt?: number;
+    };
+}
+interface ClientCreateSessionInput {
+    readonly mcpServers?: Readonly<Record<string, ClientMcpServerConfig>>;
+    /** Delete this Session when its task ends, including after the client detaches. */
+    readonly temporary?: boolean;
+    readonly sessionId?: string;
+    readonly title?: string;
+    readonly projectPath?: string;
+    readonly gitRoot?: string;
+    readonly surface?: string;
+    readonly profileId?: string;
+    readonly tag?: string;
+}
+interface ClientSubmitInput {
+    /** 'steer' and 'redirect' additionally require targetRunId. */
+    readonly delivery?: 'immediate' | 'after_turn' | 'steer' | 'redirect';
+    readonly sessionId: string;
+    readonly inputId: string;
+    readonly text: string;
+    /** The only Run a 'steer' or 'redirect' delivery may act on. */
+    readonly targetRunId?: string;
+    /**
+     * Image/file/video references anchored by the prompt (@path syntax,
+     * clipboard, drag-drop). Part of the input's intent: resubmitting the same
+     * inputId with a different artifact set is a conflict.
+     */
+    readonly inputArtifacts?: readonly KodaXInputArtifact[];
+}
+/** Identity of an accepted input in the current Host, not a completion receipt. */
+interface ClientInputAcceptance {
+    /**
+     * 'submitted' is saved in the conversation context (does not prove the
+     * Provider received it); 'queued' waits for its slot; 'withdrawn' was
+     * taken back by the user; 'dropped' means the target Run settled before
+     * delivery — the text never entered the context, so resubmit with a new ID.
+     */
+    readonly state: 'submitted' | 'queued' | 'withdrawn' | 'dropped';
+    readonly sessionId: string;
+    readonly inputId: string;
+    readonly runId?: string;
+}
+interface ClientQueuedInput {
+    readonly inputId: string;
+    /** Bounded display preview; withdraw returns the complete original text. */
+    readonly text: string;
+    readonly enqueuedAt: number;
+}
+/** User-explainable lifecycle facts; accepting a Stop never implies them. */
+interface ClientRunTerminal {
+    readonly revision: number;
+    readonly kind: 'completed' | 'failed' | 'cancelled' | 'interrupted';
+    readonly code: string;
+    /** Execution settlement and confirmed tool effects are separate facts. */
+    readonly effectOutcome: 'none' | 'known' | 'unknown';
+    readonly message?: string;
+    readonly failureKind?: string;
+}
+interface ClientRunStatus {
+    readonly terminal?: ClientRunTerminal;
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly phase: string;
+    readonly startedAt?: string;
+    readonly error?: string;
+    readonly stop?: {
+        readonly requestedAt: string;
+        readonly state: string;
+        readonly outcome: string;
+        readonly reason: string;
+        readonly resolvedAt?: string;
+    };
+}
+/** Stop acceptance is distinct from the Run's real terminal outcome. */
+interface ClientRunStopReceipt {
+    readonly runId: string;
+    readonly sessionId: string;
+    /** True only when this call durably created the Stop request. */
+    readonly accepted: boolean;
+    readonly state: string;
+    readonly outcome: string;
+    readonly phase: string;
+}
+interface ClientSessionSettingsSnapshot {
+    readonly revision: number;
+    readonly value: ClientSessionSettings;
+}
+interface ClientSessionCancelInput {
+    readonly sessionId: string;
+    readonly expectedRunId: string;
+    readonly requestId: string;
+}
+interface ClientSessionCancelReceipt extends ClientSessionCancelInput {
+    readonly frontier: number;
+    readonly receipts: readonly ClientRunStopReceipt[];
+}
+interface ClientToolInvocationInput {
+    readonly sessionId: string;
+    readonly inputId: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+    readonly rawInput: string;
+}
+/**
+ * Terminal facts of one Run. `result` is present only for settled runs the
+ * Host could observe; `phase: 'unknown'` means settlement could not be
+ * confirmed, even on a healthy connection. Preserve error; transport failures
+ * reject separately. Unknown is never success or cancellation.
+ */
+interface ClientRunOutcome {
+    readonly terminal?: ClientRunTerminal;
+    readonly stop?: ClientRunStatus['stop'];
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly phase: string;
+    readonly result?: KodaXResult;
+    readonly error?: string;
+}
+/** Facts of one concrete operation awaiting an approval decision. */
+interface ClientPermissionInteractionOptions {
+    /** Complete finalized plan for exit_plan_mode approval; never a truncated input preview. */
+    readonly plan?: string;
+    readonly toolName: string;
+    readonly toolCallId?: string;
+    readonly reason?: string;
+    readonly risk?: 'low' | 'medium' | 'high';
+    readonly inputPreview?: string;
+    readonly executionCwd?: string;
+    /** Opaque pending-request-local ids; return one unchanged to widen a decision. */
+    readonly grantSuggestions?: readonly {
+        readonly id: string;
+        readonly kind: 'session' | 'persistent';
+        readonly label: string;
+    }[];
+}
+/**
+ * One pending answer the Host is waiting for. `kind` selects both the typed
+ * payload and the typed response this request accepts.
+ */
+type ClientInteraction = ClientInteractionBase & {
+    readonly kind: 'question';
+    readonly options: AskUserQuestionOptions;
+    readonly expiresAt: string;
+} | ClientInteractionBase & {
+    readonly kind: 'question_multi';
+    readonly options: AskUserMultiOptions;
+    readonly expiresAt: string;
+} | ClientInteractionBase & {
+    readonly kind: 'question_input';
+    readonly options: {
+        readonly question: string;
+        readonly default?: string;
+    };
+    readonly expiresAt: string;
+} | ClientInteractionBase & {
+    readonly kind: 'permission';
+    readonly options: ClientPermissionInteractionOptions;
+    readonly expiresAt?: string;
+};
+interface ClientInteractionBase {
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly createdAt: string;
+}
+/** Typed answer for one pending interaction; kinds must match the request. */
+type ClientInteractionResponse = {
+    readonly kind: 'question';
+    readonly answer: AskUserAnswer;
+} | {
+    readonly kind: 'question_multi';
+    readonly answers: Readonly<Record<string, AskUserAnswer>>;
+} | {
+    readonly kind: 'question_input';
+    readonly text: string;
+} | {
+    readonly kind: 'permission';
+    readonly decision: ClientPermissionDecision;
+} | {
+    readonly kind: 'cancel';
+    readonly reason?: string;
+};
+type ClientPermissionDecision = {
+    readonly type: 'allow_once';
+} | {
+    readonly type: 'allow_session';
+    readonly suggestionId: string;
+} | {
+    readonly type: 'allow_always';
+    readonly suggestionId: string;
+} | {
+    readonly type: 'reject';
+    readonly reason?: string;
+};
+/** First valid answer wins; every other case is explicitly not accepted. */
+interface ClientInteractionResult {
+    readonly requestId: string;
+    readonly accepted: boolean;
+    /** 'already_resolved' covers late, duplicate, cancelled, expired and unknown targets. */
+    readonly status: 'answered' | 'dismissed' | 'already_resolved';
+}
+interface ClientPermissionGrant {
+    readonly id: string;
+    /** Host-recorded Session scope. Absence alone does not imply a global grant. */
+    readonly sessionId?: string;
+    readonly label?: string;
+    readonly persistence?: 'session' | 'persistent';
+}
+interface ClientPermissionGrants {
+    readonly revision: number;
+    readonly grants: readonly ClientPermissionGrant[];
+}
+interface ClientSessionSettings {
+    /** Host-owned plan-mode default; an explicit Session effort takes precedence. */
+    readonly planModeEffort?: string;
+    readonly repoIntelligenceMode?: 'auto' | 'off' | 'light' | 'full';
+    readonly repoIntelligenceTrace?: boolean;
+    /** Shared manual/automatic summary policy, independent of main-turn effort. */
+    readonly compactionReasoning?: boolean | {
+        readonly effort: string;
+    };
+    readonly provider?: string;
+    readonly model?: string;
+    readonly effort?: string;
+    readonly thinking?: boolean;
+    readonly reasoningMode?: 'off' | 'auto' | 'quick' | 'balanced' | 'deep';
+    readonly permissionMode?: 'plan' | 'accept-edits' | 'auto' | 'full-access';
+    readonly agentMode?: 'ama' | 'sa' | 'amaw';
+    readonly autoModeClassifierModel?: string;
+    readonly compactionTriggerPercent?: number;
+    readonly compactionTriggerTokens?: number;
+    /** Per-run iteration fuse; unset falls back to the engine default. */
+    readonly maxIter?: number;
+}
+type ClientSessionSettingsPatch = {
+    readonly [Key in keyof ClientSessionSettings]?: ClientSessionSettings[Key] | null;
+};
+interface ClientConfig {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly effort?: string;
+    readonly planModeEffort?: string;
+    readonly thinking?: boolean;
+    readonly reasoningMode?: ClientSessionSettings['reasoningMode'];
+    readonly permissionMode?: ClientSessionSettings['permissionMode'];
+    readonly agentMode?: ClientSessionSettings['agentMode'];
+    readonly locale?: string;
+    readonly providerModels?: Record<string, string[]>;
+    readonly extensions?: string[];
+    readonly fallbackProviders?: string[];
+    readonly repoIntelligenceMode?: 'auto' | 'off' | 'light' | 'full';
+    readonly repoIntelligenceTrace?: boolean;
+    readonly verifierLog?: boolean;
+    readonly stallLog?: boolean;
+    readonly fastProvider?: string;
+    readonly fastModel?: string;
+    readonly deepProvider?: string;
+    readonly deepModel?: string;
+    readonly maxOutputTokens?: number;
+    readonly disablePromptCache?: boolean;
+    readonly lsp?: boolean;
+    readonly lspAutoDownload?: boolean;
+    readonly acpLogLevel?: string;
+    readonly sessionRetentionDays?: number;
+    readonly repoIntelligence?: {
+        readonly toolWaitMs?: number;
+        readonly workerTimeoutMs?: number;
+        readonly workerOldSpaceMb?: number;
+        readonly storageDir?: string;
+    };
+    readonly workflow?: {
+        readonly maxConcurrency?: number;
+    };
+}
+interface ClientEffectiveConfigValue<T> {
+    readonly value: T;
+    readonly source: 'runtime_override' | 'environment' | 'persisted' | 'unset';
+    readonly applied: boolean;
+}
+interface ClientEffectiveExecutionConfig {
+    readonly verifierLog: ClientEffectiveConfigValue<boolean>;
+    readonly stallLog: ClientEffectiveConfigValue<boolean>;
+    readonly fallbackProviders: ClientEffectiveConfigValue<readonly string[]>;
+}
+/** MCP configuration only; executable connections and callbacks stay in the Host. */
+interface ClientMcpServerConfig {
+    readonly type?: 'stdio' | 'sse' | 'streamable-http' | 'http';
+    readonly command?: string;
+    readonly args?: string[];
+    readonly cwd?: string;
+    readonly env?: Record<string, string>;
+    readonly url?: string;
+    readonly headers?: Record<string, string>;
+    readonly connect?: 'lazy' | 'prewarm' | 'disabled';
+    readonly startupTimeoutMs?: number;
+    readonly requestTimeoutMs?: number;
+    readonly auth?: {
+        readonly type: 'oauth2';
+        readonly clientId?: string;
+        readonly authorizationUrl?: string;
+        readonly tokenUrl?: string;
+        readonly scopes?: readonly string[];
+        readonly redirectPort?: number;
+    };
+}
+interface ClientMcpServerStatus {
+    readonly serverId: string;
+    readonly config: ClientMcpServerConfig;
+    readonly connect: 'lazy' | 'prewarm' | 'disabled';
+    readonly status: 'idle' | 'connecting' | 'ready' | 'error' | 'disabled';
+    readonly tools: number;
+    readonly resources: number;
+    readonly prompts: number;
+    readonly dirty: boolean;
+    readonly resolvedTransport?: string;
+    readonly cachedAt?: string;
+    readonly lastError?: string;
+}
+type ClientWorkflowStartSource = {
+    readonly kind: 'inline';
+    readonly manifest: unknown;
+    readonly source: string;
+} | {
+    readonly kind: 'request';
+    readonly request: string;
+} | {
+    readonly kind: 'name';
+    readonly name: string;
+};
+/**
+ * FEATURE_298 T22 — serializable process metadata for a declarative start.
+ * Mirrors the run-graph WorkflowRunProcessMetadata the Host attaches to the
+ * minted run, so saved/rerun lineage (savedWorkflowName, sourceRunId, …)
+ * survives the client→Host boundary.
+ */
+interface ClientWorkflowStartMetadata {
+    readonly displayName?: string;
+    readonly goal?: string;
+    readonly source?: 'command' | 'review' | 'sdk' | 'capsule' | 'extension' | 'automation';
+    readonly savedWorkflowName?: string;
+    readonly sourceRunId?: string;
+    readonly sourceWorkflowName?: string;
+    readonly revisionOf?: string;
+    readonly resumedFromRunId?: string;
+    readonly hostMetadata?: Readonly<Record<string, string>>;
+}
+interface ClientWorkflowStartInput {
+    readonly sessionId?: string;
+    readonly projectRoot: string;
+    readonly source: ClientWorkflowStartSource;
+    readonly args?: unknown;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly metadata?: ClientWorkflowStartMetadata;
+}
+type ClientWorkflowStartResult = {
+    readonly kind: 'declined';
+    readonly reason: string;
+} | {
+    readonly kind: 'started';
+    readonly runId: string;
+};
+type ClientWorkflowProcess = WorkflowProcessSnapshot;
+type ClientWorkflowEvent = WorkflowProcessEvent;
+interface ClientWorkflowRun {
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly status: ManagedWorkflowStatus;
+    readonly totalSpawned: number;
+    readonly eventCount: number;
+    readonly runDir: string;
+    readonly endedAt?: string;
+    readonly startedAt: string;
+    readonly updatedAt: string;
+    readonly displayName?: string;
+    readonly resultSummary?: string;
+    readonly error?: string;
+}
+/** Read-only Auto review facts; changing permissions still uses Session settings. */
+interface ClientAutoModeStats {
+    readonly classifierHealth: 'healthy' | 'degraded';
+    readonly classifierModel?: string;
+    readonly denials: DenialTracker;
+    readonly breaker: CircuitBreaker;
+}
+
+export type { ClientPermissionGrants as $, ClientInteractionResponse as A, ClientInteractionResult as B, ClientAutoModeStats as C, ClientItemContent as D, ClientItemReadOptions as E, ClientLearningService as F, ClientLearningSubscription as G, ClientLifecycleService as H, ClientLineageEntry as I, ClientLineageLabelInput as J, ClientLineageSummary as K, ClientLoadedExtension as L, ClientMcpServerConfig as M, ClientMcpServerStatus as N, ClientMcpTool as O, ClientMemoryController as P, ClientMemoryPlane as Q, ClientMemoryProposal as R, ClientMemoryRebuildResult as S, ClientMemoryService as T, ClientModelCatalog as U, ClientModelSelection as V, ClientObservation as W, ClientObservationStatus as X, ClientObserveOptions as Y, ClientPermissionDecision as Z, ClientPermissionGrant as _, ClientCapabilityProbeResult as a, ClientPermissionInteractionOptions as a0, ClientProviderInfo as a1, ClientProviderRequestFact as a2, ClientQueuedInput as a3, ClientReviewInput as a4, ClientReviewService as a5, ClientRunOutcome as a6, ClientRunStatus as a7, ClientRunStopReceipt as a8, ClientRunTerminal as a9, ClientWorkflowStartSource as aA, KodaXProductClient as aB, ClientSession as aa, ClientSessionActivity as ab, ClientSessionCancelInput as ac, ClientSessionCancelReceipt as ad, ClientSessionFilter as ae, ClientSessionForkInput as af, ClientSessionGoal as ag, ClientSessionRecoverInput as ah, ClientSessionSettings as ai, ClientSessionSettingsPatch as aj, ClientSessionSettingsSnapshot as ak, ClientSessionSummary as al, ClientSessionView as am, ClientSkillInfo as an, ClientStatisticsService as ao, ClientSubmitInput as ap, ClientToolExecutionFact as aq, ClientToolInvocationInput as ar, ClientUsageTotals as as, ClientViewItem as at, ClientWorkflowEvent as au, ClientWorkflowProcess as av, ClientWorkflowRun as aw, ClientWorkflowStartInput as ax, ClientWorkflowStartMetadata as ay, ClientWorkflowStartResult as az, ClientCommandInfo as b, ClientCommandInput as c, ClientCommandResult as d, ClientCommandService as e, ClientCompactSessionResult as f, ClientConfig as g, ClientContextBudget as h, ClientContextBudgetFact as i, ClientCreateSessionInput as j, ClientEffectiveConfigValue as k, ClientEffectiveExecutionConfig as l, ClientExecutionFactsPage as m, ClientExecutionTarget as n, ClientExitReceipt as o, ClientExtensionDiagnostics as p, ClientExtensionSource as q, ClientGoalCreateInput as r, ClientHistoryBoundary as s, ClientHistoryIssue as t, ClientHistoryPage as u, ClientHistoryReadOptions as v, ClientHistorySearchInput as w, ClientHistorySearchResult as x, ClientInputAcceptance as y, ClientInteraction as z };