@scotthuang/agent-knock-knock 0.12.11 → 0.12.13

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

@@ -0,0 +1,229 @@
+import type { CodexOpenRootRolloutInventory } from "./agent-session-provider.js";
+import { type DeferredForegroundApplicationScope } from "./deferred-foreground-boundary.js";
+import { DeferredForegroundApplicationService } from "./deferred-foreground-application-service.js";
+import * as deferredRecoveryAdapter from "./deferred-foreground-recovery-cli-adapter.js";
+import { type ExecutorKind } from "./executors.js";
+import { type HumanObservedHandoffTargetSnapshot, type ManagedSessionState, type NativeThreadTransition } from "./managed-session.js";
+import { type CanonicalMutationLockPorts, type CanonicalMutationResources, type CanonicalMutationScopes, type CanonicalStateMutationResources, type CanonicalStateMutationScopes } from "./mutation-transaction.js";
+import { type Conversation } from "./protocol.js";
+import type { TerminalControlRef } from "./terminal-agent-adapter.js";
+import type { ResolvedTerminalConversation, TerminalAgentBridge, TerminalBridgeStatus } from "./terminal-agent-bridge.js";
+import type { TerminalNativeIdentity as NativeAgentSessionIdentity } from "./terminal-binding-authority.js";
+import { type DeferredCodexForegroundBindingBoundary, type TerminalDispatchTerminal, type VerifiedEmptyCodexHandoffBoundary } from "./terminal-dispatch-composition.js";
+import { type NativeAgentSessionIdentityObservation } from "./terminal-dispatch-execution.js";
+import { type TerminalDispatchLedgerDocument } from "./terminal-dispatch-ledger-codec.js";
+import type { createTerminalAcceptanceCliFacade } from "./terminal-acceptance-cli-adapter.js";
+import type { createTerminalIdentityAuthorityCliAdapter } from "./terminal-identity-authority-cli-adapter.js";
+export type TerminalHandoffCliOptions = Readonly<Record<string, unknown>>;
+type UnknownRecord = Record<string, unknown>;
+export interface TerminalHandoffRuntimePorts {
+    storeDir(options: TerminalHandoffCliOptions): string;
+    createBridge(options: TerminalHandoffCliOptions): TerminalAgentBridge;
+    agentVersion(agent: ExecutorKind, pid: number, options: TerminalHandoffCliOptions): string | undefined;
+    required<Value>(value: Value | null | undefined, message: string): Value;
+    isStoreMutationLockTimeout(error: unknown): boolean;
+}
+type TerminalIdentityAuthorityFacade = ReturnType<typeof createTerminalIdentityAuthorityCliAdapter>;
+type TerminalAcceptanceFacade = Pick<ReturnType<typeof createTerminalAcceptanceCliFacade>, "inspectCodexOpenRoots" | "observeNativeIdentity" | "resolveNativeIdentity" | "assertTurnIdentity">;
+export interface TerminalHandoffAuthorityPorts {
+    assertTerminalCanStartTurn(storeDir: string, terminalControl: TerminalControlRef): void;
+    hasUnresolvedTransition(storeDir: string, session: ManagedSessionState): boolean;
+    assertSessionCanStartTurn(turns: Conversation[]): void;
+    turnsForSession(storeDir: string, sessionId: string): Conversation[];
+    assertTerminalReady(input: {
+        options: TerminalHandoffCliOptions;
+        terminal: TerminalDispatchTerminal;
+        terminalStatus: TerminalBridgeStatus;
+    }): void;
+    assertSafeSend(agent: ExecutorKind, status: TerminalBridgeStatus): void;
+    assertExclusive(input: {
+        options: TerminalHandoffCliOptions;
+        agent: ExecutorKind;
+        currentPid: number;
+        nativeThreadId: string;
+        storeDir: string;
+        terminalControl: TerminalControlRef;
+        excludedManagedSessionId?: string;
+        allowedManagedSessionIds?: string[];
+    }): Promise<void>;
+}
+export interface TerminalHandoffRepositoryPorts {
+    storeDirForConversation(conversation: Conversation): string | undefined;
+    loadLedger(terminalControl: TerminalControlRef): TerminalDispatchLedgerDocument | undefined;
+    saveLedger(terminalControl: TerminalControlRef, ledger: TerminalDispatchLedgerDocument): void;
+    ledgerMatchesControl(ledger: TerminalDispatchLedgerDocument | undefined, terminalControl: TerminalControlRef, options?: {
+        requireCurrentRoute?: boolean;
+        requireProcessAnchor?: boolean;
+    }): boolean;
+    bindingFields(conversation: Conversation): UnknownRecord;
+    withNativeIdentity(conversation: Conversation, identity: NativeAgentSessionIdentity): Conversation;
+    withSubmission(mutation: Parameters<deferredRecoveryAdapter.DeferredForegroundRecoveryAdapterPorts["turn"]["withSubmission"]>[0]): Conversation;
+    saveLifecycleLedger(terminalControl: TerminalControlRef, ledger: TerminalDispatchLedgerDocument, options: {
+        expectedTransitionId: string | null;
+        expectedStatus?: string;
+    }): void;
+    mutationLocks(storeDir: string, terminalControl: TerminalControlRef): CanonicalMutationLockPorts;
+    withStateScope<Result>(scopes: CanonicalMutationScopes, resources: CanonicalMutationResources, statePath: string, logPath: string, operation: (scopes: CanonicalStateMutationScopes, resources: CanonicalStateMutationResources) => Promise<Result>): Promise<Result>;
+}
+export interface TerminalHandoffCliDependencies {
+    runtime: TerminalHandoffRuntimePorts;
+    identity: TerminalIdentityAuthorityFacade;
+    acceptance: TerminalAcceptanceFacade;
+    authority: TerminalHandoffAuthorityPorts;
+    repository: TerminalHandoffRepositoryPorts;
+}
+declare function assertSafeAbortedTerminalRetryBinding({ owner, receipt, storeDir, terminalControl, messageId }: {
+    owner: Conversation;
+    receipt: Record<string, any>;
+    storeDir: string;
+    terminalControl: TerminalControlRef;
+    messageId: string;
+}): ManagedSessionState | undefined;
+declare function exactSafeAbortedRecoveredSessionMatches({ owner, receipt, storeDir, terminalControl, messageId, expectedSessionId }: {
+    owner: Conversation;
+    receipt?: Record<string, any>;
+    storeDir: string;
+    terminalControl: TerminalControlRef;
+    messageId: string;
+    expectedSessionId: string;
+}): boolean;
+declare function maybeDetachVerifiedEmptyCodexSource({ options, terminal, sourceSession, observation }: {
+    options: Record<string, any>;
+    terminal: ResolvedTerminalConversation;
+    sourceSession?: ManagedSessionState;
+    observation: NativeAgentSessionIdentityObservation;
+}): Promise<{
+    detached: ManagedSessionState;
+    boundary: VerifiedEmptyCodexHandoffBoundary;
+} | undefined>;
+declare function assertVerifiedEmptyCodexTransportBoundary({ options, boundary, requireEmptyComposer }: {
+    options: Record<string, any>;
+    boundary: VerifiedEmptyCodexHandoffBoundary;
+    requireEmptyComposer: boolean;
+}): Promise<void>;
+declare function assertDeferredCodexForegroundBindingBoundary({ options, scope, boundary, expectedSourceStatus, requireNoDispatch, requireEmptyComposer }: {
+    options: Record<string, any>;
+    scope: DeferredForegroundApplicationScope;
+    boundary: DeferredCodexForegroundBindingBoundary;
+    expectedSourceStatus: "bound" | "transitioning";
+    requireNoDispatch: boolean;
+    requireEmptyComposer: boolean;
+}): Promise<ManagedSessionState>;
+declare function prepareDeferredCodexForegroundBinding({ options, scope, terminal, sourceSession, observation, candidateInventory, requestText, allowImplicitFreshAuthority }: {
+    options: Record<string, any>;
+    scope: DeferredForegroundApplicationScope;
+    terminal: ResolvedTerminalConversation;
+    sourceSession?: ManagedSessionState;
+    observation: NativeAgentSessionIdentityObservation;
+    candidateInventory?: CodexOpenRootRolloutInventory;
+    requestText: string;
+    allowImplicitFreshAuthority?: boolean;
+}): Promise<DeferredCodexForegroundBindingBoundary | undefined>;
+declare function deferredForegroundApplication(options: Record<string, any>, terminal?: TerminalDispatchTerminal): DeferredForegroundApplicationService;
+declare function deferredForegroundRecoveryAdapterPorts(): deferredRecoveryAdapter.DeferredForegroundRecoveryAdapterPorts;
+declare function observedHandoffAuthorityToken({ terminal, identity, sourceSession, target }: {
+    terminal: ResolvedTerminalConversation;
+    identity: NativeAgentSessionIdentity;
+    sourceSession: ManagedSessionState;
+    target: HumanObservedHandoffTargetSnapshot;
+}): string;
+declare function activeTurnHandoffDecisionToken({ handoffToken, turn, ledger }: {
+    handoffToken: string;
+    turn: Record<string, any>;
+    ledger?: Record<string, any>;
+}): string;
+declare function assertExpectedHandoffTokenUsesExactTerminalSelector({ options, terminal }: {
+    options: Record<string, any>;
+    terminal: ResolvedTerminalConversation;
+}): void;
+declare function observedExternalHandoffIdentity({ options, terminal, sourceSession, resolvedIdentity, requireSafeTerminal }: {
+    options: Record<string, any>;
+    terminal: ResolvedTerminalConversation;
+    sourceSession: ManagedSessionState;
+    resolvedIdentity?: NativeAgentSessionIdentity;
+    requireSafeTerminal?: boolean;
+}): Promise<{
+    identity?: NativeAgentSessionIdentity;
+    status: Awaited<ReturnType<TerminalAgentBridge["status"]>>;
+}>;
+type ObservedHandoffTargetResolution = {
+    status: "eligible";
+    session?: ManagedSessionState;
+    snapshot: HumanObservedHandoffTargetSnapshot;
+} | {
+    status: "blocked";
+    reason: string;
+};
+declare function observedHandoffTargetResolution({ storeDir, agent, workspace, nativeThreadId, sourceSessionId }: {
+    storeDir: string;
+    agent: ExecutorKind;
+    workspace: string;
+    nativeThreadId: string;
+    sourceSessionId: string;
+}): ObservedHandoffTargetResolution;
+declare function maybeAdoptObservedExternalThread({ options, terminal, sourceSession, resolvedIdentity, storeDir }: {
+    options: Record<string, any>;
+    terminal: ResolvedTerminalConversation;
+    sourceSession?: ManagedSessionState;
+    resolvedIdentity?: NativeAgentSessionIdentity;
+    storeDir: string;
+}): Promise<{
+    session?: ManagedSessionState;
+    identity?: NativeAgentSessionIdentity;
+    transition?: NativeThreadTransition;
+    adopted: boolean;
+}>;
+declare function assertObservedHandoffTransportBoundary({ options, terminal, transition, requireEmptyComposer }: {
+    options: Record<string, any>;
+    terminal: ResolvedTerminalConversation;
+    transition: NativeThreadTransition;
+    requireEmptyComposer: boolean;
+}): Promise<void>;
+declare function assertConversationHasNoNonterminalDeferredForegroundTransfer({ storeDir, conversation, action }: {
+    storeDir: string;
+    conversation: Conversation;
+    action: string;
+}): void;
+declare function assertTerminalHasNoNonterminalDeferredForegroundTransfer({ storeDir, pid, terminalControl, action }: {
+    storeDir: string;
+    pid: number;
+    terminalControl: TerminalControlRef;
+    action: string;
+}): void;
+declare function recoverDeferredCodexForegroundTransferBeforeMutation({ options, terminal }: {
+    options: Record<string, any>;
+    terminal: ResolvedTerminalConversation;
+}): Promise<void>;
+declare function recoverDeferredCodexForegroundTransferWhileWriterLease({ options, terminal, storeDir, scopes, resources }: {
+    options: Record<string, any>;
+    terminal: ResolvedTerminalConversation;
+    storeDir: string;
+    scopes: CanonicalMutationScopes;
+    resources: CanonicalMutationResources;
+}): Promise<void>;
+declare const terminalHandoffOperations: {
+    assertSafeAbortedTerminalRetryBinding: typeof assertSafeAbortedTerminalRetryBinding;
+    exactSafeAbortedRecoveredSessionMatches: typeof exactSafeAbortedRecoveredSessionMatches;
+    maybeDetachVerifiedEmptyCodexSource: typeof maybeDetachVerifiedEmptyCodexSource;
+    assertVerifiedEmptyCodexTransportBoundary: typeof assertVerifiedEmptyCodexTransportBoundary;
+    assertDeferredCodexForegroundBindingBoundary: typeof assertDeferredCodexForegroundBindingBoundary;
+    prepareDeferredCodexForegroundBinding: typeof prepareDeferredCodexForegroundBinding;
+    observedHandoffAuthorityToken: typeof observedHandoffAuthorityToken;
+    activeTurnHandoffDecisionToken: typeof activeTurnHandoffDecisionToken;
+    assertExpectedHandoffTokenUsesExactTerminalSelector: typeof assertExpectedHandoffTokenUsesExactTerminalSelector;
+    observedExternalHandoffIdentity: typeof observedExternalHandoffIdentity;
+    observedHandoffTargetResolution: typeof observedHandoffTargetResolution;
+    maybeAdoptObservedExternalThread: typeof maybeAdoptObservedExternalThread;
+    assertObservedHandoffTransportBoundary: typeof assertObservedHandoffTransportBoundary;
+    assertConversationHasNoNonterminalDeferredForegroundTransfer: typeof assertConversationHasNoNonterminalDeferredForegroundTransfer;
+    assertTerminalHasNoNonterminalDeferredForegroundTransfer: typeof assertTerminalHasNoNonterminalDeferredForegroundTransfer;
+    recoverDeferredCodexForegroundTransferBeforeMutation: typeof recoverDeferredCodexForegroundTransferBeforeMutation;
+    recoverDeferredCodexForegroundTransferWhileWriterLease: typeof recoverDeferredCodexForegroundTransferWhileWriterLease;
+};
+export type TerminalHandoffCliFacade = Readonly<typeof terminalHandoffOperations & {
+    rememberOriginalExpectedTerminalSelector(options: object, selector: string | undefined): void;
+    deferredForegroundApplication: typeof deferredForegroundApplication;
+    deferredForegroundRecoveryAdapterPorts: typeof deferredForegroundRecoveryAdapterPorts;
+}>;
+export declare function createTerminalHandoffCliFacade(dependencies: TerminalHandoffCliDependencies): TerminalHandoffCliFacade;
+export {};