@sayknow-cli/coding-agent 0.4.2 → 0.4.4

package/dist/types/task/types.d.ts

@@ -0,0 +1,516 @@
+import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import type { Usage } from "@sayknow-cli/ai";
+import * as z from "zod/v4";
+import type { TaskResultReceipt } from "./receipt";
+import type { SpawnRoiReconciliation } from "./roi-reconciliation";
+import { type TaskSimpleMode } from "./simple-mode";
+import type { SpawnPlanReceipt } from "./spawn-gate";
+import type { NestedRepoPatch } from "./worktree";
+/** Source of an agent definition */
+export type AgentSource = "bundled" | "user" | "project";
+export type ForkContextPolicy = "forbidden" | "allowed";
+export type ForkContextMode = "none" | "receipt" | "last-turn" | "bounded" | "full";
+/** Maximum output bytes per agent */
+export declare const MAX_OUTPUT_BYTES: number;
+/** Maximum output lines per agent */
+export declare const MAX_OUTPUT_LINES: number;
+/** EventBus channel for raw subagent events */
+export declare const TASK_SUBAGENT_EVENT_CHANNEL = "task:subagent:event";
+/** EventBus channel for aggregated subagent progress */
+export declare const TASK_SUBAGENT_PROGRESS_CHANNEL = "task:subagent:progress";
+/** EventBus channel for subagent lifecycle (start/end) */
+export declare const TASK_SUBAGENT_LIFECYCLE_CHANNEL = "task:subagent:lifecycle";
+/** Payload emitted on TASK_SUBAGENT_PROGRESS_CHANNEL */
+export interface SubagentProgressPayload {
+    index: number;
+    agent: string;
+    agentSource: AgentSource;
+    task: string;
+    assignment?: string;
+    progress: AgentProgress;
+    sessionFile?: string;
+}
+/** Payload emitted on TASK_SUBAGENT_LIFECYCLE_CHANNEL */
+export interface SubagentLifecyclePayload {
+    id: string;
+    agent: string;
+    agentSource: AgentSource;
+    description?: string;
+    status: "started" | "completed" | "failed" | "aborted" | "paused";
+    sessionFile?: string;
+    index: number;
+}
+/** Single task item for parallel execution (default shape with context enabled). */
+export declare const taskItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    assignment: z.ZodString;
+    inheritContext: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        receipt: "receipt";
+        "last-turn": "last-turn";
+        bounded: "bounded";
+        full: "full";
+    }>>;
+}, z.core.$strip>;
+export type TaskItem = z.infer<typeof taskItemSchema>;
+export declare const taskSchema: z.ZodObject<{
+    agent: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            receipt: "receipt";
+            "last-turn": "last-turn";
+            bounded: "bounded";
+            full: "full";
+        }>>;
+    }, z.core.$strip>>;
+    spawnPlan: z.ZodOptional<z.ZodObject<{
+        whyParallel: z.ZodString;
+        whyNotLocal: z.ZodString;
+        independence: z.ZodString;
+        expectedReceiptShape: z.ZodString;
+        maxInlineTokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const taskSchemaNoIsolation: z.ZodObject<{
+    agent: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            receipt: "receipt";
+            "last-turn": "last-turn";
+            bounded: "bounded";
+            full: "full";
+        }>>;
+    }, z.core.$strip>>;
+    spawnPlan: z.ZodOptional<z.ZodObject<{
+        whyParallel: z.ZodString;
+        whyNotLocal: z.ZodString;
+        independence: z.ZodString;
+        expectedReceiptShape: z.ZodString;
+        maxInlineTokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
+    agent: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            receipt: "receipt";
+            "last-turn": "last-turn";
+            bounded: "bounded";
+            full: "full";
+        }>>;
+    }, z.core.$strip>>;
+    spawnPlan: z.ZodOptional<z.ZodObject<{
+        whyParallel: z.ZodString;
+        whyNotLocal: z.ZodString;
+        independence: z.ZodString;
+        expectedReceiptShape: z.ZodString;
+        maxInlineTokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    agent: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            receipt: "receipt";
+            "last-turn": "last-turn";
+            bounded: "bounded";
+            full: "full";
+        }>>;
+    }, z.core.$strip>>;
+    spawnPlan: z.ZodOptional<z.ZodObject<{
+        whyParallel: z.ZodString;
+        whyNotLocal: z.ZodString;
+        independence: z.ZodString;
+        expectedReceiptShape: z.ZodString;
+        maxInlineTokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    agent: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            receipt: "receipt";
+            "last-turn": "last-turn";
+            bounded: "bounded";
+            full: "full";
+        }>>;
+    }, z.core.$strip>>;
+    spawnPlan: z.ZodOptional<z.ZodObject<{
+        whyParallel: z.ZodString;
+        whyNotLocal: z.ZodString;
+        independence: z.ZodString;
+        expectedReceiptShape: z.ZodString;
+        maxInlineTokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    agent: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            receipt: "receipt";
+            "last-turn": "last-turn";
+            bounded: "bounded";
+            full: "full";
+        }>>;
+    }, z.core.$strip>>;
+    spawnPlan: z.ZodOptional<z.ZodObject<{
+        whyParallel: z.ZodString;
+        whyNotLocal: z.ZodString;
+        independence: z.ZodString;
+        expectedReceiptShape: z.ZodString;
+        maxInlineTokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    agent: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            receipt: "receipt";
+            "last-turn": "last-turn";
+            bounded: "bounded";
+            full: "full";
+        }>>;
+    }, z.core.$strip>>;
+    spawnPlan: z.ZodOptional<z.ZodObject<{
+        whyParallel: z.ZodString;
+        whyNotLocal: z.ZodString;
+        independence: z.ZodString;
+        expectedReceiptShape: z.ZodString;
+        maxInlineTokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    agent: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            receipt: "receipt";
+            "last-turn": "last-turn";
+            bounded: "bounded";
+            full: "full";
+        }>>;
+    }, z.core.$strip>>;
+    spawnPlan: z.ZodOptional<z.ZodObject<{
+        whyParallel: z.ZodString;
+        whyNotLocal: z.ZodString;
+        independence: z.ZodString;
+        expectedReceiptShape: z.ZodString;
+        maxInlineTokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>];
+type DynamicTaskSchema = (typeof ALL_TASK_SCHEMAS)[number];
+export type TaskSchema = typeof taskSchema;
+/** Active task tool parameter schema for the current simple-mode / isolation flags */
+export type TaskToolSchemaInstance = DynamicTaskSchema;
+export declare function getTaskSchema(options: {
+    isolationEnabled: boolean;
+    simpleMode: TaskSimpleMode;
+}): DynamicTaskSchema;
+export interface TaskParams {
+    agent: string;
+    context?: string;
+    schema?: string;
+    spawnPlan?: SpawnPlanReceipt;
+    tasks: TaskItem[];
+    isolated?: boolean;
+}
+/** A code review finding reported by the reviewer agent */
+export interface ReviewFinding {
+    title: string;
+    body: string;
+    priority: number;
+    confidence: number;
+    file_path: string;
+    line_start: number;
+    line_end: number;
+}
+/** Review summary submitted by the reviewer agent */
+export interface ReviewSummary {
+    overall_correctness: "correct" | "incorrect";
+    explanation: string;
+    confidence: number;
+}
+/** Structured review data extracted from reviewer agent */
+export interface ReviewData {
+    findings: ReviewFinding[];
+    summary?: ReviewSummary;
+}
+/** Agent definition (bundled or discovered) */
+export interface AgentDefinition {
+    name: string;
+    description: string;
+    systemPrompt: string;
+    tools?: string[];
+    spawns?: string[] | "*";
+    model?: string[];
+    thinkingLevel?: ThinkingLevel;
+    output?: unknown;
+    blocking?: boolean;
+    autoloadSkills?: string[];
+    hide?: boolean;
+    forkContext?: ForkContextPolicy;
+    bashAllowedPrefixes?: string[];
+    source: AgentSource;
+    filePath?: string;
+}
+export interface ModelSubstitutionWarning {
+    requested: string;
+    effective: string;
+    reason: "auth_unavailable" | "assistant_model_mismatch";
+}
+/** Progress tracking for a single agent */
+export interface AgentProgress {
+    index: number;
+    id: string;
+    agent: string;
+    agentSource: AgentSource;
+    status: "pending" | "running" | "completed" | "failed" | "aborted" | "paused";
+    task: string;
+    assignment?: string;
+    description?: string;
+    lastIntent?: string;
+    currentTool?: string;
+    currentToolArgs?: string;
+    currentToolStartMs?: number;
+    recentTools: Array<{
+        tool: string;
+        args: string;
+        endMs: number;
+    }>;
+    recentOutput: string[];
+    toolCount: number;
+    /** Cumulative input + output + cacheWrite tokens across all turns. Excludes cacheRead (re-reads cached context every turn, making cumulative sum misleading). */
+    tokens: number;
+    /**
+     * Current per-turn context size: latest assistant message's `usage.totalTokens`.
+     * This is the number to compare against `contextWindow` — what compaction
+     * decides on, what the user typically reads as "how full is the context".
+     * Distinct from `tokens`, which is a lifetime billing-volume counter.
+     */
+    contextTokens?: number;
+    /** Model's context window in tokens, when known. Lets the UI render `<curr>/<window>` gauges. */
+    contextWindow?: number;
+    /** Cumulative billing cost in USD, accumulated incrementally from message_end events. */
+    cost: number;
+    durationMs: number;
+    modelOverride?: string | string[];
+    modelSubstitutionWarning?: ModelSubstitutionWarning;
+    /** Data extracted by registered subprocess tool handlers (keyed by tool name) */
+    extractedToolData?: Record<string, unknown[]>;
+    /**
+     * Auto-retry state when the subagent is sleeping between provider retries
+     * (e.g. 429 rate-limit with retry-after). Cleared when the retry resolves
+     * or fails. Surfacing this to the parent prevents the task tool from
+     * looking indefinitely "in progress" when a child is actually blocked on
+     * provider quota.
+     */
+    retryState?: {
+        attempt: number;
+        maxAttempts: number;
+        unbounded?: boolean;
+        delayMs: number;
+        errorMessage: string;
+        startedAtMs: number;
+    };
+    /**
+     * Terminal retry failure surfaced once the subagent gave up retrying
+     * (e.g. retry-after exceeded the cap, or all attempts exhausted). Carries
+     * the final error so the parent UI can render "blocked: rate-limited"
+     * instead of waiting for a status that never arrives.
+     */
+    retryFailure?: {
+        attempt: number;
+        errorMessage: string;
+    };
+    /**
+     * Snapshot of the most recent `task` tool call's in-flight `TaskToolDetails`,
+     * captured from `tool_execution_update`. Lets the parent UI surface live
+     * nested-subagent progress while this agent is still inside its own `task`
+     * call. Cleared when the call ends — finalized data lives in
+     * `extractedToolData.task` after that.
+     */
+    inflightTaskDetails?: TaskToolDetails;
+}
+/** Result from a single agent execution */
+export interface SingleResult {
+    index: number;
+    id: string;
+    agent: string;
+    agentSource: AgentSource;
+    task: string;
+    assignment?: string;
+    description?: string;
+    lastIntent?: string;
+    exitCode: number;
+    output: string;
+    stderr: string;
+    truncated: boolean;
+    durationMs: number;
+    /** Cumulative input + output + cacheWrite tokens across all turns. Excludes cacheRead (re-reads cached context every turn, making cumulative sum misleading). */
+    tokens: number;
+    /** Latest per-turn context size at task completion. See `AgentProgress.contextTokens`. */
+    contextTokens?: number;
+    /** Model's context window in tokens, when known. */
+    contextWindow?: number;
+    modelOverride?: string | string[];
+    modelSubstitutionWarning?: ModelSubstitutionWarning;
+    error?: string;
+    aborted?: boolean;
+    abortReason?: string;
+    paused?: boolean;
+    /** Aggregated usage from the subprocess, accumulated incrementally from message_end events. */
+    usage?: Usage;
+    /** True only when every usage-contributing assistant supplied a complete, non-negative raw cost breakdown. */
+    usageCostBreakdownComplete?: true;
+    /** Output path for the task result */
+    outputPath?: string;
+    /** Patch path for isolated worktree output */
+    patchPath?: string;
+    /** Branch name for isolated branch-mode output */
+    branchName?: string;
+    /** Nested repo patches to apply after parent merge */
+    nestedPatches?: NestedRepoPatch[];
+    /** Whether isolated execution produced a non-empty root or nested patch. */
+    producedChanges?: boolean;
+    /** Data extracted by registered subprocess tool handlers (keyed by tool name) */
+    extractedToolData?: Record<string, unknown[]>;
+    /**
+     * Terminal retry failure, when the subagent exited because the auto-retry
+     * loop gave up (retry-after exceeded the cap, or all attempts exhausted).
+     * Lets the parent task tool surface a "blocked: rate-limited" outcome
+     * instead of a generic failure.
+     */
+    retryFailure?: {
+        attempt: number;
+        errorMessage: string;
+    };
+    /** Output metadata for agent:// URL integration */
+    outputMeta?: {
+        lineCount: number;
+        charCount: number;
+        byteSize?: number;
+        sha256?: string;
+    };
+    /** Fork-context seed accounting for this subagent, when inherited parent context was cloned. */
+    forkContext?: {
+        mode: ForkContextMode;
+        clonedTokens: number;
+    };
+    /**
+     * Advisory fork-context mode recommendation for this task (logged only;
+     * never changes the actual mode selection).
+     */
+    forkContextAdvisory?: {
+        recommendedMode: ForkContextMode;
+        reasons: string[];
+    };
+}
+/** True only for complete, factual five-bucket cost accounting. */
+export declare function hasCompleteUsageCostBreakdown(usage: unknown): boolean;
+/** True only when every usage-contributing result has explicit, complete cost provenance. */
+export declare function hasCompleteAggregateUsageCostBreakdown(results: readonly Pick<SingleResult, "usage" | "usageCostBreakdownComplete">[]): boolean;
+/** Tool details for TUI rendering */
+export interface TaskToolDetails {
+    projectAgentsDir: string | null;
+    results: TaskResultReceipt[];
+    totalDurationMs: number;
+    /** Aggregated usage across all subagents. */
+    usage?: Usage;
+    /** True only when every usage-contributing subagent supplied a complete raw cost breakdown. */
+    usageCostBreakdownComplete?: true;
+    /** Aggregate cloned tokens copied into fork-context seeds across subagents. */
+    forkContextClonedTokens?: number;
+    roiSummary?: {
+        childCount: number;
+        totalTokens: number;
+        totalCostTotal?: number;
+        totalClonedTokens?: number;
+        /** Advisory ids for terminal children that spent tokens without detectable output/review/changes. */
+        lowRoiChildIds: string[];
+    };
+    roiReconciliation?: SpawnRoiReconciliation;
+    progress?: AgentProgress[];
+    async?: {
+        state: "running" | "paused" | "queued" | "completed" | "failed";
+        jobId: string;
+        type: "task";
+    };
+}
+/**
+ * Persisted per-turn / per-subagent token record (Phase 0 instrumentation).
+ *
+ * Additive: this does not alter any existing task result shape. It is the
+ * durable, model-independent unit the deterministic orchestration-token
+ * benchmark (`@sayknow-cli/orchestration-token-benchmark`) consumes to measure
+ * token efficiency without any live-model calls.
+ */
+export interface TaskTokenLog {
+    /** Subagent id, or "root" for the orchestrator's own turn. */
+    subagentId: string;
+    /** Agent name for attribution, when known. */
+    agent?: string;
+    /** 1-based turn index within the subagent's session. */
+    turn: number;
+    /** ISO-8601 timestamp the turn completed. */
+    at: string;
+    /** Cost-bearing input tokens (excludes cache reads), mirrors `Usage.input`. */
+    input: number;
+    /** Total output tokens for the turn, mirrors `Usage.output`. */
+    output: number;
+    /** Tokens read from the prompt cache, mirrors `Usage.cacheRead`. */
+    cacheRead: number;
+    /** Tokens written to the prompt cache, mirrors `Usage.cacheWrite`. */
+    cacheWrite: number;
+    /** input + output + cacheRead + cacheWrite. */
+    totalTokens: number;
+    /** Latest per-turn context-window occupancy, when known. */
+    contextTokens?: number;
+    /** Estimated USD cost for the turn, when known. */
+    cost?: number;
+    /** Model id used for the turn, when known. */
+    model?: string;
+}
+/**
+ * Deterministic aggregate token metrics computed from a set of `TaskTokenLog`
+ * entries. The cache-hit-rate field is the primary prompt-cache signal called
+ * out by the prefix-stability invariant (see the approved plan).
+ */
+export interface TaskTokenMetrics {
+    /** Number of token-log entries aggregated. */
+    turns: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    /** cacheRead / (input + cacheRead); 0 when there is no input-class traffic. */
+    cacheHitRate: number;
+}
+export {};

