@scotthuang/agent-knock-knock 0.14.13 → 0.14.15

package/docs/codex-desktop-compatibility.md

@@ -4,7 +4,7 @@ AKK can discover an existing local Codex Desktop conversation, send a task to
 its original Desktop owner, and monitor the exact native task for completion
 or attention. It can notify and answer asynchronous questions in the same active
 native task. It does not open a second CLI conversation from the same history.
-On the fully reviewed build, command/file approvals, blocking questions, session settings, and exact task interruption use that same original owner. Other builds have narrower capability profiles; unsupported controls remain manual.
+Command/file approvals, blocking questions, session settings, and exact task interruption use that same original owner. Starting in AKK 0.14.14, an application update alone does not disable these operations: AKK attempts its implemented native contracts and reports actual incompatibility.
 
 AKK 0.14.0 introduces these Desktop controls. See the [README](../README.md)
 for the first-task workflow and [OpenClaw installation](openclaw-operations.md#choose-one-installation-path)
@@ -12,29 +12,33 @@ for packaged and optional source installation.
 
 ## Version and platform evidence
 
-Desktop compatibility is checked per capability against an exact application
-version and build. It is not a minimum-version promise:
-
-| macOS Desktop application | Send to live owner / Status / Watch | Native approvals, answers, model/permission changes, cancellation | New conversation |
-| --- | --- | --- | --- |
-| `26.1002.52244` / `13536` | Existing verified adapter | Existing verified adapter | Not enabled |
-| `26.1007.30912` / `20156` | Send profile for the new-conversation workflow; read-only observation retains exact owner/turn checks | Command/file approvals in AKK 0.14.7; blocking and asynchronous answers in AKK 0.14.8. Model/permission changes and cancellation remain unavailable | Available in AKK 0.14.5; see the creation boundary below |
-| `26.1007.71326` / `20398` | AKK 0.14.9: exact owner, Send, public progress and exact-task completion | Command/file approvals, blocking/asynchronous answers, effective model/permission settings and exact cancellation | Available in AKK 0.14.9; projectless creation and first-task handoff verified |
-| Other builds | Compatible read-only observations may work; no native writes are advertised | Not enabled | Not enabled |
-
-The `20156` profile does not inherit the old build's full native controls.
-AKK 0.14.6 exposes pending interactions but requires handling them in
-Desktop. AKK 0.14.7 adds an Approve action for recognized
-command/file requests, with explicit `approve_once` or `reject` decisions.
-AKK 0.14.8 enables blocking and asynchronous
-answers through separate `blockingAnswers` and `asyncAnswers` capability checks.
-On `20156`, settings, model/permission changes, and cancellation still require Desktop.
-Watch attention notifications follow the same per-operation boundary.
-`desktop_scan.send_contract_verified` reports the Send profile;
-`approval_contract_verified` reports the per-build approval profile;
-`write_contract_verified` continues to mean the full native-control profile.
-The Send profile and creation workflow are available starting in AKK 0.14.5.
-These question capabilities do not change the existing `13536` full-control profile or enable writes on unknown builds.
+The following matrix records tested combinations, not an allowlist or a minimum
+version. Starting in AKK 0.14.14, all implemented Desktop operations may be
+attempted on an unreviewed application/build. Actual application identity, protocol, owner, task,
+revision, input and interaction checks still apply. A connection or incompatible
+response fails explicitly; AKK does not switch to UI typing or blindly retry a
+possibly submitted operation.
+
+| macOS Desktop application | Existing-conversation evidence | Creation evidence |
+| --- | --- | --- |
+| `26.1002.52244` / `13536` | Send, Status, Watch, approvals, answers, model/permission settings and exact cancellation | Not live-verified |
+| `26.1007.30912` / `20156` | Send/Status/Watch, command/file approvals, blocking and asynchronous answers; settings and cancellation not live-verified | Project and projectless creation, original-owner first task |
+| `26.1007.71326` / `20398` | Send, public progress, exact completion, approvals, both answer forms, effective model/permission settings and cancellation | Projectless creation and original-owner first task |
+| Other builds | Attempt the implemented contracts; not claimed as live-verified | Attempt with verified bundle identity and a compatible real backend handshake; not claimed as live-verified |
+
+`compatibility_policy: "attempt_native_contract"` describes this policy.
+Per-conversation `capability_verification` and `desktop_scan` fields
+`send_contract_verified`, `approval_contract_verified` and `write_contract_verified`
+remain evidence about the installed build, not permission to dispatch. In
+particular, a contract-verification value of `false` does not by itself make Send
+or another supported action unavailable. `application_identity_verified: false`
+is different: AKK could not verify the installed Codex application, so writes
+remain disabled. Use fresh action availability and the actual operation result.
+
+An operation can still be unavailable because no live owner is verified, the
+conversation is busy, a request has expired, or the native contract is not
+recognized. Missing API support is reported, not invented. Arbitrary cold
+loading/resume and a Desktop model catalog remain unsupported.
 
 The original fully reviewed application is macOS Codex Desktop `26.1002.52244`, build `13536`,
 bundle ID `com.openai.codex`, installed as `/Applications/ChatGPT.app`. These
@@ -46,10 +50,10 @@ uses that version.
 A read-only audit on 2026-10-10 reconfirmed those installed bundle values.
 [The runtime](../src/desktop-runtime.ts) currently reads that fixed application
 path on Darwin and requires the correct bundle ID.
-[The capability profiles](../src/desktop-compatibility.ts) require both
-the version and build to match exactly for each operation. This is **not a minimum version** or a
-promise of compatibility with later builds. An unreviewed build may still
-return a compatible read-only snapshot; that does not authorize native writes.
+[The capability profiles](../src/desktop-compatibility.ts) retain exact
+application/build matches as verification metadata. Dispatch uses the actual
+contract checks, independently of that historical matrix. This does not promise
+compatibility with every later protocol.
 
 The app's own `LSMinimumSystemVersion=13.0` metadata is not an AKK-verified
 minimum macOS version. No Desktop Linux/Windows or alternate installation-path
@@ -71,11 +75,11 @@ build, not the latest build available to every account.
 
 The bundled owner/follower IPC still uses the existing exact Send, approval,
 typed input, asynchronous steer, settings and interruption contracts. AKK adds
-an exact application/build profile; it does not permit future builds or remove
-the private socket, owner, revision, task or interaction checks. Creation also
-checks the installed app and bundled backend as one verified tuple. Mixing a
-known application version with another build or backend is rejected before the
-creation process starts.
+an exact application/build evidence profile. In 0.14.9 this was also a write
+allowlist; 0.14.14 removes that version gate while retaining the private socket,
+owner, revision, task and interaction checks. Creation verifies the actual
+bundled binary and its initialized backend identity instead of requiring a
+previously recorded version tuple.
 
 The dedicated real Desktop acceptance run verified:
 
@@ -117,9 +121,29 @@ The dedicated conversation finished idle in Default mode, with `gpt-6-astra`,
 not restore an inherited `null` effort; no user conversation or global default
 was changed to perform this validation.
 
+## Version-policy validation — AKK 0.14.14
+
+Isolated protocol regressions cover unreviewed app/build values for Send,
+creation, approvals, both answer forms, settings and cancellation, while keeping
+verification metadata false. They also cover actual unsupported responses,
+explicit application-identity failure, stale or mismatched identity, and zero
+replay after uncertain dispatch. These fixtures do not establish compatibility
+with a future installed Desktop version.
+
+A dedicated real run on build `20398` exercised creation and first-task handoff,
+Send/public progress/exact completion, command approval with native execution,
+Unicode asynchronous answers, a two-question typed answer, permission and
+model/effort/mode readback, exact interruption and a subsequent successful task.
+Six exact tasks settled: five completed and one intentionally interrupted.
+All nine attention/completion notifications were accepted once at an isolated
+local receiver. No user work conversation or external chat channel was used.
+The new test conversation finished idle in Default mode, with `gpt-6-astra`,
+`medium` effort and Read Only permissions. The initially inherited null effort
+is not restored by the explicit settings API; no user default was changed.
+
 ## Capability boundary
 
-| Operation | Behavior on full-control builds `13536` and `20398` |
+| Operation | Implemented behavior, subject to the actual native contract and state |
 | --- | --- |
 | List | Default to persisted expanded sidebar membership; offer the broader saved catalog with explicit `desktop_view: "history"`; retain unconnected rows and support search, project filtering, and pagination |
 | Status | Read a fresh snapshot from the exact local Desktop owner when available; report unknown live state when only metadata is available |
@@ -135,7 +159,7 @@ was changed to perform this validation.
 | Cancellation | Interrupt the exact selected native task; an old task ID never cancels a newer task |
 | Unwatch | Stop observation without cancelling or changing the Desktop task |
 | Existing-conversation cold loading, resume | Not supported by the Desktop adapter |
-| New conversation | Separate creation workflow; supported application/backend combinations are listed above |
+| New conversation | Separate creation workflow; bundle/backend identity, compatible initialization and original-owner handoff are required |
 
 No Desktop operation types a slash command or uses terminal activity as exact
 completion evidence. Existing terminal capabilities remain separate and retain
@@ -202,8 +226,8 @@ The Plan-mode change was dedicated test setup through native IPC, not evidence
 that AKK model/settings controls are enabled on this build. Permissions remained
 Read Only/on-request and the model was unchanged. The test conversation was
 restored to Default mode and left idle with no pending interaction. These question changes enable
-only the separately checked answer operations; settings and cancellation retain
-their existing build restrictions. The original isolated validation did not
+only the separately checked answer operations in AKK 0.14.8; the version
+restrictions on settings and cancellation were removed in 0.14.14. The original isolated validation did not
 install the package or send notifications to external chat channels.
 
 The native typed `item/tool/requestUserInput` form may have `isBlocking: false`.
@@ -242,8 +266,9 @@ conversation. A failed or uncertain create/load/send stage must preserve its
 record and exact identities; it must not silently create another conversation
 or replay a task. AKK 0.14.7 supports the command/file approvals described
 above on build `20156`; AKK 0.14.8 adds blocking
-and asynchronous question replies. Model/permission changes and cancellation
-remain unavailable on `20156`; the separate `20398` validation is recorded above.
+and asynchronous question replies. From AKK 0.14.14, model/permission changes
+and cancellation can also be attempted on `20156`, but this is not a new
+live-validation claim; the separate `20398` evidence is recorded above.
 
 ## Find and select a conversation
 
@@ -424,9 +449,10 @@ This adapter uses the app's private local IPC socket under the selected Codex
 home. The reviewed route discovers the current thread owner, follows its
 state stream, and submits through that owner. It validates socket ownership,
 message shapes, peer identity, thread identity, revision freshness, pending
-interactions, and the send receipt. Each write requires its own reviewed Desktop
-version/build capability profile. This IPC surface is not an official stable third-party API;
-an app upgrade may require another compatibility review.
+interactions, and the send receipt. Application/build profiles record tested
+evidence without blocking attempts on newer versions. This IPC surface is not an
+official stable third-party API; an incompatible protocol can still require an
+adapter update after an app upgrade.
 
 Catalog reads copy supported SQLite database/WAL files to a private temporary
 directory, validate the copy, and query it without opening the user's source

package/docs/desktop-create.md

@@ -129,9 +129,12 @@ not a new external-channel delivery claim. See the
 [validation record](codex-desktop-compatibility.md#build-20398-validation--akk-0149)
 for the exact effects and remaining limits.
 
-Creation requires one coherent application version/build/bundled-backend
-combination. A later version is not implicitly supported, and a metadata
-creation receipt cannot substitute for a live Desktop owner. The private IPC
+From AKK 0.14.14, creation attempts the installed Desktop’s bundled backend
+without requiring an exact tested version tuple. It verifies bundle identity,
+binary provenance and the real initialized backend identity/home, then checks
+the native creation response. Unsupported methods/parameters produce an
+explicit protocol error. A metadata creation receipt cannot substitute for
+a live Desktop owner, and an uncertain creation is never blindly replayed. The private IPC
 is not a stable public third-party interface; alternate installation paths,
 Windows/Linux and a running owner different from the installed bundle remain
 outside the verified boundary.
@@ -141,8 +144,8 @@ macOS Desktop `26.1007.30912`, build `20156`. It preserves exact owner and task
 checks for Status/Watch. AKK 0.14.7 adds command/file approvals with explicit
 allow-once or reject decisions. AKK 0.14.8 adds
 blocking and asynchronous question replies through the advertised Respond
-action. Permission/model changes and cancellation remain unavailable on this
-build; handle those actions in Desktop. Approval and question replies do not
+action. From AKK 0.14.14, permission/model changes and cancellation can also be
+attempted on this build; they have not been independently live-verified there. Approval and question replies do not
 change the permissions inherited when the conversation was created.
 
 The question changes passed dedicated real Desktop choice, free-text, and
@@ -151,8 +154,9 @@ original-task completion.
 Local callback acceptance does not establish external chat-channel delivery.
 
 The existing full native-control profile for Desktop `26.1002.52244`, build
-`13536`, is unchanged; it does not enable this new creation workflow. These are
-per-capability profiles, not a minimum version or future-version promise.
+`13536`, remains recorded. Creation can now be attempted there too, but is
+not live-verified on that build. These are evidence profiles, not a minimum
+version or a guarantee of future protocol compatibility.
 [Desktop compatibility](codex-desktop-compatibility.md) is the authoritative
 operation matrix.
 

package/docs/openclaw-operations.md

@@ -20,7 +20,7 @@ backend, Desktop, and backend Recovery support described here.
 | --- | --- |
 | Codex CLI shared backend | An authenticated, loaded main CLI conversation on a compatible local backend; [CLI backend guide](codex-cli-native-compatibility.md). No tmux or Herdr required. |
 | Codex Desktop | The supported local app and the intended conversation open in its original owner; [Desktop guide](codex-desktop-compatibility.md). No tmux or Herdr required. |
-| Codex or Claude Code terminal | An authenticated CLI in tmux or local Herdr `0.8.0` using socket protocol 19; [tmux](quickstart-tmux.md) or [Herdr](quickstart-herdr.md) setup. |
+| Codex or Claude Code terminal | An authenticated CLI in tmux or local Herdr with the required operation capabilities; [tmux](quickstart-tmux.md) or [Herdr](quickstart-herdr.md#current-boundary) setup. |
 
 OpenClaw and AKK inspect local processes, private backend endpoints, and any
 selected terminal provider. Workspace is not a routing boundary: exact current

package/docs/quickstart-herdr.md

@@ -1,6 +1,6 @@
 # Quick Start with Herdr
 
-AKK supports local Herdr `0.8.0` (socket protocol 19) as a terminal provider alongside tmux. AKK does not start Herdr or a coding agent.
+Starting in AKK `0.14.15`, local Herdr works alongside tmux according to the capabilities available for each operation. Herdr `0.8.0` (socket protocol 19) and `0.9.5` (socket protocol 22) are tested baselines, not a version allowlist. AKK `0.14.14` supported only `0.8.0`. AKK does not start Herdr or a coding agent.
 
 Install and open Herdr, then start Codex or Claude Code in a pane:
 
@@ -40,10 +40,22 @@ This creates an independent Terminal Watch schema-v3 record, not an AKK Session
 
 Herdr's raw `pane send-text` command is not used for task delivery. AKK uses the Unix-socket `pane.send_input` method so multiline text follows Herdr's bracketed-paste-aware path, persists the text-injected stage, resolves the stable terminal again, and then dispatches one separate Enter.
 
-Current boundary:
+## Current boundary
 
 - local Unix-domain sockets only;
-- exact Herdr `0.8.0`, protocol 19;
+- Herdr version and protocol are observed and must remain consistent during each operation; an unfamiliar pair alone does not prevent discovery;
 - the Codex and Claude Code versions in the main compatibility matrix are regression-tested; other complete `x.y.z` versions use the generic runtime protocol with a warning;
 - remote/SSH Herdr sessions and Windows named pipes are not yet supported;
 - Herdr's agent status is diagnostic only—AKK's existing screen, transcript, rollout, and native identity fences remain authoritative.
+
+Discovery must still prove the current socket, stable pane identity and process anchor. Zero-line, read-only probes independently check each pane's visible text, visible ANSI and detection text response contracts, including their source and format. A failed read capability is unavailable without disabling the other valid capabilities. No discovery or capability probe sends terminal input.
+
+For input, AKK checks `herdr api schema --json` from a CLI whose version matches the live server, requires the schema's protocol to match, and validates the request payload and acknowledgement declarations used by each input operation. The resulting `matching_cli_schema` evidence is a declaration of compatibility, not runtime negotiation or proof of atomic, single-enqueue input. An untested server without a matching declaration can expose only its verified read capabilities. Tested baselines may fall back to their reviewed input behavior when a matching schema is unavailable; an explicitly incompatible or malformed matching schema, including a protocol mismatch, does not use that fallback.
+
+Every operation revalidates current identity and capabilities. Dispatch acknowledgements do not prove that a coding agent accepted a task. For an untested server, an API error after input dispatch remains uncertain, including `pane_send_failed`; AKK does not assume it rejected input before enqueueing. Lost or unknown acknowledgements are never retried automatically.
+
+Doctor checks whether the installed Herdr command is a usable candidate without rejecting an unfamiliar version. It leaves live capabilities `not_probed`; installation readiness does not establish that a live pane can be read or controlled.
+
+The tested baselines include the official [Herdr `0.9.5` release](https://github.com/herdrdev/herdr/releases/tag/v0.9.5) of 2026-10-14 and its [protocol `22` declaration](https://github.com/herdrdev/herdr/blob/v0.9.5/src/protocol/wire.rs#L20). This does not claim live end-to-end Send/Watch validation for untested releases or every coding-agent version.
+
+Herdr's [live server handoff](https://github.com/herdrdev/herdr/blob/v0.9.5/docs/next/website/src/content/docs/session-state.mdx#L127) is experimental. This adapter does not promise uninterrupted tasks across an upgrade or restart. After a server change, refresh discovery so AKK can revalidate the current socket, terminal and process identities before further input.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.14.13",
+  "version": "0.14.15",
   "description": "Delegate to existing Codex CLI, Codex Desktop, and Claude Code sessions from OpenClaw or compatible controller Hosts, with native direct control and supported terminal fallbacks.",
   "license": "MIT",
   "type": "module",

package/templates/openclaw-skills/agent-knock-knock/SKILL.md

@@ -7,7 +7,9 @@ description: Use Agent Knock Knock to discover and control Codex CLI, Codex Desk
 
 Use this skill when the user explicitly invokes `AKK`, `akk`, or `Agent Knock Knock`, or asks a supported controller Host to inspect or control a coding-agent conversation listed by AKK.
 
-AKK supports loaded local Codex CLI threads through their shared backend, local Codex Desktop conversations (with explicit creation when the Desktop Create tool is available), compatible already-open Claude Code CLIs through their native inbox, and Codex or Claude Code already running inside tmux or local Herdr `0.8.0`. It never launches a replacement coding agent. The controller Host, AKK, the coding agent, and its Desktop app or terminal host must run as the same OS user.
+AKK supports loaded local Codex CLI threads through their shared backend, local Codex Desktop conversations (with explicit creation when the Desktop Create tool is available), compatible already-open Claude Code CLIs through their native inbox, and Codex or Claude Code already running inside tmux or local Herdr with the required operation capabilities. It never launches a replacement coding agent. The controller Host, AKK, the coding agent, and its Desktop app or terminal host must run as the same OS user.
+
+Herdr `0.8.0` / protocol `19` and `0.9.5` / protocol `22` are tested baselines, not a version allowlist. Use fresh discovery and advertised actions: each pane's read capabilities are probed without input, while input requires a matching CLI schema declaration or verified baseline behavior. `matching_cli_schema` is declarative evidence from the same CLI version and server protocol, not runtime negotiation or proof of single-enqueue behavior. An untested server without that declaration exposes only verified reads; an incompatible declaration does not fall back to baseline behavior. Doctor installation readiness leaves live capabilities `not_probed`. Once input may have been dispatched, an uncertain response must not be retried automatically.
 
 Treat `AKK` and `akk` the same way.
 
@@ -77,7 +79,7 @@ Desktop rows in `conversations[]` have `surface="desktop"` and a full `desktop:v
 - `model_options({conversation_id})` reads the current model, reasoning effort, and Plan/default mode. Desktop does not expose a model catalog (`catalog_available=false`). Use `set_model({conversation_id,model,reasoning_effort,collaboration_mode?})` only with an explicitly requested model ID; optional `collaboration_mode` is `plan` or `default`. Omitting it preserves the existing mode. Effective settings do not prove a model is available to the account. An unconfirmed update must be inspected, not blindly replayed.
 - Cancel with `cancel({watch_id})` for the exact watched task, or `cancel({conversation_id,expected_native_turn_id})` using the native task ID advertised by fresh Status. A late cancel must never interrupt a newer task. `unwatch` only stops observation. Arbitrary cold loading/resume remains unsupported; explicit creation uses the separate tool below.
 
-Full Desktop control is reviewed for macOS Codex Desktop `26.1002.52244` build `13536` and, in AKK 0.14.9, `26.1007.71326` build `20398` through private local IPC. The `20398` profile also supports new-conversation creation with its verified bundled backend. Its command/file approvals, blocking/asynchronous answers, settings and exact cancellation have dedicated native-effect evidence; callback acceptance is separate from downstream chat delivery. The older `26.1007.30912` build `20156` supports creation, Send/Status/Watch, command/file approvals and blocking/asynchronous answers, but permission/model changes and cancellation remain unavailable there. Use only the currently advertised action. Unknown Desktop builds do not gain native write capability. Read the actual capability and error result after an app update; never downgrade to raw UI input or relax identity checks. The native protocol has no atomic idle-and-send operation, so concurrent human input can make acceptance uncertain. Preserve the returned Watch and reconcile it instead of repeating the task.
+Desktop uses private local IPC. Full controls have native-effect evidence on macOS builds `13536` (`26.1002.52244`) and `20398` (`26.1007.71326`); build `20156` (`26.1007.30912`) has creation, Send/Status/Watch, approval and answer evidence. Starting in AKK 0.14.14, all implemented Desktop operations, including creation and settings, can be attempted on other builds. An app update alone is not a write prohibition. `compatibility_policy: "attempt_native_contract"` describes this behavior; `capability_verification` and `*_contract_verified` describe tested evidence, not current action authority. Use fresh advertised actions and the actual operation result. Protocol, owner, task, revision and interaction checks remain mandatory; actual unsupported interfaces return errors. Never downgrade to raw UI input or relax identity checks. The native protocol has no atomic idle-and-send operation, so concurrent human input can make acceptance uncertain. Preserve the returned Watch and reconcile it instead of repeating the task. Callback acceptance remains separate from downstream chat delivery.
 
 ### Create a Desktop conversation