@scotthuang/agent-knock-knock 0.13.2 → 0.13.4

package/dist/src/terminal-native-inspection-bridge.d.ts

@@ -0,0 +1,211 @@
+import type { ExecutorKind } from "./executors.js";
+import type { TerminalAgentAdapter, TerminalAgentAdapterRegistry, TerminalControlCapability, TerminalNativeInspectionEvidenceInventoryEntry, TerminalNativeInspectionObservation, TerminalNativeInspectionObservationRequest, TerminalNativeInspectionPlan, TerminalRuntimeIdentity, TerminalScreenInspection } from "./terminal-agent-adapter.js";
+import { type TerminalControlProvider } from "./terminal-control-provider.js";
+import { type TerminalControlRef, type TerminalEndpointRef, type TerminalProviderCapability } from "./terminal-control-ref.js";
+export declare const CODEX_COMPOSER_MARKER: RegExp;
+export declare const CODEX_COMPOSER_FOOTER: RegExp;
+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";
+/**
+ * A fail-closed native-inspection submission result.
+ *
+ * Only `not_started` proves that a caller may safely retry. Once text has
+ * reached the composer, or Enter has been attempted, automated retries could
+ * duplicate input or execute a different command after terminal drift.
+ */
+export declare class NativeInspectionSubmissionError extends Error {
+    readonly stage: NativeInspectionSubmissionStage;
+    readonly code = "AKK_NATIVE_INSPECTION_SUBMISSION_FAILED";
+    readonly doNotRetry: boolean;
+    constructor(stage: NativeInspectionSubmissionStage, message: string, options?: {
+        cause?: unknown;
+        diagnostic?: NativeInspectionSubmissionDiagnostic;
+    });
+    readonly diagnostic?: NativeInspectionSubmissionDiagnostic;
+}
+/** A verified modal could not be dismissed across one exact key attempt. */
+export declare class NativeInspectionDismissalError extends Error {
+    readonly code = "AKK_NATIVE_INSPECTION_DISMISSAL_FAILED";
+    readonly doNotRetry = true;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export type TerminalNativeInspectionMaterializationKind = "exact_slash_composer" | "exact_slash_popup";
+export interface TerminalNativeInspectionMaterializationEvidence {
+    kind: TerminalNativeInspectionMaterializationKind;
+    digest: string;
+    stableForMs: number;
+    stableCaptures: number;
+}
+export interface TerminalNativeInspectionBeforeEnterContext {
+    agent: ExecutorKind;
+    terminalControl: TerminalControlRef;
+    plan: TerminalNativeInspectionPlan;
+    preEnterScreenDigest: string;
+    materialization: TerminalNativeInspectionMaterializationEvidence;
+}
+export interface TerminalNativeInspectionOptions {
+    runtime?: TerminalRuntimeIdentity;
+    /**
+     * Gives the CLI one final in-lock authorization point for its Store binding
+     * and action-token fences. The bridge recaptures the exact composer and
+     * revalidates terminal identity again after this hook before pressing Enter.
+     */
+    beforeEnter?: (context: TerminalNativeInspectionBeforeEnterContext) => void | Promise<void>;
+}
+export interface TerminalNativeInspectionResult {
+    stage: "enter_dispatched";
+    agent: ExecutorKind;
+    terminalControl: TerminalControlRef;
+    command: string;
+    behaviorProfile: string;
+    preEnterScreenDigest: string;
+    preEnterEvidenceInventory: readonly TerminalNativeInspectionEvidenceInventoryEntry[];
+    materialization: TerminalNativeInspectionMaterializationEvidence;
+    enterCount: 1;
+}
+export interface TerminalCodexStatusProbeResult extends TerminalNativeInspectionResult {
+    agent: "codex";
+    /** Identity-fenced ANSI capture proving an empty/dim placeholder composer. */
+    preTextScreenDigest: string;
+    /**
+     * Bare SHA-256 of the final pre-Enter 240-line capture. This deliberately
+     * matches `status().screen.digest` when observed with the returned depth.
+     */
+    observationBaselineDigest: string;
+    /** Capture depth required for same-domain post-Enter freshness checks. */
+    observationScrollbackLines: 240;
+}
+export interface TerminalNativeInspectionBeforeDismissContext {
+    agent: ExecutorKind;
+    terminalControl: TerminalControlRef;
+    plan: TerminalNativeInspectionPlan;
+    evidenceFingerprint: string;
+}
+export interface TerminalNativeInspectionDismissalOptions {
+    runtime?: TerminalRuntimeIdentity;
+    scrollbackLines?: number;
+    beforeDismiss?: (context: TerminalNativeInspectionBeforeDismissContext) => void | Promise<void>;
+}
+export interface TerminalNativeInspectionDismissalResult {
+    stage: "dismiss_dispatched";
+    agent: ExecutorKind;
+    terminalControl: TerminalControlRef;
+    keys: readonly string[];
+    dismissCount: 1;
+}
+export interface TerminalNativeInspectionTransportObservationResult<TStatus> {
+    terminalControl: TerminalControlRef;
+    status: TStatus;
+    /** Same raw-screen fingerprint format used by adapter stale checks. */
+    screenDigest: string;
+    observation: TerminalNativeInspectionObservation;
+}
+interface TerminalNativeInspectionCapture {
+    terminalControl: TerminalControlRef;
+    screen: string;
+    inspection: TerminalScreenInspection;
+}
+interface TerminalNativeInspectionRuntime<TStatus> {
+    captureInspection: (adapter: TerminalAgentAdapter, terminalControl: TerminalControlRef, options: {
+        runtime?: TerminalRuntimeIdentity;
+        scrollbackLines?: number;
+    }) => Promise<TerminalNativeInspectionCapture>;
+    verifyIdentity: (agent: ExecutorKind, terminalControl: TerminalControlRef, runtime?: TerminalRuntimeIdentity) => Promise<TerminalControlRef>;
+    statusFromInspection: (adapter: TerminalAgentAdapter, terminalControl: TerminalControlRef, inspection: TerminalScreenInspection, options: {
+        screen?: string;
+        runtime?: TerminalRuntimeIdentity;
+    }) => TStatus;
+    nowMs: () => number;
+    sleep: (milliseconds: number) => Promise<void>;
+}
+/**
+ * Closed native-inspection transport. Terminal locking, Store authority, and
+ * the caller's one-shot input ledger remain outside this internal service.
+ */
+export declare class TerminalNativeInspectionBridge<TStatus> {
+    readonly registry: TerminalAgentAdapterRegistry;
+    readonly terminalProvider: TerminalControlProvider;
+    constructor(options: {
+        registry: TerminalAgentAdapterRegistry;
+        terminalProvider: TerminalControlProvider;
+        runtime: TerminalNativeInspectionRuntime<TStatus>;
+    });
+    private readonly runtime;
+    private captureInspection;
+    private verifyTerminalIdentity;
+    private nowMs;
+    private sleep;
+    /**
+     * Submit one closed, adapter-owned native inspection command.
+     *
+     * This intentionally does not use `send()`: native slash commands need a
+     * stricter composer proof, and failures after text injection must leave the
+     * draft untouched instead of issuing the legacy best-effort C-u cleanup.
+     */
+    submitNativeInspection(agent: ExecutorKind, terminalControl: TerminalControlRef, plan: TerminalNativeInspectionPlan, options?: TerminalNativeInspectionOptions): Promise<TerminalNativeInspectionResult>;
+    /**
+     * Submit Codex's closed, version-profiled `/status` probe.
+     *
+     * Unlike the generic native-inspection entry point, callers provide only
+     * the detected Codex version, never a command or plan. The bridge proves an
+     * exact empty (or fully dim replace-on-type) ANSI composer before injecting
+     * text, then crosses Codex's paste suppression window under the same exact
+     * composer and terminal-identity fences used by native inspection.
+     */
+    submitCodexStatusProbe(terminalControl: TerminalControlRef, agentVersion: string, options?: TerminalNativeInspectionOptions): Promise<TerminalCodexStatusProbeResult>;
+    private submitClosedNativeInspection;
+    observeNativeInspection(agent: ExecutorKind, terminalControl: TerminalControlRef, request: TerminalNativeInspectionObservationRequest, options?: {
+        runtime?: TerminalRuntimeIdentity;
+        scrollbackLines?: number;
+    }): Promise<TerminalNativeInspectionTransportObservationResult<TStatus>>;
+    /**
+     * Dismiss one exact adapter-owned modal result after re-observing the same
+     * evidence under the terminal identity fence. There is exactly one key
+     * attempt and no automated retry across an uncertain dismissal boundary.
+     */
+    dismissNativeInspection(agent: ExecutorKind, terminalControl: TerminalControlRef, plan: TerminalNativeInspectionPlan, request: TerminalNativeInspectionObservationRequest, expectedEvidenceFingerprint: string, options?: TerminalNativeInspectionDismissalOptions): Promise<TerminalNativeInspectionDismissalResult>;
+    private captureCodexReadyComposer;
+    private assertFinalCodexStatusViewport;
+    private settleNativeInspectionComposer;
+    private revalidateNativeInspectionComposer;
+}
+export declare function assertTerminalMutationCapabilities({ provider, terminal, semantic, transport }: {
+    provider: TerminalControlProvider;
+    terminal: TerminalEndpointRef;
+    semantic: readonly TerminalControlCapability[];
+    transport: readonly TerminalProviderCapability[];
+}): void;
+/**
+ * Prove Claude Code's exact current idle input frame. This is shared by every
+ * automated-input path: a loose or historical `❯` prompt is not authority to
+ * inject text into the terminal.
+ */
+export declare function isExactClaudeIdleComposer(screen: string): boolean;
+/**
+ * Compatibility export retained for callers that adopted the native-status
+ * name before the same exact-frame proof was reused by lifecycle handoff.
+ */
+export declare function isExactClaudeNativeInspectionIdleComposer(screen: string): boolean;
+export declare function exactClaudeComposerFrame(screen: string): {
+    lines: string[];
+    openIndex: number;
+    closeIndex: number;
+    composerRows: string[];
+    trailing: string[];
+} | undefined;
+export declare function claudeNativeInspectionTrailingIsFooter(lines: readonly string[]): boolean;
+export declare function stripTerminalEscapeSequences(value: string): string;
+export declare function exactCodexReadyStyledComposerCapture(screen: string): {
+    digest: string;
+} | undefined;
+/**
+ * Infer a viewport only from fixed-width visible-buffer rows. Trimmed captures
+ * deliberately return undefined: a short content row is not proof of a short
+ * terminal. This keeps the fallback provider-neutral and fail-closed only on
+ * positive geometry evidence.
+ */
+export declare function inferCodexVisibleViewportColumns(screen: string): number | undefined;
+export {};