@scotthuang/agent-knock-knock 0.12.11 → 0.12.13

package/dist/src/callback-cli-adapter.js

@@ -0,0 +1,156 @@
+// Raw CLI composition for callback commands, outbox recovery, and transport.
+import { AsyncLocalStorage } from "node:async_hooks";
+import path from "node:path";
+import { createCallbackOutboxService } from "./callback-outbox-service.js";
+import { createOpenClawCallbackTransport } from "./openclaw-callback-transport.js";
+import { budgetAction } from "./protocol.js";
+import { redactString } from "./runtime-log.js";
+import { appendEvent, assertStoreWriterCompatible, loadState, logPathForStatePath, messageEvent, pathsForConversationDir, saveState } from "./store.js";
+import { expandHome, redactCliOutput, writeCliJson } from "./cli-command-runtime.js";
+import { cliEnv, cliExit, cliNow, cliNowMs, cliPid, cliRuntimeLog, cliSleepSync } from "./cli-runtime-context.js";
+const callbackCliContext = new AsyncLocalStorage();
+function callbackRuntime() {
+    const runtime = callbackCliContext.getStore();
+    if (!runtime)
+        throw new Error("Callback CLI facade runtime is unavailable");
+    return runtime;
+}
+function required(value, message) {
+    if (value === undefined || value === "")
+        throw new Error(message);
+    return value;
+}
+function callbackStoreDir(statePath) {
+    return pathsForConversationDir(path.dirname(statePath)).storeDir;
+}
+function runCallback(options) {
+    const statePath = expandHome(required(options.state, "--state is required"));
+    runCallbackTransaction({ ...options, statePath });
+}
+function runRetryCallback(options) {
+    const runtime = callbackRuntime();
+    const { conversation, statePath, logPath } = runtime.state.loadConversation(options);
+    const storeDir = callbackStoreDir(statePath);
+    runtime.state.withWriter(storeDir, () => {
+        const fresh = loadState(statePath);
+        runtime.authority.assertNoDeferredTransfer({
+            storeDir,
+            conversation: fresh,
+            action: "retry callback for"
+        });
+    });
+    const outcome = callbackOutboxService().retry({
+        options: { ...options, statePath }, conversation, statePath, logPath
+    });
+    if (outcome.kind === "recovered")
+        emitPreparedCallbackResult(outcome.result);
+}
+function runCallbackTransaction(options) {
+    let prepared;
+    callbackRuntime().state.withWriter(callbackStoreDir(options.statePath), () => {
+        const releaseState = callbackRuntime().state.acquireFileLock(`${options.statePath}.lock`);
+        try {
+            prepared = prepareLockedCallback(options);
+        }
+        finally {
+            releaseState();
+        }
+    });
+    return runPreparedCallback(prepared);
+}
+function callbackOutboxService() {
+    const runtime = callbackRuntime();
+    return createCallbackOutboxService({
+        state: {
+            load: loadState, save: saveState,
+            readEvents: runtime.state.readEvents,
+            append: appendEvent,
+            appendMessage: (logPath, message) => appendEvent(logPath, messageEvent(message)),
+            assertWriterCompatible: assertStoreWriterCompatible,
+            withTransaction: (statePath, operation) => {
+                const releaseState = runtime.state.acquireFileLock(`${statePath}.lock`);
+                try {
+                    return operation();
+                }
+                finally {
+                    releaseState();
+                }
+            },
+            storeDirForStatePath: callbackStoreDir, logPathForStatePath
+        },
+        authority: runtime.authority,
+        retry: runtime.retry,
+        runtime: {
+            now: cliNow, nowMs: cliNowMs, pid: cliPid, log: cliRuntimeLog,
+            textSummary: runtime.runtime.textSummary,
+            sleepSync: cliSleepSync,
+            crashCheckpoint: () => {
+                if (cliEnv().AKK_TEST_EXIT_AFTER_LOCAL_COMPLETION_STATE === "1") {
+                    cliExit(86);
+                }
+            }
+        },
+        delivery: { deliver: (input) => openClawCallbackTransport().deliverCallback(input),
+            runTransaction: runCallbackTransaction }
+    });
+}
+function prepareLockedCallback(options) {
+    required(options.messageJson, "--message-json is required");
+    return callbackOutboxService().prepare({
+        options, logPath: expandHome(options.log ?? logPathForStatePath(options.statePath))
+    });
+}
+function emitPreparedCallbackResult(result) {
+    writeCliJson({
+        conversation: result.conversation, message: result.message,
+        budget: budgetAction(result.conversation),
+        delivered: result.delivered, duplicate: result.duplicate,
+        ...(result.delivery === undefined ? {} : { delivery: result.delivery })
+    });
+}
+function runPreparedCallback(prepared, { emit = true } = {}) {
+    const result = callbackOutboxService().runPrepared(prepared);
+    if (emit)
+        emitPreparedCallbackResult(result);
+    return result;
+}
+function recordCallbackProcessDelivery(observation) {
+    const { logPath, conversation, message, event, runtimeEvent, delivery } = observation;
+    const detail = observation.detail ?? {};
+    appendEvent(logPath, {
+        ts: cliNow().toISOString(), conversation_id: conversation.conversation_id,
+        event, from: message.from, to: "openclaw", round: message.round, ...detail,
+        status: delivery.status, stdout: redactString(delivery.stdout),
+        stderr: redactString(delivery.stderr)
+    });
+    cliRuntimeLog("info", runtimeEvent, {
+        conversation_id: conversation.conversation_id, ...detail,
+        status: delivery.status,
+        failure_kind: callbackRuntime().runtime.classifyProcessFailure(delivery),
+        stdout: callbackRuntime().runtime.textSummary(delivery.stdout),
+        stderr: callbackRuntime().runtime.textSummary(delivery.stderr)
+    });
+}
+function openClawCallbackTransport() {
+    return createOpenClawCallbackTransport({
+        now: cliNow, environment: cliEnv, redactConversation: redactCliOutput,
+        recordCallbackProcessDelivery
+    });
+}
+export function createCallbackCliFacade(dependencies) {
+    const call = (operation) => callbackCliContext.run(dependencies, operation);
+    return Object.freeze({
+        runCallback: (options) => call(() => runCallback(options)),
+        runRetryCallback: (options) => call(() => runRetryCallback(options)),
+        retryDisposition: (delivery) => call(() => callbackOutboxService().retryDisposition(delivery)),
+        reconcileDelivery: (input) => call(() => callbackOutboxService().reconcileDelivery(input)),
+        runRetryMonitor: (input) => call(() => callbackOutboxService().runRetryMonitor(input)),
+        prepareApprovalNotification: (input) => call(() => callbackOutboxService().prepareApprovalNotification(input)),
+        prepareTerminalCompletion: (input) => call(() => callbackOutboxService().prepareTerminalCompletion(input)),
+        runPrepared: (prepared, options) => call(() => runPreparedCallback(prepared, options)),
+        emitPreparedResult: (result) => call(() => emitPreparedCallbackResult(result)),
+        deliverGatewayMethod: (input) => call(() => openClawCallbackTransport().deliverGatewayMethod(input)),
+        deliverChatSend: (input) => call(() => openClawCallbackTransport().deliverChatSend(input))
+    });
+}
+//# sourceMappingURL=callback-cli-adapter.js.map

