@scotthuang/agent-knock-knock 0.13.7 → 0.13.8

package/dist/src/codex-async-question-adapter.d.ts

@@ -0,0 +1,156 @@
+/**
+ * This adapter is deliberately version-bound. Later Codex releases gained
+ * different durable answer identities; callers must not silently reuse this
+ * TUI contract for an unverified release.
+ */
+export declare const CODEX_ASYNC_QUESTION_PROFILES: Readonly<Record<string, string>>;
+export declare const CODEX_ASYNC_QUESTION_LIMITS: Readonly<{
+    maxRecords: 4096;
+    maxArgumentsBytes: number;
+    maxQuestions: 16;
+    maxOptions: 32;
+    maxTitleCharacters: 4096;
+    maxOptionCharacters: 512;
+    maxIdentifierCharacters: 256;
+    maxScreenCharacters: number;
+    maxScreenLines: 160;
+}>;
+export type CodexAsyncQuestionSurfaceState = "absent" | "collapsed" | "expanded" | "ambiguous";
+export type CodexAsyncQuestionOpenBinding = "shift_left" | "alt_up";
+export type CodexAsyncQuestionDeliveryMode = "steer_current_turn" | "queue_next_turn";
+export interface CodexAsyncQuestionDurableQuestion {
+    readonly title: string;
+    readonly options?: readonly string[];
+}
+/**
+ * Owner-private durable evidence supplied by an exact rollout reader. This
+ * module never opens rollout files and never returns a raw JSONL record.
+ */
+export interface CodexAsyncQuestionDurableEvidence {
+    readonly itemId: string;
+    readonly turnId: string;
+    readonly questions: readonly CodexAsyncQuestionDurableQuestion[];
+    /** Zero-based index within `questions`, when the caller can prove it. */
+    readonly currentIndex?: number;
+    /** Number still retained by the native client, when independently known. */
+    readonly remainingCount?: number;
+}
+export interface CodexAsyncQuestionSemanticOption {
+    readonly option_id: string;
+    readonly label: string;
+    readonly kind: "suggested" | "free_text_entry";
+}
+export interface CodexAsyncQuestionSemanticQuestion {
+    readonly question_id: string;
+    readonly prompt: string;
+    readonly response_kind: "single_select" | "free_text";
+    readonly required: true;
+    readonly options?: readonly CodexAsyncQuestionSemanticOption[];
+}
+export interface CodexAsyncQuestionMatch {
+    readonly source_id: string;
+    readonly source_question_index: number;
+    readonly question: CodexAsyncQuestionSemanticQuestion;
+    readonly selected_option_id?: string;
+}
+export interface CodexAsyncQuestionPromptEvidence {
+    readonly profile: string;
+    /** Exact rendered region digest for dispatch-time recapture. */
+    readonly exact_region_sha256: string;
+    /** Stable semantic digest, independent of cursor and countdown redraws. */
+    readonly semantic_sha256: string;
+}
+/**
+ * Owner-private plan. It intentionally describes native intent rather than
+ * exposing terminal keys or menu indexes to a public interaction projection.
+ */
+export type CodexAsyncQuestionOwnerPrivateActionPlan = {
+    readonly kind: "open_async_question_editor";
+    readonly binding: CodexAsyncQuestionOpenBinding;
+    readonly expected_pending_count: number;
+    readonly expected_region_sha256: string;
+} | {
+    readonly kind: "answer_async_question";
+    readonly question_id: string;
+    readonly choices: readonly {
+        readonly option_id: string;
+        readonly native_ordinal: number;
+        readonly intent: "submit_choice" | "open_free_text";
+    }[];
+    readonly free_text: {
+        readonly intent: "enter_free_text" | "select_other_then_enter_text";
+        readonly native_ordinal?: number;
+        readonly max_characters: number;
+    };
+    readonly delivery: Readonly<Record<CodexAsyncQuestionDeliveryMode, "submit" | "queue">>;
+    readonly expected_region_sha256: string;
+};
+export type CodexAsyncQuestionInspection = {
+    readonly state: "absent";
+    readonly reason: "no_async_question_surface";
+} | {
+    readonly state: "ambiguous";
+    readonly reason: "unsupported_version" | "capture_limit_exceeded" | "unsafe_control" | "partial_or_unknown_surface" | "invalid_durable_evidence" | "pending_count_mismatch" | "question_match_missing" | "question_match_ambiguous" | "clipped_question" | "unsupported_keymap" | "existing_answer_draft";
+    readonly profile?: string;
+} | {
+    readonly state: "collapsed";
+    readonly profile: string;
+    readonly pending_count: number;
+    readonly countdown_seconds?: number;
+    /** Present only when durable order and remaining count prove it. */
+    readonly match?: CodexAsyncQuestionMatch;
+    readonly prompt_evidence: CodexAsyncQuestionPromptEvidence;
+    readonly owner_private_action_plan: CodexAsyncQuestionOwnerPrivateActionPlan;
+} | {
+    readonly state: "expanded";
+    readonly profile: string;
+    readonly current_step: number;
+    readonly total_steps: number;
+    readonly match: CodexAsyncQuestionMatch;
+    readonly prompt_evidence: CodexAsyncQuestionPromptEvidence;
+    readonly owner_private_action_plan: CodexAsyncQuestionOwnerPrivateActionPlan;
+};
+export type CodexAsyncQuestionRecordCandidates = {
+    readonly status: "unsupported_version";
+} | {
+    readonly status: "none";
+} | {
+    readonly status: "ambiguous";
+    readonly reason: "record_limit_exceeded" | "invalid_arguments" | "invalid_identity" | "duplicate_item_id";
+} | {
+    readonly status: "candidates";
+    readonly evidence: readonly CodexAsyncQuestionDurableEvidence[];
+};
+export declare function codexAsyncQuestionProfile(version: string): string | undefined;
+/**
+ * Parse already-bounded, already-read rollout records. `function_call_output`
+ * with `{accepted:true}` is deliberately ignored: request_user_input_async
+ * returns immediately, so that output does not mean the user answered.
+ */
+export declare function parseCodexAsyncQuestionRecordCandidates(input: {
+    readonly version: string;
+    readonly records: readonly unknown[];
+    readonly fallbackTurnId?: string;
+}): CodexAsyncQuestionRecordCandidates;
+export declare function inspectCodexAsyncQuestion(input: {
+    readonly version: string;
+    readonly screen: string;
+    readonly evidence?: readonly CodexAsyncQuestionDurableEvidence[];
+}): CodexAsyncQuestionInspection;
+/**
+ * Owner-private pre-submit proof after one text injection. The public observer
+ * continues to reject drafts. Text must be wholly visible on one row: terminal
+ * wrapping cannot prove the original buffer's whitespace or hidden contents.
+ */
+export declare function verifyCodexAsyncQuestionInjectedText(input: {
+    readonly version: string;
+    readonly screen: string;
+    readonly evidence: readonly CodexAsyncQuestionDurableEvidence[];
+    readonly expectedQuestionId: string;
+    readonly expectedText: string;
+}): boolean;
+/** Withdraw-only observation; this never grants main-Composer input authority. */
+export declare function codexAsyncQuestionMainComposerVisible(input: {
+    readonly version: string;
+    readonly screen: string;
+}): boolean;