@scotthuang/agent-knock-knock 0.11.3 → 0.11.4

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "agent-knock-knock",
   "name": "Agent Knock Knock",
-  "description": "Control local Codex and Claude Code through shared tmux terminals, with native-thread lifecycle controls, live monitoring, approvals, and human takeover.",
+  "description": "Control local Codex and Claude Code through shared tmux terminals, with Codex version-scoped native inspection, native-thread lifecycle controls, live monitoring, approvals, and human takeover.",
   "icon": "https://raw.githubusercontent.com/scotthuang/agent-knock-knock/main/docs/assets/agent-knock-knock-icon.png",
   "activation": {
     "onStartup": true,
@@ -17,6 +17,7 @@
     "tools": [
       "agent_knock_knock_list",
       "agent_knock_knock_list_resumable_threads",
+      "agent_knock_knock_native_inspect",
       "agent_knock_knock_new_thread",
       "agent_knock_knock_reconcile_binding",
       "agent_knock_knock_resume_thread",
@@ -37,6 +38,9 @@
     "agent_knock_knock_list_resumable_threads": {
       "optional": true
     },
+    "agent_knock_knock_native_inspect": {
+      "optional": true
+    },
     "agent_knock_knock_new_thread": {
       "optional": true
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "Control local Codex and Claude Code from OpenClaw through shared tmux terminals, with seamless human-agent handoff.",
   "license": "MIT",
   "type": "module",
@@ -72,7 +72,13 @@
     "build": "npm run clean && tsc -p tsconfig.json",
     "prepack": "npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --test dist/test/*.test.js",
+    "test": "npm run test:full",
+    "test:fast": "npm run build && node scripts/run-test-tier.js fast",
+    "test:integration": "npm run build && node scripts/run-test-tier.js integration",
+    "test:full": "npm run build && node scripts/run-test-tier.js full",
+    "test:profile": "npm run build && node scripts/profile-test-tier.js",
+    "test:release": "node scripts/run-release-tests.js",
+    "test:release:live": "node scripts/run-release-tests.js --live",
     "clawhub:validate": "npm run build && clawhub --workdir . package validate . --out .clawhub-validation --runtime --allow-execute --no-mock-sdk",
     "clawhub:dry-run": "npm run build && clawhub package publish . --family code-plugin --owner scotthuang --tags latest --topics tmux,codex,claude-code,agent-orchestration,terminal-handoff --dry-run",
     "compat:openclaw": "npm run build && node scripts/verify-openclaw-compatibility.js",

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

@@ -43,6 +43,7 @@ Natural-language forms:
 - `AKK Codex: <task>`: call `agent_knock_knock_send` with `request=<task>` and `selector="codex"`.
 - `AKK Claude: <task>`: call `agent_knock_knock_send` with `request=<task>` and `selector="claude"`.
 - Requests to list AKK or local coding-agent work: call `agent_knock_knock_list`.
+- Requests for the coding agent's native Codex status card: first call `agent_knock_knock_list`, then call `agent_knock_knock_native_inspect` only when the exact terminal row advertises `native_inspect`. Preserve its complete `terminal_id`, `inspection="status"`, and `expected_binding_token`; do not substitute AKK Turn status or ordinary send.
 - Requests to list resumable native threads for an exact terminal: call `agent_knock_knock_list_resumable_threads` with the terminal row's prefilled `terminal_id`.
 - Explicit requests to start a new thread or clear context: call `agent_knock_knock_new_thread` only from an advertised `new_thread` action, preserving its exact `terminal_id` and `expected_binding_token`.
 - Explicit requests to recover a listed binding conflict: call `agent_knock_knock_reconcile_binding` only from that terminal row's advertised `reconcile_binding` action, preserving its exact terminal, Session revision, binding token, and terminal token. This detaches the stale/conflicting binding without adopting the live thread; refresh the list before any later control.
@@ -64,13 +65,21 @@ For ordinary send or an in-flight answer:
 1. Reuse an AKK session only when the user's reference uniquely identifies its verified native session and terminal incarnation.
 2. If no ID is supplied and more than one eligible pane may exist, call `agent_knock_knock_list`.
 3. Treat `terminals[]` as the primary resource list. Its managed context exposes `session_id`; `managed.current_turn` is the only current AKK owner, while `managed.recent_turn` and `managed.history` are retained Turn history. Records in `unavailable_managed_turns[]` have no live pane in this snapshot.
-4. Read the selected resource's `available_actions`. Use only an action present there, start with its prefilled authoritative arguments, supply every `missing_required` field, and consult the top-level contract for optional fields.
+4. Read the selected resource's `available_actions`. Use only an action present there, start with its prefilled authoritative arguments, supply every `missing_required` field, and consult the top-level v7 `action_contracts` for optional fields.
 5. For an existing managed Session, use `send` with its prefilled `session_id`; it creates a new Turn. For first attach only, use a discovery selector explicitly named by the user or the selected unmanaged raw-terminal row's prefilled `selector`. Never infer or reuse a selector. Use `respond` with its prefilled `turn_id` only when that Turn is explicitly `waiting_for_openclaw`; the answer stays in the same Turn. Add the text as `request`. Do not add timeout fields for ordinary use; `timeoutSeconds` is unsupported.
 6. If multiple terminals match, show their `short_ref`, agent, and tmux target, then ask the user to choose. Never guess or send to a pane that AKK has not verified as idle.
 
 An idle pane is at a verified ready prompt, with no current work or unresolved permission request. A previously completed managed turn alone is not proof that the pane is still idle.
 
-Do not treat ordinary send as native clear, new-session, fork, branch, side thread, status probe, or resume. Do not send `/clear`, `/new`, `/resume`, `/status`, Codex `/fork`, `/side`, `/btw`, Claude `/branch`, or any other first-line native slash command as ordinary task or answer text. Native lifecycle tools own supported keystrokes, capability checks, serialization, identity verification, and binding changes; express other requests in natural language or leave unsupported native commands to a human in tmux. Each successful lifecycle transition creates no Turn.
+Do not treat ordinary send as native clear, new-session, fork, branch, side thread, status probe, or resume. Do not send `/clear`, `/new`, `/resume`, `/status`, Codex `/fork`, `/side`, `/btw`, Claude `/branch`, or any other first-line native slash command as ordinary task or answer text. Dedicated native lifecycle and inspection tools own their closed commands, capability checks, serialization, identity verification, and binding fences; express other requests in natural language or leave unsupported native commands to a human in tmux. Each successful lifecycle transition creates no Turn, and native inspection creates no Session or Turn.
+
+For native status inspection:
+
+1. Use only a current `available_actions.native_inspect` entry. Its structured arguments are authoritative and complete; never construct or reuse them.
+2. Initial support is Codex-only: exact Codex 0.146.0/0.146.1 `inspection="status"`. The tool does not accept `/status` text or any arbitrary command string. Claude native commands, `/usage`, `/model`, `/compact`, and unsupported versions remain unavailable. Never automate bare Codex `/usage`: it opens an interactive menu whose later Enter can select an account-side usage-limit reset.
+3. Treat this as terminal input even though the native command is read-only. AKK requires an idle empty composer, fresh binding token, exact PID/process/pane/cwd/version identity, and no conflicting Turn, transition, dispatch, approval, or owner.
+4. The result is valid only when AKK proves one fresh bounded native status result and the pane returns to idle. On an uncertain or unproven submission, do not retry, send Enter, clear the composer, or fall back to raw tmux.
+5. Native inspection creates no AKK Session, Turn, receipt, monitor, callback, or response round.
 
 For native-thread lifecycle discovery or mutation:
 
@@ -115,7 +124,7 @@ After an asynchronous send operation is accepted, end the OpenClaw turn. Wait fo
 
 ## Status
 
-For managed terminal entries, `agent_knock_knock_status` captures a bounded terminal screen and returns `terminal_screen`. Do not inspect the pane with raw tmux or shell commands unless AKK status is unavailable or fails.
+For managed terminal entries, `agent_knock_knock_status` captures AKK Turn state plus a bounded terminal screen and returns `terminal_screen`. It does not actively execute native Codex `/status`. Use `agent_knock_knock_native_inspect` only for a terminal row's advertised, version-scoped native status action. Do not inspect the pane with raw tmux or shell commands unless the relevant AKK inspection is unavailable or fails.
 
 ## Cancellation and Recovery
 
@@ -154,7 +163,7 @@ A trusted, default-disabled plugin `autoApprove` policy may independently approv
 
 `agent_knock_knock_list` is terminal-first: every eligible already-running Codex or Claude Code pane appears once in `terminals[]`, even when retained managed Turns reference it. The resource chain is terminal → verified native session → managed AKK `session_id` → Turns. `process_state` reports process liveness and `activity_state` reports the parsed screen state. `managed.current_turn` is the authoritative active Turn for that terminal; otherwise `managed.recent_turn` shows the newest retained context. Request `all=true` only when older `managed.history` or retained unavailable history is needed. By default, `unavailable_managed_turns[]` contains attention-needed records whose terminal is unavailable.
 
-The top-level v6 `action_contracts` summarizes each tool's managed target and its narrow compatibility inputs; `available_actions` is the authoritative current-action source after listing. An existing managed Session's ordinary `send` targets `session_id` and starts a new managed Turn. On first attach only, `selector` may preserve a discovery target explicitly named by the user or the exact selector prefilled by an unmanaged raw-terminal row; it must never be passed as `session_id`. `respond` and every managed control target `turn_id`; `respond` is offered only for a Turn waiting on OpenClaw. The read-only `list_resumable_threads` action is advertised on the terminal row, requires only its full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows. The `new_thread` mutation is advertised on the terminal row and requires that terminal ID and token; each resumable candidate row advertises its own `resume_thread` mutation with the same snapshot token, its complete `native_thread_id`, and its opaque `candidate_token`. A conflict-only `reconcile_binding` action may be advertised for one exact, idle binding conflict; it preserves the listed Session revision, binding token, and terminal token, then CAS-detaches the old binding without adopting the live thread, sending terminal input, or creating a Turn. A top-level `previous` block, when present, is the only authority for a “previous/刚才那个” request. Number, short ID, and snapshot handle fields are human-facing navigation only; never pass them to the exact resume tool. Lifecycle discovery and mutations never create a Turn. A raw terminal may be controlled only through the exact action that its own row advertises; prefilled compatibility selectors, lifecycle IDs, and tokens must never be inferred, copied from another row, or reused from another snapshot. Start with the prefilled full argument, supply all `missing_required` fields, and use a returned `@short-ref` only for human-facing ordinary-send selection. Availability is a snapshot, so AKK revalidates it before side effects.
+The top-level v7 `action_contracts` summarizes each tool's managed target and its narrow compatibility inputs; `available_actions` is the authoritative current-action source after listing. An existing managed Session's ordinary `send` targets `session_id` and starts a new managed Turn. On first attach only, `selector` may preserve a discovery target explicitly named by the user or the exact selector prefilled by an unmanaged raw-terminal row; it must never be passed as `session_id`. `respond` and every managed control target `turn_id`; `respond` is offered only for a Turn waiting on OpenClaw. The read-only `list_resumable_threads` action is advertised on the terminal row, requires only its full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows. The `new_thread` mutation is advertised on the terminal row and requires that terminal ID and token; each resumable candidate row advertises its own `resume_thread` mutation with the same snapshot token, its complete `native_thread_id`, and its opaque `candidate_token`. A conflict-only `reconcile_binding` action may be advertised for one exact, idle binding conflict; it preserves the listed Session revision, binding token, and terminal token, then CAS-detaches the old binding without adopting the live thread, sending terminal input, or creating a Turn. A top-level `previous` block, when present, is the only authority for a “previous/刚才那个” request. Number, short ID, and snapshot handle fields are human-facing navigation only; never pass them to the exact resume tool. Lifecycle discovery and mutations never create a Turn. A raw terminal may be controlled only through the exact action that its own row advertises; prefilled compatibility selectors, lifecycle IDs, and tokens must never be inferred, copied from another row, or reused from another snapshot. Start with the prefilled full argument, supply all `missing_required` fields, and use a returned `@short-ref` only for human-facing ordinary-send selection. Availability is a snapshot, so AKK revalidates it before side effects.
 
 Before every terminal operation, AKK revalidates the expected agent PID and tmux pane identity, then confirms that the process and pane working directories match. Sending new work additionally requires a verified idle prompt. Humans can attach to the same tmux session and continue directly at any time.