package/dist/src/callback-cli-adapter.js.map

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

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

@@ -0,0 +1,95 @@
+import type { AgentMessage, Conversation } from "./protocol.js";
+export interface CallbackDeliveryOutcome {
+    kind: string;
+    injection: Record<string, unknown>;
+    wake: Record<string, unknown>;
+    run_observation?: Record<string, unknown>;
+}
+export interface CallbackProcessFailureObservation {
+    status?: number | null;
+    stdout?: string;
+    stderr?: string;
+    error?: {
+        message?: string;
+    };
+}
+export declare function classifyCallbackProcessFailure(result: CallbackProcessFailureObservation): string | undefined;
+export interface CallbackDeliveryOptions {
+    gatewayMethod?: string;
+    openclawBin?: string;
+    gatewayUrl?: string;
+    token?: string;
+    gatewaySession?: string;
+    openclawSession?: string;
+}
+export interface DeliverCallbackInput {
+    options: CallbackDeliveryOptions;
+    statePath: string;
+    logPath: string;
+    conversation: Conversation;
+    message: AgentMessage;
+    onProgress?: (progress: Record<string, unknown>) => void;
+    onAccepted?: (outcome: CallbackDeliveryOutcome) => void;
+}
+export type CallbackRetryDisposition = {
+    state: "retryable";
+    attempt: number;
+} | {
+    state: "in_flight";
+    attempt: number;
+    attempt_pid?: number;
+    lease_expires_at?: string;
+    next_attempt_at?: string;
+} | {
+    state: "accepted";
+    attempt: number;
+} | {
+    state: "exhausted";
+    attempt: number;
+} | {
+    state: "unavailable";
+    attempt: number;
+    reason: string;
+};
+export type CallbackRetryPolicyState = {
+    phase: "decided";
+    disposition: CallbackRetryDisposition;
+} | {
+    phase: "observe_process";
+    attempt: number;
+    attempt_pid: number;
+    effective_lease_expires_at_ms?: number;
+    persisted_lease_expires_at?: string;
+    next_attempt_at?: string;
+} | {
+    phase: "observe_clock";
+    attempt: number;
+    attempt_pid: number;
+    effective_lease_expires_at_ms: number;
+    persisted_lease_expires_at?: string;
+    next_attempt_at?: string;
+};
+export type CallbackRetryObservation = {
+    kind: "process_alive";
+    alive: boolean;
+} | {
+    kind: "clock";
+    now_ms: number;
+};
+export interface CallbackRetryPolicyLimits {
+    attemptLeaseMs: number;
+    retryDelayCount: number;
+}
+/**
+ * Classify durable callback-outbox evidence before observing live process or
+ * clock state. The returned phase names the first ephemeral observation the
+ * caller may need; already-decided states never authorize either observation.
+ */
+export declare function beginCallbackRetryPolicy(callbackDelivery: unknown, limits: CallbackRetryPolicyLimits): CallbackRetryPolicyState;
+/**
+ * Advance one callback retry observation without performing I/O. A live
+ * process advances to a clock observation only when usable lease evidence is
+ * present, preserving the legacy short-circuit order.
+ */
+export declare function reduceCallbackRetryPolicy(state: CallbackRetryPolicyState, observation: CallbackRetryObservation): CallbackRetryPolicyState;
+export declare function callbackDeliveryHasAcceptedTransport(callbackDelivery: unknown): boolean;