package/dist/types/task/worktree.d.ts

@@ -0,0 +1,94 @@
+import * as natives from "@sayknow-cli/natives";
+declare const IsoBackendKind: typeof natives.IsoBackendKind;
+type IsoBackendKind = natives.IsoBackendKind;
+/** Baseline state for a single git repository. */
+export interface RepoBaseline {
+    repoRoot: string;
+    headCommit: string;
+    staged: string;
+    unstaged: string;
+    untracked: string[];
+    untrackedPatch: string;
+}
+/** Baseline state for the project, including any nested git repos. */
+export interface WorktreeBaseline {
+    root: RepoBaseline;
+    /** Nested git repos (path relative to root.repoRoot). */
+    nested: Array<{
+        relativePath: string;
+        baseline: RepoBaseline;
+    }>;
+}
+export declare function getRepoRoot(cwd: string): Promise<string>;
+export declare function getGitNoIndexNullPath(): string;
+export declare function captureBaseline(repoRoot: string): Promise<WorktreeBaseline>;
+export interface NestedRepoPatch {
+    relativePath: string;
+    patch: string;
+}
+export interface DeltaPatchResult {
+    rootPatch: string;
+    nestedPatches: NestedRepoPatch[];
+}
+export declare function captureDeltaPatch(isolationDir: string, baseline: WorktreeBaseline): Promise<DeltaPatchResult>;
+/**
+ * Apply nested repo patches directly to their working directories after parent merge.
+ * @param commitMessage Optional async function to generate a commit message from the combined diff.
+ *                      If omitted or returns null, falls back to a generic message.
+ */
+export declare function applyNestedPatches(repoRoot: string, patches: NestedRepoPatch[], commitMessage?: (diff: string) => Promise<string | null>): Promise<void>;
+/**
+ * User-facing isolation mode names exposed by the `task.isolation.mode`
+ * setting. Mapped to a backend-kind hint via {@link parseIsolationMode};
+ * the PAL's `iso_resolve` then falls back through the kind order
+ * whenever the hint isn't available on the current host.
+ */
+export type TaskIsolationMode = "none" | "auto" | "apfs" | "btrfs" | "zfs" | "reflink" | "overlayfs" | "projfs" | "block-clone" | "rcopy" | "worktree" | "fuse-overlay" | "fuse-projfs";
+/**
+ * Translate a {@link TaskIsolationMode} string to an [`IsoBackendKind`]
+ * the PAL can act on. `"none"` returns `null` (caller skips isolation
+ * entirely); `"auto"` returns `undefined` (no hint — let the resolver
+ * pick). Anything else returns the matching kind.
+ */
+export declare function parseIsolationMode(mode: TaskIsolationMode): IsoBackendKind | undefined;
+export interface IsolationHandle {
+    /** Merged view materialised by the backend; pass this to the task. */
+    mergedDir: string;
+    /** Backend the PAL actually used. */
+    backend: IsoBackendKind;
+    /** True when the resolver downgraded from `preferred` to `backend`. */
+    fellBack: boolean;
+    /** Optional reason associated with `fellBack`. */
+    fallbackReason: string | null;
+}
+export declare function ensureIsolation(baseCwd: string, id: string, preferred?: IsoBackendKind): Promise<IsolationHandle>;
+/** Tear down a handle returned by {@link ensureIsolation}. */
+export declare function cleanupIsolation(handle: IsolationHandle): Promise<void>;
+export interface CommitToBranchResult {
+    branchName?: string;
+    nestedPatches: NestedRepoPatch[];
+}
+/**
+ * Commit task-only changes to a new branch.
+ * Only root repo changes go on the branch. Nested repo patches are returned
+ * separately since the parent git can't track files inside gitlinks.
+ */
+export declare function commitToBranch(isolationDir: string, baseline: WorktreeBaseline, taskId: string, description: string | undefined, commitMessage?: (diff: string) => Promise<string | null>): Promise<CommitToBranchResult | null>;
+export interface MergeBranchResult {
+    merged: string[];
+    failed: string[];
+    conflict?: string;
+}
+/**
+ * Cherry-pick task branch commits sequentially onto HEAD.
+ * Each branch has a single commit that gets replayed cleanly.
+ * Stops on first conflict and reports which branches succeeded.
+ */
+export declare function mergeTaskBranches(repoRoot: string, branches: Array<{
+    branchName: string;
+    taskId: string;
+    description?: string;
+}>): Promise<MergeBranchResult>;
+/** Clean up temporary task branches. */
+export declare function cleanupTaskBranches(repoRoot: string, branches: string[]): Promise<void>;
+export {};

