@scotthuang/agent-knock-knock 0.13.2 → 0.13.4

package/dist/src/terminal-model-control.d.ts

@@ -0,0 +1,331 @@
+import type { ExecutorKind } from "./executors.js";
+import { type TerminalModelControlCapabilities, type TerminalModelControlPlan, type TerminalModelControlScope } from "./terminal-model-control-profile.js";
+import { type TerminalControlRef } from "./terminal-control-ref.js";
+export { CLAUDE_MODEL_CONTROL_AGENT_VERSION, CODEX_MODEL_CONTROL_AGENT_VERSION, TERMINAL_MODEL_CONTROL_PROFILE_IDS, isTerminalModelControlPlanForAgent, terminalModelControlPlanConforms, terminalModelControlProfileFor, terminalModelControlProfileForPlan, terminalModelControlProfiles, terminalModelControlSlashCompletionRows, type TerminalModelControlBehaviorProfile, type TerminalModelControlCapabilities, type TerminalModelControlPlan, type TerminalModelControlProfile, type TerminalModelControlScope } from "./terminal-model-control-profile.js";
+export { canonicalModelControlSubject, type CanonicalTerminalModelControlSubject, type TerminalModelControlSubjectInput } from "./terminal-model-control-subject.js";
+/** Caller-visible reasoning values. Native labels and menu positions stay private. */
+export declare const TERMINAL_MODEL_REASONING_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max", "ultra"];
+export type TerminalModelReasoningEffort = typeof TERMINAL_MODEL_REASONING_EFFORTS[number];
+type TerminalModelNativeEffort = TerminalModelReasoningEffort | "ultracode";
+export interface TerminalModelChoice {
+    readonly id: string;
+    readonly label: string;
+    readonly reasoningEfforts: readonly TerminalModelReasoningEffort[];
+}
+export interface TerminalModelValue {
+    readonly model: string;
+    readonly reasoningEffort?: TerminalModelReasoningEffort;
+}
+export interface TerminalModelCatalog {
+    readonly agent: ExecutorKind;
+    readonly agentVersion: string;
+    readonly behaviorProfile: TerminalModelControlPlan["behaviorProfile"];
+    readonly scope: TerminalModelControlScope;
+    readonly current: TerminalModelValue;
+    readonly models: readonly TerminalModelChoice[];
+    readonly catalogFingerprint: string;
+}
+export interface TerminalModelSwitchRequest {
+    readonly model: string;
+    readonly reasoningEffort: TerminalModelReasoningEffort;
+}
+export interface TerminalModelSwitchResult {
+    readonly outcome: "changed" | "already_effective" | "uncertain";
+    readonly scope: TerminalModelControlScope;
+    /** null means an irreversible native commit left persistence uncertain. */
+    readonly defaultsChanged: boolean | null;
+    readonly requested: TerminalModelSwitchRequest;
+    readonly effective?: TerminalModelValue;
+    readonly newSessionDefaults?: TerminalModelValue;
+    readonly doNotRetry: boolean;
+    readonly reason?: string;
+}
+export type TerminalModelControlResidualKind = "profiled_command_popup" | "bare_command" | "model_surface";
+export type TerminalModelControlResidualObservation = {
+    readonly state: "recoverable";
+    readonly kind: TerminalModelControlResidualKind;
+    readonly fingerprint: string;
+    readonly terminalControl: unknown;
+} | {
+    readonly state: "absent" | "unsafe";
+    readonly reason: string;
+    readonly terminalControl: unknown;
+};
+export interface TerminalModelControlRepairResult {
+    readonly outcome: "repaired" | "uncertain";
+    readonly terminalControl: unknown;
+    readonly terminalInputAttempted: boolean;
+    readonly composerPostcondition: "empty" | "unproven";
+    readonly doNotRetry: boolean;
+    readonly reason?: string;
+}
+/**
+ * One action-specific physical authority token for fresh Codex model control.
+ * The domain separator and exact profile keep this authority from being reused
+ * as Send or native-lifecycle authority even though all bind the same pane.
+ */
+export declare function terminalUserExplicitModelControlBindingToken(value: {
+    terminalId: string;
+    terminalControl: TerminalControlRef;
+    pid: number;
+    workspace: string;
+    processUuid: string;
+    processBirth: string;
+    agentVersion: string;
+    behaviorProfile: TerminalModelControlPlan["behaviorProfile"];
+}): string;
+/**
+ * Snapshot authority for adopting and cleaning one exact native `/model`
+ * residual. The residual kind and normalized surface digest prevent a token
+ * for one popup, pane generation, or bare Composer from authorizing another.
+ */
+export declare function terminalUserExplicitModelControlRepairBindingToken(value: {
+    terminalId: string;
+    terminalControl: TerminalControlRef;
+    pid: number;
+    workspace: string;
+    processUuid: string;
+    processBirth: string;
+    agentVersion: string;
+    behaviorProfile: TerminalModelControlPlan["behaviorProfile"];
+    residualKind: TerminalModelControlResidualKind;
+    residualFingerprint: string;
+}): string;
+/**
+ * Snapshot authority for continuing one exact native `/model` residual into
+ * the read-only catalog picker. This is deliberately domain-separated from
+ * cleanup-only repair: a repair offer never authorizes Enter, while this
+ * offer authorizes exactly one profiled slash-command dispatch.
+ */
+export declare function terminalUserExplicitModelControlResidualEntryBindingToken(value: {
+    terminalId: string;
+    terminalControl: TerminalControlRef;
+    pid: number;
+    workspace: string;
+    processUuid: string;
+    processBirth: string;
+    agentVersion: string;
+    behaviorProfile: TerminalModelControlPlan["behaviorProfile"];
+    residualKind: TerminalModelControlResidualKind;
+    residualFingerprint: string;
+}): string;
+/** Read-only catalog returned by the exact running Codex executable. */
+export interface CodexNativeModelCatalog {
+    readonly models: readonly TerminalModelChoice[];
+}
+export declare function parseCodexNativeModelCatalog(value: unknown): CodexNativeModelCatalog;
+interface ModelRow {
+    readonly id: string;
+    readonly label: string;
+    /** Zero-based position in the complete native menu, including excluded rows. */
+    readonly nativeIndex: number;
+    readonly selected: boolean;
+    readonly current: boolean;
+    /** Codex catalog visibility marker, not the persisted user default. */
+    readonly presetDefault: boolean;
+}
+interface EffortRow {
+    readonly effort?: TerminalModelReasoningEffort;
+    readonly kind: "effort" | "advanced" | "unsupported";
+    readonly selected: boolean;
+    readonly current: boolean;
+    /** Model preset default, not the persisted user reasoning setting. */
+    readonly presetDefault: boolean;
+}
+export type TerminalModelControlObservation = {
+    /** Exact 0.154 quick-auto menu, or cleanup-only Luna Reserve menu. */
+    readonly state: "codex_entry_model_picker";
+    readonly fingerprint: string;
+    readonly kind: "quick_auto" | "luna_reserve";
+    readonly selectedIndex: number;
+    readonly currentNativeIndex: number;
+    readonly allModelsNativeIndex?: number;
+} | {
+    readonly state: "codex_model_picker";
+    readonly fingerprint: string;
+    readonly rows: readonly ModelRow[];
+    readonly selectedIndex: number;
+    readonly currentNativeIndex: number;
+    readonly currentModel: string;
+} | {
+    readonly state: "codex_reasoning_picker";
+    readonly fingerprint: string;
+    readonly model: string;
+    readonly rows: readonly EffortRow[];
+    readonly selectedIndex: number;
+    readonly currentEffort?: TerminalModelReasoningEffort;
+    readonly presetDefaultEffort?: TerminalModelReasoningEffort;
+} | {
+    readonly state: "codex_advanced_reasoning_picker";
+    readonly fingerprint: string;
+    readonly rows: readonly EffortRow[];
+    readonly selectedIndex: number;
+    readonly currentEffort?: TerminalModelReasoningEffort;
+    readonly presetDefaultEffort?: TerminalModelReasoningEffort;
+} | {
+    readonly state: "codex_plan_scope_picker";
+    readonly fingerprint: string;
+    readonly rows: readonly string[];
+    readonly selectedIndex: number;
+} | {
+    readonly state: "claude_model_picker";
+    readonly fingerprint: string;
+    readonly rows: readonly ModelRow[];
+    readonly selectedIndex: number;
+    readonly currentNativeIndex: number;
+    readonly currentModel: string;
+    readonly currentEffort?: TerminalModelReasoningEffort;
+    readonly displayedEffort?: TerminalModelNativeEffort;
+} | {
+    readonly state: "none" | "ambiguous";
+    readonly fingerprint: string;
+    readonly reason: string;
+};
+export declare function isTerminalModelReasoningEffort(value: unknown): value is TerminalModelReasoningEffort;
+export declare function probeTerminalModelControl(agent: ExecutorKind, agentVersion: string | undefined): TerminalModelControlCapabilities;
+export declare function planTerminalModelControl(capabilities: TerminalModelControlCapabilities): TerminalModelControlPlan;
+/**
+ * Observe only complete, current model-control modal frames. Historical or
+ * partial picker text is never sufficient to authorize a key dispatch.
+ */
+export declare function observeTerminalModelControl(plan: TerminalModelControlPlan, screen: string): TerminalModelControlObservation;
+export declare function terminalModelCatalogFingerprint(input: {
+    agent: ExecutorKind;
+    agentVersion: string;
+    behaviorProfile: string;
+    scope: TerminalModelControlScope;
+    current: TerminalModelValue;
+    models: readonly TerminalModelChoice[];
+}): string;
+export declare function modelControlMoveKeys(currentIndex: number, targetIndex: number): readonly string[];
+/** Adapter-owned native navigation; never serialize these keys to a caller. */
+export declare function modelControlSelectModelKeys(observation: Extract<TerminalModelControlObservation, {
+    state: "codex_model_picker" | "claude_model_picker";
+}>, model: string): readonly string[];
+export declare function codexModelControlSelectEffortKeys(observation: Extract<TerminalModelControlObservation, {
+    state: "codex_reasoning_picker" | "codex_advanced_reasoning_picker";
+}>, effort: TerminalModelReasoningEffort): readonly string[];
+export declare function codexModelControlAllModesKeys(observation: Extract<TerminalModelControlObservation, {
+    state: "codex_plan_scope_picker";
+}>): readonly string[];
+export declare function claudeModelControlEffortKey(direction: "lower" | "higher"): readonly ["Left" | "Right"];
+export declare function claudeModelControlCommitKeys(plan: TerminalModelControlPlan): readonly ["s"];
+export interface TerminalModelControlCapture {
+    readonly terminalControl: unknown;
+    readonly screen: string;
+    readonly activityState: "awaiting_approval" | "working" | "idle" | "unknown";
+    readonly approvalBlocked: boolean;
+    readonly exactEmptyComposer: boolean;
+    /** Exact adapter-profiled slash selection is ready for Enter. */
+    readonly exactCommandReady: boolean;
+    /** Exact `/model` text, including the post-Escape bare cleanup state. */
+    readonly exactCommandComposer: boolean;
+    /** Exact command text in the ordinary Composer with its complete footer. */
+    readonly exactBareCommand?: boolean;
+    /** Digest of only the exact current `/model` Composer and popup region. */
+    readonly exactCommandFingerprint?: string;
+    /** A questionnaire, editor, viewer, or other non-model input owner exists. */
+    readonly inputBlocked?: boolean;
+}
+type ExactTerminalModelControlObservation = Exclude<TerminalModelControlObservation, {
+    state: "none" | "ambiguous";
+}>;
+/**
+ * One mutually exclusive semantic owner for the current model-control frame.
+ * Raw capture facts remain transport-private; policy code consumes this union
+ * so an exact profiled picker cannot simultaneously be treated as generic
+ * agent activity.
+ */
+export type TerminalModelControlSurface = {
+    readonly state: "idle_empty";
+} | {
+    readonly state: "command_popup";
+    readonly fingerprint?: string;
+} | {
+    readonly state: "bare_command";
+    readonly fingerprint?: string;
+} | {
+    /** Exact `/model` draft whose popup/bare shape is not profile-authorized. */
+    readonly state: "command_draft";
+    readonly fingerprint?: string;
+} | {
+    readonly state: "picker";
+    readonly pickerKind: "model" | "effort" | "scope";
+    readonly observation: ExactTerminalModelControlObservation;
+} | {
+    readonly state: "blocked";
+    readonly owner: "approval" | "input" | "agent";
+} | {
+    readonly state: "unknown";
+    readonly reason: string;
+};
+/** Pure capture classifier. It never authorizes input by itself. */
+export declare function classifyTerminalModelControlSurface(plan: TerminalModelControlPlan, capture: TerminalModelControlCapture): TerminalModelControlSurface;
+/** Runtime ports are implemented only by TerminalAgentBridge. */
+export interface TerminalModelControlPorts {
+    /** Revalidate current-snapshot and Store authority before each input call. */
+    beforeInput(): void | Promise<void>;
+    capture(input: {
+        terminalControl: unknown;
+        expectedComposer?: string;
+    }): Promise<TerminalModelControlCapture>;
+    sendText(terminalControl: unknown, text: "/model"): Promise<void>;
+    sendKeys(terminalControl: unknown, keys: readonly string[]): Promise<void>;
+    /** Exact running Codex 0.154.0 `debug models` output, already validated. */
+    loadCodexCatalog?(): Promise<CodexNativeModelCatalog>;
+    sleep(milliseconds: number): Promise<void>;
+}
+export interface TerminalModelOptionsExecution {
+    readonly terminalControl: unknown;
+    readonly catalog: TerminalModelCatalog;
+}
+/**
+ * Read-only, two-frame proof for one exact Codex `/model` residual or exact
+ * native model-control surface. It never treats arbitrary Composer text,
+ * transcript text, or an incomplete/unknown picker as recoverable authority.
+ */
+export declare function inspectTerminalModelControlResidual(input: {
+    plan: TerminalModelControlPlan;
+    terminalControl: unknown;
+    ports: TerminalModelControlPorts;
+}): Promise<TerminalModelControlResidualObservation>;
+/**
+ * Consume one current residual offer. Once any cleanup key is attempted, all
+ * failures are response-uncertain and callers must not retry automatically.
+ */
+export declare function repairTerminalModelControlResidual(input: {
+    plan: TerminalModelControlPlan;
+    terminalControl: unknown;
+    expectedResidualFingerprint: string;
+    ports: TerminalModelControlPorts;
+}): Promise<TerminalModelControlRepairResult>;
+/**
+ * Run one bounded, reversible native catalog inspection. It enters only the
+ * adapter-owned `/model` surface and always returns through exact Escape paths.
+ */
+export declare function discoverTerminalModelOptions(input: {
+    agent: ExecutorKind;
+    agentVersion: string;
+    plan: TerminalModelControlPlan;
+    terminalControl: unknown;
+    ports: TerminalModelControlPorts;
+    initialResidual?: Extract<TerminalModelControlResidualObservation, {
+        state: "recoverable";
+    }>;
+}): Promise<TerminalModelOptionsExecution>;
+/**
+ * Re-discover the exact catalog, consume one adapter-owned model path, then
+ * reopen the picker to prove the effective postcondition. No automatic retry
+ * is possible after the native commit key is attempted.
+ */
+export declare function switchTerminalModel(input: {
+    agent: ExecutorKind;
+    agentVersion: string;
+    plan: TerminalModelControlPlan;
+    terminalControl: unknown;
+    expectedCatalogFingerprint: string;
+    request: TerminalModelSwitchRequest;
+    ports: TerminalModelControlPorts;
+}): Promise<TerminalModelSwitchResult & {
+    readonly terminalControl: unknown;
+}>;