@scotthuang/agent-knock-knock 0.12.11 → 0.12.12

package/dist/src/callback-outbox-service.d.ts

@@ -0,0 +1,247 @@
+import { type AgentMessage, type Actor, type Conversation } from "./protocol.js";
+import type { TerminalCompletionEvidence, TerminalControlRef } from "./terminal-agent-adapter.js";
+import type { CallbackDeliveryOptions, CallbackDeliveryOutcome, CallbackRetryDisposition, DeliverCallbackInput } from "./callback-outbox-policy.js";
+import type { TranscriptEvent } from "./transcript.js";
+export interface CallbackPreparationOptions extends CallbackDeliveryOptions {
+    statePath: string;
+    messageJson?: string;
+    log?: string;
+    conversationOverride?: unknown;
+    callbackDeliveryKind?: string;
+    allowTerminalCompletionRecoveryStatus?: boolean;
+    closeTerminalBridgeOnDone?: boolean;
+    disableCallbackRetry?: boolean;
+    preserveMessageId?: boolean;
+    recordOnly?: boolean;
+    recoverMissingOutbox?: boolean;
+    recoverTerminalCompletion?: boolean;
+    retryPending?: boolean;
+}
+export interface PrepareCallbackOutboxInput {
+    options: CallbackPreparationOptions;
+    logPath: string;
+}
+interface PreparedCallbackBase {
+    conversation: Conversation;
+    message: AgentMessage;
+}
+export interface PreparedCallbackWithoutDelivery extends PreparedCallbackBase {
+    outcome: "duplicate" | "record_only";
+}
+export interface PreparedCallbackDelivery extends PreparedCallbackBase {
+    outcome: "deliver";
+    options: CallbackPreparationOptions;
+    statePath: string;
+    logPath: string;
+    deliveryAttempt: number;
+    deliveryAttemptId: string;
+}
+export type PreparedCallback = PreparedCallbackWithoutDelivery | PreparedCallbackDelivery;
+export interface CallbackExecutionResult {
+    delivered: boolean;
+    duplicate: boolean;
+    conversation: Conversation;
+    message: unknown;
+    delivery?: string;
+}
+export interface CallbackDeliveryReconciliationInput {
+    statePath: string;
+    logPath: string;
+    delayMs?: unknown;
+}
+export interface CallbackRetryMonitorInput {
+    statePath: string;
+    initialDelayMs?: unknown;
+}
+export interface RetryCallbackInput {
+    options: CallbackPreparationOptions;
+    conversation: Conversation;
+    statePath: string;
+    logPath: string;
+}
+export type RetryCallbackOutcome = {
+    kind: "recovered";
+    result: CallbackExecutionResult;
+} | {
+    kind: "retried";
+    result: CallbackExecutionResult;
+};
+export interface TerminalCompletionPreparationInput {
+    options: CallbackPreparationOptions;
+    statePath: string;
+    logPath: string;
+    conversationId: string;
+    actor: Actor;
+    terminalControl: TerminalControlRef;
+    terminalMessageId: string;
+    completion: TerminalCompletionEvidence;
+    allowSupersedeRecovery?: boolean;
+    completionFingerprint?: string;
+}
+export interface ApprovalNotificationPreparationInput {
+    options: CallbackPreparationOptions;
+    statePath: string;
+    logPath: string;
+    conversation: Conversation;
+    actor: Actor;
+    type: "blocked" | "question";
+    body: string;
+    metadata: Record<string, unknown>;
+    recoverMissingOutbox?: boolean;
+}
+export interface CallbackOutboxServicePorts {
+    state: {
+        load(statePath: string): Conversation;
+        save(statePath: string, conversation: Conversation): void;
+        readEvents(logPath: string): TranscriptEvent[];
+        append(logPath: string, event: Record<string, unknown>): void;
+        appendMessage(logPath: string, message: AgentMessage): void;
+        assertWriterCompatible(storeDir: string): void;
+        withTransaction<Result>(statePath: string, operation: () => Result): Result;
+        storeDirForStatePath(statePath: string): string;
+        logPathForStatePath(statePath: string): string;
+    };
+    authority: {
+        assertNoDeferredTransfer(input: {
+            storeDir: string;
+            conversation: Conversation;
+            action: string;
+        }): void;
+        assertBindingCurrent(conversation: Conversation, action: string): void;
+        resolveCompletionDispatch(input: {
+            terminalControl: TerminalControlRef;
+            conversation: Conversation;
+            expectedMessageId: string;
+            reason: string;
+        }): boolean;
+    };
+    retry: {
+        startMonitor(input: {
+            statePath: string;
+            delayMs: number;
+        }): {
+            pid?: number | null;
+        };
+        isProcessAlive(pid: number): boolean;
+        attemptLeaseMs: number;
+        delaysMs: readonly number[];
+    };
+    runtime: {
+        now(): Date;
+        nowMs(): number;
+        pid(): number;
+        log(level: "info" | "warn" | "error", event: string, fields: Record<string, unknown>): void;
+        textSummary(value: unknown): unknown;
+        sleepSync(milliseconds: number): void;
+        crashCheckpoint(name: "after_local_completion_state"): void;
+    };
+    delivery: {
+        deliver(input: DeliverCallbackInput): CallbackDeliveryOutcome;
+        runTransaction(options: CallbackPreparationOptions): CallbackExecutionResult;
+    };
+}
+export interface CallbackGatewayRouteCandidate {
+    gatewayUrl?: unknown;
+    token?: unknown;
+}
+export declare function resolveCallbackGatewayRoute(...candidates: CallbackGatewayRouteCandidate[]): {
+    gatewayUrl: string | undefined;
+    token: string;
+} | {
+    gatewayUrl: undefined;
+    token: undefined;
+};
+export declare function createCallbackOutboxService(ports: CallbackOutboxServicePorts): {
+    prepare: ({ options, logPath }: PrepareCallbackOutboxInput) => PreparedCallback;
+    runPrepared: (prepared: PreparedCallback) => CallbackExecutionResult;
+    reconcileDelivery: (input: CallbackDeliveryReconciliationInput) => {
+        handled: true;
+        conversationId: string;
+        status: string;
+        reason: string;
+        diagnostic: string;
+        attempt?: undefined;
+        attemptPid?: undefined;
+        leaseExpiresAt?: undefined;
+        nextAttemptAt?: undefined;
+        monitorPid?: undefined;
+    } | {
+        reason?: undefined;
+        diagnostic?: undefined;
+        handled: false;
+        attempt?: undefined;
+        attemptPid?: undefined;
+        leaseExpiresAt?: undefined;
+        nextAttemptAt?: undefined;
+        conversationId?: undefined;
+        status?: undefined;
+        monitorPid?: undefined;
+    } | {
+        diagnostic?: undefined;
+        handled: true;
+        conversationId: string;
+        status: string;
+        reason: string;
+        attempt?: undefined;
+        attemptPid?: undefined;
+        leaseExpiresAt?: undefined;
+        nextAttemptAt?: undefined;
+        monitorPid?: undefined;
+    } | {
+        diagnostic?: undefined;
+        handled: true;
+        conversationId: string;
+        status: string;
+        reason: string;
+        attempt: number;
+        attemptPid: number | undefined;
+        leaseExpiresAt: string | undefined;
+        nextAttemptAt: string | undefined;
+        monitorPid?: undefined;
+    } | {
+        diagnostic?: undefined;
+        attempt?: undefined;
+        attemptPid?: undefined;
+        leaseExpiresAt?: undefined;
+        nextAttemptAt?: undefined;
+        handled: true;
+        conversationId: string;
+        status: string;
+        reason: string;
+        monitorPid: number | null | undefined;
+    };
+    runRetryMonitor: (input: CallbackRetryMonitorInput) => void;
+    retry: (input: RetryCallbackInput) => RetryCallbackOutcome;
+    retryDisposition: (delivery: unknown) => CallbackRetryDisposition;
+    prepareApprovalNotification: (input: ApprovalNotificationPreparationInput) => {
+        callbackMessage: AgentMessage;
+        delivered: false;
+        prepared?: undefined;
+    } | {
+        delivered?: undefined;
+        callbackMessage: AgentMessage;
+        prepared: PreparedCallback;
+    };
+    prepareTerminalCompletion: (input: TerminalCompletionPreparationInput) => {
+        claimed: true;
+        conversation: Conversation;
+        prepared: PreparedCallback;
+        callbackMessageId: string;
+    } | {
+        claimed: false;
+        conversation: Conversation;
+        reason: string;
+        resumed?: undefined;
+    };
+};
+export declare function deterministicTerminalCallbackMessageId(input: {
+    conversationId: string;
+    terminalMessageId: string;
+    completionFingerprint: string;
+    outcome: string;
+}): string;
+export declare function terminalBridgeCompletionFingerprint(input: {
+    completion: TerminalCompletionEvidence;
+    terminalMessageId?: string;
+}): string;
+export {};