@scotthuang/agent-knock-knock 0.14.15 → 0.14.17

package/docs/codex-0.164.0-compatibility.md

@@ -0,0 +1,122 @@
+# Codex CLI 0.164.0 compatibility
+
+AKK 0.14.17 includes this compatibility update. Publishing the package does not
+upgrade an existing local installation. The reviewed combination is
+macOS Codex CLI **0.164.0** with app-server **0.164.0**. It is a tested
+combination, not a numeric minimum for [direct control](codex-cli-native-compatibility.md).
+
+## Terminal changes
+
+The real 0.164.0 terminal can show `GPT-6.1-Sol default` in its model footer.
+It can also put the model, directory and warning on one contextual footer row,
+without a separate `? for shortcuts` row. The previous closed composer grammar
+rejected these surfaces, preventing native status or controls even when the
+original session was idle.
+
+The adapter recognizes the observed `default` label and the version-specific
+single-row composer layout. The label does **not** prove an effective reasoning
+effort such as `low`. Process, pane, native-thread, styled empty-input, approval,
+busy-state and input-ownership checks remain necessary before terminal input.
+An accepted footer alone does not prove that a task is idle.
+
+The centered Full Access confirmation can overlap this footer. Its geometry
+parser now accepts the observed single-column `›`, `»` and `·` background
+glyphs; it still requires the exact styled rectangle, warning and choices.
+
+Asynchronous question titles are now rendered as Markdown. The terminal
+adapter accepts only single-line plain titles whose rendering is provably
+unchanged, against the full native question identity. If any candidate contains
+Markdown-sensitive syntax, a character reference or a line break, the expanded
+surface remains ambiguous; it cannot be discarded to select another question.
+Two requests with the same visible title also remain unproven. These terminal
+restrictions do not apply to the backend's structured question response.
+
+The status, model, permission and question profiles are reviewed separately.
+Terminal paginated interaction writes add the audited **0.164.0/0.164.0** pair;
+other existing pairs retain their own checks. Unknown or mixed versions do not
+inherit this pair's terminal write authority. Direct-backend controls continue
+to validate live methods and response contracts independently of that table.
+
+## Native protocol
+
+Official binaries generated 888 experimental TypeScript schema files for
+0.162.1 and 904 for 0.164.0: 24 changed, 16 added and none removed. The 30
+reviewed schemas used by AKK for initialization, native identity, paged history,
+subscription, settings, interactions and responses are byte-identical.
+
+`ThreadReadResponse.readState` is additive relative to 0.162.1 and was already
+present in 0.163.0. It records reading position, not task execution, acceptance
+or completion. Regression coverage verifies that an all-read marker or an
+unread marker for another turn cannot change the exact selected task.
+`turn/start` and `turn/steer` add optional `responsesapiClientMetadataPatch`;
+AKK's existing requests remain valid without that field.
+
+Upstream now preserves saved settings during resume. AKK's existing loaded
+thread subscription sends only `threadId` and `excludeTurns`, without overriding
+model, sandbox or service tier. No backend parser or request workaround was
+needed for these changes. Schema agreement is separate from live validation.
+
+## Verification boundaries
+
+Live checks use dedicated CLI processes launched through the existing proxy
+wrapper, private Codex homes and isolated AKK storage. User work sessions,
+Gateway, Desktop and the shared production daemon are not restarted. A local
+callback receipt proves acceptance only at that receiver, not delivery to
+OpenClaw or WeChat.
+
+The backend harness uses the production public CLI dispatcher, native runtime,
+Store, response service and callback outbox. It substitutes a local receiver
+and performs reconciliation in the harness process. It does not establish a
+new independent-monitor-process or messaging-channel end-to-end result.
+
+| Check | Evidence and result |
+| --- | --- |
+| Installed backend read contract | Read-only initialization and reads succeeded for all 13 loaded threads observed at the time. This is read evidence, not 13 independent task or Send verifications. |
+| Native Send and exact Watch | Two real tasks in one dedicated CLI/backend pair completed through AKK's public CLI dispatcher. The first started with no materialized history. Each produced one local completion receipt. |
+| Public progress and task isolation | Captured public commentary and a bounded tool-status summary while active. The old Watch kept its original turn when the next task started. |
+| Monitoring and idempotency | Actual default deadline was 720 minutes. Repeated Send kept the original receipt and native turn; observer reconnection and repeated reads did not duplicate completion notifications. |
+| Native permission settings | Public permission options and Default/Read Only round trips confirmed effective settings. The isolated launch initially had custom read-only settings without a profile ID; the check established the explicit Read Only profile and left it restrictive before cleanup. It did not claim byte-identical restoration of that private initial setting. |
+| Native command approval | A real pending approval was matched to its exact thread, turn and fixture command. Public approve-once caused exactly one file append and one completion receipt; repeating the same response did not execute it again. |
+| Native blocking question | A dedicated native Plan-mode turn produced one real single-choice request. AKK's public Watch, Status and Respond operations selected the exact opaque question/option IDs; the final answer confirmed the selection and one local completion receipt. Repeating the response retained one dispatch. Native setup is not evidence of an AKK Plan-mode setter. |
+| Terminal status/model/permissions | Exercised the real native menus in a separate private CLI, including session-only High effort and Full Access followed by restoration to Read Only. The built AKK parsers accepted the saved exact status, styled popups, model/effort menus and permission confirmation; they rejected the history viewer. This is native UI exercise plus production-parser replay, **not** a full AKK terminal transaction end-to-end result. |
+| Development gates | Final `npm run test:fast`: **3,099 passed, zero failures**. `npm run typecheck`, `npm run build`, `npm run validate:architecture`, Skill consistency and `git diff --check` passed. |
+| Cleanup | Both dedicated frontends and their private backend/tmux hosts stopped; copied authentication files and owned sockets removed. Existing user processes and installed AKK were unchanged. |
+
+The asynchronous-question rendering change is supported by official source
+review and synthetic regressions, not a new live asynchronous-question run.
+The live approval check covers one command approval; it does not add a new
+file-patch approval or rejection matrix.
+
+The formal publication gate runs `npm run test:release` (connector checks, full
+regressions, isolated OpenClaw compatibility and ClawHub validation/dry-run),
+type checking, architecture validation and package-content checks. Its actual
+results are recorded in the release PR, separately from the development and
+live evidence above. No new external-channel delivery is implied by that gate.
+
+## Retained limits
+
+- CLI native new/clear/resume lifecycle controls remain unavailable for these
+  paginated versions. Discovering a loaded thread is not permission to cold-load
+  another process or substitute a conversation.
+- Direct CLI model changes and cancellation still require an eligible terminal
+  route; a version profile does not add backend methods to AKK.
+- When the terminal reports only `default` effort, AKK cannot prove the current
+  effective effort from that footer. Model catalog/control can still reject
+  this ambiguous state. The adapter does not silently turn `default` into `low`.
+- Public progress keeps its 800-code-point, redacted, grapheme-safe budget and
+  exact turn. Read receipts, idle state and partial answers are not completion
+  authority.
+- Monitoring retains the shared 720-minute hard deadline, managed-terminal
+  60-minute inactivity window, immutable existing deadlines and notification
+  deduplication. Replaying Send returns its original receipt; use Status for
+  current acceptance and completion evidence.
+- No new Desktop, Linux or Windows live compatibility claim is made. Previously
+  supported CLI versions are retained through regression and source evidence,
+  not new old-version live sessions.
+
+## Sources
+
+- [Official 0.164.0 release](https://github.com/openai/codex/releases/tag/rust-v0.164.0), published 2026-10-23.
+- [Official app-server protocol](https://learn.chatgpt.com/docs/app-server#protocol).
+- [Saved settings during resume](https://github.com/openai/codex/pull/55923).
+- [Earlier 0.162.1 operation matrix](codex-0.162.1-compatibility.md#verification-record).

package/docs/codex-cli-native-compatibility.md

@@ -98,6 +98,9 @@ and terminal records needing attention or management recovery remain visible.
 Direct-only and terminal-only CLIs remain listed. `terminalDebug: true` /
 `list --terminal-debug` expands all connections. Raw CLI discovery arrays also
 remain available for diagnosis.
+AKK `0.14.16` adds display-only folding of unstarted, unnamed
+candidates beside an established conversation. Exact-ID first Send remains
+available; see [candidate selection and its frontend-identity limits](list-output.md#conversation-selection).
 
 Actual routing association still requires the exact current thread, verified
 Codex home and physical process incarnation. A configured home, matching cwd,
@@ -199,6 +202,7 @@ permit automatic replay of `sent` or `uncertain` responses.
 | Live-tested combination, 2026-10-09 | **macOS: Codex CLI 0.160.0 + shared app-server 0.162.0**; production-adapter operations and limits are recorded below. |
 | Additional targeted live proof, 2026-10-10 | **macOS: Codex CLI 0.162.1 + shared app-server 0.162.1**. Verified public Status progress while a task was in progress through the running OpenClaw plugin, an actual 720-minute Send deadline, one isolated local completion acknowledgement, and repeated Send retaining the original task/deadline. No new WeChat delivery or full native-operation matrix is claimed. |
 | 0.14.2 compatibility review, 2026-10-10 | **macOS: Codex CLI 0.162.1 + shared app-server 0.162.1**. Expanded dedicated-session validation, native UI fixes and retained limits are recorded in the [operation matrix](codex-0.162.1-compatibility.md#verification-record). |
+| 0.14.17 review, 2026-10-23 | **macOS: Codex CLI 0.164.0 + app-server 0.164.0**. Dedicated native-task checks and version-specific terminal changes are recorded in the [0.164.0 review](codex-0.164.0-compatibility.md). The release includes the corresponding terminal adaptation. |
 | Runtime admission | A loaded main CLI thread, the selected local Codex home, valid stable `x.y.z` backend metadata, and the required live protocol shapes/methods. There is **no established numeric minimum** or exact version allowlist for direct control. |
 | Platform evidence | The live proof was on macOS. It does not establish a Linux/Windows direct-control validation matrix. |
 

package/docs/list-output.md

@@ -22,6 +22,29 @@ display grouping alone does not copy terminal permissions or redirect selectors.
 Multiple candidates, conflicts and terminals needing management recovery remain
 visible. Rows and connections are not a count of independent tasks.
 
+Starting in AKK `0.14.16`, default List also folds unnamed, unstarted Codex
+candidates when there is exactly one established conversation in the same Codex
+home and project, no conflicting identity, and no evidence of multiple physical
+terminals. This uses an explicitly unmaterialized native history, not an empty
+title or an unavailable read alone. Named threads, sole new sessions, exact
+terminal aliases, active/blocked resources and multiple established threads
+remain visible. An omitted candidate remains in the raw native discovery array
+and `terminalDebug: true` / `list --terminal-debug`, with its original ID and
+first-Send capability. The default view reports `unstarted_candidates_omitted`
+and a diagnostic query. Starting its first task restores ordinary presentation
+on the next List; nothing is unloaded, deleted, migrated or redirected.
+
+This is display folding, **not proof of an abandoned or duplicate thread**.
+The native loaded-list API does not expose which frontend is currently attached;
+`startup-thread-start` also creates legitimate new sessions. Consequently, a
+second unnamed empty frontend in the same project may require the diagnostic
+view when no exact frontend identity is available. Empty candidates without an
+exact terminal alias report backend reachability and unverified frontend presence,
+rather than claiming a separate confirmed online CLI. Counts are not task counts.
+List still does not scan persisted Watches: an uncertain first Send may have no
+native task history yet and can remain folded. Inspect its original Watch or
+`watches`; folding never proves that a request was not submitted or permits a retry.
+
 Host List uses `agent-knock-knock/host-list-compact` v4. Follow
 `pagination.next_args` while `has_more` is true. `listLimit` defaults to 40 and
 accepts 1–100. Pages are fresh discoveries, not a frozen snapshot; restart if

package/docs/pi-dsh-compatibility.md

@@ -1,10 +1,65 @@
 # Pi and DeepSeek Harness connector compatibility
 
 These are independently versioned controller connectors. Installing an AKK
-core/OpenClaw release does not update an already installed connector. The
-published 2026-10-14 connectors pin AKK core `0.14.7`; DSH connector `0.1.0-rc.6`
-pins `0.14.8`. Each carries its runtime's canonical Skill and 26-tool
-capability handshake. Neither connector update requires a new core release.
+core/OpenClaw release does not update an already installed connector. Select
+npm `next` or the exact connector version below; their `latest` tags remain
+unchanged. Neither connector update requires a new core release.
+
+## Core 0.14.16 alignment — 2026-10-23
+
+| Connector | Release (`next`) | Exact core dependency | Host scope |
+| --- | --- | --- | --- |
+| Pi | `0.1.0-poc.5` | `0.14.16` | Pi `1.2.0` and `0.84.4` |
+| DeepSeek Harness | `0.1.0-rc.8` | `0.14.16` | Existing reviewed DSH/Cordis sets, including `0.2.1-rc.2` / `4.0.5` |
+
+Both connectors inherit the bounded List candidate-folding fix and unchanged
+exact Send/Watch identity rules. Core and both connectors now form one release
+set; see [the release procedure](../CONTRIBUTING.md). The connectors remain
+prereleases on `next`: installing without that tag may select an older `latest`.
+Upgrading a standalone core does not change a connector's installed dependency.
+This alignment adds no new Host compatibility claim or tclaude preview support.
+
+## Core 0.14.15 alignment — 2026-10-21
+
+| Connector | Version on `next` | Exact core dependency | Retained Host boundary |
+| --- | --- | --- | --- |
+| Pi | `0.1.0-poc.4` | `0.14.15` | Pi `1.2.0` and `0.84.4` |
+| DeepSeek Harness | `0.1.0-rc.7` | `0.14.15` | DSH `0.2.1-rc.2` / Cordis `4.0.5`; earlier reviewed RC/alpha/legacy sets below |
+
+This update aligns manifests, lockfiles, runtime version constants and
+regression checks with the published core. Both connectors dynamically
+register all **27 tools**, including `agent_knock_knock_watches`, and verify
+the bundled canonical Skill against the actual runtime capability handshake.
+The HostAdapter and handshake APIs remain compatible; this update does not
+broaden the supported Host versions or change callback admission policy.
+
+`/akk list` now returns discoverable conversations only. Use `/akk watches`
+for the separate, paginated observation inventory (recent 24 hours by default;
+older active or unresolved records remain visible). The core's lifecycle
+maintenance removes eligible healthy completed observations after 48 hours,
+while preserving unresolved records and deduplication receipts. Existing
+absolute deadlines, Store locations and callback routes are not migrated.
+The DSH-specific Store and Pi's existing Store configuration remain in effect.
+Core `0.14.13` introduced Store writer protocol 10; an older writer cannot
+continue writing that Store after activation. A downgrade requires a coherent
+backup or a compatible writer, rather than only changing the connector version.
+
+Validation uses the actual pinned core and real Host SDK dependencies in
+isolated installations: typecheck, connector fast tests (Pi 30; DSH 40),
+package/Skill parity, 27-tool registration and List/Watches command/schema
+checks. Pi `1.2.0` also passed an isolated real RPC startup and `/akk`
+registration check without a model task. Publication
+repeats each connector's own release gate on clean synchronized `main`, followed
+by a clean install of the public artifacts. The checks do not send tasks to
+business sessions or external chat channels. Full live task/model-consumption
+results below are dated historical evidence, not repeated claims for this
+core-only update. Daily Host installations are not upgraded by publication.
+
+## Historical verification
+
+The following dated records describe the Host compatibility work behind the
+retained support boundary. Their connector/core versions and test counts are
+kept as recorded at the time.
 
 ## DSH 0.2.1-rc.2 compatibility — 2026-10-17
 

package/docs/testing.md

@@ -27,7 +27,7 @@ synchronization have explicit non-regression budgets. See
 | `npm run test:affected` | Complete fast tier plus mapped integration tests; unknown or shared-core changes run the full tier | Maintainer/release diagnostics only; not an ordinary development command |
 | `npm run test:full` | The exact union of fast and integration tests | Immediate pre-publication gate for an actual npm or ClawHub release |
 | `npm test` | Compatibility alias for `test:full` | Same release-only boundary as `test:full` |
-| `npm run test:release` | Full suite, isolated current-build OpenClaw compatibility check, ClawHub runtime validation, and ClawHub publish dry-run | Immediate pre-publication gate for an actual npm or ClawHub release |
+| `npm run test:release` | Coordinated core/Pi/DSH version preflight and connector gates, full suite, isolated current-build OpenClaw compatibility check, ClawHub runtime validation, and ClawHub publish dry-run | Immediate pre-publication gate for an actual npm or ClawHub release |
 | `npm run test:release:live` | The release tier plus credentialed native Codex and Claude lifecycle smoke/attestation | Optional release-time diagnostic with dedicated prepared tmux panes |
 | `npm run compat:openclaw` | Full minimum/current/API-boundary OpenClaw compatibility matrix | Periodic maintainer check and any change to declared compatibility floors; not required for every package release |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.14.15",
+  "version": "0.14.17",
   "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

@@ -23,7 +23,7 @@ Keep the user's requested scope and approval boundaries. Do not expand a task, a
 
 Present `conversations[]` as **CLI** or **Desktop** using `surface`, and keep Codex/Claude Code as the agent type. Select the displayed `conversation_id` and its advertised operation; AKK chooses the connection internally. Do not make separate user-facing backend and terminal lists, repeat raw discovery arrays, or count Watches as additional conversations or tasks. Preserve unavailable actions, current questions/approvals, and management/recovery records. Scoped controls, when present, are operations on exact targets within a row, not extra conversations.
 
-Default CLI presentation prefers the verified backend entry for a one-to-one same-agent/project discovery pair without known identity conflicts. Use that returned conversation ID and its actions directly; do not search for or choose an alternative transport. Its title, state and actions belong to the selected backend. Presentation preference does not prove a terminal alias, copy terminal permissions, or redirect a previously selected terminal ID. Multiple candidates, conflicts and terminal attention/recovery records remain visible. Proven exact aliases still combine verified controls. Use `terminalDebug: true` (CLI `list --terminal-debug`) only when connection diagnostics are needed, not as a routine selection step.
+Default CLI presentation prefers the verified backend entry for a one-to-one same-agent/project discovery pair without known identity conflicts. Use that returned conversation ID and its actions directly; do not search for or choose an alternative transport. Its title, state and actions belong to the selected backend. Presentation preference does not prove a terminal alias, copy terminal permissions, or redirect a previously selected terminal ID. Multiple candidates, conflicts and terminal attention/recovery records remain visible. Proven exact aliases still combine verified controls. Use `terminalDebug: true` (CLI `list --terminal-debug`) only when connection diagnostics are needed, not as a routine selection step. Unnamed, unstarted Codex candidates beside an established same-project conversation may be folded for display; `conversation_presentation.unstarted_candidates_omitted` reports their count and `diagnostic_query` expands them. This does not prove abandonment or an exact alias. If the requested new empty session is missing, use that query and its original exact ID; never substitute the established conversation. Sole or exactly associated new sessions remain visible, and a first task restores ordinary display.
 
 AKK prefers a reachable direct connection only after proving the exact selected native session and process or thread. An unavailable backend may retain an eligible terminal path; busy/blocked state or identity conflict cannot authorize bypass. Targeted operations on an idle terminal can use the existing advertised `/status` inspection to learn its identity; working or blocked terminals are not interrupted. List itself sends no terminal input. Keep an uncertain dispatch receipt and inspect it instead of retrying through another connection.
 
@@ -204,7 +204,7 @@ success; never retry an uncertain repair automatically.
 For native status inspection:
 
 1. Use only a current `available_actions.native_inspect({terminal_id,inspection:"status"})` entry. Those semantic arguments are complete; never add a command or authority field.
-2. Regression-tested profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1/0.150.1/0.151.0/0.153.0/0.153.4/0.154.0/0.155.1/0.158.0/0.159.0/0.159.2/0.159.3/0.160.0/0.162.1 and Claude Code 2.1.218/2.1.226/2.1.237/2.1.251/2.1.259/2.1.263/2.1.266/2.1.267/2.1.285 `inspection="status"`. Other complete `x.y.z` versions remain callable through the generic runtime profile and add a compatibility warning; actual incompatible UI or schema evidence fails at runtime and is not automatically retried. Claude success includes parsing and safely dismissing the newly opened Status panel. The inspection tool does not accept `/status` text or any arbitrary command string. `/usage`, `/cost`, `/stats`, `/usage-credits`, raw `/model`, `/compact`, and arbitrary slash commands remain unavailable; model changes use only the typed model-control tools above. Never automate bare Codex `/usage`: it opens an interactive menu whose later Enter can select an account-side usage-limit reset.
+2. Regression-tested profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1/0.150.1/0.151.0/0.153.0/0.153.4/0.154.0/0.155.1/0.158.0/0.159.0/0.159.2/0.159.3/0.160.0/0.162.1/0.164.0 and Claude Code 2.1.218/2.1.226/2.1.237/2.1.251/2.1.259/2.1.263/2.1.266/2.1.267/2.1.285 `inspection="status"`. Other complete `x.y.z` versions remain callable through the generic runtime profile and add a compatibility warning; actual incompatible UI or schema evidence fails at runtime and is not automatically retried. Claude success includes parsing and safely dismissing the newly opened Status panel. The inspection tool does not accept `/status` text or any arbitrary command string. `/usage`, `/cost`, `/stats`, `/usage-credits`, raw `/model`, `/compact`, and arbitrary slash commands remain unavailable; model changes use only the typed model-control tools above. 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 privately derives a fresh binding fence and requires an idle empty composer, exact PID/process/pane/cwd/version identity, and no conflicting Turn, transition, dispatch, approval, or owner.
 4. Codex `/status` requires an exact viewport of at least 80 columns so the full Session UUID can be proven. That pre-UUID gate applies to native inspection, lifecycle, and strict Session operations that must know the UUID before terminal input. Legacy terminal-scoped ordinary tasks may send once and bind from exact native acceptance afterward without running `/status` or failing merely because the pane is narrow. Codex paginated read-contract candidates attempt their separate closed `/status` binding before physical Send. If an exact callback Watch cannot be prepared safely, AKK may prepare terminal-activity observation; report the receipt's actual callback mode and limitation.
 5. 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 bypass AKK with raw terminal input.
@@ -314,7 +314,7 @@ Action-name glossary:
 
 - `status`: inspect one terminal, Turn, or Watch; it sends no native slash command.
 - `send`: deliver a new request, or perform the separately advertised immutable `retry_submission` form.
-- `watch` / `unwatch`: create or stop durable terminal observation; Codex 0.158.0/0.159.0/0.159.2/0.159.3/0.160.0/0.162.1 exact creation performs the closed `/status` transaction, while subsequent observation is read-only.
+- `watch` / `unwatch`: create or stop durable terminal observation; Codex 0.158.0/0.159.0/0.159.2/0.159.3/0.160.0/0.162.1/0.164.0 exact creation performs the closed `/status` transaction, while subsequent observation is read-only.
 - `list_resumable_threads`, `new_thread`, and `resume_thread`: inspect or change native thread context through their closed lifecycle protocols.
 - `native_inspect`: run only an advertised closed native inspection such as `status`.
 - `model_options`, `repair_model_control`, and `set_model`: discover the current native catalog, clear only a proven model-control residue, or consume one catalog offer.