package/dist/src/callback-outbox-policy.js

@@ -0,0 +1,149 @@
+import { nonBlankString as stringValue, recordValue } from "./value-guards.js";
+export function classifyCallbackProcessFailure(result) {
+    const status = result.status ?? 0;
+    const combined = [
+        result.error?.message,
+        result.stderr,
+        result.stdout
+    ].filter(Boolean).join("\n").toLowerCase();
+    if (!combined && status === 0) {
+        return undefined;
+    }
+    if (isRemoteCompactStreamDisconnect(combined)) {
+        return "transient_remote_compact_failure";
+    }
+    if (combined.includes("agent needs reconnect") ||
+        combined.includes("internal error")) {
+        return "agent_reconnect_required";
+    }
+    if (combined.includes("permission denied") ||
+        combined.includes("operation not permitted")) {
+        return "permission_denied";
+    }
+    if (combined.includes("sandbox") ||
+        combined.includes("outside workspace")) {
+        return "sandbox_denied";
+    }
+    if (combined.includes("timed out") || combined.includes("timeout")) {
+        return "timeout";
+    }
+    return status !== 0 ? "nonzero_exit" : undefined;
+}
+function isRemoteCompactStreamDisconnect(text) {
+    const value = String(text ?? "").toLowerCase();
+    return value.includes("error running remote compact task") &&
+        value.includes("stream disconnected") &&
+        value.includes("/codex/responses/compact");
+}
+/**
+ * Classify durable callback-outbox evidence before observing live process or
+ * clock state. The returned phase names the first ephemeral observation the
+ * caller may need; already-decided states never authorize either observation.
+ */
+export function beginCallbackRetryPolicy(callbackDelivery, limits) {
+    const delivery = recordValue(callbackDelivery);
+    const attemptValue = Number(delivery?.attempts ?? 0);
+    const attempt = Number.isSafeInteger(attemptValue) && attemptValue >= 0
+        ? attemptValue
+        : 0;
+    if (!delivery ||
+        !recordValue(delivery.message) ||
+        !["pending", "failed"].includes(String(delivery.status ?? ""))) {
+        return decided({
+            state: "unavailable",
+            attempt,
+            reason: "no pending or failed callback outbox is available"
+        });
+    }
+    if (callbackDeliveryHasAcceptedTransport(delivery)) {
+        return decided({ state: "accepted", attempt });
+    }
+    if (!Number.isSafeInteger(attemptValue) || attemptValue < 1) {
+        return decided({
+            state: "unavailable",
+            attempt,
+            reason: "callback outbox has invalid attempt metadata"
+        });
+    }
+    if (attemptValue > limits.retryDelayCount) {
+        return decided({ state: "exhausted", attempt });
+    }
+    if (delivery.status === "failed") {
+        return decided({ state: "retryable", attempt });
+    }
+    const attemptPidValue = Number(delivery.attempt_pid);
+    const attemptPid = Number.isSafeInteger(attemptPidValue) && attemptPidValue > 0
+        ? attemptPidValue
+        : undefined;
+    if (attemptPid === undefined) {
+        return decided({ state: "retryable", attempt });
+    }
+    const persistedLeaseExpiresAt = stringValue(delivery.attempt_lease_expires_at);
+    const leaseExpiresAtMs = validTimestampMs(persistedLeaseExpiresAt);
+    const legacyLastAttemptAtMs = validTimestampMs(delivery.last_attempt_at);
+    return {
+        phase: "observe_process",
+        attempt,
+        attempt_pid: attemptPid,
+        effective_lease_expires_at_ms: leaseExpiresAtMs ??
+            (legacyLastAttemptAtMs === undefined
+                ? undefined
+                : legacyLastAttemptAtMs + limits.attemptLeaseMs),
+        persisted_lease_expires_at: persistedLeaseExpiresAt,
+        next_attempt_at: stringValue(delivery.next_attempt_at)
+    };
+}
+/**
+ * Advance one callback retry observation without performing I/O. A live
+ * process advances to a clock observation only when usable lease evidence is
+ * present, preserving the legacy short-circuit order.
+ */
+export function reduceCallbackRetryPolicy(state, observation) {
+    if (state.phase === "decided") {
+        throw new Error("callback retry policy is already decided");
+    }
+    if (state.phase === "observe_process") {
+        if (observation.kind !== "process_alive") {
+            throw new Error("callback retry policy requires a process observation");
+        }
+        if (!observation.alive || state.effective_lease_expires_at_ms === undefined) {
+            return decided({ state: "retryable", attempt: state.attempt });
+        }
+        return {
+            phase: "observe_clock",
+            attempt: state.attempt,
+            attempt_pid: state.attempt_pid,
+            effective_lease_expires_at_ms: state.effective_lease_expires_at_ms,
+            persisted_lease_expires_at: state.persisted_lease_expires_at,
+            next_attempt_at: state.next_attempt_at
+        };
+    }
+    if (observation.kind !== "clock") {
+        throw new Error("callback retry policy requires a clock observation");
+    }
+    if (state.effective_lease_expires_at_ms > observation.now_ms) {
+        return decided({
+            state: "in_flight",
+            attempt: state.attempt,
+            attempt_pid: state.attempt_pid,
+            lease_expires_at: state.persisted_lease_expires_at ??
+                new Date(state.effective_lease_expires_at_ms).toISOString(),
+            next_attempt_at: state.next_attempt_at
+        });
+    }
+    return decided({ state: "retryable", attempt: state.attempt });
+}
+export function callbackDeliveryHasAcceptedTransport(callbackDelivery) {
+    const delivery = recordValue(callbackDelivery);
+    const injection = recordValue(delivery?.injection);
+    const wake = recordValue(delivery?.wake);
+    return injection?.status === "accepted" || wake?.status === "accepted";
+}
+function decided(disposition) {
+    return { phase: "decided", disposition };
+}
+function validTimestampMs(value) {
+    const parsed = Date.parse(String(value ?? ""));
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+//# sourceMappingURL=callback-outbox-policy.js.map

package/dist/src/callback-outbox-policy.js.map

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

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 {};