@scotthuang/agent-knock-knock 0.2.51 → 0.3.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.3.0-beta.2 - 2026-07-28
+
+### Added
+
+- Add bounded real probes and OpenClaw config, plugin runtime, skill, workspace, and Gateway diagnostics to `doctor`.
+- Add fail-closed session selectors, stable short references, and independent five-minute tmux and Managed ACPX quickstarts.
+- Add deterministic onboarding coverage and explicitly opt-in live ACPX and tmux smoke scripts.
+
+### Changed
+
+- Make `install-openclaw` configure workspace, default agent, and mode atomically, preserve approval policy, restart the Gateway at most once, and optionally verify readiness.
+- Verify the packaged README after every ClawHub publish and the default README after stable releases.
+
+## 0.3.0-beta.1 - 2026-07-28
+
+### Added
+
+- Add ClawHub package metadata, bundled skill discovery, a square catalog icon, and a package-local OpenClaw runtime entry.
+- Add manifest/runtime contract tests and a ClawHub validation and dry-run release path.
+
+### Changed
+
+- Compile against the tested OpenClaw `2026.7.1-2` SDK instead of a handwritten type shim.
+- Separate ClawHub and npm installation guidance, including the explicit optional-tool grant required by a clean OpenClaw profile.
+- Publish prerelease builds to npm's `next` dist-tag and mark their GitHub releases as prereleases.
+
+### Fixed
+
+- Align the declared `/akk` command, bundled skill, and tool inventory with the capabilities registered at runtime.
+- Resolve the bundled CLI relative to the loaded plugin entry so ClawHub installs do not depend on a global executable.
+
 ## 0.2.51 - 2026-07-25
 
 ### Added

package/README.md

@@ -5,17 +5,23 @@
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.14-339933)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/scotthuang/agent-knock-knock/blob/main/LICENSE)
 
-Agent Knock Knock connects OpenClaw to local coding agents. Share a live terminal through tmux, delegate managed work through ACP, and continue the same task from chat or the terminal.
+Agent Knock Knock lets you control local Codex and Claude Code from any configured OpenClaw channel, then take over the same live tmux session without losing context. For managed background work, Managed ACP (via ACPX) also supports Cursor.
 
