@kodax-ai/kodax 0.7.63 → 0.7.66

package/dist/types-chunks/types.d-CUN_bZU7.d.ts

@@ -0,0 +1,975 @@
+import { a8 as KodaXWireReasoningEffort, a0 as KodaXToolDefinition, a2 as KodaXToolResultContentItem, j as KodaXMessage } from './types.d-Bp4Lm1jv.js';
+import { K as KodaXBaseProvider } from './base.d-DalIRhbb.js';
+import { C as CapabilityKind, a as CapabilityProvider } from './capability.d-3C62G8Eq.js';
+import { a4 as KodaXJsonValue, U as KodaXExtensionSessionRecord, W as KodaXExtensionStore } from './process.d-CY2g03Mb.js';
+import { aw as KodaXToolExecutionContext, bd as ToolSideEffect } from './bash-prefix-extractor.d-BjkITAva.js';
+
+/**
+ * KodaX Constructed-World types (FEATURE_087, v0.7.28).
+ *
+ * Runtime-generated capabilities (tools / agents / skills / ...) live in
+ * `.kodax/constructed/` and are loaded into the same registries as builtin
+ * primitives. v0.7.28 only ships tool generation (FEATURE_088); other kinds
+ * land in FEATURE_089 / FEATURE_090.
+ *
+ * Cross-references:
+ *   - DD §14 — lifecycle, security model, registry merge semantics.
+ *   - docs/features/v0.7.28.md — capability schema, generation flow.
+ */
+
+/**
+ * Handler script source. v0.7.28 limits language to `'javascript'` so that
+ * `loadHandler()` can `await import()` the file directly without an
+ * intermediate TS → JS compile step (no esbuild / tsx dependency).
+ *
+ * TypeScript handlers are explicitly out of scope; Coding Agent generates
+ * JS strings on the wire.
+ */
+interface ScriptSource {
+    readonly kind: 'script';
+    readonly language: 'javascript';
+    readonly code: string;
+}
+/**
+ * Capability declaration.
+ *
+ * v0.7.28 ships the single-dimension form: a whitelist of builtin tool
+ * names that the handler may invoke through `ctx.tools.<name>(...)`.
+ * All I/O — fs / net / env — must flow through builtin tools (`read` /
+ * `write` / `bash` / etc.); handlers do not receive direct `ctx.fs` /
+ * `ctx.net` / `ctx.env` entry points.
+ *
+ * Forward-compatible evolution: if the future demands path/domain-level
+ * constraints, this can grow to `(string | { name; constraints })[]`
+ * without breaking existing manifests.
+ */
+interface Capabilities {
+    readonly tools: readonly string[];
+}
+/**
+ * Tool-kind artifact body (the `content` of `ConstructionArtifact` when
+ * `kind === 'tool'`).
+ */
+interface ToolContent {
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    readonly capabilities: Capabilities;
+    readonly handler: ScriptSource;
+    /**
+     * Per-tool timeout override. Defaults to {@link DEFAULT_HANDLER_TIMEOUT_MS}
+     * when omitted. Bounded by AbortController in `loadHandler()`.
+     */
+    readonly timeoutMs?: number;
+}
+/**
+ * Default handler timeout. Picked to match the historical ceiling on
+ * builtin streaming tools (30s); revisit if a constructed tool demands
+ * longer-running computation.
+ */
+declare const DEFAULT_HANDLER_TIMEOUT_MS = 30000;
+/**
+ * Lifecycle state on disk. Drives both the startup glob filter and the
+ * `revoke()` semantics. See DD §14.1 — file system is the single source
+ * of truth; no separate `_manifest.json` index file (C4 decision).
+ */
+type ArtifactStatus = 'staged' | 'active' | 'revoked';
+/**
+ * Reference to a tool by stable id. v0.7.31 (FEATURE_089) introduces
+ * Agent manifests that bundle tool refs rather than inline tool bodies;
+ * the resolver expands these refs to concrete `KodaXToolDefinition`
+ * instances at activate time.
+ *
+ * `ref` shape:
+ *   - `builtin:<name>`            — a tool from the static registry
+ *     (e.g. `builtin:read`, `builtin:bash`)
+ *   - `constructed:<name>@<ver>`  — a previously-activated constructed tool
+ */
+interface ToolRef {
+    readonly ref: string;
+}
+/**
+ * Reference to a Guardrail by stable id. The Layer A `Guardrail`
+ * declaration is name-only (no runtime hooks); resolvers map known
+ * names to constructed `ToolGuardrail` / `InputGuardrail` /
+ * `OutputGuardrail` instances at activation time.
+ */
+interface GuardrailRef {
+    readonly kind: 'input' | 'output' | 'tool';
+    readonly ref: string;
+}
+/**
+ * Reference to a handoff target by stable id (another constructed agent
+ * or a builtin role). The resolver expands `target.ref` to the actual
+ * `Agent` declaration at admission time so the handoff DAG check
+ * (`handoffLegality` invariant) sees the full graph.
+ */
+interface AgentHandoffRef {
+    readonly target: {
+        readonly ref: string;
+    };
+    readonly kind: 'continuation' | 'as-tool';
+    readonly description?: string;
+}
+/**
+ * Reasoning profile declaration mirroring the Layer A
+ * `AgentReasoningProfile`. Kept structurally identical so the resolver
+ * passes the value through without re-shaping.
+ */
+interface AgentReasoningRef {
+    readonly default: 'quick' | 'balanced' | 'deep';
+    readonly max?: 'quick' | 'balanced' | 'deep';
+    readonly escalateOnRevise?: boolean;
+}
+/**
+ * Sandbox test case. Used by `sandbox_test_agent` to verify a
+ * constructed agent before it can activate. Each case feeds `input`
+ * to a sandbox Runner instance and grades the agent's final output:
+ *
+ *   - `expectMatch`     — final text must match this regex (string form)
+ *   - `expectNotMatch`  — final text must NOT match this regex
+ *   - `expectFinalText` — exact substring match (case-sensitive)
+ *
+ * At least one of the three expect-fields must be present; the cases
+ * are graded by `runSandboxAgentTest()` (FEATURE_089 Phase 3.5).
+ */
+interface AgentTestCase {
+    readonly id: string;
+    readonly input: string;
+    readonly expectMatch?: string;
+    readonly expectNotMatch?: string;
+    readonly expectFinalText?: string;
+}
+/**
+ * Agent-kind artifact body (the `content` of `ConstructionArtifact`
+ * when `kind === 'agent'`).
+ *
+ * FEATURE_089 (v0.7.31): all fields except `instructions` are optional;
+ * a minimal "echo agent" can be expressed as `{ instructions: '...' }`.
+ * Tool / handoff / guardrail refs are resolved at admission time
+ * (Runner.admit's 5-step audit expands them and feeds the resolved
+ * Agent through the invariant chain).
+ */
+interface AgentContent {
+    readonly instructions: string;
+    readonly tools?: readonly ToolRef[];
+    readonly handoffs?: readonly AgentHandoffRef[];
+    readonly reasoning?: AgentReasoningRef;
+    readonly guardrails?: readonly GuardrailRef[];
+    readonly model?: string;
+    readonly provider?: string;
+    readonly effort?: KodaXWireReasoningEffort;
+    /**
+     * FEATURE_191 — one-sentence human-readable summary surfaced in the
+     * Worker system prompt's `=== Available specialist agents ===`
+     * block (FEATURE_191 A.3) and in `/agents list` UIs. Frontmatter
+     * `description` field of `~/.kodax/agents/<name>.md` and the
+     * `name`-paired argument of `KodaXExtensionAPI.registerAgent`
+     * funnel into this field. Optional for backward compatibility with
+     * FEATURE_089 minimal-agent shape (`{ instructions: '...' }`);
+     * the SP block renders `(no description)` when absent.
+     */
+    readonly description?: string;
+    /**
+     * Optional structured-output schema mirroring `Agent.outputSchema`.
+     * Pure pass-through to the runtime — admission does not validate
+     * shape semantics here, only well-formed JSON.
+     */
+    readonly outputSchema?: Record<string, unknown>;
+    /**
+     * Optional sandbox test cases. When present, `sandbox_test_agent`
+     * runs them; when absent, the test step performs only the static
+     * checks (manifest schema + admission audit).
+     */
+    readonly testCases?: readonly AgentTestCase[];
+    /**
+     * Maximum total budget (iteration count) the agent may consume.
+     * Plumbed onto the resolved `AgentManifest.maxBudget` and clamped by
+     * `budgetCeiling` invariant during admission.
+     */
+    readonly maxBudget?: number;
+    /**
+     * Voluntary additional invariants the LLM declares this agent
+     * commits to. Plumbed onto `AgentManifest.declaredInvariants`;
+     * unioned on top of the required set during admission.
+     */
+    readonly declaredInvariants?: readonly string[];
+}
+/**
+ * Persisted artifact shape (one JSON file per name/version under
+ * `.kodax/constructed/<kind>s/<name>/<version>.json`).
+ *
+ * Discriminated union over `kind`:
+ *   - `kind: 'tool'`  — v0.7.28 (FEATURE_088) tool generation
+ *   - `kind: 'agent'` — v0.7.31 (FEATURE_089) agent generation; passes
+ *                       through `Runner.admit()` at activation time
+ *
+ * Lifecycle fields (status / timestamps / contentHash / sourceAgent /
+ * signedBy) are common to all kinds.
+ */
+type ConstructionArtifact = ToolArtifact | AgentArtifact;
+interface ConstructionArtifactBase {
+    readonly name: string;
+    readonly version: string;
+    status: ArtifactStatus;
+    readonly signedBy?: string;
+    readonly createdAt: number;
+    readonly sourceAgent?: string;
+    testedAt?: number;
+    activatedAt?: number;
+    revokedAt?: number;
+    /**
+     * SHA-256 of `JSON.stringify(content)` captured at activate time.
+     * `rehydrateActiveArtifacts()` recomputes and compares — a mismatch
+     * indicates the manifest was edited between activation and the next
+     * boot (naive cross-session tampering, e.g. an LLM rewriting the .json
+     * via the Write tool without recomputing the hash). Mismatched
+     * artifacts are skipped at rehydrate with a stderr warning. This is
+     * NOT a defense against a coordinated attacker who recomputes the
+     * hash; the threat model is single-user CLI integrity, not multi-user
+     * supply chain.
+     */
+    contentHash?: string;
+}
+interface ToolArtifact extends ConstructionArtifactBase {
+    readonly kind: 'tool';
+    readonly content: ToolContent;
+}
+interface AgentArtifact extends ConstructionArtifactBase {
+    readonly kind: 'agent';
+    readonly content: AgentContent;
+}
+/**
+ * Returned by {@link ConstructionRuntime.stage}; opaque handle that
+ * downstream `test()` / `activate()` calls bind to.
+ */
+interface StagedHandle {
+    readonly artifact: ConstructionArtifact;
+    readonly stagedAt: number;
+}
+/**
+ * Outcome of {@link ConstructionRuntime.test}. `ok=false` blocks
+ * activation; `warnings` surface but do not block.
+ */
+interface TestResult {
+    readonly ok: boolean;
+    readonly errors?: readonly string[];
+    readonly warnings?: readonly string[];
+}
+/**
+ * Policy gate — invoked once per `activate()` before the artifact is
+ * registered. Default rejects implicit auto-approval; the REPL surface
+ * binds a dialog-based policy in `packages/repl/src/common/construction-
+ * bootstrap.ts` so user approval flows through the live askUser channel.
+ *
+ * Modeled as a function type rather than an interface (D3 decision):
+ * keeps the contract surface tiny, no class boilerplate.
+ *
+ * No declarative `kodax.config.ts` override hatch is provided — see the
+ * "Deferred Design Decisions" section in `features/v0.7.28.md` for why
+ * a `risk_mode` enum (when truly needed) is preferred over user-authored
+ * policy functions.
+ */
+type ConstructionPolicy = (artifact: ConstructionArtifact) => Promise<ConstructionPolicyVerdict>;
+type ConstructionPolicyVerdict = 'approve' | 'reject' | 'ask-user';
+/** Default policy: always ask the user; no implicit approvals. */
+declare const defaultPolicy: ConstructionPolicy;
+/**
+ * Thrown by `CtxProxy` when handler attempts to access a tool not declared
+ * in `capabilities.tools`. Caught in tracer; surfaces as a tool error.
+ */
+declare class CapabilityDeniedError extends Error {
+    readonly toolName: string;
+    readonly declaredTools: readonly string[];
+    constructor(toolName: string, declaredTools: readonly string[]);
+}
+/**
+ * Thrown when a manifest cannot be parsed / is missing required fields.
+ * Surfaces during stage() / startup glob; tracer records details.
+ */
+declare class ConstructionManifestError extends Error {
+    readonly path?: string;
+    constructor(message: string, path?: string);
+}
+
+/**
+ * KodaX Tool Types
+ */
+
+/**
+ * Progress yield from a streaming (async generator) tool.
+ * Each yield appears as a real-time status update in the REPL transcript.
+ */
+interface ToolProgress {
+    readonly stage: string;
+    readonly message: string;
+}
+/**
+ * Final result a tool may return. Either a plain string (the default for
+ * text-only tools) OR a typed-array form for multimodal returns (e.g.
+ * `read` on an image path returns `[{type:'text',...}, {type:'image',...}]`).
+ * Providers serialize each shape to their wire format; OpenAI-compat
+ * gateways downgrade image items to a placeholder rather than rejecting.
+ *
+ * The array form mirrors claudecode's FileReadTool image return — Claude
+ * Code packs image data into `tool_result` content so the model can
+ * re-fetch images via the tool path. See
+ * `c:/Works/claudecode/src/tools/FileReadTool/FileReadTool.ts:866-891`.
+ */
+type ToolResult = string | readonly KodaXToolResultContentItem[];
+/** Standard tool handler — returns a final result (text or multimodal). */
+type ToolHandlerSync = (input: Record<string, unknown>, context: KodaXToolExecutionContext) => Promise<ToolResult>;
+/** Streaming tool handler — yields progress updates, returns final result. */
+type ToolHandlerStreaming = (input: Record<string, unknown>, context: KodaXToolExecutionContext) => AsyncGenerator<ToolProgress, ToolResult, void>;
+/** Union of both handler types. Existing tools use ToolHandlerSync; new long-running tools may use ToolHandlerStreaming. */
+type ToolHandler = ToolHandlerSync | ToolHandlerStreaming;
+
+/**
+ * FEATURE_149 (v0.7.38) — interrupt-on-submit policy for in-flight tools.
+ *
+ * Controls whether submitting a new prompt while THIS tool is mid-execution
+ * triggers a fast-abort of the current agent round (so the new prompt starts
+ * immediately) or queues the prompt to run after the tool resolves.
+ *
+ *   - `'cancel'` — long-running tools whose work the user is likely to want
+ *     to abandon when they redirect (e.g., `bash` running a 30s script,
+ *     `dispatch_child_task` synchronously awaiting a child, sleep-style
+ *     tools). InkREPL submit handler aborts the round immediately.
+ *
+ *   - `'wait'` (default) — atomic / fast tools (read, grep, glob, write,
+ *     edit, …) where waiting for completion is cheaper than aborting and
+ *     redoing.
+ *
+ * Mirrors Claude Code `interruptBehavior` (`utils/handlePromptSubmit.ts`).
+ */
+type ToolInterruptBehavior = 'cancel' | 'wait';
+interface LocalToolDefinition extends KodaXToolDefinition {
+    handler: ToolHandler;
+    /**
+     * v0.7.42 — Required declarative side-effect class. See
+     * {@link ToolSideEffect} for category definitions and rationale. Plan
+     * mode and SDK embedders' permission brokers consume this; failure to
+     * declare is a TypeScript error (by design — `sideEffect` is required,
+     * not optional, to prevent silent drift when new tools are added).
+     */
+    sideEffect: ToolSideEffect;
+    /**
+     * v0.7.42 — Optional plan-mode override.
+     *
+     *   - `undefined` (default): plan-mode permits only `sideEffect ===
+     *     'readonly'` tools.
+     *   - `true`: explicitly permitted in plan mode even when sideEffect is
+     *     not `'readonly'`. Reserve for tools whose effect is itself part of
+     *     the planning loop (`exit_plan_mode`, `task_stop`, `todo_update`,
+     *     `todo_create`, `ask_user_question`).
+     *   - `false`: explicitly blocked in plan mode even when sideEffect is
+     *     `'readonly'`. Rare — useful for read-only tools whose output would
+     *     leak content the planner should not see.
+     */
+    planModeAllowed?: boolean;
+    /**
+     * FEATURE_149 (v0.7.38) — submit-time interrupt policy. See
+     * {@link ToolInterruptBehavior}. Default `'wait'` when undefined.
+     */
+    interruptBehavior?: ToolInterruptBehavior;
+    /**
+     * Progressive disclosure — when `true`, the tool's full description is
+     * replaced with `searchHint` (a one-line summary) in the LLM-visible
+     * tool schema until the per-session unlock Set marks the tool name as
+     * unlocked. Unlocking happens via the `tool_search` tool: the LLM
+     * invokes `tool_search` with a query that selects this tool, and the
+     * full description + JSON schema are returned in the tool_result text.
+     * The next `getActiveToolDefinitions` call for the same session sees
+     * the unlock and emits the full description.
+     *
+     * Use for tools with rich descriptions (>500 bytes) whose teaching
+     * content the model only needs to consume when it actually plans to
+     * call the tool. Saves turn-1 context without dropping the tool.
+     *
+     * Mirrors claudecode `Tool.shouldDefer` — see
+     * `c:/Works/claudecode/src/tools/Tool.ts` for the parent design and
+     * `c:/Works/claudecode/src/tools/ToolSearchTool/` for the bootstrap.
+     */
+    shouldDefer?: boolean;
+    /**
+     * One-line hint shown in place of the full description when this tool
+     * is deferred and not yet unlocked. Required when `shouldDefer: true`.
+     * Should answer "when would I want to look this up" in ≤ 100 chars
+     * so the LLM can decide whether to invoke `tool_search` for the full
+     * schema. Example: `'Fetch a specific remote URL — use tool_search to load full schema.'`
+     */
+    searchHint?: string;
+    /**
+     * Classifier projection — REQUIRED (FEATURE_092 v0.7.33).
+     *
+     * Returns a one-line string that the auto-mode classifier sees as the
+     * `<action>` to evaluate. The classifier asks: "Given the user's
+     * intent + rules, should the agent be allowed to run this?"
+     *
+     * THREE-TIER STRATEGY (pick by tool's risk profile):
+     *
+     *   1. ZERO RISK (read-only, structural):
+     *      → return ''  (Tier 1 — classifier is skipped entirely, zero token cost)
+     *      Examples: read, grep, glob, ask_user_question, exit_plan_mode
+     *
+     *   2. HIGH RISK (mutates state, network, exec, spawn):
+     *      → write a CUSTOM projection that surfaces the risk-bearing fields
+     *      Examples: bash (`Bash: ${i.command}`), web_fetch (`WebFetch ${i.url}`)
+     *      See `classifier-projection.ts` for examples by category.
+     *
+     *   3. LOW RISK (structured input, side-effect-capable):
+     *      → return defaultToClassifierInput(name, input)  (one-line helper)
+     *      Examples: semantic_lookup (refresh: true rebuilds index)
+     *
+     * KEEP IT SHORT: ≤ 100 chars typical. Variable-length user-provided fields
+     * (bash command, URL, dispatch_child_task objective) may legitimately
+     * exceed this — the projection's job is to make the risk visible, not to
+     * fit a fixed budget at the cost of hiding it.
+     *
+     * NEVER include: raw file contents, secrets, API keys, full LLM-emitted
+     * reasoning, or untrusted text passed through verbatim. Use byte/line
+     * counts as proxies (`Write ${path} (${content.length} bytes)`).
+     *
+     * See `docs/features/v0.7.33.md` "Tool 接口扩展" for design rationale.
+     */
+    toClassifierInput: (input: unknown) => string;
+}
+interface ToolDefinitionSource {
+    /**
+     * Origin of the registered tool. `'constructed'` (FEATURE_087, v0.7.28)
+     * marks tools materialized at runtime by `ConstructionRuntime` from
+     * `.kodax/constructed/tools/<name>/<version>.json` artifacts.
+     */
+    kind: 'builtin' | 'extension' | 'constructed';
+    id?: string;
+    label?: string;
+    /**
+     * Constructed-only: semver of the activated artifact. Used by
+     * `findByVersion()` and by `revoke()` to locate a specific stack entry.
+     */
+    version?: string;
+    /**
+     * Constructed-only: absolute path to the artifact JSON on disk.
+     * Lets revoke / inspect operations round-trip back to the source of
+     * truth without re-globbing.
+     */
+    manifestPath?: string;
+}
+interface RegisteredToolDefinition extends LocalToolDefinition {
+    registrationId: string;
+    requiredParams: string[];
+    source: ToolDefinitionSource;
+}
+interface ToolRegistrationOptions {
+    source?: ToolDefinitionSource;
+}
+type ToolRegistry = Map<string, RegisteredToolDefinition[]>;
+type KodaXRetrievalToolName = 'web_search' | 'web_fetch' | 'code_search' | 'semantic_lookup' | 'mcp_search' | 'mcp_describe' | 'mcp_call' | 'mcp_read_resource' | 'mcp_get_prompt';
+type KodaXRetrievalScope = 'workspace' | 'remote';
+type KodaXRetrievalTrust = 'workspace' | 'provider' | 'open-world';
+type KodaXRetrievalFreshness = 'fresh' | 'snapshot' | 'unknown';
+interface KodaXRetrievalArtifact {
+    kind: 'url' | 'path' | 'symbol' | 'module' | 'process' | 'provider';
+    label: string;
+    value: string;
+}
+interface KodaXRetrievalItem {
+    title: string;
+    locator?: string;
+    snippet?: string;
+    score?: number;
+    metadata?: Record<string, unknown>;
+}
+interface KodaXRetrievalResult {
+    tool: KodaXRetrievalToolName;
+    query?: string;
+    scope: KodaXRetrievalScope;
+    trust: KodaXRetrievalTrust;
+    freshness: KodaXRetrievalFreshness;
+    provider?: string;
+    summary: string;
+    content?: string;
+    items: KodaXRetrievalItem[];
+    artifacts?: KodaXRetrievalArtifact[];
+    metadata?: Record<string, unknown>;
+}
+
+interface ExecOptions {
+    /** Extra environment variables to inject (merged with safe base env). */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Working directory. Defaults to process.cwd(). */
+    readonly cwd?: string;
+    /** Timeout in milliseconds. Defaults to 30000. */
+    readonly timeout?: number;
+    /** Shell to use. Defaults to 'bash' on Unix, 'powershell' on Windows. */
+    readonly shell?: 'bash' | 'powershell';
+}
+interface ExecResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Run a shell command with a sandboxed environment.
+ *
+ * SECURITY: Only a whitelist of safe environment variables is passed to the
+ * subprocess. API keys and tokens from the parent environment are NOT inherited.
+ */
+declare function exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+interface WebhookOptions {
+    /** HTTP method. Defaults to 'POST'. */
+    readonly method?: 'POST' | 'PUT';
+    /** Extra HTTP headers. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Timeout in milliseconds. Defaults to 10000. */
+    readonly timeout?: number;
+}
+interface WebhookResult {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly body?: string;
+}
+/**
+ * Send an HTTP webhook with timeout support.
+ * Returns a result object instead of throwing on errors.
+ */
+declare function webhook(url: string, payload: unknown, options?: WebhookOptions): Promise<WebhookResult>;
+
+interface ModelProviderRegistration {
+    name: string;
+    factory: () => KodaXBaseProvider;
+}
+interface ExtensionCommandDefinition {
+    name: string;
+    aliases?: string[];
+    description: string;
+    usage?: string;
+    metadata?: Record<string, unknown>;
+    handler: (args: string[], context: ExtensionCommandContext) => Promise<ExtensionCommandResult | void> | ExtensionCommandResult | void;
+}
+interface ExtensionModelSelection {
+    provider?: string;
+    model?: string;
+}
+interface ExtensionLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+interface ExtensionFileContributionSource {
+    kind: 'extension';
+    id: string;
+    label: string;
+    path: string;
+}
+interface RuntimeContributionSource {
+    kind: 'runtime';
+    id: string;
+    label: string;
+    path?: string;
+}
+type ExtensionContributionSource = ExtensionFileContributionSource | RuntimeContributionSource;
+type ExtensionLoadSource = 'api' | 'cli' | 'config' | 'discovery';
+interface LoadedExtensionDiagnostic {
+    path: string;
+    label: string;
+    loadSource: ExtensionLoadSource;
+    sessionStateKeys?: string[];
+    sessionRecordCounts?: Record<string, number>;
+}
+interface RegisteredCapabilityProviderDiagnostic {
+    id: string;
+    kinds: CapabilityKind[];
+    source: ExtensionContributionSource;
+    metadata?: Record<string, unknown>;
+}
+interface RegisteredCommandDiagnostic {
+    name: string;
+    aliases?: string[];
+    description: string;
+    usage?: string;
+    metadata?: Record<string, unknown>;
+    source: ExtensionContributionSource;
+}
+interface RegisteredToolDiagnostic {
+    name: string;
+    description: string;
+    requiredParams: string[];
+    source: RegisteredToolDefinition['source'];
+    shadowedSources: RegisteredToolDefinition['source'][];
+}
+interface RegisteredHookDiagnostic {
+    hook: keyof ExtensionHookMap;
+    order: number;
+    source: ExtensionContributionSource;
+}
+type ExtensionFailureStage = 'load' | 'reload' | 'event' | 'hook' | 'persistence';
+interface ExtensionFailureDiagnostic {
+    stage: ExtensionFailureStage;
+    target: string;
+    message: string;
+    occurredAt: string;
+    source: ExtensionContributionSource;
+}
+interface ExtensionRuntimeDiagnostics {
+    loadedExtensions: LoadedExtensionDiagnostic[];
+    capabilityProviders: RegisteredCapabilityProviderDiagnostic[];
+    commands: RegisteredCommandDiagnostic[];
+    tools: RegisteredToolDiagnostic[];
+    hooks: RegisteredHookDiagnostic[];
+    failures: ExtensionFailureDiagnostic[];
+    defaults: {
+        activeTools?: string[];
+        modelSelection: ExtensionModelSelection;
+        thinkingLevel?: KodaXWireReasoningEffort;
+    };
+}
+interface ExtensionCommandInvocation {
+    prompt: string;
+    displayName?: string;
+    disableModelInvocation?: boolean;
+    allowedTools?: string;
+    context?: 'fork';
+    model?: string;
+}
+interface ExtensionCommandResult {
+    success?: boolean;
+    message?: string;
+    data?: unknown;
+    invocation?: ExtensionCommandInvocation;
+}
+interface ExtensionCommandContext {
+    sessionId?: string;
+    gitRoot?: string;
+    workingDirectory: string;
+    reloadExtensions: () => Promise<void>;
+    getDiagnostics: () => ExtensionRuntimeDiagnostics;
+    logger: ExtensionLogger;
+}
+interface ExtensionToolBeforeHookContext {
+    name: string;
+    input: Record<string, unknown>;
+    toolId?: string;
+    executionCwd?: string;
+    gitRoot?: string;
+}
+interface ExtensionProviderBeforeHookContext {
+    provider: string;
+    model?: string;
+    reasoningMode?: KodaXWireReasoningEffort;
+    systemPrompt: string;
+    block: (reason: string) => void;
+    replaceProvider: (provider: string) => void;
+    replaceModel: (model?: string) => void;
+    replaceSystemPrompt: (systemPrompt: string) => void;
+    setThinkingLevel: (level: KodaXWireReasoningEffort) => void;
+}
+interface ExtensionTurnSettleHookContext {
+    sessionId: string;
+    lastText: string;
+    hadToolCalls: boolean;
+    success: boolean;
+    signal?: 'COMPLETE' | 'BLOCKED' | 'DECIDE';
+    queueUserMessage: (message: string | KodaXMessage) => void;
+    setModelSelection: (next: ExtensionModelSelection) => void;
+    setThinkingLevel: (level: KodaXWireReasoningEffort) => void;
+}
+/**
+ * FEATURE_184 (v0.7.45) — Stop Hook bridge context for extensions.
+ *
+ * Fires ONLY when the model terminates a turn text-only (no tool_use)
+ * — a strict subset of `turn:settle`, which fires on every turn end
+ * including mid-task tool turns. Use this hook for verification or
+ * "is the task actually done?" checks. The three-state return surface
+ * mirrors `RunOptions.stopHook` at the agent layer; the bridge passes
+ * the extension's return through unchanged.
+ *
+ * Coding-layer first-party consumers (Sidecar Verifier, FEATURE_184
+ * Phase D) wire directly to the agent `stopHook`. Third-party
+ * extensions write `api.hook('turn:complete', handler)` and the bridge
+ * dispatches to them inside the agent's `stopHook` callback. Handlers
+ * fire in registration order, first non-`void` return short-circuits
+ * the chain (matches `tool:before` semantics).
+ *
+ * Scope note: this hook fires on the AMA `runner-driven` path only
+ * (main loop, B1 retry, V2 worker). SA-path child agents dispatched
+ * via `dispatch_child_task` go through `runKodaX` and do NOT trigger
+ * this hook — observe their lifecycle via `turn:settle` on the SA
+ * path. Extensions wanting "every agent termination" semantics must
+ * register both hooks.
+ */
+interface ExtensionTurnCompleteHookContext {
+    sessionId: string;
+    lastAssistantText: string;
+    signal: 'natural-end';
+    reanimateCount: number;
+    reanimateBudget: number;
+}
+/**
+ * FEATURE_184 (v0.7.45) — Extension `turn:complete` return surface.
+ *
+ *   - `void` / `undefined` → accept the termination, defer to next
+ *     handler (or fall through to agent terminal path if none).
+ *   - `string` → reanimate: synthesize a user message, run another
+ *     turn. Bounded by Runner's `stopHookReanimateBudget`.
+ *   - `{ abort: true, reason }` → halt the run, surface reason to
+ *     caller via `RunResult.output` + `stoppedByHook = true`.
+ */
+type ExtensionTurnCompleteHookResult = void | string | {
+    readonly abort: true;
+    readonly reason: string;
+};
+interface ExtensionSessionHydrateHookContext {
+    sessionId: string;
+    getState: <T = KodaXJsonValue>(key: string) => T | undefined;
+    setState: (key: string, value: KodaXJsonValue | undefined) => void;
+    listRecords: (type?: string) => KodaXExtensionSessionRecord[];
+    appendRecord: (type: string, data?: KodaXJsonValue, options?: {
+        dedupeKey?: string;
+    }) => KodaXExtensionSessionRecord | undefined;
+    clearRecords: (type?: string) => number;
+}
+interface ExtensionEventMap {
+    'session:start': {
+        provider: string;
+        sessionId: string;
+    };
+    'turn:start': {
+        sessionId: string;
+        iteration: number;
+        maxIter: number;
+    };
+    'text:delta': {
+        text: string;
+    };
+    'thinking:delta': {
+        text: string;
+    };
+    'thinking:end': {
+        thinking: string;
+    };
+    'tool:start': {
+        name: string;
+        id: string;
+        input?: Record<string, unknown>;
+    };
+    'tool:result': {
+        id: string;
+        name: string;
+        content: string;
+    };
+    'provider:selected': {
+        provider: string;
+        model?: string;
+    };
+    'provider:rate-limit': {
+        provider: string;
+        attempt: number;
+        maxRetries: number;
+        delayMs: number;
+    };
+    'capability:search': {
+        providerId: string;
+        query: string;
+        kind?: CapabilityKind;
+        limit?: number;
+    };
+    'capability:describe': {
+        providerId: string;
+        capabilityId: string;
+    };
+    'capability:invoke': {
+        providerId: string;
+        capabilityId: string;
+        kind: CapabilityKind;
+    };
+    'capability:refresh': {
+        providerId: string;
+    };
+    'stream:end': undefined;
+    'turn:end': {
+        sessionId: string;
+        iteration: number;
+        lastText: string;
+        hadToolCalls: boolean;
+        signal?: 'COMPLETE' | 'BLOCKED' | 'DECIDE';
+    };
+    'complete': {
+        success: boolean;
+        signal?: 'COMPLETE' | 'BLOCKED' | 'DECIDE';
+    };
+    'error': {
+        error: Error;
+    };
+    'todo:created': {
+        id: string;
+        item: KodaXTodoItem;
+        source: TodoMutationSource;
+    };
+    'todo:updated': {
+        id: string;
+        before: KodaXTodoItem;
+        after: KodaXTodoItem;
+        changedFields: readonly (keyof KodaXTodoItem)[];
+        source: TodoMutationSource;
+    };
+    'todo:deleted': {
+        id: string;
+        item: KodaXTodoItem;
+        source: TodoMutationSource;
+    };
+}
+/**
+ * FEATURE_170 v0.7.41 — provenance tag for todo:* events / hooks. Lets
+ * extension authors distinguish LLM-driven mutations (`tool`) from
+ * runner-side automation (`internal`) — e.g. an extension that audits
+ * todo churn should ignore `internal` flips to avoid false positives.
+ */
+type TodoMutationSource = 'tool' | 'internal';
+/**
+ * FEATURE_170 v0.7.41 — seed shape passed to `'todo:before-create'`.
+ * Mirrors `TodoAddSeed` from todo-store.ts (kept structurally compatible
+ * to avoid coupling extension authors to the internal task-engine type).
+ *
+ * v0.7.42 — `content` renamed to `subject` + optional `description` to
+ * match claudecode V2 `TaskCreateTool` schema. See `TodoItem` JSDoc in
+ * packages/coding/src/types.ts.
+ */
+interface ExtensionTodoCreateSeed {
+    readonly subject: string;
+    readonly description?: string;
+    readonly activeForm?: string;
+    readonly evaluator?: 'build' | 'test' | 'lint';
+    readonly owner?: string;
+    readonly sourceObligationIndex?: number;
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * FEATURE_170 v0.7.41 — minimal todo item shape exposed to extensions
+ * via the todo:* events. Kept structurally identical to the engine's
+ * `TodoItem` so the runtime can pass values straight through without
+ * conversion, but redeclared here so extension consumers don't import
+ * from `packages/coding/src/types.ts` (which is task-engine internal).
+ *
+ * Drift guard: a compile-time assignability assertion at the bottom of
+ * this file fires if `TodoItem` (engine) gains a field that this
+ * extension-facing shape does NOT mirror — see `__todoItemParity` below.
+ */
+interface KodaXTodoItem {
+    readonly id: string;
+    /** v0.7.42 — see TodoItem.subject JSDoc in packages/coding/src/types.ts. */
+    readonly subject: string;
+    readonly description?: string;
+    readonly status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped' | 'cancelled';
+    readonly owner?: string;
+    readonly sourceObligationIndex?: number;
+    readonly note?: string;
+    readonly evaluator?: 'build' | 'test' | 'lint';
+    readonly activeForm?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+interface ExtensionHookMap {
+    'tool:before': (context: ExtensionToolBeforeHookContext) => Promise<void | string | false> | void | string | false;
+    'provider:before': (context: ExtensionProviderBeforeHookContext) => Promise<void> | void;
+    'turn:settle': (context: ExtensionTurnSettleHookContext) => Promise<void> | void;
+    'turn:complete': (context: ExtensionTurnCompleteHookContext) => Promise<ExtensionTurnCompleteHookResult> | ExtensionTurnCompleteHookResult;
+    'session:hydrate': (context: ExtensionSessionHydrateHookContext) => Promise<void> | void;
+    'todo:before-create': (context: {
+        seed: ExtensionTodoCreateSeed;
+    }) => Promise<void | string | false> | void | string | false;
+    'todo:before-complete': (context: {
+        id: string;
+        item: KodaXTodoItem;
+    }) => Promise<void | string | false> | void | string | false;
+}
+interface ExtensionRuntimeController {
+    queueUserMessage(message: string | KodaXMessage): void;
+    getSessionState<T = KodaXJsonValue>(key: string): T | undefined;
+    setSessionState(key: string, value: KodaXJsonValue | undefined): void;
+    appendSessionRecord(type: string, data?: KodaXJsonValue, options?: {
+        dedupeKey?: string;
+    }): KodaXExtensionSessionRecord | undefined;
+    listSessionRecords(type?: string): KodaXExtensionSessionRecord[];
+    clearSessionRecords(type?: string): number;
+    getActiveTools(): string[];
+    setActiveTools(toolNames: string[]): void;
+    getModelSelection(): ExtensionModelSelection;
+    setModelSelection(next: ExtensionModelSelection): void;
+    getThinkingLevel(): KodaXWireReasoningEffort | undefined;
+    setThinkingLevel(level: KodaXWireReasoningEffort): void;
+}
+interface KodaXExtensionAPI {
+    registerTool: (definition: LocalToolDefinition) => () => void;
+    getTool: (name: string) => RegisteredToolDefinition | undefined;
+    getBuiltinTool: (name: string) => RegisteredToolDefinition | undefined;
+    registerModelProvider: (registration: ModelProviderRegistration) => () => void;
+    registerCapabilityProvider: (provider: CapabilityProvider) => () => void;
+    registerCommand: (command: ExtensionCommandDefinition) => () => void;
+    registerSkillPath: (skillPath: string) => () => void;
+    /**
+     * FEATURE_191 (v0.7.43) — register a constructed agent at extension
+     * activate time. The extension supplies the agent name and an
+     * `AgentContent` body (instructions + optional tools/handoffs/
+     * reasoning/model/description); the runtime threads it through
+     * `buildAdmissionManifest` + `Runner.admit` and registers the
+     * activated Agent via `registerConstructedAgent({ source:
+     * 'extension' })`. The returned dispose fn (also auto-pushed onto
+     * the extension's disposables list) unregisters the agent on
+     * extension deactivate.
+     *
+     * Returns `Promise<() => void>` — **you MUST `await` the call**
+     * before invoking the dispose function. Unlike sibling
+     * `registerTool` (sync), this is async because `Runner.admit` is
+     * declared async (FEATURE_101 admission contract — admission may
+     * consult disk for handoff-target staged-agent resolution).
+     *
+     * @example
+     * ```ts
+     * // CORRECT — await unwraps the Promise to a sync dispose
+     * export default async function activate(api: KodaXExtensionAPI) {
+     *   const dispose = await api.registerAgent('db-reviewer', {
+     *     instructions: 'You review DB migrations.',
+     *     description: 'DB migration reviewer',
+     *   });
+     *   // dispose() is now callable on demand; the runtime also auto-
+     *   // disposes via the extension's disposables list at deactivate.
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // WRONG — TypeScript catches this; .js / @ts-ignore consumers
+     * // hit a runtime TypeError because Promise is not a function.
+     * export default function activate(api: KodaXExtensionAPI) {
+     *   const dispose = api.registerAgent('x', { instructions: '...' });
+     *   dispose();  // TypeError: dispose is not a function
+     * }
+     * ```
+     *
+     * Throws on admission rejection (with the verdict reason) so the
+     * extension author sees the failure at activate time rather than
+     * having a silently-dropped registration. The throw also halts
+     * extension loading — the extension's other registrations roll back
+     * via `LoadedExtensionRecord.disposables` reverse-iterate.
+     */
+    registerAgent: (name: string, content: AgentContent) => Promise<() => void>;
+    on: <TEvent extends keyof ExtensionEventMap>(event: TEvent, handler: (payload: ExtensionEventMap[TEvent]) => Promise<void> | void) => () => void;
+    hook: <THook extends keyof ExtensionHookMap>(hook: THook, handler: ExtensionHookMap[THook]) => () => void;
+    logger: ExtensionLogger;
+    config: Readonly<Record<string, unknown>>;
+    runtime: ExtensionRuntimeController;
+    /** Extension-scoped key-value store that persists across sessions. */
+    persistence: KodaXExtensionStore;
+    /** Run a shell command with sandboxed environment (no API key leakage). */
+    exec: (command: string, options?: ExecOptions) => Promise<ExecResult>;
+    /** Send an HTTP webhook with timeout support. */
+    webhook: (url: string, payload: unknown, options?: WebhookOptions) => Promise<WebhookResult>;
+}
+type KodaXExtensionActivationResult = void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+interface KodaXExtensionModule {
+    default?: (api: KodaXExtensionAPI) => KodaXExtensionActivationResult;
+    activate?: (api: KodaXExtensionAPI) => KodaXExtensionActivationResult;
+}
+
+export { DEFAULT_HANDLER_TIMEOUT_MS as D, defaultPolicy as a1, exec as a2, webhook as a3, CapabilityDeniedError as c, ConstructionManifestError as e };
+export type { WebhookOptions as $, AgentArtifact as A, KodaXRetrievalItem as B, Capabilities as C, ExecOptions as E, KodaXRetrievalResult as F, KodaXRetrievalScope as G, KodaXRetrievalToolName as H, KodaXRetrievalTrust as I, LocalToolDefinition as J, KodaXExtensionAPI as K, LoadedExtensionDiagnostic as L, ModelProviderRegistration as M, RegisteredCommandDiagnostic as N, RegisteredHookDiagnostic as O, RegisteredToolDefinition as P, RegisteredToolDiagnostic as Q, RegisteredCapabilityProviderDiagnostic as R, ScriptSource as S, StagedHandle as T, TestResult as U, ToolContent as V, ToolDefinitionSource as W, ToolHandler as X, ToolHandlerSync as Y, ToolRegistrationOptions as Z, ToolRegistry as _, AgentContent as a, WebhookResult as a0, ArtifactStatus as b, ConstructionArtifact as d, ConstructionPolicy as f, ConstructionPolicyVerdict as g, ExecResult as h, ExtensionCommandContext as i, ExtensionCommandDefinition as j, ExtensionCommandInvocation as k, ExtensionCommandResult as l, ExtensionContributionSource as m, ExtensionEventMap as n, ExtensionFailureDiagnostic as o, ExtensionFailureStage as p, ExtensionHookMap as q, ExtensionLoadSource as r, ExtensionLogger as s, ExtensionRuntimeController as t, ExtensionRuntimeDiagnostics as u, ExtensionToolBeforeHookContext as v, KodaXExtensionActivationResult as w, KodaXExtensionModule as x, KodaXRetrievalArtifact as y, KodaXRetrievalFreshness as z };