@scotthuang/agent-knock-knock 0.12.11 → 0.12.13

package/dist/src/terminal-acceptance-application-service.d.ts

@@ -0,0 +1,65 @@
+import type { ExecutorKind } from "./executors.js";
+import type { TerminalSubmissionAcceptanceEvidence } from "./terminal-submission-facts.js";
+export type VirginBindingRecoveryState = "not_applicable" | "already_bound" | "pending" | "recovered";
+export interface TerminalAcceptanceTurnFacts {
+    turnStatus: string;
+    messageId?: string;
+    submissionStatus?: string;
+    requestText: string;
+    enterDispatchedAtMs?: number;
+    codexAnchorVersion?: number;
+}
+export interface TerminalAcceptanceBindingRecovery<Turn> {
+    turn: Turn;
+    state: VirginBindingRecoveryState;
+}
+export type TerminalAcceptanceResolution = {
+    outcome: "agent_accepted";
+    evidence: TerminalSubmissionAcceptanceEvidence;
+} | {
+    outcome: "not_accepted";
+    reason: string;
+};
+export interface TerminalAcceptanceApplicationPorts<Turn> {
+    clock: {
+        nowMs(): number;
+    };
+    binding: {
+        recover(turn: Turn): Promise<TerminalAcceptanceBindingRecovery<Turn>>;
+    };
+    acceptance: {
+        detect(executor: ExecutorKind, turn: Turn): Promise<TerminalSubmissionAcceptanceEvidence | undefined>;
+    };
+    terminal: {
+        proveExactDraftStillPresent(turn: Turn, requestText: string): Promise<boolean>;
+    };
+    repository: {
+        commit(input: {
+            turn: Turn;
+            expected: TerminalAcceptanceTurnFacts;
+            resolution: TerminalAcceptanceResolution;
+        }): Promise<Turn>;
+    };
+}
+export type TerminalAcceptanceApplicationResult<Turn> = {
+    outcome: "accepted";
+    turn: Turn;
+} | {
+    outcome: "pending";
+} | {
+    outcome: "not_accepted";
+    turn: Turn;
+};
+/**
+ * Owns the monotonic acceptance polling order while concrete terminal and
+ * repository resources remain outside the service boundary.
+ */
+export declare class TerminalAcceptanceApplicationService<Turn> {
+    #private;
+    constructor(ports: TerminalAcceptanceApplicationPorts<Turn>);
+    reconcile(input: {
+        executor: ExecutorKind;
+        turn: Turn;
+        project(turn: Turn): TerminalAcceptanceTurnFacts;
+    }): Promise<TerminalAcceptanceApplicationResult<Turn>>;
+}

package/dist/src/terminal-acceptance-application-service.js

@@ -0,0 +1,63 @@
+/**
+ * Owns the monotonic acceptance polling order while concrete terminal and
+ * repository resources remain outside the service boundary.
+ */
+export class TerminalAcceptanceApplicationService {
+    #ports;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    async reconcile(input) {
+        let recovery = await this.#ports.binding.recover(input.turn);
+        let turn = recovery.turn;
+        let evidence = await this.#ports.acceptance.detect(input.executor, turn);
+        let facts = input.project(turn);
+        if (evidence &&
+            facts.codexAnchorVersion === 2 &&
+            recovery.state === "not_applicable") {
+            throw new Error("virgin Codex acceptance appeared without a recoverable Session/Turn binding");
+        }
+        if (evidence &&
+            facts.codexAnchorVersion === 2 &&
+            recovery.state === "pending") {
+            recovery = await this.#ports.binding.recover(turn);
+            if (recovery.state !== "recovered" &&
+                recovery.state !== "already_bound") {
+                return { outcome: "pending" };
+            }
+            turn = recovery.turn;
+            evidence = await this.#ports.acceptance.detect(input.executor, turn);
+            if (!evidence) {
+                return { outcome: "pending" };
+            }
+            facts = input.project(turn);
+        }
+        if (!facts.messageId) {
+            throw new Error("terminal acceptance monitor lost its exact message identity");
+        }
+        let notAcceptedReason;
+        if (!evidence) {
+            const oldEnough = facts.enterDispatchedAtMs !== undefined &&
+                this.#ports.clock.nowMs() - facts.enterDispatchedAtMs >= 250;
+            if (oldEnough &&
+                await this.#ports.terminal.proveExactDraftStillPresent(turn, facts.requestText)) {
+                notAcceptedReason =
+                    "the exact managed draft remains in the terminal composer";
+            }
+            if (!notAcceptedReason) {
+                return { outcome: "pending" };
+            }
+        }
+        const committed = await this.#ports.repository.commit({
+            turn,
+            expected: facts,
+            resolution: notAcceptedReason
+                ? { outcome: "not_accepted", reason: notAcceptedReason }
+                : { outcome: "agent_accepted", evidence: evidence }
+        });
+        return notAcceptedReason
+            ? { outcome: "not_accepted", turn: committed }
+            : { outcome: "accepted", turn: committed };
+    }
+}
+//# sourceMappingURL=terminal-acceptance-application-service.js.map