package/dist/types/thinking-metadata.d.ts

@@ -0,0 +1,16 @@
+export type ThinkingLevelValue = "inherit" | "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * Metadata used to render thinking selector values in the coding-agent UI.
+ *
+ * This module is intentionally provider/native-free so schema generation can
+ * import settings metadata before native addons have been built in CI.
+ */
+export interface ThinkingLevelMetadata {
+    value: ThinkingLevelValue;
+    label: string;
+    description: string;
+}
+/**
+ * Returns display metadata for a thinking selector.
+ */
+export declare function getThinkingLevelMetadata(level: ThinkingLevelValue): ThinkingLevelMetadata;

package/dist/types/thinking.d.ts

@@ -0,0 +1,29 @@
+import { type ResolvedThinkingLevel, ThinkingLevel } from "@sayknow-cli/agent-core/thinking";
+import { type Effort } from "@sayknow-cli/ai/model-thinking";
+import type { Model } from "@sayknow-cli/ai/types";
+export { getThinkingLevelMetadata, type ThinkingLevelMetadata } from "./thinking-metadata";
+/**
+ * Parses a provider-facing effort value.
+ */
+export declare function parseEffort(value: string | null | undefined): Effort | undefined;
+/**
+ * Parses an agent-local thinking selector.
+ */
+export declare function parseThinkingLevel(value: string | null | undefined): ThinkingLevel | undefined;
+/**
+ * Converts an agent-local selector into the effort sent to providers.
+ */
+export declare function toReasoningEffort(level: ThinkingLevel | undefined): Effort | undefined;
+/**
+ * Resolves a selector against the current model while preserving explicit "off".
+ */
+export declare function resolveThinkingLevelForModel(model: Model | undefined, level: ThinkingLevel | undefined): ResolvedThinkingLevel | undefined;
+export declare function clampExplicitThinkingLevelForModel(model: Model | undefined, level: ThinkingLevel | undefined): ThinkingLevel | undefined;
+export interface SelectorThinkingSuffix {
+    selector: string;
+    thinkingLevel?: ThinkingLevel;
+    invalidSuffix?: string;
+}
+/** Split the final selector suffix once, preserving colons in model IDs. */
+export declare function splitSelectorThinkingSuffix(selector: string): SelectorThinkingSuffix;
+export declare function formatClampedModelSelector(selector: string, model: Model | undefined): string;