@scotthuang/agent-knock-knock 0.12.13 → 0.12.15

package/dist/src/openclaw-managed-callback-cli-adapter.d.ts

@@ -0,0 +1,23 @@
+import { type OpenClawCallbackTransport } from "./openclaw-callback-transport.js";
+import { type DeliverCallbackInput } from "./callback-outbox-policy.js";
+import { type CallbackTransportDeliverInput } from "./callback-transport.js";
+import type { Conversation } from "./protocol.js";
+type ResolvedCallbackTransportDelivery = Omit<CallbackTransportDeliverInput, "reportCheckpoint">;
+export interface OpenClawManagedCallbackCliAdapterPorts {
+    now(): Date;
+    environment(): NodeJS.ProcessEnv;
+    redactConversation(conversation: Conversation): unknown;
+    textSummary(value: unknown): unknown;
+    log(level: "info" | "warn" | "error", event: string, fields: Record<string, unknown>): void;
+}
+export interface OpenClawManagedCallbackCliAdapter {
+    transport: OpenClawCallbackTransport;
+    resolve(input: DeliverCallbackInput): ResolvedCallbackTransportDelivery;
+}
+/**
+ * Compose the legacy OpenClaw process adapter behind the host-neutral callback
+ * transport port. The CLI root supplies runtime capabilities but owns no
+ * delivery parsing, logging, or route-resolution policy.
+ */
+export declare function createOpenClawManagedCallbackCliAdapter(ports: OpenClawManagedCallbackCliAdapterPorts): OpenClawManagedCallbackCliAdapter;
+export {};

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

@@ -0,0 +1,77 @@
+import { createOpenClawCallbackTransport } from "./openclaw-callback-transport.js";
+import { classifyCallbackProcessFailure } from "./callback-outbox-policy.js";
+import { parseCallbackRoute } from "./callback-transport.js";
+import { redactString } from "./runtime-log.js";
+import { appendEvent } from "./store.js";
+import { nonBlankString } from "./value-guards.js";
+/**
+ * Compose the legacy OpenClaw process adapter behind the host-neutral callback
+ * transport port. The CLI root supplies runtime capabilities but owns no
+ * delivery parsing, logging, or route-resolution policy.
+ */
+export function createOpenClawManagedCallbackCliAdapter(ports) {
+    const transport = createOpenClawCallbackTransport({
+        now: ports.now,
+        environment: ports.environment,
+        redactConversation: ports.redactConversation,
+        recordCallbackProcessDelivery
+    });
+    return Object.freeze({ transport, resolve });
+    function recordCallbackProcessDelivery(observation) {
+        const { logPath, conversation, message, event, runtimeEvent, delivery } = observation;
+        const detail = observation.detail ?? {};
+        appendEvent(logPath, {
+            ts: ports.now().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)
+        });
+        ports.log("info", runtimeEvent, {
+            conversation_id: conversation.conversation_id,
+            ...detail,
+            status: delivery.status,
+            failure_kind: classifyCallbackProcessFailure(delivery),
+            stdout: ports.textSummary(delivery.stdout),
+            stderr: ports.textSummary(delivery.stderr)
+        });
+    }
+    function resolve(input) {
+        const route = parseCallbackRoute(input.route ?? input.options.callbackRoute);
+        if (!input.envelope) {
+            throw new Error("managed callback envelope is required for delivery");
+        }
+        const attemptNumber = Number(input.attempt?.number);
+        const attemptId = nonBlankString(input.attempt?.id);
+        if (!Number.isSafeInteger(attemptNumber) ||
+            attemptNumber < 1 ||
+            !attemptId) {
+            throw new Error("managed callback attempt identity is invalid");
+        }
+        return {
+            route,
+            envelope: input.envelope,
+            attempt: { number: attemptNumber, id: attemptId },
+            context: {
+                statePath: input.statePath,
+                logPath: input.logPath,
+                conversation: input.conversation,
+                message: input.message,
+                legacyOptions: {
+                    gatewayMethod: input.options.gatewayMethod,
+                    gatewaySession: input.options.gatewaySession,
+                    openclawSession: input.options.openclawSession,
+                    openclawBin: input.options.openclawBin,
+                    gatewayUrl: input.options.gatewayUrl,
+                    token: input.options.token
+                }
+            }
+        };
+    }
+}
+//# sourceMappingURL=openclaw-managed-callback-cli-adapter.js.map

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

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

