@scotthuang/agent-knock-knock 0.12.28 → 0.12.30

package/dist/src/host-adapter.d.ts

@@ -43,7 +43,7 @@ export interface HostAdapter {
     disposeContext(authority: object): void;
 }
 /**
- * Adapt AKK's established slash command and 16 semantic tools to a native Host.
+ * Adapt AKK's established slash command and 17 semantic tools to a native Host.
  *
  * Public metadata is captured exactly once. Executable registries are created
  * lazily per exact Host authority object so private approvals, action offers,

package/dist/src/host-adapter.js

@@ -9,7 +9,7 @@ const METADATA_CONTEXT = Object.freeze({
     sessionId: "host-adapter:metadata"
 });
 /**
- * Adapt AKK's established slash command and 16 semantic tools to a native Host.
+ * Adapt AKK's established slash command and 17 semantic tools to a native Host.
  *
  * Public metadata is captured exactly once. Executable registries are created
  * lazily per exact Host authority object so private approvals, action offers,

package/dist/src/host-bridge-tools.js

@@ -97,8 +97,8 @@ export function createHostBridgeToolRegistry(options) {
     if (!commandDescriptor) {
         throw new Error("host bridge did not capture the akk command");
     }
-    if (descriptors.length !== 16) {
-        throw new Error(`host bridge expected 16 semantic tools, received ${descriptors.length}`);
+    if (descriptors.length !== 17) {
+        throw new Error(`host bridge expected 17 semantic tools, received ${descriptors.length}`);
     }
     const listed = Object.freeze([...descriptors]);
     const capturedCommand = commandDescriptor;

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

@@ -3,10 +3,12 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { executorDefinitionForKind } from "./executors.js";
+import { isTerminalApprovalDecision } from "./terminal-agent-adapter.js";
 import { isRecord, nonBlankString as stringValue } from "./value-guards.js";
 import { AKK_CALLBACK_METHOD, akkUsageText, buildAkkCommandCliArgs, formatAkkListCommandResult, formatAkkRespondCommandResult, formatAkkTerminalWatchHint, formatAkkThreadsCommandResult, formatAkkThreadTransitionCommandResult, formatAkkUnwatchCommandResult, formatAkkWatchCommandResult, formatAkkWatchStatusCommandResult, isAkkModelFacingDiagnosticField, isAkkModelFacingPrivateAuthorityField, isAkkNativeSubmissionAccepted, isAkkThreadTransitionSuccess, normalizeAkkModelFacingFieldName, parseAkkCommand, resolvePluginStoreDir, sanitizeAkkModelFacingDiagnosticText, sanitizeAkkModelFacingLegacyAuthorityInstructionText } from "./openclaw-plugin-helpers.js";
-import { approveParameters, cancelParameters, closeParameters, listParameters, listResumableThreadsParameters, nativeInspectParameters, newThreadParameters, reconcileBindingParameters, renewParameters, respondParameters, resumeThreadParameters, retryCallbackParameters, sendParameters, statusParameters, unwatchParameters, watchParameters } from "./openclaw-plugin-schemas.js";
-import { consumeOpenClawPrivateAuthorityOffer, openClawApprovalAuthorityOfferKey, rememberOpenClawPrivateAuthorityOffer } from "./openclaw-private-authority-offers.js";
+import { approveParameters, cancelParameters, closeParameters, listParameters, listResumableThreadsParameters, nativeInspectParameters, newThreadParameters, reconcileBindingParameters, renewParameters, respondInteractionParameters, respondParameters, resumeThreadParameters, retryCallbackParameters, sendParameters, statusParameters, unwatchParameters, watchParameters } from "./openclaw-plugin-schemas.js";
+import { consumeOpenClawPrivateAuthorityOffer, openClawApprovalAuthorityOfferKey, openClawInteractionAuthorityOfferKey, rememberOpenClawPrivateAuthorityOffer } from "./openclaw-private-authority-offers.js";
+import { TERMINAL_INTERACTION_LIMITS, validateTerminalInteractionProjection, validateTerminalInteractionResponse } from "./terminal-interaction-protocol.js";
 const MAX_DISPLAYED_RESUME_SNAPSHOTS = 512;
 const OPENCLAW_HANDOFF_AUTHORITY_KIND = "handoff";
 const OPENCLAW_RECONCILE_BINDING_AUTHORITY_KIND = "reconcile_binding";
@@ -272,6 +274,7 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
                 const result = await runHostAwareCli(api, buildStatusCliArgs(api, isRecord(params) ? params : {}));
                 const rendered = toolResult(result);
                 rememberDisplayedApprovalOffer(api, toolContext?.sessionKey, toolContext?.sessionId, result);
+                rememberDisplayedInteractionOffer(api, toolContext?.sessionKey, toolContext?.sessionId, result);
                 return rendered;
             }
             catch (error) {
@@ -324,9 +327,18 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
             return args;
         }
     });
+    registerCliTool(api, {
+        name: "agent_knock_knock_respond_interaction",
+        description: "Answer exactly one current native questionnaire step shown by agent_knock_knock_status in this controller conversation. Supply only the exact turn_id, interaction_id, and typed semantic answer using advertised question_id and option_id values. AKK consumes the displayed private offer and revalidates its prompt, expiry, owner, and terminal authority before any input. Raw keys, menu indexes, rendered labels, fingerprints, versions, and terminal commands are never accepted. An uncertain response must never be retried blindly.",
+        parameters: respondInteractionParameters,
+        buildArgs: (params, toolContext) => buildPrivateInteractionResponseArgs(api, params, {
+            sessionKey: requiredOpenClawSessionKey(toolContext?.sessionKey),
+            sessionId: requiredOpenClawSessionId(toolContext?.sessionId)
+        })
+    });
     registerCliTool(api, {
         name: "agent_knock_knock_approve",
-        description: "Manually approve the current exact permission request only after the user reviews and explicitly confirms it. Use turn_id for a managed Turn or terminal_id for a separately advertised terminal-scoped approval. AKK privately refreshes the approval prompt and terminal authority, then the CLI recaptures the same prompt under lock before sending keys. Never retry an interrupted approval blindly. This tool cannot enable automatic approval.",
+        description: "Dispatch one closed semantic decision for the current exact permission request only after the user reviews and explicitly chooses it. decision defaults to approve_once for compatibility; reject is available only on a managed Turn when the adapter proves a safe native reject choice. Use turn_id for a managed Turn or terminal_id for a separately advertised approve_once-only terminal action. AKK privately refreshes the prompt and authority, then recaptures it under lock. Raw keys, indexes, and labels are not accepted. Never retry an interrupted decision blindly.",
         parameters: approveParameters,
         buildArgs: (params, toolContext) => buildPrivateApprovalArgs(api, params, {
             sessionKey: requiredOpenClawSessionKey(toolContext?.sessionKey),
@@ -459,7 +471,10 @@ async function handleAkkCommand(api, ctx, displayedResumeSnapshots) {
             return await handleAkkLifecycleCommand(api, ctx, parsed, config, displayedResumeSnapshots);
         }
         const args = parsed.action === "approve"
-            ? await buildPrivateApprovalArgs(api, { turn_id: parsed.turnId }, {
+            ? await buildPrivateApprovalArgs(api, {
+                turn_id: parsed.turnId,
+                decision: parsed.decision
+            }, {
                 sessionKey: requiredOpenClawSessionKey(ctx.sessionKey),
                 sessionId: requiredOpenClawSessionId(ctx.sessionId)
             })
@@ -1261,13 +1276,45 @@ function rememberDisplayedApprovalOffer(api, sessionKeyValue, sessionIdValue, re
     const sessionId = stringValue(sessionIdValue);
     if (!sessionKey || !sessionId || !isRecord(result))
         return;
-    const fingerprints = currentApprovalFingerprints(result);
-    if (fingerprints.length !== 1)
+    const decisionFingerprints = currentApprovalDecisionFingerprints(result);
+    const fingerprint = decisionFingerprints.approve_once;
+    if (!fingerprint)
         return;
     const target = approvalTargetFromStatus(result);
     if (!target)
         return;
-    rememberOpenClawPrivateAuthorityOffer(api, openClawApprovalAuthorityOfferKey(sessionKey, sessionId, target), { fingerprint: fingerprints[0] });
+    rememberOpenClawPrivateAuthorityOffer(api, openClawApprovalAuthorityOfferKey(sessionKey, sessionId, target), {
+        fingerprint,
+        decision_fingerprints: decisionFingerprints
+    });
+}
+function rememberDisplayedInteractionOffer(api, sessionKeyValue, sessionIdValue, result) {
+    const sessionKey = stringValue(sessionKeyValue);
+    const sessionId = stringValue(sessionIdValue);
+    if (!sessionKey || !sessionId || !isRecord(result))
+        return;
+    const terminalStatus = isRecord(result.terminal_status)
+        ? result.terminal_status
+        : undefined;
+    const fingerprint = stringValue(terminalStatus?.interaction_prompt_fingerprint);
+    if (!isExactInteractionFingerprint(fingerprint))
+        return;
+    let interactionState;
+    try {
+        interactionState = validateTerminalInteractionProjection(terminalStatus?.interaction_state);
+    }
+    catch {
+        return;
+    }
+    if (interactionState.state !== "pending" ||
+        interactionState.capabilities.respond !== true ||
+        publicTurnIdentity(result).turnId !== interactionState.turn_id) {
+        return;
+    }
+    rememberOpenClawPrivateAuthorityOffer(api, openClawInteractionAuthorityOfferKey(sessionKey, sessionId, interactionState.turn_id, interactionState.interaction_id), {
+        fingerprint,
+        interaction_state: interactionState
+    });
 }
 function approvalTargetFromStatus(result) {
     const conversationId = stringValue(result.conversation_id);
@@ -1340,27 +1387,43 @@ function authoritativeHandoffActionArguments(terminals) {
             : [];
     });
 }
-function currentApprovalFingerprint(result) {
-    const unique = isRecord(result) ? currentApprovalFingerprints(result) : [];
-    if (unique.length !== 1) {
-        throw new Error("the current status does not contain one exact approvable prompt; refresh status and ask the user to review it again");
+function currentApprovalFingerprint(result, decision) {
+    const fingerprint = isRecord(result)
+        ? currentApprovalDecisionFingerprints(result)[decision]
+        : undefined;
+    if (!fingerprint) {
+        throw new Error(`the current status does not contain one exact ${decision} choice; refresh status and ask the user to review it again`);
     }
-    return unique[0];
+    return fingerprint;
 }
 async function buildPrivateApprovalArgs(api, params, { sessionKey, sessionId }) {
     const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
     const turnId = stringValue(params.turn_id);
     const terminalId = stringValue(params.terminal_id);
+    const decisionValue = params.decision ?? "approve_once";
+    if (!isTerminalApprovalDecision(decisionValue)) {
+        throw new Error("decision must be one of: approve_once, reject");
+    }
+    const decision = decisionValue;
     if (Boolean(turnId) === Boolean(terminalId)) {
         throw new Error("approve requires exactly one of turn_id or terminal_id");
     }
+    if (terminalId && decision !== "approve_once") {
+        throw new Error("terminal-scoped approval supports approve_once only; reject requires an exact managed Turn");
+    }
     const target = terminalId
         ? { type: "terminal_id", id: terminalId }
         : { type: "turn_id", id: requiredString(turnId, "turn_id") };
     const offered = consumeOpenClawPrivateAuthorityOffer(api, openClawApprovalAuthorityOfferKey(sessionKey, sessionId, target));
-    const offeredFingerprint = stringValue(offered?.fingerprint) ??
+    const offeredDecisions = isRecord(offered?.decision_fingerprints)
+        ? offered.decision_fingerprints
+        : undefined;
+    const offeredFingerprint = stringValue(offeredDecisions?.[decision]) ??
+        (decision === "approve_once" ? stringValue(offered?.fingerprint) : undefined) ??
         (isRecord(offered?.args)
-            ? stringValue(offered.args.expected_approval_fingerprint)
+            ? decision === "approve_once"
+                ? stringValue(offered.args.expected_approval_fingerprint)
+                : undefined
             : undefined);
     if (!isExactApprovalFingerprint(offeredFingerprint)) {
         throw new Error("approve requires a current approval request shown by agent_knock_knock_status in this controller conversation; refresh status, ask the user to review it, and explicitly confirm again");
@@ -1387,10 +1450,11 @@ async function buildPrivateApprovalArgs(api, params, { sessionKey, sessionId })
     else {
         args.push("--turn", requiredString(turnId, "turn_id"));
     }
-    const currentFingerprint = currentApprovalFingerprint(await runHostAwareCli(api, statusArgs));
+    const currentFingerprint = currentApprovalFingerprint(await runHostAwareCli(api, statusArgs), decision);
     if (currentFingerprint !== offeredFingerprint) {
         throw new Error("the approval request changed after it was shown; refresh AKK status, ask the user to review the current request, and explicitly confirm again");
     }
+    args.push("--decision", decision);
     args.push("--expected-approval-fingerprint", currentFingerprint);
     if (terminalId) {
         args.push("--expected-terminal-token", requiredString(action?.expected_terminal_token, "current internal terminal approval authority"));
@@ -1398,10 +1462,43 @@ async function buildPrivateApprovalArgs(api, params, { sessionKey, sessionId })
     pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
     return args;
 }
+function buildPrivateInteractionResponseArgs(api, params, { sessionKey, sessionId }) {
+    const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+    const turnId = requiredTerminalInteractionIdentifier(params.turn_id, "turn_id");
+    const interactionId = requiredTerminalInteractionIdentifier(params.interaction_id, "interaction_id");
+    const offered = consumeOpenClawPrivateAuthorityOffer(api, openClawInteractionAuthorityOfferKey(sessionKey, sessionId, turnId, interactionId));
+    const fingerprint = stringValue(offered?.fingerprint);
+    if (!isExactInteractionFingerprint(fingerprint) ||
+        offered?.interaction_state === undefined) {
+        throw new Error("respond_interaction requires a current pending interaction shown by agent_knock_knock_status in this controller conversation; refresh status, review the current questions, and respond again");
+    }
+    const projection = validateTerminalInteractionProjection(offered.interaction_state);
+    const response = validateTerminalInteractionResponse(params, projection);
+    const args = [
+        "respond-interaction",
+        "--turn",
+        response.turn_id,
+        "--interaction",
+        response.interaction_id,
+        "--response-json",
+        JSON.stringify(response),
+        "--expected-interaction-fingerprint",
+        fingerprint,
+        "--expected-interaction-expires-at",
+        projection.expires_at,
+        "--openclaw-session",
+        sessionKey
+    ];
+    pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+    return args;
+}
 function isExactApprovalFingerprint(value) {
     return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
 }
-function currentApprovalFingerprints(result) {
+function isExactInteractionFingerprint(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+}
+function currentApprovalDecisionFingerprints(result) {
     const terminalStatus = isRecord(result.terminal_status)
         ? result.terminal_status
         : undefined;
@@ -1411,14 +1508,31 @@ function currentApprovalFingerprints(result) {
             ? terminalStatus.approval_state
             : undefined
     ];
-    return [...new Set(states.flatMap((state) => {
-            const fingerprint = state?.approvable === true
-                ? stringValue(state.fingerprint)
-                : undefined;
-            return fingerprint && /^[a-f0-9]{64}$/u.test(fingerprint)
-                ? [fingerprint]
-                : [];
-        }))];
+    const found = new Map();
+    const remember = (decision, value) => {
+        if (!isExactApprovalFingerprint(value))
+            return;
+        const fingerprints = found.get(decision) ?? new Set();
+        fingerprints.add(value);
+        found.set(decision, fingerprints);
+    };
+    for (const state of states) {
+        const fingerprint = state?.approvable === true
+            ? stringValue(state.fingerprint)
+            : undefined;
+        remember("approve_once", fingerprint);
+        if (state?.approvable !== true || !Array.isArray(state.choices))
+            continue;
+        for (const choice of state.choices) {
+            if (isRecord(choice) &&
+                isTerminalApprovalDecision(choice.decision)) {
+                remember(choice.decision, choice.fingerprint);
+            }
+        }
+    }
+    return Object.fromEntries([...found.entries()].flatMap(([decision, fingerprints]) => fingerprints.size === 1
+        ? [[decision, [...fingerprints][0]]]
+        : []));
 }
 function sanitizeModelFacingValue(value, parentKey, path = []) {
     if (Array.isArray(value)) {
@@ -1449,6 +1563,15 @@ function sanitizeModelFacingValue(value, parentKey, path = []) {
             (key === "fingerprint" && parentKey === "approval_state")) {
             continue;
         }
+        if (key === "interaction_state") {
+            try {
+                output[key] = validateTerminalInteractionProjection(item);
+            }
+            catch {
+                continue;
+            }
+            continue;
+        }
         output[key] = sanitizeModelFacingValue(item, key, [...path, key]);
     }
     if (output.tool === "agent_knock_knock_send" && isRecord(output.arguments)) {
@@ -2000,6 +2123,14 @@ function requiredOpenClawSessionKey(value) {
 function requiredOpenClawSessionId(value) {
     return requiredString(value, "Controller conversation incarnation for this confirmed action");
 }
+function requiredTerminalInteractionIdentifier(value, name) {
+    const identifier = requiredString(value, name);
+    if (identifier.length > TERMINAL_INTERACTION_LIMITS.maxIdentifierLength ||
+        !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(identifier)) {
+        throw new Error(`${name} must be an exact safe interaction identifier`);
+    }
+    return identifier;
+}
 function parseJson(text) {
     try {
         return JSON.parse(text);