@scotthuang/agent-knock-knock 0.11.4 → 0.11.5

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

@@ -24,6 +24,14 @@ export declare class NativeInspectionSubmissionError extends Error {
         cause?: unknown;
     });
 }
+/** 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 interface TerminalBridgeStatus {
     provider: "tmux";
     target: string;
@@ -129,7 +137,7 @@ export interface TerminalNativeInspectionMaterializationEvidence {
     stableCaptures: number;
 }
 export interface TerminalNativeInspectionBeforeEnterContext {
-    agent: "codex";
+    agent: ExecutorKind;
     terminalControl: TerminalControlRef;
     plan: TerminalNativeInspectionPlan;
     preEnterScreenDigest: string;
@@ -146,15 +154,33 @@ export interface TerminalNativeInspectionOptions {
 }
 export interface TerminalNativeInspectionResult {
     stage: "enter_dispatched";
-    agent: "codex";
+    agent: ExecutorKind;
     terminalControl: TerminalControlRef;
-    command: "/status";
+    command: string;
     behaviorProfile: string;
     preEnterScreenDigest: string;
     preEnterEvidenceInventory: readonly TerminalNativeInspectionEvidenceInventoryEntry[];
     materialization: TerminalNativeInspectionMaterializationEvidence;
     enterCount: 1;
 }
+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 TerminalNativeInspectionObservationResult {
     terminalControl: TerminalControlRef;
     status: TerminalBridgeStatus;
@@ -221,8 +247,14 @@ export declare class TerminalAgentBridge {
         runtime?: TerminalRuntimeIdentity;
         scrollbackLines?: number;
     }): Promise<TerminalNativeInspectionObservationResult>;
-    private settleCodexNativeInspectionComposer;
-    private revalidateCodexNativeInspectionComposer;
+    /**
+     * 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 settleNativeInspectionComposer;
+    private revalidateNativeInspectionComposer;
     private settleCodexMultilineComposer;
     /**
      * Prove that the exact managed draft is still present after Enter dispatch.
@@ -281,6 +313,12 @@ export declare class TerminalAgentBridge {
     private captureInspection;
     private verifyTerminalIdentity;
 }
+/**
+ * Prove the exact idle input frame from the verified Claude Code 2.1.218
+ * profile. A loose or historical `❯` prompt is not enough to authorize even
+ * the initial literal `/status` injection.
+ */
+export declare function isExactClaudeNativeInspectionIdleComposer(screen: string): boolean;
 export declare function terminalApprovalFingerprint(agent: ExecutorKind, terminalControl: TerminalControlRef, inspection: TerminalScreenInspection, options?: {
     screen?: string;
     runtime?: TerminalRuntimeIdentity;

package/dist/src/terminal-agent-bridge.js

@@ -18,6 +18,14 @@ const CODEX_NATIVE_STATUS_POPUP_BY_PROFILE = {
     "codex-tui-0.146.0": "  /status  show current session configuration and token usage",
     "codex-tui-0.146.1": "  /status  show current session configuration and token usage"
 };
+const CLAUDE_NATIVE_STATUS_POPUP_BY_PROFILE = {
+    "claude-code-2.1.218-native-status": [
+        "/status Show Claude Code status including version, model, account, API connectivity, and tool statuses",
+        "/statusline Set up Claude Code's status line UI",
+        "/ide Manage IDE integrations and show status",
+        "/usage Show session cost, plan usage, and activity stats"
+    ]
+};
 const CODEX_LARGE_PASTE_CHAR_THRESHOLD = 1_000;
 /** A terminal send failed at a boundary that proves input never started. */
 export class TerminalInputNotStartedError extends Error {
@@ -45,6 +53,15 @@ export class NativeInspectionSubmissionError extends Error {
         this.doNotRetry = stage !== "not_started";
     }
 }
+/** A verified modal could not be dismissed across one exact key attempt. */
+export class NativeInspectionDismissalError extends Error {
+    code = "AKK_NATIVE_INSPECTION_DISMISSAL_FAILED";
+    doNotRetry = true;
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "NativeInspectionDismissalError";
+    }
+}
 export class TerminalAgentBridge {
     registry;
     terminalProvider;
@@ -254,7 +271,7 @@ export class TerminalAgentBridge {
     async submitNativeInspection(agent, terminalControl, plan, options = {}) {
         const adapter = this.registry.require(agent);
         try {
-            assertCodexStatusInspectionPlan(adapter, terminalControl, plan);
+            assertClosedStatusInspectionPlan(adapter, terminalControl, plan);
         }
         catch (error) {
             throw nativeInspectionSubmissionError("not_started", error);
@@ -279,15 +296,15 @@ export class TerminalAgentBridge {
         }
         let settled;
         try {
-            settled = await this.settleCodexNativeInspectionComposer(adapter, terminalControl, plan, options.runtime);
+            settled = await this.settleNativeInspectionComposer(adapter, terminalControl, plan, options.runtime);
             await options.beforeEnter?.({
-                agent: "codex",
+                agent: adapter.agent,
                 terminalControl: settled.terminalControl,
                 plan,
                 preEnterScreenDigest: settled.screenDigest,
                 materialization: settled.materialization
             });
-            settled = await this.revalidateCodexNativeInspectionComposer(adapter, settled.terminalControl, plan, settled.materialization, options.runtime);
+            settled = await this.revalidateNativeInspectionComposer(adapter, settled.terminalControl, plan, settled.materialization, options.runtime);
         }
         catch (error) {
             throw nativeInspectionSubmissionError("text_injected", error);
@@ -302,9 +319,9 @@ export class TerminalAgentBridge {
         }
         return {
             stage: "enter_dispatched",
-            agent: "codex",
+            agent: adapter.agent,
             terminalControl: settled.terminalControl,
-            command: "/status",
+            command: plan.command,
             behaviorProfile: plan.behaviorProfile,
             preEnterScreenDigest: settled.screenDigest,
             preEnterEvidenceInventory: settled.evidenceInventory,
@@ -322,14 +339,24 @@ export class TerminalAgentBridge {
             scrollbackLines: options.scrollbackLines
         });
         const screenDigest = nativeInspectionScreenFingerprint(captured.screen);
-        const observation = adapter.observeNativeInspection({
+        const adapterObservation = adapter.observeNativeInspection({
             operation: request.operation,
             previousScreenFingerprint: request.previousScreenFingerprint,
             preEnterEvidenceInventory: request.preEnterEvidenceInventory,
             expectedNativeThreadId: request.expectedNativeThreadId,
             expectedAgentVersion: request.expectedAgentVersion,
+            expectedCwd: request.expectedCwd,
             screen: captured.screen
         });
+        const observation = adapter.agent === "claude" &&
+            options.runtime?.requireExactClaudeAgentRow === true &&
+            adapterObservation.status === "observed" &&
+            adapterObservation.evidence === "claude_status_panel"
+            ? {
+                ...adapterObservation,
+                evidence: "claude_status_panel+claude_agents_exact_pid"
+            }
+            : adapterObservation;
         return {
             terminalControl: captured.terminalControl,
             status: statusFromInspection(adapter, captured.terminalControl, captured.inspection, { screen: captured.screen, runtime: options.runtime }),
@@ -337,7 +364,78 @@ export class TerminalAgentBridge {
             observation
         };
     }
-    async settleCodexNativeInspectionComposer(adapter, terminalControl, plan, runtime) {
+    /**
+     * 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.
+     */
+    async dismissNativeInspection(agent, terminalControl, plan, request, expectedEvidenceFingerprint, options = {}) {
+        const adapter = this.registry.require(agent);
+        try {
+            assertClosedStatusInspectionPlan(adapter, terminalControl, plan);
+            assertClosedNativeInspectionDismissal(plan);
+        }
+        catch (error) {
+            throw new NativeInspectionDismissalError(error instanceof Error ? error.message : String(error), { cause: error });
+        }
+        const observeExactPanel = async (control) => {
+            const captured = await this.captureInspection(adapter, control, {
+                runtime: options.runtime,
+                scrollbackLines: options.scrollbackLines
+            });
+            const observation = adapter.observeNativeInspection?.({
+                operation: request.operation,
+                previousScreenFingerprint: request.previousScreenFingerprint,
+                preEnterEvidenceInventory: request.preEnterEvidenceInventory,
+                expectedNativeThreadId: request.expectedNativeThreadId,
+                expectedAgentVersion: request.expectedAgentVersion,
+                expectedCwd: request.expectedCwd,
+                screen: captured.screen
+            });
+            if (!observation ||
+                observation.status !== "observed" ||
+                observation.result?.kind !== "native_status" ||
+                observation.evidenceFingerprint !== expectedEvidenceFingerprint) {
+                throw new Error(observation?.reason ??
+                    "the exact fresh native status panel changed before dismissal");
+            }
+            const verified = await this.verifyTerminalIdentity(adapter.agent, captured.terminalControl, options.runtime);
+            if (!sameTerminalControlIdentity(captured.terminalControl, verified)) {
+                throw new Error("terminal control identity changed before native status dismissal");
+            }
+            return verified;
+        };
+        try {
+            let verified = await observeExactPanel(terminalControl);
+            await options.beforeDismiss?.({
+                agent: adapter.agent,
+                terminalControl: verified,
+                plan,
+                evidenceFingerprint: expectedEvidenceFingerprint
+            });
+            verified = await observeExactPanel(verified);
+            try {
+                await this.terminalProvider.sendKeys(verified.target, plan.expectedResult.dismissal.keys, { socketPath: verified.socketPath });
+            }
+            catch (error) {
+                throw new NativeInspectionDismissalError("native status modal dismissal outcome is uncertain; do not retry automatically", { cause: error });
+            }
+            return {
+                stage: "dismiss_dispatched",
+                agent: adapter.agent,
+                terminalControl: verified,
+                keys: plan.expectedResult.dismissal.keys,
+                dismissCount: 1
+            };
+        }
+        catch (error) {
+            if (error instanceof NativeInspectionDismissalError) {
+                throw error;
+            }
+            throw new NativeInspectionDismissalError(error instanceof Error ? error.message : String(error), { cause: error });
+        }
+    }
+    async settleNativeInspectionComposer(adapter, terminalControl, plan, runtime) {
         const startedAt = performance.now();
         let stableDigest;
         let stableKind;
@@ -349,7 +447,7 @@ export class TerminalAgentBridge {
                 scrollbackLines: CODEX_MULTILINE_SETTLE_SCROLLBACK_LINES
             });
             assertNativeInspectionComposerSafe(captured.inspection);
-            const materialized = exactCodexNativeInspectionComposerCapture(captured.screen, plan);
+            const materialized = exactNativeInspectionComposerCapture(adapter.agent, captured.screen, plan);
             const now = performance.now();
             if (materialized) {
                 if (materialized.digest === stableDigest &&
@@ -371,7 +469,7 @@ export class TerminalAgentBridge {
                         stableForMs,
                         stableCaptures
                     };
-                    return this.revalidateCodexNativeInspectionComposer(adapter, captured.terminalControl, plan, evidence, runtime);
+                    return this.revalidateNativeInspectionComposer(adapter, captured.terminalControl, plan, evidence, runtime);
                 }
             }
             else {
@@ -387,19 +485,19 @@ export class TerminalAgentBridge {
             }
             await terminalSettleDelay(Math.min(CODEX_MULTILINE_SETTLE_POLL_MS, remaining));
         }
-        throw new Error("Codex /status composer did not become exact, idle, and stable before the bounded submit deadline");
+        throw new Error(`${adapter.displayName} /status composer did not become exact, idle, and stable before the bounded submit deadline`);
     }
-    async revalidateCodexNativeInspectionComposer(adapter, terminalControl, plan, expected, runtime) {
+    async revalidateNativeInspectionComposer(adapter, terminalControl, plan, expected, runtime) {
         const captured = await this.captureInspection(adapter, terminalControl, {
             runtime,
             scrollbackLines: CODEX_MULTILINE_SETTLE_SCROLLBACK_LINES
         });
         assertNativeInspectionComposerSafe(captured.inspection);
-        const materialized = exactCodexNativeInspectionComposerCapture(captured.screen, plan);
+        const materialized = exactNativeInspectionComposerCapture(adapter.agent, captured.screen, plan);
         if (!materialized ||
             materialized.digest !== expected.digest ||
             materialized.kind !== expected.kind) {
-            throw new Error("Codex /status composer changed after its stable pre-submit capture");
+            throw new Error(`${adapter.displayName} /status composer changed after its stable pre-submit capture`);
         }
         const baseline = adapter.observeNativeInspection?.({
             operation: plan.operation,
@@ -409,11 +507,11 @@ export class TerminalAgentBridge {
             baseline.status === "ambiguous" ||
             !Array.isArray(baseline.evidenceInventory)) {
             throw new Error(baseline?.reason ??
-                "Codex /status pre-Enter evidence inventory was not proven");
+                `${adapter.displayName} /status pre-Enter evidence inventory was not proven`);
         }
         const verifiedImmediatelyBeforeEnter = await this.verifyTerminalIdentity(adapter.agent, captured.terminalControl, runtime);
         if (!sameTerminalControlIdentity(captured.terminalControl, verifiedImmediatelyBeforeEnter)) {
-            throw new Error("terminal control identity changed after the final Codex /status composer capture");
+            throw new Error(`terminal control identity changed after the final ${adapter.displayName} /status composer capture`);
         }
         return {
             terminalControl: verifiedImmediatelyBeforeEnter,
@@ -958,36 +1056,55 @@ function nativeInspectionSubmissionError(stage, error) {
     }
     return new NativeInspectionSubmissionError(stage, error instanceof Error ? error.message : String(error), { cause: error });
 }
-function assertCodexStatusInspectionPlan(adapter, terminalControl, plan) {
-    if (adapter.agent !== "codex") {
-        throw new Error("native /status inspection is currently supported only for Codex");
-    }
+function assertClosedStatusInspectionPlan(adapter, terminalControl, plan) {
     if (!terminalControl.capabilities.includes("send_keys")) {
-        throw new Error("Codex terminal input is not supported");
+        throw new Error(`${adapter.displayName} terminal input is not supported`);
     }
     if (!terminalControl.capabilities.includes("screen_status")) {
-        throw new Error("Codex terminal screen inspection is not supported");
+        throw new Error(`${adapter.displayName} terminal screen inspection is not supported`);
     }
+    const codexProfile = adapter.agent === "codex" && [
+        "codex-tui-0.146.0",
+        "codex-tui-0.146.1"
+    ].includes(plan.behaviorProfile);
+    const claudeProfile = adapter.agent === "claude" &&
+        plan.behaviorProfile === "claude-code-2.1.218-native-status";
+    const exactPresentation = codexProfile
+        ? plan.expectedResult.presentation === "inline" &&
+            plan.expectedResult.dismissal === undefined &&
+            plan.composer.minimumStableMs >= CODEX_PASTE_ENTER_SETTLE_MS
+        : claudeProfile
+            ? plan.expectedResult.presentation === "modal" &&
+                plan.composer.minimumStableMs >= 80 &&
+                plan.expectedResult.dismissal?.expected === "idle_empty_composer" &&
+                JSON.stringify(plan.expectedResult.dismissal.keys) ===
+                    JSON.stringify(["Escape"])
+            : false;
     if (plan.operation.kind !== "status" ||
         plan.command !== "/status" ||
         plan.effect !== "read_only" ||
         plan.requiresIdle !== true ||
         plan.composer.kind !== "exact" ||
         !Number.isFinite(plan.composer.minimumStableMs) ||
-        plan.composer.minimumStableMs < CODEX_PASTE_ENTER_SETTLE_MS ||
+        plan.composer.minimumStableMs < 0 ||
         plan.expectedResult.kind !== "native_status" ||
-        ![
-            "codex-tui-0.146.0",
-            "codex-tui-0.146.1"
-        ].includes(plan.behaviorProfile)) {
+        !exactPresentation) {
         throw new Error("refusing a non-closed or unverified native inspection plan");
     }
 }
-function assertNativeInspectionComposerSafe(inspection) {
+function assertClosedNativeInspectionDismissal(plan) {
+    if (plan.expectedResult.presentation !== "modal" ||
+        plan.expectedResult.dismissal?.expected !== "idle_empty_composer" ||
+        JSON.stringify(plan.expectedResult.dismissal.keys) !==
+            JSON.stringify(["Escape"])) {
+        throw new Error("native inspection has no closed verified modal dismissal plan");
+    }
+}
+function assertNativeInspectionComposerSafe(inspection, displayName = "terminal agent") {
     if (inspection.approval.blocked ||
         inspection.activity.state === "awaiting_approval" ||
         inspection.activity.state === "working") {
-        throw new Error("Codex became busy or blocked while its /status composer was settling");
+        throw new Error(`${displayName} became busy or blocked while its /status composer was settling`);
     }
     // Codex's generic activity parser deliberately reports a non-empty slash
     // composer as unknown. At this stage the caller has already proved an idle,
@@ -995,6 +1112,11 @@ function assertNativeInspectionComposerSafe(inspection) {
     // capture below is the stronger continuation proof after AKK injected only
     // the adapter-owned /status command.
 }
+function exactNativeInspectionComposerCapture(agent, screen, plan) {
+    return agent === "codex"
+        ? exactCodexNativeInspectionComposerCapture(screen, plan)
+        : exactClaudeNativeInspectionComposerCapture(screen, plan);
+}
 function exactCodexNativeInspectionComposerCapture(screen, plan) {
     const lines = screen.replace(/\r\n?/gu, "\n").split("\n");
     let currentComposerIndex = -1;
@@ -1037,6 +1159,88 @@ function exactCodexNativeInspectionComposerCapture(screen, plan) {
         digest: createHash("sha256").update(region.join("\n")).digest("hex")
     };
 }
+function exactClaudeNativeInspectionComposerCapture(screen, plan) {
+    const frame = exactClaudeNativeInspectionComposerFrame(screen);
+    if (!frame) {
+        return undefined;
+    }
+    const { lines, openIndex, closeIndex, composerRows, trailing } = frame;
+    if (composerRows.length !== 1 ||
+        !/^\s*❯(?:\s|$)/u.test(composerRows[0]) ||
+        composerRows[0].replace(/^\s*❯\s?/u, "").trimEnd() !== plan.command) {
+        return undefined;
+    }
+    let kind;
+    if (trailing.length === 0 || claudeNativeInspectionTrailingIsFooter(trailing)) {
+        kind = "exact_slash_composer";
+    }
+    else {
+        const suggestions = [];
+        for (const line of trailing) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith("/")) {
+                suggestions.push(trimmed.replace(/\s+/gu, " "));
+            }
+            else if (suggestions.length > 0) {
+                suggestions[suggestions.length - 1] +=
+                    ` ${trimmed.replace(/\s+/gu, " ")}`;
+            }
+            else {
+                return undefined;
+            }
+        }
+        if (JSON.stringify(suggestions) !== JSON.stringify(CLAUDE_NATIVE_STATUS_POPUP_BY_PROFILE[plan.behaviorProfile])) {
+            return undefined;
+        }
+        kind = "exact_slash_popup";
+    }
+    return {
+        kind,
+        digest: createHash("sha256")
+            .update(lines.slice(openIndex, closeIndex + 1).concat(trailing).join("\n"))
+            .digest("hex")
+    };
+}
+/**
+ * Prove the exact idle input frame from the verified Claude Code 2.1.218
+ * profile. A loose or historical `❯` prompt is not enough to authorize even
+ * the initial literal `/status` injection.
+ */
+export function isExactClaudeNativeInspectionIdleComposer(screen) {
+    const frame = exactClaudeNativeInspectionComposerFrame(screen);
+    if (!frame) {
+        return false;
+    }
+    return (frame.composerRows.length === 1 &&
+        /^\s*❯\s*$/u.test(frame.composerRows[0]) &&
+        (frame.trailing.length === 0 ||
+            claudeNativeInspectionTrailingIsFooter(frame.trailing)));
+}
+function exactClaudeNativeInspectionComposerFrame(screen) {
+    const lines = screen.replace(/\r\n?/gu, "\n").replace(/\u00a0/gu, " ")
+        .split("\n");
+    const dividerIndexes = lines
+        .map((line, index) => /^\s*[─━]{8,}\s*$/u.test(line) ? index : -1)
+        .filter((index) => index >= 0);
+    if (dividerIndexes.length < 2) {
+        return undefined;
+    }
+    const closeIndex = dividerIndexes.at(-1);
+    const openIndex = dividerIndexes.at(-2);
+    return {
+        lines,
+        openIndex,
+        closeIndex,
+        composerRows: lines.slice(openIndex + 1, closeIndex)
+            .filter((line) => line.trim().length > 0),
+        trailing: lines.slice(closeIndex + 1)
+            .filter((line) => line.trim().length > 0)
+    };
+}
+function claudeNativeInspectionTrailingIsFooter(lines) {
+    return lines.length <= 2 && lines.every((line) => /^\s*(?:[⏵⏴]{1,2}|\?)\s*.*(?:shift\+tab|accept edits|bypass permissions|for shortcuts|← for agents)/iu
+        .test(line));
+}
 function nativeInspectionScreenFingerprint(screen) {
     return `sha256:${createHash("sha256").update(screen).digest("hex")}`;
 }