package/dist/src/openclaw-plugin-command-adapter.js

@@ -1,5 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { executorDefinitionForKind } from "./executors.js";
 import { isRecord, nonBlankString as stringValue } from "./value-guards.js";
@@ -25,13 +25,13 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
             default: "AKK is handling the request..."
         },
         agentPromptGuidance: [
-            "Use /akk <task> when exactly one eligible idle coding-agent terminal pane should receive new work. Structured tools use only semantic identifiers returned by AKK: session_id for an exact managed context, terminal_id for the currently verified pane, turn_id for one managed Turn, watch_id for one Terminal Watch, and native_thread_id for one resumable native thread. AKK keeps all opaque freshness authority private and revalidates it under its locks. Use /akk watch only from a currently advertised watch action to observe one human-started active task; it sends no input and creates no Session or Turn. New/clear/resume, approval, reconciliation, handoff, and recovery still require the documented user intent or explicit confirmation. AKK never starts a coding-agent process."
+            "Use /akk <task> when exactly one send-ready coding-agent terminal pane should receive new work. Send-ready means an exact live process and terminal, a verified non-blocked approval state, and an exactly empty composer; parsed activity and broken AKK management state do not veto the user's Send. Structured tools use only semantic identifiers returned by AKK: session_id for an exact managed context, terminal_id for the currently verified pane, turn_id for one managed Turn, watch_id for one Terminal Watch, and native_thread_id for one resumable native thread. AKK keeps all opaque freshness authority private and revalidates it under its locks. Use /akk watch only from a currently advertised watch action to observe one human-started active task; it sends no input and creates no Session or Turn. New/clear/resume, approval, reconciliation, handoff, and recovery still require the documented user intent or explicit confirmation. AKK never starts a coding-agent process."
         ],
         handler: async (ctx) => handleAkkCommand(api, ctx, displayedResumeSnapshots)
     });
     registerCliTool(api, {
         name: "agent_knock_knock_list",
-        description: "List existing Codex and Claude Code tmux or Herdr panes as the primary terminals[] resources, plus durable terminal_watches[] records. Use only advertised actions and their semantic IDs. AKK keeps opaque freshness authority private and revalidates terminal, binding, candidate, approval, and handoff state before every side effect. A session_exact send uses session_id; terminal_follow_current and Watch use terminal_id; managed controls use turn_id; lifecycle resume additionally uses the complete native_thread_id. Recovery actions remain explicit-confirmation operations. AKK never starts a coding-agent process.",
+        description: "List existing Codex and Claude Code tmux or Herdr panes as the primary terminals[] resources, plus durable terminal_watches[] records. Use only advertised actions and their semantic IDs. A terminal_user_explicit send is user-priority authority for one exact live physical prompt with no active approval and an empty composer; broken AKK Turn, Session, transfer, ledger, or Store state does not veto a new user Send. AKK tries the managed fast path first, then delivers once as unmanaged work with no callback before best-effort management release. Existing or possibly existing same-message idempotency evidence rejects replay. If fresh durability is unavailable, AKK proceeds with a warning and the result must not be automatically retried. Refresh list afterward and use Watch. A session_exact send uses session_id; terminal_follow_current and terminal_user_explicit Send use terminal_id; Watch uses terminal_id; managed controls use turn_id; lifecycle resume additionally uses the complete native_thread_id. AKK keeps opaque freshness authority private and never starts a coding-agent process.",
         parameters: listParameters,
         buildArgs: (params) => {
             const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
@@ -253,7 +253,7 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
     api.registerTool((toolContext) => ({
         label: "AKK Send",
         name: "agent_knock_knock_send",
-        description: "Start a new AKK Turn. Use session_id only for an advertised session_exact action, or terminal_id for an advertised terminal_follow_current action; omit both only when AKK should require one unique eligible idle pane. AKK derives all terminal freshness authority privately, revalidates the exact pane/process/context under lock, sends once, and binds only the unique accepting native thread. Never pass a Turn id as a destination. This is asynchronous: after acceptance, yield and wait for the callback or an explicit status request.",
+        description: "Start a new AKK Turn, use one advertised terminal_user_explicit user-priority send, or explicitly recover one current uncertain submission only through its advertised retry_submission action. Ordinary send requires request and may use session_id or terminal_id exactly as advertised. terminal_user_explicit is gated only by one exact live physical prompt, no active approval prompt, and an empty composer. AKK tries its managed fast path first; if broken internal AKK state prevents it, AKK delivers once as unmanaged work with no callback Turn or callback before best-effort management release. Refresh list afterward and use Watch. Retry submission is the mutually exclusive exact {turn_id} form and cannot change request text or routing. AKK derives all freshness authority privately. A Turn id is never an ordinary-send destination. Managed acceptance is asynchronous: yield and wait for its callback or an explicit status request.",
         parameters: sendParameters,
         async execute(toolCallId, params) {
             try {
@@ -344,38 +344,17 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
     });
     registerCliTool(api, {
         name: "agent_knock_knock_close",
-        description: "Close one managed Turn record without terminating the shared pane. Ordinary close uses turn_id. Orphan dispatch/lifecycle recovery may additionally use its exact expected_message_id or expected_transition_id. Human-context handoff uses the advertised turn_id plus reason=superseded_by_human_context_switch after explicit confirmation; AKK resolves the current handoff authority privately. Refresh list afterward.",
+        description: "Honor an explicit user request to close one managed turn_id and release AKK management. Raw orphan recovery may instead use conversation_id with expected_message_id or expected_transition_id. Close never sends terminal input, stops the coding agent, or closes the shared pane. Deferred transfer, Session, ledger, and callback cleanup is best-effort and cannot veto closing the Turn; warnings identify metadata AKK preserved. Refresh list afterward and use Watch if the coding agent is still working.",
         parameters: closeParameters,
         isErrorResult: isBlockedTerminalDispatchResult,
-        buildArgs: (params, toolContext) => {
+        buildArgs: (params) => {
             const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
             const args = ["close"];
             assertExclusiveRecoveryFence(params);
-            const handoffReason = stringValue(params.reason) ===
-                "superseded_by_human_context_switch";
-            const handoffAction = handoffReason
-                ? consumeDisplayedPrivateAction(api, {
-                    sessionKey: requiredOpenClawSessionKey(toolContext?.sessionKey),
-                    sessionId: requiredOpenClawSessionId(toolContext?.sessionId),
-                    kind: OPENCLAW_HANDOFF_AUTHORITY_KIND,
-                    target: {
-                        type: "turn_id",
-                        id: requiredString(params.turn_id, "turn_id")
-                    },
-                    tool: "agent_knock_knock_close",
-                    matches: (argumentsValue) => stringValue(argumentsValue.turn_id) ===
-                        stringValue(params.turn_id) &&
-                        stringValue(argumentsValue.reason) ===
-                            "superseded_by_human_context_switch"
-                })
-                : undefined;
             pushTurnTarget(args, params);
             pushOptional(args, "--reason", stringValue(params.reason));
             pushOptional(args, "--expected-message-id", stringValue(params.expected_message_id));
             pushOptional(args, "--expected-transition-id", stringValue(params.expected_transition_id));
-            pushOptional(args, "--expected-handoff-token", handoffAction
-                ? requiredString(handoffAction.expected_handoff_token, "current internal handoff authority")
-                : undefined);
             pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
             return args;
         }
@@ -428,10 +407,17 @@ async function handleAkkCommand(api, ctx, displayedResumeSnapshots) {
         }
         if (parsed.action === "delegate") {
             const result = await runDelegate(api, {
-                request: parsed.request
+                request: parsed.request,
+                messageId: `openclaw-command-${randomUUID()}`
             }, {
                 sessionKey: ctx.sessionKey
             });
+            if (result.scope === "terminal_user_explicit") {
+                return {
+                    text: formatSendCommandResult(result),
+                    isError: sendCommandResultIsError(result)
+                };
+            }
             return {
                 text: formatDelegateCommandResult(result),
                 isError: result.status !== "async_pending"
@@ -449,7 +435,10 @@ async function handleAkkCommand(api, ctx, displayedResumeSnapshots) {
                 sessionId: requiredOpenClawSessionId(ctx.sessionId)
             })
             : buildAkkCommandCliArgs(parsed, config, {
-                sessionKey: ctx.sessionKey
+                sessionKey: ctx.sessionKey,
+                messageId: parsed.action === "send"
+                    ? `openclaw-command-${randomUUID()}`
+                    : undefined
             });
         if (!args) {
             return { text: akkUsageText(), isError: true };
@@ -476,9 +465,7 @@ async function handleAkkCommand(api, ctx, displayedResumeSnapshots) {
             case "send":
                 return {
                     text: formatSendCommandResult(result),
-                    isError: terminalSubmissionReported(result)
-                        ? !isAkkNativeSubmissionAccepted(result)
-                        : result.status === "delivered_unfenced"
+                    isError: sendCommandResultIsError(result)
                 };
             case "respond":
                 return formatAkkRespondCommandResult(result);
@@ -505,6 +492,14 @@ async function handleAkkCommand(api, ctx, displayedResumeSnapshots) {
         };
     }
 }
+function sendCommandResultIsError(result) {
+    return result.delivered === true &&
+        result.scope === "terminal_user_explicit"
+        ? false
+        : terminalSubmissionReported(result)
+            ? !isAkkNativeSubmissionAccepted(result)
+            : result.status === "delivered_unfenced";
+}
 async function handleAkkLifecycleCommand(api, ctx, parsed, config, displayedResumeSnapshots) {
     const selectionScope = resumeSelectionScope(ctx.sessionKey, ctx.sessionId);
     const snapshotCacheKey = resumeSnapshotCacheKey(ctx.sessionKey, ctx.sessionId, parsed.terminalId);
@@ -808,6 +803,37 @@ function formatRetryCallbackCommandResult(result) {
     ].join("\n");
 }
 function formatSendCommandResult(result) {
+    if (result.scope === "terminal_user_explicit") {
+        const unmanaged = result.delivered_unmanaged === true;
+        const replayed = result.replayed === true;
+        if (result.delivered !== true) {
+            return [
+                "AKK already dispatched this managed terminal Send; native acceptance is still pending.",
+                `terminal: ${result.terminal_id ?? "unknown"}`,
+                `message: ${result.message_id ?? "unknown"}`,
+                "delivery: Enter dispatched; do not resend this message id.",
+                "next: inspect AKK status or the terminal; wait for the existing managed Turn."
+            ].join("\n");
+        }
+        return [
+            unmanaged
+                ? replayed
+                    ? "AKK confirmed this direct terminal Send was already delivered."
+                    : "AKK delivered the user's request directly to the coding agent."
+                : replayed
+                    ? "AKK confirmed this managed terminal Send was already delivered."
+                    : "AKK delivered the user's terminal Send through managed routing.",
+            `terminal: ${result.terminal_id ?? "unknown"}`,
+            `message: ${result.message_id ?? "unknown"}`,
+            `delivery: ${unmanaged ? "unmanaged fallback" : "managed"}`,
+            ...(unmanaged
+                ? ["callback: none; no AKK Turn was created for this delivery."]
+                : []),
+            unmanaged
+                ? "next: refresh AKK list and use Watch to observe the still-running coding-agent task."
+                : "next: refresh AKK list; do not resend this message id."
+        ].join("\n");
+    }
     const conversation = result.conversation ?? {};
     const conversationId = conversation.conversation_id ?? result.conversation_id ?? "unknown";
     const sessionId = conversation.session_id ?? result.session_id ?? conversationId;
@@ -948,7 +974,12 @@ function formatCloseCommandResult(result) {
         "AKK Turn record closed.",
         `session: ${sessionId}`,
         `turn: ${turnId}`,
-        `status: ${conversation.status ?? "unknown"}`
+        `status: ${conversation.status ?? "unknown"}`,
+        "AKK management was released; the coding agent and terminal pane were not stopped.",
+        ...(Array.isArray(result.warnings) && result.warnings.length > 0
+            ? [`cleanup warnings: ${result.warnings.map((warning) => sanitizeAkkModelFacingDiagnosticText(String(warning))).join("; ")}`]
+            : []),
+        "Refresh the AKK list; if the coding agent is still working, Watch can attach to it again."
     ].join("\n");
 }
 function publicTurnIdentity(result) {
@@ -1016,6 +1047,22 @@ function terminalScreenExcerpt(result) {
         : `…${text.slice(-1599)}`;
 }
 async function runSendRequest(api, params, toolContext, messageId) {
+    if (Object.hasOwn(params, "turn_id")) {
+        const unexpected = Object.keys(params).filter((key) => key !== "turn_id");
+        if (unexpected.length > 0) {
+            throw new Error("send retry_submission accepts exactly turn_id; do not pass request, terminal_id, session_id, timeout overrides, or callback route data");
+        }
+        const turnId = authoritativeManagedId(params.turn_id, "turn_id");
+        privateActionArguments(api, {
+            tool: "agent_knock_knock_send",
+            matches: (argumentsValue) => Object.keys(argumentsValue).length === 1 &&
+                stringValue(argumentsValue.turn_id) === turnId
+        });
+        const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+        const args = ["send", "--turn", turnId];
+        pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+        return runCli(api, args);
+    }
     const requestedType = Object.hasOwn(params, "type")
         ? stringValue(params.type)
         : "task";
@@ -1410,6 +1457,10 @@ function isSubmissionError(result) {
     if (!isRecord(result)) {
         return false;
     }
+    if (result.delivered === true &&
+        result.scope === "terminal_user_explicit") {
+        return false;
+    }
     if (terminalSubmissionReported(result)) {
         return !isAkkNativeSubmissionAccepted(result);
     }
@@ -1512,6 +1563,12 @@ async function runDelegate(api, params, toolContext) {
     if (!isRecord(parsed)) {
         throw new Error("agent-knock-knock delegate returned a non-object result");
     }
+    if (parsed.scope === "terminal_user_explicit") {
+        // A uniquely delegated user-priority Send may deliberately complete
+        // without creating a managed Turn. Preserve that terminal receipt for the
+        // shared Send formatter instead of inventing Session/Turn identity.
+        return parsed;
+    }
     const conversationId = stringValue(parsed.conversation_id) ??
         (isRecord(parsed.conversation)
             ? stringValue(parsed.conversation.conversation_id)
@@ -1819,12 +1876,9 @@ function assertExclusiveRecoveryFence(params) {
     if (closeFenceCount > 1) {
         throw new Error("close accepts only one of expected_message_id or expected_transition_id");
     }
-    const handoffReason = stringValue(params.reason) ===
-        "superseded_by_human_context_switch";
-    if (handoffReason && (!stringValue(params.turn_id) ||
-        stringValue(params.conversation_id) ||
-        closeFenceCount > 0)) {
-        throw new Error("human-context handoff requires only the exact managed turn_id and supersede reason");
+    if (stringValue(params.reason) === "superseded_by_human_context_switch" &&
+        (!stringValue(params.turn_id) || stringValue(params.conversation_id))) {
+        throw new Error("human-context handoff Close requires the exact managed turn_id");
     }
 }
 export function pushOptional(args, flag, value) {