package/dist/src/terminal-acceptance-application-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-acceptance-application-service.js","sourceRoot":"","sources":["../../src/terminal-acceptance-application-service.ts"],"names":[],"mappings":"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"}

package/dist/src/terminal-acceptance-cli-adapter.d.ts

@@ -0,0 +1,210 @@
+import type { CodexOpenRootRolloutInventory, CodingAgentSessionProvider } from "./agent-session-provider.js";
+import type { ClaudeAgentRow } from "./claude-terminal-agent-adapter.js";
+import { type AgentMessage, type Conversation, type Executor } from "./protocol.js";
+import type { ExecutorKind } from "./executors.js";
+import { type ManagedSessionState } from "./managed-session.js";
+import type { TerminalControlRef, TerminalDurableCompletionRequest, TerminalRuntimeIdentity } from "./terminal-agent-adapter.js";
+import { type TerminalNativeIdentity } from "./terminal-binding-authority.js";
+import type { TerminalDispatchLedgerDocument } from "./terminal-dispatch-ledger-codec.js";
+import type { TerminalDispatchTerminal } from "./terminal-dispatch-composition.js";
+import { TerminalDispatchExecutionService, type NativeAgentSessionIdentityObservation, type NativeIdentityResolutionRequest } from "./terminal-dispatch-execution.js";
+import { type VirginBindingRecoveryState } from "./terminal-acceptance-application-service.js";
+import type { DeferredForegroundTransfer } from "./deferred-foreground-transfer.js";
+import type { FileLockAcquisitionOptions } from "./file-lock-cli-adapter.js";
+export interface TerminalAcceptanceCliOptions {
+    claudeHome?: string;
+    gatewayMethod?: string;
+    gatewaySession?: string;
+    gatewayUrl?: string;
+    hardLimit?: number | string;
+    logDir?: string;
+    messageId?: string;
+    openclawBin?: string;
+    openclawSession?: string;
+    scrollbackLines?: number | string;
+    softLimit?: number | string;
+    storeDir?: string;
+    type?: string;
+    [option: string]: unknown;
+}
+export interface TerminalAcceptanceBridge {
+    proveExactDraftStillPresent(executor: ExecutorKind, terminalControl: TerminalControlRef, requestText: string, options: {
+        scrollbackLines: number;
+        runtime: TerminalRuntimeIdentity;
+    }): Promise<boolean>;
+    resolveStoredTerminal(agent: "codex", pid: number, terminalControl: TerminalControlRef, expected: {
+        pid: number;
+    }): Promise<TerminalDispatchTerminal>;
+}
+interface ManagedTerminalTurn {
+    conversation: Conversation;
+    nextConversation: Conversation;
+    statePath: string;
+    logPath: string;
+    executor: Executor;
+    message: AgentMessage;
+}
+interface DeferredTurnAuthority {
+    conversation: Conversation;
+    statePath: string;
+    submission: {
+        message_body_hash?: unknown;
+    };
+}
+interface TerminalAcceptanceRepositoryPorts {
+    acquireStateLock(lockPath: string, options?: FileLockAcquisitionOptions): () => void;
+    acquireTerminalLock(storeDir: string, terminalControl: TerminalControlRef, options?: FileLockAcquisitionOptions): () => void;
+    loadLedger(terminalControl: TerminalControlRef): TerminalDispatchLedgerDocument | undefined;
+    saveLedger(terminalControl: TerminalControlRef, ledger: TerminalDispatchLedgerDocument): void;
+    reconcileLedger(terminalControl: TerminalControlRef, ledger?: TerminalDispatchLedgerDocument): TerminalDispatchLedgerDocument | undefined;
+    bindingFields(conversation: Conversation): Partial<TerminalDispatchLedgerDocument>;
+}
+export interface TerminalAcceptanceCliDependencies {
+    native: {
+        codexProvider(options: TerminalAcceptanceCliOptions): CodingAgentSessionProvider;
+        codexProcessIncarnation(pid: number): {
+            processUuid: string;
+            processBirth: string;
+        };
+        assertExclusive(input: {
+            options: TerminalAcceptanceCliOptions;
+            agent: "codex";
+            currentPid: number;
+            nativeThreadId: string;
+            storeDir: string;
+            terminalControl: TerminalControlRef;
+            excludedManagedSessionId: string;
+        }): Promise<void>;
+    };
+    terminal: {
+        runtime(options: TerminalAcceptanceCliOptions): {
+            loadClaudeAgentRows(observation?: {
+                required?: boolean;
+            }): readonly ClaudeAgentRow[];
+            createBridge(): TerminalAcceptanceBridge;
+        };
+        durableRequest(conversation: Conversation, terminalControl: TerminalControlRef): TerminalDurableCompletionRequest;
+        runtimeIdentity(conversation: Conversation, terminalControl: TerminalControlRef): TerminalRuntimeIdentity;
+    };
+    authority: {
+        assertTurnCurrent(conversation: Conversation, operation: string): void;
+        terminalControl(value: unknown): TerminalControlRef | undefined;
+        isDiscoverableTurn(conversation: Conversation): boolean;
+        workspaceMatches(configured: unknown, observed: unknown): boolean;
+    };
+    repository: TerminalAcceptanceRepositoryPorts;
+    deferred: {
+        recover(input: {
+            options: TerminalAcceptanceCliOptions;
+            terminal: TerminalDispatchTerminal;
+        }): Promise<void>;
+        loadAuthority(input: {
+            storeDir: string;
+            terminal: TerminalDispatchTerminal;
+            transfer: DeferredForegroundTransfer;
+        }): DeferredTurnAuthority;
+        assertLedgerAuthority(input: {
+            storeDir: string;
+            terminal: Pick<TerminalDispatchTerminal, "terminalControl">;
+            transfer: DeferredForegroundTransfer;
+            ledger: TerminalDispatchLedgerDocument;
+            statePath: string;
+            expectedMessageBodyHash?: string;
+        }): void;
+        loadTransfer(storeDir: string, transferId: string): DeferredForegroundTransfer;
+    };
+}
+export interface TerminalAcceptanceCliFacade {
+    execution(options: TerminalAcceptanceCliOptions, bridge?: TerminalAcceptanceBridge): TerminalDispatchExecutionService;
+    recoverVirgin(input: {
+        options: TerminalAcceptanceCliOptions;
+        conversation: Conversation;
+        statePath: string;
+        logPath: string;
+        terminalLockHeld?: boolean;
+    }): Promise<{
+        conversation: Conversation;
+        state: VirginBindingRecoveryState;
+    }>;
+    reconcileMonitor(input: {
+        options: TerminalAcceptanceCliOptions;
+        conversation: Conversation;
+        statePath: string;
+        logPath: string;
+        terminalControl: TerminalControlRef;
+        executor: Executor;
+        terminalBridge: TerminalAcceptanceBridge;
+    }): Promise<{
+        outcome: "accepted";
+        conversation: Conversation;
+    } | {
+        outcome: "pending";
+    } | {
+        outcome: "not_accepted";
+        conversation: Conversation;
+    }>;
+    markUncertain(input: {
+        conversation: Conversation;
+        statePath: string;
+        logPath: string;
+        terminalControl: TerminalControlRef;
+        reason: string;
+    }): Conversation;
+    inspectCodexOpenRoots(input: {
+        options: TerminalAcceptanceCliOptions;
+        pid: number;
+        cwd?: string;
+    }): Promise<CodexOpenRootRolloutInventory>;
+    resolveNativeIdentity(request: NativeIdentityResolutionRequest & {
+        options: TerminalAcceptanceCliOptions;
+    }): Promise<TerminalNativeIdentity | undefined>;
+    observeNativeIdentity(request: NativeIdentityResolutionRequest & {
+        options: TerminalAcceptanceCliOptions;
+    }): Promise<NativeAgentSessionIdentityObservation>;
+    assertTurnIdentity(input: {
+        conversation: Conversation;
+        currentIdentity: TerminalNativeIdentity | undefined;
+        operation: string;
+    }): void;
+    withNativeIdentity(conversation: Conversation, identity: TerminalNativeIdentity): Conversation;
+    storeDirForConversation(conversation: Conversation): string | undefined;
+    refineSessionIdentity(input: {
+        storeDir: string;
+        session: ManagedSessionState;
+        terminalControl: TerminalControlRef;
+        identity?: TerminalNativeIdentity;
+    }): ManagedSessionState;
+    persistSessionIdentity(input: {
+        conversation: Conversation;
+        terminalControl: TerminalControlRef;
+        identity: TerminalNativeIdentity;
+        storeDir: string;
+    }): ManagedSessionState | undefined;
+    quarantineSession(input: {
+        conversation: Conversation;
+        reason: string;
+        storeDir: string;
+    }): void;
+    turnsForSession(storeDir: string, sessionId: string): Conversation[];
+    assertSessionCanStartTurn(turns: Conversation[]): void;
+    turnMatchesTerminal(input: {
+        conversation: Conversation;
+        terminal: TerminalDispatchTerminal;
+        currentIdentity?: TerminalNativeIdentity;
+    }): boolean;
+    createManagedTurn(input: {
+        options: TerminalAcceptanceCliOptions;
+        conversationId: string;
+        agent: ExecutorKind;
+        pid: number;
+        messageBody: string;
+        terminalControl: TerminalControlRef;
+        previousTurn?: Conversation;
+        managedSession?: ManagedSessionState;
+        nativeAgentIdentity?: TerminalNativeIdentity;
+        deferredForegroundTransferId?: string;
+    }): ManagedTerminalTurn;
+}
+/** Factory-scoped CLI composition; it retains no mutable module runtime. */
+export declare function createTerminalAcceptanceCliFacade(dependencies: TerminalAcceptanceCliDependencies): TerminalAcceptanceCliFacade;
+export {};