-**No hooks. No agent-side plugins. Just share a terminal and stay in control. No YOLO. Automate the trusted. Review the rest.**
-
-![Agent Knock Knock cover: OpenClaw knocking on coding agents' door](docs/assets/agent-knock-knock-cover.jpg)
+**Local-first, with no hosted control plane or telemetry. tmux mode keeps the coding agent's existing permission settings; Managed ACP uses a separate background permission model.**
 
 ## See It in Action
 
 [![AKK orchestrating a Claude Code-to-Codex handoff through tmux](docs/assets/akk-tmux-handoff-demo.gif)](docs/assets/akk-tmux-handoff-demo.mp4)
 
-*OpenClaw asks Claude Code to write a file, waits for AKK to report completion, then hands the result to Codex. Click the preview to watch in full quality.*
+*OpenClaw asks Claude Code to write a file, waits for AKK to report completion, then hands the result to Codex. Both terminals remain available for direct human takeover. The demo uses the agents' existing permission settings; AKK does not switch them. Click the preview to watch in full quality.*
+
+## Use Cases
+
+**Delegate from anywhere.** Use any configured OpenClaw channel to hand work to a local coding agent wherever you are. AKK keeps the task running outside the chat, reports when the agent needs input or finishes, and lets you continue from chat or the shared terminal.
+
+**Orchestrate specialist agents.** OpenClaw can coordinate agent handoffs: Claude Code can plan, Codex can implement, and Claude Code can review. In tmux mode, AKK can also automatically approve trusted permission requests under rules you define. At any point, you can take over the shared terminal, keep working yourself, then hand the same task back to OpenClaw—with context intact.
+
+![Agent Knock Knock cover: OpenClaw knocking on coding agents' door](docs/assets/agent-knock-knock-cover.jpg)
 
 ## Choose an Execution Mode
 
@@ -26,20 +32,53 @@ Agent Knock Knock connects OpenClaw to local coding agents. Share a live termina
 
 Install either mode or both. tmux does not require ACPX. Cursor tmux control is [not yet supported](https://github.com/scotthuang/agent-knock-knock/issues/42). AKK can also discover, resume, or fork local Codex sessions; that is a Codex capability, not a third installation mode.
 
+For a complete first run, choose [tmux bridge in 5 minutes](https://github.com/scotthuang/agent-knock-knock/blob/main/docs/quickstart-tmux.md) or [Managed ACPX in 5 minutes](https://github.com/scotthuang/agent-knock-knock/blob/main/docs/quickstart-managed-acpx.md). Both guides use the npm installer so configuration, restart, and verification fit in one copy-paste path.
+
+### Permission Boundaries
+
+The two modes intentionally use different permission models:
+
+- **tmux bridge:** AKK does not change the coding agent's configured permission mode. For supported prompts in an AKK-managed turn, disabled-by-default exact-command rules may auto-approve a trusted request; unmatched or uncertain requests stay manual.
+- **Managed ACP:** AKK starts ACPX-backed agents with `--approve-all`; the tmux prompt inspection and exact-command `autoApprove` policy do not apply to this mode. Claude Code may still surface permission requests through ACPX, while some Codex sandbox-sensitive operations fail directly. Keep managed work inside an explicit workspace.
+
 ## Install
 
 Core requirements:
 
-- Node.js 22.14+ (Node.js 24 recommended; use a version supported by your OpenClaw release)
-- [OpenClaw](https://docs.openclaw.ai/) Gateway and plugin API `2026.3.24-beta.2` or newer
+- A Node.js version supported by OpenClaw (Node.js 24.15+ on the 24.x line is recommended for the compatibility floor below)
+- [OpenClaw](https://docs.openclaw.ai/) Gateway and plugin API `2026.7.1-2` or newer
 - At least one authenticated coding agent: Codex, Claude Code, or Cursor
 
+### Install from ClawHub (recommended)
+
 ```bash
-npm install -g @scotthuang/agent-knock-knock
-agent-knock-knock install-openclaw
+openclaw plugins install clawhub:@scotthuang/agent-knock-knock@beta
+openclaw config set plugins.entries.agent-knock-knock.config.workspace "$PWD"
+openclaw config set plugins.entries.agent-knock-knock.config.defaultAgent codex
+openclaw config set plugins.entries.agent-knock-knock.config.mode tmux
+openclaw gateway restart
 ```
 
-`install-openclaw` installs or updates the plugin, enables it, installs the AKK skill template, and restarts the OpenClaw Gateway. It is safe to rerun. Use `--skill-only` to skip plugin installation; add `--no-restart` to skip the automatic Gateway restart.
+The explicit `@beta` selector follows the `0.3.0` prerelease channel. Remove it after the stable ClawHub release is available.
+
+ClawHub installs the OpenClaw plugin, bundled AKK skill, and package-local relay CLI together. OpenClaw invokes that bundled CLI directly, but ClawHub does not add the `agent-knock-knock` command to your shell `PATH`. Do not run `install-openclaw` after a ClawHub install; that command belongs to the npm installation path below and would repeat the plugin setup.
+
+If you also want standalone shell commands such as `agent-knock-knock doctor`, install the npm package globally without running `install-openclaw`:
+
+```bash
+npm install -g @scotthuang/agent-knock-knock@next
+```
+
+### Install from npm (beta)
+
+```bash
+npm install -g @scotthuang/agent-knock-knock@next
+agent-knock-knock install-openclaw --workspace "$PWD" --default-agent codex --mode tmux --verify
+```
+
+The npm `next` dist-tag follows the same prerelease line. Remove `@next` after `0.3.0` becomes stable.
+
+`install-openclaw` installs or updates the plugin, atomically configures the selected workspace, agent, and mode without replacing unrelated settings, installs the AKK skill template, restarts the Gateway at most once, and optionally verifies the full runtime chain. It is safe to rerun. Without `--verify`, the result remains unverified rather than claiming readiness. Use `--skill-only` to skip plugin installation; add `--no-restart` to leave an explicit pending-restart state.
 
 If OpenClaw runs from a local checkout or another nonstandard location, pass its CLI explicitly:
 
@@ -47,6 +86,19 @@ If OpenClaw runs from a local checkout or another nonstandard location, pass its
 agent-knock-knock install-openclaw --openclaw-bin /path/to/openclaw/openclaw.mjs
 ```
 
+AKK's agent tools are optional and require an explicit OpenClaw tool-policy opt-in. If you use the default `coding` profile and do not already have `tools.allow`, add AKK without replacing the profile:
+
+```json5
+{
+  tools: {
+    profile: "coding",
+    alsoAllow: ["agent-knock-knock"]
+  }
+}
+```
+
+If your configuration already has a restrictive `tools.allow` list, add `"agent-knock-knock"` to that existing list instead. Do not set `allow` and `alsoAllow` at the same scope.
+
 Choose one execution mode, or install both.
 
 ### Option A: tmux bridge (recommended)
@@ -83,72 +135,34 @@ npm install -g acpx
 
 AKK uses ACPX to start managed Codex, Claude Code, or Cursor sessions from OpenClaw.
 
-Finally, check which modes are ready:
+Finally, check which modes are ready if the global CLI is installed:
 
 ```bash
-agent-knock-knock doctor
+agent-knock-knock doctor --mode tmux
 ```
 
-### Trust and Privacy
-
-AKK is local-first: its state, logs, and terminal control stay on your machine. AKK has no hosted control plane or telemetry, and its tmux integration does not modify coding-agent settings.
-
-For a managed Claude tmux turn, AKK reads only the bytes appended to Claude Code's owner-private local JSONL transcript after the send boundary. It uses them locally to bind the exact prompt, extract a redacted final answer, and correlate a pending Bash tool request with the current permission screen. The raw pending command remains inside the local approval executor for exact policy matching; AKK does not copy it into callbacks, conversation state, events, runtime logs, or redacted screen summaries. AKK does not upload the transcript or persist a copy of its raw contents. The final answer still travels through your configured local OpenClaw callback.
+For a ClawHub-only installation, use the package-local chat diagnostic:
 
-This does not mean task content can never leave the machine. OpenClaw and each coding agent or model provider still process content according to your configuration. Managed ACP tasks currently use ACPX `--approve-all`; treat them as trusted automation, set an explicit workspace, and review the agent's sandbox and credentials.
-
-AKK's normal callback uses the OpenClaw Gateway configuration without putting its token in the agent prompt or child-process arguments. Keep credentials out of a custom `callbackCommand`. The legacy direct CLI `--token` callback embeds that credential in its callback command and should not be used for untrusted delegations.
-
-## Quick Start
-
-First merge this configuration into `~/.openclaw/openclaw.json`, setting `workspace` to the absolute path of the project agents may modify:
-
-```json5
-// ~/.openclaw/openclaw.json
-{
-  plugins: {
-    entries: {
-      "agent-knock-knock": {
-        config: {
-          defaultAgent: "codex",
-          workspace: "/absolute/path/to/project"
-        }
-      }
-    }
-  }
-}
-```
-
-Restart the Gateway after changing the configuration:
-
-```bash
-openclaw gateway restart
+```text
+/akk doctor tmux
 ```
 
-For the recommended tmux mode, start an agent in tmux, then ask AKK to list and send to the discovered terminal:
+### Trust and Privacy
 
-```bash
-tmux new -s claude-work
-claude
-```
+AKK is local-first. It has no hosted control plane or telemetry, does not modify coding-agent settings, and keeps its state, logs, terminal control, and approval decisions on your machine. Sensitive approval commands are never included in callbacks or AKK logs.
 
-```text
-AKK list
-AKK send <terminal-controlled-id>: inspect this repository and summarize it
-AKK status <managed-conversation-id>
-```
+Your task content is still processed by OpenClaw and the coding-agent or model providers you configure. Use explicit workspaces, review agent permissions, and keep secrets out of custom callback commands.
 
-Attach to the same tmux session whenever you want to take over directly. Avoid typing while AKK is sending the same turn.
+## Five-Minute Quick Starts
 
-For Managed ACP, start a new task and use its conversation ID for follow-ups:
+Choose one complete, copy-paste path:
 
-```text
-AKK Codex: inspect this repository and summarize it
-AKK status <conversation-id>
-AKK send <conversation-id>: run the tests and fix any failures
-```
+| Path | Result |
+| --- | --- |
+| [tmux bridge in 5 minutes](https://github.com/scotthuang/agent-knock-knock/blob/main/docs/quickstart-tmux.md) | Connect OpenClaw to an existing Codex or Claude Code terminal and keep direct human takeover. |
+| [Managed ACPX in 5 minutes](https://github.com/scotthuang/agent-knock-knock/blob/main/docs/quickstart-managed-acpx.md) | Start managed Codex, Claude Code, or Cursor background tasks with durable state and callbacks. |
 
-For new ACP tasks, omitting the agent uses `defaultAgent`, falling back to Codex.
+The five-minute paths use the npm installer so installation, configuration, restart, and verification fit in one command. The ClawHub path above remains the OpenClaw-native distribution option and exposes the same package-local `/akk doctor`.
 
 ## How It Works
 
@@ -161,8 +175,8 @@ Use conversational `AKK` prompts on any chat surface. Explicit agent names overr
 ```text
 AKK Claude: review the latest commit
 AKK Cursor: fix the flaky UI test
-AKK describe <conversation-id>
-AKK recover <conversation-id>
+AKK describe latest
+AKK recover only
 ```
 
 Surfaces with native commands use the same operations:
@@ -170,15 +184,18 @@ Surfaces with native commands use the same operations:
 ```text
 /akk <task>
 /akk list
-/akk status <conversation-id>
-/akk describe <conversation-id>
-/akk send <conversation-id> <message>
-/akk cancel <conversation-id>
-/akk renew <conversation-id> [minutes]
-/akk retry-callback <conversation-id>
-/akk close <conversation-id> [reason]
+/akk doctor [tmux|acpx|all]
+/akk status [only|latest|codex|claude|cursor|@short-ref]
+/akk describe [session-selector]
+/akk send <session-selector>: <message>
+/akk cancel <session-selector>
+/akk renew <session-selector> [minutes]
+/akk retry-callback <session-selector>
+/akk close <session-selector> [reason]
 ```
 
+Selectors fail closed: `only` works only with one actionable target, `latest` requires a unique newest target, and an agent name must identify exactly one actionable session. `AKK list` shows stable short references while JSON output retains the authoritative full IDs.
+
 Codex CLI sessions started outside AKK can also be resumed, opened in a terminal, or forked:
 
 ```text
@@ -189,11 +206,12 @@ AKK fork takeover Codex <session-id>
 
 ## Configuration
 
-Configure AKK under `plugins.entries.agent-knock-knock.config` in `~/.openclaw/openclaw.json`, as shown in the Quick Start.
+AKK reads these options from `plugins.entries.agent-knock-knock.config`. The npm installer writes them for you; the ClawHub install section shows the equivalent `openclaw config set` commands.
 
 | Option | Default | Purpose |
 | --- | --- | --- |
 | `defaultAgent` | `codex` | Agent used when a request does not name one. |
+| `mode` | `all` | Mode checked by `/akk doctor`: `tmux`, `acpx`, or `all`. |
 | `workspace` | OpenClaw process directory | Working directory for delegated tasks. |
 | `storeDir` | `~/.agent-knock-knock/conversations` | Conversation state location; relative plugin paths resolve from `workspace`. |
 | `openclawBin` | Auto-detected | OpenClaw CLI used for callback delivery. |
@@ -211,7 +229,7 @@ For tmux-backed Codex, AKK reports visible approval prompts. Claude approval is
 
 - It is available only for the current AKK-managed turn.
 - AKK accepts only an exact, current Bash dialog with the one-time **Yes** choice already highlighted, correlated to one unresolved foreground Bash tool request in the anchored owner-private transcript. Persistent permission choices are rejected.
-- When no trusted rule matches, the callback takes the manual path. The user must personally inspect the named tmux pane, explicitly confirm the exact request, and then run `AKK approve <conversation-id>`; the hash-only callback is not sufficient for review.
+- When no trusted rule matches, the callback takes the manual path. The user must personally inspect the named tmux pane, explicitly confirm the exact request, and then run `AKK approve <@short-ref>`; the hash-only callback is not sufficient for review.
 - A disabled-by-default `autoApprove` rule may approve Claude only when its agent, canonical workspace, and exact argument vector all match the freshly re-read local evidence.
 - AKK re-evaluates the policy, reserves the one-shot dispatch, recaptures the one-time choice and transcript evidence, and revalidates the process and pane before sending one Enter. A stale, changed, replayed, or uncertain request fails closed and must be resolved in the terminal.
 
@@ -235,15 +253,15 @@ Place `autoApprove` inside the plugin `config` object. It is disabled by default
 
 ## Troubleshooting
 
-Start with `agent-knock-knock doctor`. It checks the core installation and reports ACPX and tmux readiness separately; either execution mode is enough. It does not authenticate an agent, verify live Gateway/plugin connectivity, or run a real task.
+With the global npm CLI installed, start with `agent-knock-knock doctor --mode tmux|acpx|all`. It runs bounded version probes, validates the OpenClaw config and AKK workspace, verifies the installed/enabled/loaded plugin and bundled skill, and checks Gateway health separately. For a ClawHub-only installation, use `/akk doctor`.
 
 | Symptom | Action |
 | --- | --- |
-| Installer or callbacks cannot find a local OpenClaw CLI | Set `openclawBin` and pass `--openclaw-bin` to `install-openclaw`. |
+| The npm installer or callbacks cannot find a local OpenClaw CLI | Set `openclawBin` and pass `--openclaw-bin` to `install-openclaw`. |
 | Source changes do not appear | Build, reinstall from the checkout, and restart the Gateway. |
-| Terminal bridge task is `stalled` | Inspect `status` and the terminal; use `/akk renew <conversation-id> <minutes>` only when more monitoring time is useful. |
+| Terminal bridge task is `stalled` | Inspect `status` and the terminal; use `/akk renew only <minutes>` only when exactly one stalled task needs more monitoring time. |
 | ACPX task is `stalled` | Inspect `status --trace`; close and redelegate if the executor cannot continue. |
-| Task is `callback_failed` | Run `/akk retry-callback <conversation-id>` in a native-command chat. |
+| Task is `callback_failed` | Run `/akk retry-callback only` when it is the only actionable failed callback, or use its `@short-ref`. |
 | Terminal takeover is unavailable | Run Codex or Claude Code inside tmux and check `AKK list` for a `terminal_controlled` entry. |
 | Claude permission is not offered through AKK | Use the managed conversation returned by a background send. If the dialog is not the exact supported one-time Bash prompt, resolve it in the terminal. |
 | Claude request was not auto-approved | Check `autoApprove.enabled`, `agents: ["claude"]`, the canonical workspace, and the exact command vector. The request must also be a current one-time Bash prompt with matching local transcript evidence from a supported Claude `2.1.x` version. |
@@ -252,13 +270,22 @@ Start with `agent-knock-knock doctor`. It checks the core installation and repor
 For local diagnostics, use:
 
 ```bash
-agent-knock-knock status --conversation <conversation-id> --trace
+agent-knock-knock status --conversation latest --trace
 agent-knock-knock list --terminal-debug
 agent-knock-knock list --managed-only
 ```
 
 Codex ACP uses the pinned `@agentclientprotocol/codex-acp` adapter. Override it only with a compatible command through `AKK_CODEX_ACPX_AGENT_COMMAND`.
 
+Credentialed smoke tests stay outside normal CI. From a repository checkout, the ACPX smoke creates a nonce-scoped session and closes it; the tmux smoke requires the exact pane PID and a freshly verified idle pane before sending one real turn:
+
+```bash
+AKK_RUN_LIVE_ACPX_SMOKE=1 npm run smoke:acpx -- --confirm-live --agent codex --workspace "$PWD"
+AKK_RUN_LIVE_TMUX_SMOKE=1 npm run smoke:tmux -- --confirm-live --agent codex --target akk-work:0.0 --expected-pane-pid <pid>
+```
+
+Both commands can use coding-agent credentials and may incur cost. Read the warning before opting in.
+
 ## Development
 
 ```bash
@@ -269,6 +296,20 @@ npm test                      # build and run the full test suite
 
 See [CONTRIBUTING.md](https://github.com/scotthuang/agent-knock-knock/blob/main/CONTRIBUTING.md) for the development and pull request workflow. For local OpenClaw testing, rebuild, run `node dist/src/cli.js install-openclaw`, and restart the Gateway.
 
+### ClawHub Maintainer Release
+
+The first `0.3.0` beta publish is intentionally manual and must stay on ClawHub's `beta` tag:
+
+```bash
+npm ci
+npm run build
+npm exec clawhub -- login
+npm exec clawhub -- package publish . --family code-plugin --owner scotthuang --tags beta --dry-run --json
+npm exec clawhub -- package publish . --family code-plugin --owner scotthuang --tags beta
+```
+
+After that first release creates the package, configure this repository as its trusted publisher. Future publishes use the manually dispatched `ClawHub Publish` workflow, which defaults to a dry run and derives `beta` versus `latest` from the package version.
+
 ## Storage and Logs
 
 State lives under `~/.agent-knock-knock/`. Directories use mode `0700`; state and log files use `0600`. Runtime logs redact common secrets and default to 14-day retention. Configure storage and logging with `--store-dir`, `AKK_LOG_DIR`, `AKK_LOG_LEVEL`, and `AKK_LOG_RETENTION_DAYS`; use a dedicated custom log directory.