@scotthuang/agent-knock-knock 0.12.13 → 0.12.15

package/dist/src/terminal-agent-bridge.d.ts

@@ -8,6 +8,33 @@ export declare class TerminalInputNotStartedError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Text is already in the terminal composer, but this bridge invocation proved
+ * that it never called the Enter transport boundary.
+ *
+ * Callers may persist this as narrow recovery evidence. It says nothing about
+ * whether the draft remains exact or whether a later human action submitted
+ * it; those facts must be re-observed under the terminal lock.
+ */
+export declare class TerminalEnterDispatchNotAttemptedError extends Error {
+    readonly code = "AKK_TERMINAL_ENTER_DISPATCH_NOT_ATTEMPTED";
+    readonly stage = "enter_not_attempted";
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The caller's one-shot Enter reservation was invoked, so this recovery
+ * attempt is permanently consumed even though C-m was not proven dispatched.
+ */
+export declare class TerminalEnterDispatchReservedError extends Error {
+    readonly code = "AKK_TERMINAL_ENTER_DISPATCH_RESERVED";
+    readonly stage = "enter_reserved";
+    readonly doNotRetry = true;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 export type NativeInspectionSubmissionStage = "not_started" | "text_injected" | "enter_uncertain";
 /** Machine-readable reason for a closed native-inspection submission failure. */
 export type NativeInspectionSubmissionDiagnostic = "unsupported_profile" | "capability_unavailable" | "identity_unverified" | "composer_not_ready" | "viewport_too_narrow" | "viewport_unavailable" | "text_delivery_unproven" | "composer_viewport_truncated" | "composer_not_exact" | "composer_drift" | "evidence_unproven" | "enter_uncertain";
@@ -133,6 +160,14 @@ export interface TerminalSendOptions {
     beforeEnter?: (context: TerminalSendBoundaryContext) => void | Promise<void>;
     /** Require Codex's exact stable composer proof even for a single-line send. */
     requireExactComposerBeforeEnter?: boolean;
+    /**
+     * Retry-only authority from a preliminary exact-empty observation. After
+     * `beforeText` reserves the attempt, the bridge independently recaptures the
+     * same empty composer and then immediately makes its sole text-delivery call.
+     */
+    requireExactEmptyComposerAfterBeforeText?: {
+        preliminaryComposerDigest: string;
+    };
     /**
      * Awaited immediately after each irreversible transport boundary so the
      * caller can durably persist the exact proof level before continuing.
@@ -145,6 +180,41 @@ export interface TerminalSendResult {
     terminalControl: TerminalControlRef;
     multiline: boolean;
 }
+interface TerminalCodexStableComposerObservationBase {
+    terminalControl: TerminalControlRef;
+    digest: string;
+    stableCaptures: number;
+}
+type TerminalCodexObservedComposerState = "exact_draft" | "exact_empty" | "different_draft" | "working" | "approval_or_modal";
+/** Closed, content-redacting observation of the current Codex composer. */
+export type TerminalCodexComposerObservation = {
+    [State in TerminalCodexObservedComposerState]: TerminalCodexStableComposerObservationBase & {
+        state: State;
+    };
+}[TerminalCodexObservedComposerState] | {
+    state: "identity_drift" | "unavailable";
+    reason: string;
+};
+export interface TerminalCodexDraftSubmissionContext {
+    terminalControl: TerminalControlRef;
+    text: string;
+    composerDigest: string;
+}
+export interface TerminalCodexDraftSubmissionOptions {
+    runtime?: TerminalRuntimeIdentity;
+    /**
+     * Persist the caller's one-shot Enter reservation after the preliminary
+     * stable proof. The bridge then independently recaptures the exact draft
+     * before its sole C-m transport call. Invoking this hook consumes the attempt
+     * even when the hook or any later step fails.
+     */
+    beforeEnterReservation: (context: TerminalCodexDraftSubmissionContext) => void | Promise<void>;
+}
+export interface TerminalCodexDraftSubmissionResult {
+    stage: "enter_dispatched";
+    terminalControl: TerminalControlRef;
+    enterCount: 1;
+}
 export type TerminalNativeInspectionMaterializationKind = "exact_slash_composer" | "exact_slash_popup";
 export interface TerminalNativeInspectionMaterializationEvidence {
     kind: TerminalNativeInspectionMaterializationKind;
@@ -273,6 +343,15 @@ export declare class TerminalAgentBridge {
         runtime?: TerminalRuntimeIdentity;
     }): Promise<TerminalBridgeStatus>;
     send(agent: ExecutorKind, terminalControl: TerminalControlRef, text: string, options?: TerminalSendOptions): Promise<TerminalSendResult>;
+    /** Observe only the current, live Codex composer without exposing its text. */
+    observeCodexComposer(terminalControl: TerminalControlRef, expectedText: string, options?: {
+        runtime?: TerminalRuntimeIdentity;
+    }): Promise<TerminalCodexComposerObservation>;
+    /**
+     * Submit one already-present exact Codex draft. This primitive never writes
+     * text, clears the composer, or emits C-c, and contains exactly one C-m call.
+     */
+    submitExactCodexDraft(terminalControl: TerminalControlRef, expectedText: string, options: TerminalCodexDraftSubmissionOptions): Promise<TerminalCodexDraftSubmissionResult>;
     private verifyExactComposerBeforeEnter;
     /**
      * Submit one closed, adapter-owned native inspection command.
@@ -308,6 +387,8 @@ export declare class TerminalAgentBridge {
     private settleNativeInspectionComposer;
     private revalidateNativeInspectionComposer;
     private settleCodexMultilineComposer;
+    private settleCodexComposerObservation;
+    private captureCodexComposerSnapshot;
     /**
      * Prove that the exact managed draft is still present after Enter dispatch.
      * Two identity-fenced captures are required so transient repaint state never
@@ -383,3 +464,4 @@ export declare function terminalApprovalFingerprint(agent: ExecutorKind, termina
     screen?: string;
     runtime?: TerminalRuntimeIdentity;
 }): string | undefined;
+export {};