@scotthuang/agent-knock-knock 0.13.18 → 0.14.1

package/docs/openclaw-operations.md

@@ -0,0 +1,281 @@
+# OpenClaw Operations
+
+This document covers OpenClaw-specific installation choices, optional tool
+routing, configuration, approval policy, recovery, and diagnostics. For
+ordinary AKK commands and cross-Host reliability semantics, use the
+[Operator Guide](operator-guide.md). AKK 0.14.0 introduces the Codex CLI
+backend, Desktop, and backend Recovery support described here.
+
+## Requirements and compatibility
+
+- Node.js supported by the installed OpenClaw release; Node.js 24 LTS is
+  recommended.
+- OpenClaw `2026.6.5` or newer for normal packaged installation.
+- Plugin API and Gateway `2026.5.12` or newer. The adjacent tested boundary,
+  `2026.5.10-beta.2`, lacks the required session workflow API.
+- An existing supported coding-agent environment running under the same OS
+  user as OpenClaw and AKK; choose its setup below.
+
+| Coding-agent environment | Requirement |
+| --- | --- |
+| 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. |
+
+OpenClaw and AKK inspect local processes, private backend endpoints, and any
+selected terminal provider. Workspace is not a routing boundary: exact current
+conversation identity and explicit user selection are. Terminal setup
+instructions apply only when using the terminal route.
+
+## Choose one installation path
+
+Use one AKK installation per OpenClaw profile: ClawHub, npm, or a linked local
+checkout. ClawHub is the normal OpenClaw path; npm also provides the standalone
+CLI. A [local development build](#local-development-build) is optional.
+
+### ClawHub
+
+This installs the OpenClaw plugin with the 0.14 backend, Desktop, and terminal
+capabilities:
+
+```bash
+openclaw plugins install clawhub:@scotthuang/agent-knock-knock
+openclaw gateway restart
+```
+
+ClawHub installs the plugin, bundled AKK skill, and package-local relay CLI.
+The plugin always uses that bundled relay. It does not add the standalone
+`agent-knock-knock` command to the shell `PATH`.
+
+### npm
+
+Use npm only when the standalone shell CLI is also wanted:
+
+```bash
+npm install -g @scotthuang/agent-knock-knock
+agent-knock-knock install-openclaw --verify
+```
+
+`install-openclaw` detects whether the installed OpenClaw supports capability
+consent. When supported, this explicit installation command passes
+`--accept-capabilities` to both fresh and replacement plugin installs and
+reports `capability_consent: "accepted"` in its result. Older OpenClaw versions
+continue through the same installation path without the unsupported option.
+
+Do not run `install-openclaw` after a ClawHub installation. These are
+alternative installation paths. For a nonstandard OpenClaw executable:
+
+```bash
+agent-knock-knock install-openclaw --verify \
+  --openclaw-bin /absolute/path/to/openclaw
+```
+
+## Local development build
+
+Use a reviewed checkout when developing AKK or evaluating source changes.
+This optional source installation is not required for the 0.14 backend or
+Desktop features. Choose an OpenClaw profile with no other AKK installation,
+or remove its existing installation
+through OpenClaw's plugin management before linking this checkout. Do not
+layer the link on top of a ClawHub or npm-installed plugin in the same profile.
+
+From the reviewed repository checkout, build and link the plugin:
+
+```bash
+npm ci
+npm run build
+openclaw plugins install --link .
+openclaw plugins enable agent-knock-knock
+openclaw gateway restart
+```
+
+Keep the checkout available while the plugin is linked. After changing its
+source, rebuild and restart the Gateway so it loads the new compiled code.
+For CLI backend or Desktop use, start with a fresh AKK List, select the intended
+conversation, and inspect its Status and advertised capabilities. These paths
+use their own setup guides above; a terminal session is not a prerequisite.
+`/akk doctor` checks the terminal-oriented installation environment. Missing
+terminal prerequisites in that result do not establish that a backend or
+Desktop conversation is unavailable. See [Contributing](../CONTRIBUTING.md)
+for development checks.
+
+## Optional natural-language routing
+
+Direct `/akk ...` commands bypass model tool selection and require no tool
+policy change. To let OpenClaw decide to call AKK from natural language, grant
+the optional `agent-knock-knock` tools.
+
+With the default `coding` profile and no existing `tools.allow`:
+
+```json5
+{
+  tools: {
+    profile: "coding",
+    alsoAllow: ["agent-knock-knock"]
+  }
+}
+```
+
+If a restrictive `tools.allow` already exists at that scope, add
+`"agent-knock-knock"` to it instead. Do not configure `allow` and `alsoAllow`
+at the same scope. Restart the Gateway after changing tool policy.
+
+## Configuration
+
+AKK requires no project-specific plugin configuration. Optional settings live
+under `plugins.entries.agent-knock-knock.config`:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `storeDir` | `~/.agent-knock-knock/store` | Stable AKK Session, Turn, Watch, receipt, and callback-outbox Store. |
+| `openclawBin` | Auto-detected | OpenClaw CLI used by the callback adapter. |
+| `codexHome` | Auto-detected | Optional Codex home used for native-session discovery. |
+| `idleTimeoutMinutes` | `10080` | Retention checked during controlled reconciliation. |
+| `agentTimeoutMinutes` | `60` | Terminal inactivity timeout. |
+| `agentHardTimeoutMinutes` | `720` | New Send/Watch hard lifetime across backend and terminal routes starting in AKK 0.14.1; also the default backend Renew duration. AKK 0.14.0 backend Send/Watch used 60 minutes when this setting is omitted. |
+
+A custom `storeDir` must be a dedicated private directory. AKK initializes a
+missing or empty path and refuses a non-empty manifestless directory instead
+of guessing how to write it. The complete schema is in
+[`openclaw.plugin.json`](../openclaw.plugin.json).
+
+## Manual approval
+
+AKK preserves the coding agent's existing permission mode. An approval
+callback is not authorization: the Host must refresh Status, show the current
+request, obtain explicit human confirmation, and invoke only the approval
+action advertised for that exact prompt.
+
+CLI backend and Desktop approvals use the current typed interaction in the
+original native task and controller session. Copy the advertised interaction
+and decision; do not translate terminal approval keys into backend requests.
+See the [CLI backend](codex-cli-native-compatibility.md) and
+[Desktop](codex-desktop-compatibility.md) guides for supported request types.
+
+Terminal approval has separate boundaries. Claude Code manual approval is
+deliberately narrow. It supports the current AKK-managed Turn only and
+requires an exact one-time Bash **Yes** choice
+correlated with the owner-private transcript. Persistent permission choices,
+unknown dialogs, and changed evidence remain manual in the TUI.
+
+Codex may also advertise terminal-scoped approval when the exact visible prompt
+is known but managed foreground UUID attribution is unavailable. The action is
+prefilled with the exact `terminal_id`; never construct or guess it. Both paths
+retain the confirmation offer and prompt fence privately and recapture them
+under lock immediately before sending one key.
+
+## Automatic approval
+
+Trusted Codex and supported hookless Claude terminal commands can optionally
+be auto-approved with a deterministic, default-disabled policy:
+
+```json5
+autoApprove: {
+  enabled: true,
+  rules: [{
+    id: "project-read-status",
+    agents: ["codex", "claude"],
+    workspaces: [
+      "/absolute/path/to/project-a",
+      "/absolute/path/to/project-b"
+    ],
+    commands: [["pwd"], ["git", "status"], ["git", "diff", "--stat"]]
+  }]
+}
+```
+
+Place `autoApprove` inside the plugin `config`. Each rule may authorize
+multiple canonical workspace roots; `autoApprove.rules[].workspaces` is the
+sole workspace boundary for automatic approval and does not limit discovery or
+manual control. Rules match only the configured agents and exact argument
+vectors. Shell composition, substitutions, globs, environment assignments,
+unparseable commands, and paths outside every authorized root remain manual.
+Terminal Watch approval notifications never participate in auto-approval.
+
+## Supervisor and callbacks
+
+OpenClaw starts one non-overlapping AKK supervision cycle at startup and after
+each previous cycle completes. Terminal managed-Turn monitors, Terminal
+Watches, CLI backend Watches, and Desktop Watches have independent recovery
+phases and error boundaries, so a failure in one does not starve the others.
+
+For terminal managed Turns, with a writable Store, healthy Gateway, successful
+reconciliation, and an unchanged Turn binding, AKK prepares one immutable
+completion message and outbox entry within 30 seconds after reliable native completion evidence
+becomes stable. External transport and wake acknowledgement are outside that
+bound. Status remains the manual recovery path when presentation is delayed.
+
+For CLI backend and Desktop work, retain the exact task ID returned by Send
+or Watch. Use [backend task recovery](backend-task-recovery.md) for Recover,
+Renew, Close, Unwatch, and Retry Callback. These operations target that original
+task and controller session without terminal input. Close releases Send
+management; it does not cancel Codex. Unwatch stops observation. A callback
+accepted by OpenClaw does not prove delivery by a downstream chat channel, and
+an uncertain callback is not eligible for manual replay.
+
+Terminal binding and menu recovery remain separate; see
+[terminal recovery and diagnostics](operator-guide.md#terminal-recovery-and-diagnostics).
+
+## Troubleshooting
+
+For CLI backend and Desktop, start with fresh List and Status for the selected
+conversation or exact task. For terminal installation diagnostics, use:
+
+```text
+/akk doctor
+```
+
+With the standalone npm CLI installed, `agent-knock-knock doctor` additionally
+checks the executable environment directly. Doctor's readiness result includes
+tmux/Herdr and CLI prerequisites; a missing terminal requirement is not a
+backend or Desktop health result.
+
+| Symptom | Recovery |
+| --- | --- |
+| CLI backend conversation is missing | Check that the intended main CLI conversation is loaded under the selected local Codex home, then refresh List; see the [CLI backend guide](codex-cli-native-compatibility.md). |
+| Desktop row has no live owner | Open that exact conversation in the supported Desktop app, then refresh List. Catalog membership alone does not grant Send capability. |
+| No eligible terminal, when terminal control is intended | Start authenticated Codex or Claude Code inside tmux or supported Herdr as the same OS user, then refresh `/akk list`. |
+| Plugin or callbacks cannot find OpenClaw | Configure `openclawBin`; for npm installation, pass the matching `--openclaw-bin` to `install-openclaw`. |
+| Linked source changes do not appear | Run `npm run build` in the linked checkout and restart the Gateway; see [Local development build](#local-development-build). |
+| Backend observation is stale, stopped, or expired | Inspect Status for the original `watch_id`, then use the action advertised for its state; [backend recovery](backend-task-recovery.md) distinguishes Recover from Renew. |
+| Backend callback failed | Use only an advertised Retry Callback action for an eligible notification; select its exact `notification_id` when several are eligible. Accepted, in-flight, and uncertain deliveries cannot be replayed. |
+| Terminal Turn is `stalled` | Inspect Status and the exact pane; use the advertised Renew action only if the same Turn is still live. |
+| Terminal Turn is `callback_failed` | Use the advertised Retry Callback action; it reuses the original message identity. |
+| Human native-thread switch conflicts with active terminal work | Ask the user whether to keep the old work or take over the current thread. Use only the nested fresh action returned by List. |
+| Terminal List reports orphaned dispatch or transition state | Inspect the pane, then run only the exact Close recovery command returned by List. It leaves the coding agent and terminal running. |
+| Claude approval is not offered | Resolve unsupported, persistent, stale, or uncorrelated dialogs in the TUI. |
+| Claude request was not auto-approved | Check the enabled rule, agent, canonical workspace, exact argv, and current screen/transcript evidence. |
+
+Terminal diagnostics:
+
+```bash
+agent-knock-knock status --conversation latest --trace
+agent-knock-knock list --terminal-debug
+```
+
+For backend tasks, use the exact returned task ID instead of `latest`, for
+example `agent-knock-knock status --watch '<watch_id>'`. Status for that task
+reads its original backend without terminal input. List never types into a
+terminal; a targeted conversation Status for an unbound, idle physical Codex
+terminal may perform the closed identity inspection described in the
+[Operator Guide](operator-guide.md#akk-status-and-native-inspection).
+
+Trace and logs must not expose agent reasoning, raw callback payloads,
+credentials, tokens, passwords, or proxy secrets.
+
+## Trust and privacy
+
+AKK has no hosted control plane or telemetry. Ordinary Send preserves the
+coding agent's permission settings; an explicit supported permission action
+applies the user's selected mode. Terminal, Session, Turn, Watch, receipt, and
+log state stay on the local machine. Claude approval callbacks omit raw commands; Codex
+may include bounded visible command detail so the Host can present it for
+review.
+
+Task content is still processed by OpenClaw and the coding-agent or model
+providers configured by the user. Keep secrets out of prompts and review every
+agent's permission mode.
+
+For Store migration, filesystem permissions, retention, and log settings, see
+[Storage and Logging](storage-and-logging.md). For development and release
+workflows, see [Contributing](../CONTRIBUTING.md) and [Testing](testing.md).

package/docs/openclaw-session-turn-delivery-requirement.md

@@ -0,0 +1,45 @@
+# OpenClaw Session Turn Delivery
+
+## Status
+
+AKK delivers structured terminal-monitor callbacks into the originating OpenClaw session without asking OpenClaw to poll terminal output, logs, or process state.
+
+The current flow is:
+
+1. OpenClaw sends a request through the terminal row's current exact action: `session_exact` with `session_id`, or `terminal_follow_current` with the full `terminal_id`. AKK derives and revalidates freshness evidence inside the trusted plugin/CLI boundary.
+2. AKK creates a new `turn_id` and sends the user-facing request to the verified Codex or Claude Code tmux pane bound to that session.
+3. AKK monitors the exact terminal, native session evidence, AKK session, Turn, process, and message. The running OpenClaw service independently replaces an unexpectedly exited eligible monitor without waiting for `list` or `status`.
+4. When the adapter has reliable evidence, AKK records a canonical approval, completion, cancellation, stall, or error message.
+5. AKK calls the plugin Gateway method `agent-knock-knock.callback` and receives a validated delivery plan.
+6. AKK completes delivery into the originating OpenClaw session.
+
+The identity chain is terminal → native coding-agent session → AKK `session_id` → `turn_id`. An ordinary send creates a new Turn through exactly one current listed scope: `session_exact` targets a prefilled `session_id`, while rollout-backed Codex uses `terminal_follow_current` with its full `terminal_id`. Opaque freshness, binding, and dispatch evidence never crosses the model boundary; AKK derives it privately and revalidates it under lock. Exact callbacks and managed control operations target `turn_id`. An unmanaged raw-terminal row may expose its own prefilled compatibility selector for status or recovery controls, but that selector is not a Turn ID and must never be constructed. If the coding agent asks a question, the callback marks that Turn `waiting_for_openclaw`; `respond(turn_id, answer)` continues the same Turn.
+
+Native new/clear and resume controls operate between the terminal and Session layers. The model supplies the exact `terminal_id`; resume also supplies one complete, verified historical `native_thread_id`. AKK privately derives the current binding and candidate evidence, then revalidates both under lock. A successful transition creates or activates an AKK Session, advances the terminal binding generation, and creates no Turn. The next ordinary send creates the first Turn in that selected context.
+
+The coding agent does not invoke a callback command. Terminal monitoring and callback delivery belong to AKK.
+
+For an accepted Codex dispatch, durable completion prefers the exact rollout,
+byte anchor, process incarnation, and native turn UUID already persisted on the
+Turn. An exact identity or integrity failure is retained as a redacted detector
+diagnostic and never falls through to a same-workspace rollout guess. Monitor
+replacement reuses the immutable completion claim so recovery prepares at most
+one `done` callback/outbox entry.
+
+## Delivery Invariants
+
+Callback delivery must:
+
+1. Preserve the originating OpenClaw session, AKK `session_id`, and exact `turn_id`.
+2. Trigger the target session's next run without impersonating a user interface.
+3. Keep thinking text and unrelated raw terminal output out of callbacks, and disclose only the approval details required for review. Claude approval callbacks omit raw commands.
+4. Deduplicate retries with stable Turn, message, and delivery identities.
+5. Preserve structured provenance for audit and debugging.
+6. Persist the canonical message before attempting external delivery.
+7. Expose actionable callback failure and retry state without requiring raw-log inspection.
+8. Refuse to report completion when terminal evidence is stale, ambiguous, or unsupported.
+9. Fence every callback to the terminal incarnation, native identity, Session, Turn, and binding generation that created it, so a pre-transition callback cannot mutate the active post-transition context.
+
+These invariants apply even if OpenClaw later exposes a more direct plugin session-turn API.
+
+Native clear/new/resume operations are outside callback delivery and ordinary Turn creation. They are serialized against monitors and callback/recovery mutations; unresolved work blocks the transition, and stale delivery remains attached only to its historical Turn.