@scotthuang/agent-knock-knock 0.14.2 → 0.14.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/README.md +233 -108
- package/dist/src/backend-callback-public-projection.d.ts +27 -0
- package/dist/src/backend-callback-public-projection.js +58 -0
- package/dist/src/backend-callback-public-projection.js.map +1 -0
- package/dist/src/backend-public-progress.d.ts +2 -0
- package/dist/src/backend-public-progress.js +4 -1
- package/dist/src/backend-public-progress.js.map +1 -1
- package/dist/src/backend-recovery-semantic.js +5 -4
- package/dist/src/backend-recovery-semantic.js.map +1 -1
- package/dist/src/callback-transport.d.ts +1 -1
- package/dist/src/callback-transport.js +2 -2
- package/dist/src/callback-transport.js.map +1 -1
- package/dist/src/claude-conversation-routing-cli-adapter.d.ts +2 -0
- package/dist/src/claude-conversation-routing-cli-adapter.js +127 -0
- package/dist/src/claude-conversation-routing-cli-adapter.js.map +1 -0
- package/dist/src/claude-conversation-routing-identity.d.ts +11 -0
- package/dist/src/claude-conversation-routing-identity.js +46 -0
- package/dist/src/claude-conversation-routing-identity.js.map +1 -0
- package/dist/src/claude-native-cli-adapter.d.ts +18 -0
- package/dist/src/claude-native-cli-adapter.js +159 -0
- package/dist/src/claude-native-cli-adapter.js.map +1 -0
- package/dist/src/claude-native-client.d.ts +57 -0
- package/dist/src/claude-native-client.js +197 -0
- package/dist/src/claude-native-client.js.map +1 -0
- package/dist/src/claude-native-discovery.d.ts +20 -0
- package/dist/src/claude-native-discovery.js +111 -0
- package/dist/src/claude-native-discovery.js.map +1 -0
- package/dist/src/claude-native-identity.d.ts +29 -0
- package/dist/src/claude-native-identity.js +54 -0
- package/dist/src/claude-native-identity.js.map +1 -0
- package/dist/src/claude-native-monitor.d.ts +13 -0
- package/dist/src/claude-native-monitor.js +123 -0
- package/dist/src/claude-native-monitor.js.map +1 -0
- package/dist/src/claude-native-observation.d.ts +54 -0
- package/dist/src/claude-native-observation.js +418 -0
- package/dist/src/claude-native-observation.js.map +1 -0
- package/dist/src/claude-native-outbox.d.ts +16 -0
- package/dist/src/claude-native-outbox.js +122 -0
- package/dist/src/claude-native-outbox.js.map +1 -0
- package/dist/src/claude-native-peer-helper.d.ts +2 -0
- package/dist/src/claude-native-peer-helper.js +121 -0
- package/dist/src/claude-native-peer-helper.js.map +1 -0
- package/dist/src/claude-native-public-projection.d.ts +605 -0
- package/dist/src/claude-native-public-projection.js +98 -0
- package/dist/src/claude-native-public-projection.js.map +1 -0
- package/dist/src/claude-native-runtime.d.ts +25 -0
- package/dist/src/claude-native-runtime.js +74 -0
- package/dist/src/claude-native-runtime.js.map +1 -0
- package/dist/src/claude-native-state-store.d.ts +49 -0
- package/dist/src/claude-native-state-store.js +96 -0
- package/dist/src/claude-native-state-store.js.map +1 -0
- package/dist/src/claude-native-task-service.d.ts +70 -0
- package/dist/src/claude-native-task-service.js +327 -0
- package/dist/src/claude-native-task-service.js.map +1 -0
- package/dist/src/cli-core.js +2 -1
- package/dist/src/cli-core.js.map +1 -1
- package/dist/src/cli-runtime-context.d.ts +2 -0
- package/dist/src/cli-runtime-context.js.map +1 -1
- package/dist/src/codex-native-outbox.js +7 -5
- package/dist/src/codex-native-outbox.js.map +1 -1
- package/dist/src/codex-native-public-projection.d.ts +17 -7
- package/dist/src/codex-native-public-projection.js +4 -4
- package/dist/src/codex-native-public-projection.js.map +1 -1
- package/dist/src/codex-native-semantic.js +15 -5
- package/dist/src/codex-native-semantic.js.map +1 -1
- package/dist/src/conversation-list.js +8 -2
- package/dist/src/conversation-list.js.map +1 -1
- package/dist/src/conversation-routing-cli-adapter.d.ts +2 -7
- package/dist/src/conversation-routing-cli-adapter.js +4 -2
- package/dist/src/conversation-routing-cli-adapter.js.map +1 -1
- package/dist/src/conversation-routing-commands.d.ts +5 -0
- package/dist/src/conversation-routing-commands.js.map +1 -1
- package/dist/src/desktop-command-presentation.js +3 -1
- package/dist/src/desktop-command-presentation.js.map +1 -1
- package/dist/src/desktop-public-projection.js +3 -6
- package/dist/src/desktop-public-projection.js.map +1 -1
- package/dist/src/desktop-task-service.js +10 -3
- package/dist/src/desktop-task-service.js.map +1 -1
- package/dist/src/durable-notification-kernel.d.ts +10 -0
- package/dist/src/durable-notification-kernel.js +18 -1
- package/dist/src/durable-notification-kernel.js.map +1 -1
- package/dist/src/host-monitor-reconciliation.js +9 -1
- package/dist/src/host-monitor-reconciliation.js.map +1 -1
- package/dist/src/host-profile-runtime.js +3 -1
- package/dist/src/host-profile-runtime.js.map +1 -1
- package/dist/src/local-codex-cli-adapter.js +4 -3
- package/dist/src/local-codex-cli-adapter.js.map +1 -1
- package/dist/src/openclaw-callback-evidence.d.ts +17 -0
- package/dist/src/openclaw-callback-evidence.js +75 -0
- package/dist/src/openclaw-callback-evidence.js.map +1 -0
- package/dist/src/openclaw-callback-transport.js +90 -9
- package/dist/src/openclaw-callback-transport.js.map +1 -1
- package/dist/src/semantic-conversation-target.js +1 -1
- package/dist/src/semantic-conversation-target.js.map +1 -1
- package/dist/src/semantic-tool-command-helpers.d.ts +0 -1
- package/dist/src/semantic-tool-command-helpers.js +27 -17
- package/dist/src/semantic-tool-command-helpers.js.map +1 -1
- package/dist/src/semantic-tool-descriptions.js +3 -3
- package/dist/src/semantic-tool-descriptions.js.map +1 -1
- package/dist/src/semantic-tool-list-projection.js +11 -4
- package/dist/src/semantic-tool-list-projection.js.map +1 -1
- package/dist/src/semantic-tool-presentation.js +17 -3
- package/dist/src/semantic-tool-presentation.js.map +1 -1
- package/dist/src/semantic-tool-runtime.js +8 -1
- package/dist/src/semantic-tool-runtime.js.map +1 -1
- package/dist/src/semantic-tool-schemas.js +15 -15
- package/dist/src/semantic-tool-schemas.js.map +1 -1
- package/dist/src/terminal-list-cli-adapter.js +5 -1
- package/dist/src/terminal-list-cli-adapter.js.map +1 -1
- package/dist/src/terminal-list-ownership-service.js +1 -1
- package/dist/src/terminal-list-ownership-service.js.map +1 -1
- package/docs/backend-task-recovery.md +43 -0
- package/docs/claude-cli-direct.md +60 -0
- package/package.json +2 -2
- package/templates/openclaw-skills/agent-knock-knock/SKILL.md +14 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.14.3 - 2026-10-11
|
|
4
|
+
|
|
5
|
+
- Add direct control of existing Claude Code CLI sessions on macOS without tmux, Herdr, Claude plugins, hooks, special launch flags or a replacement agent. Discover exact live sessions, send idle tasks, read bounded public progress/results and observe exact completion or exit. Requires Python 3 on the controller side; verified with Claude Code 2.1.296.
|
|
6
|
+
- Prefer the Claude native route for supported basic operations. Preserve eligible exact terminal routes for existing special operations; unsupported approvals, questions, model/permission changes, cancellation and lifecycle controls remain unavailable without an appropriate terminal route. Busy or uncertain submissions never silently fall back or resend.
|
|
7
|
+
- Retry a callback only when structured transport evidence proves it was not submitted. Recognize the reviewed OpenClaw opening-handshake failure, retain request-phase evidence and original notification identity, and preserve the existing bounded backend retry budget. Unknown or conflicting error schemas cannot authorize replay.
|
|
8
|
+
- Make one bounded read-only exact-run check after eligible uncertain callback submissions. Only positive acceptance evidence settles the notification; missing records, query timeouts and malformed acknowledgements do not authorize another send. Historical uncertain notifications are not automatically replayed.
|
|
9
|
+
- Preserve callback deduplication across observer restart, concurrent recovery and late definitive receipts. Explain exhausted retry budgets and keep task completion, controller acceptance and downstream channel delivery separate in Status, List and recovery text.
|
|
10
|
+
|
|
11
|
+
### Validation boundaries
|
|
12
|
+
|
|
13
|
+
- Claude direct discovery, sending, progress, exact completion and terminal fallback were exercised in isolated local acceptance checks. Native special-control APIs remain outside this first direct adapter; see the [Claude direct guide](docs/claude-cli-direct.md).
|
|
14
|
+
- Callback recovery is verified with isolated transport responses and temporary durable stores. No historical callback was replayed, and this release does not claim a new live WeChat delivery test or a guarantee against arbitrarily long Gateway outages.
|
|
15
|
+
- Existing Codex CLI/Desktop compatibility boundaries, the 800-code-point Status budget, 720-minute monitoring deadline and terminal-managed 60-minute inactivity window are unchanged. Desktop live verification remains intentionally skipped.
|
|
16
|
+
|
|
3
17
|
## 0.14.2 - 2026-10-10
|
|
4
18
|
|
|
5
19
|
- Adapt Codex CLI 0.162.1 native status to the changed usage-page URL without relaxing exact thread, process, version, composer or freshness checks. A rejected status card no longer hides the underlying diagnostic behind a plain-text semantic tool error: native inspection execution failures return structured JSON with an explicit non-retryable outcome.
|
package/README.md
CHANGED
|
@@ -2,146 +2,271 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@scotthuang/agent-knock-knock)
|
|
4
4
|
[](https://nodejs.org/)
|
|
5
|
-
[](LICENSE)
|
|
5
|
+
[](https://github.com/scotthuang/agent-knock-knock/blob/main/LICENSE)
|
|
6
6
|
|
|
7
|
-
**
|
|
8
|
-
AKK lets a controller such as OpenClaw discover your conversations, send tasks,
|
|
9
|
-
and receive completion or question notifications while you stay in chat.
|
|
7
|
+
Agent Knock Knock lets **OpenClaw** control your existing **Codex CLI, Codex Desktop, and Claude Code** conversations. Watch work without staring at a terminal, send the next instruction from chat, and get callbacks when the coding agent finishes or needs attention.
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
Herdr.** AKK controls the original conversation, so you see the same work in
|
|
13
|
-
Codex. Claude Code and applicable Codex terminal workflows use tmux or Herdr.
|
|
14
|
-
AKK does not launch a hidden replacement agent.
|
|
9
|
+
AKK never launches a hidden replacement agent. The controller Host, the human, and AKK all use the same visible conversation and native coding-agent session.
|
|
15
10
|
|
|
16
|
-
|
|
17
|
-
unified conversation routing, and exact-task recovery. Bounded public progress
|
|
18
|
-
in Status and shared 12-hour monitoring defaults continue in **0.14.2, which
|
|
19
|
-
adapts Codex CLI 0.162.1 native status and interaction surfaces.** See the
|
|
20
|
-
[release notes](CHANGELOG.md#0142---2026-10-10) for changes and validation limits.
|
|
11
|
+
**Stay in the terminal. Stay in control. No hooks. No agent-side plugins. No YOLO.**
|
|
21
12
|
|
|
22
|
-
|
|
13
|
+
*Codex CLI 0.159 and later support direct control. For earlier versions, use tmux or Herdr.*
|
|
23
14
|
|
|
24
|
-
|
|
25
|
-
saved sidebar entries that are not connected; those rows cannot receive tasks.
|
|
26
|
-
- **Send and follow an exact task**, or Watch work you started yourself.
|
|
27
|
-
Results and attention notifications return to the initiating controller.
|
|
28
|
-
- **Answer supported questions, approve requests, and set permissions** through
|
|
29
|
-
the selected provider's advertised actions. Desktop also supports explicit
|
|
30
|
-
model settings and exact task cancellation.
|
|
31
|
-
- **Recover monitoring and callback failures** without resending the task.
|
|
32
|
-
[Backend Recovery](docs/backend-task-recovery.md) distinguishes Recover,
|
|
33
|
-
Renew, Close, Unwatch, and Retry Callback.
|
|
15
|
+

|
|
34
16
|
|
|
35
|
-
##
|
|
17
|
+
## Install for OpenClaw
|
|
36
18
|
|
|
37
|
-
|
|
38
|
-
under the same OS user as AKK.
|
|
19
|
+
You need OpenClaw `2026.6.5`+, Node.js `22.19.0`+, and a supported Codex Desktop app or authenticated `codex` or `claude` CLI running as the same OS user.
|
|
39
20
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
Use ClawHub for the OpenClaw plugin, including the 0.14 backend and Desktop
|
|
43
|
-
features:
|
|
21
|
+
Use ClawHub for the OpenClaw plugin, including the 0.14 backend and Desktop features:
|
|
44
22
|
|
|
45
23
|
```bash
|
|
46
24
|
openclaw plugins install clawhub:@scotthuang/agent-knock-knock
|
|
47
|
-
openclaw gateway restart
|
|
48
25
|
```
|
|
49
26
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
27
|
+
If the installer asks you to restart the Gateway, run `openclaw gateway restart`.
|
|
28
|
+
|
|
29
|
+
**For Codex CLI 0.159 or later, or Codex Desktop, keep your conversation open.**
|
|
30
|
+
You can connect directly without tmux or Herdr.
|
|
31
|
+
See the [CLI guide](docs/codex-cli-native-compatibility.md) or
|
|
32
|
+
[Desktop guide](docs/codex-desktop-compatibility.md) for supported setups.
|
|
33
|
+
|
|
34
|
+
In OpenClaw, first send:
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
/akk list
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Choose a conversation by project and title, then send a separate message:
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
Use AKK to ask Codex in my-project to run the tests and summarize any failures.
|
|
44
|
+
Tell me when it's done.
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
AKK chooses the connection for you. Keep the task/Watch ID returned by Send
|
|
48
|
+
to check its status later. To follow a task you already started yourself,
|
|
49
|
+
ask OpenClaw to Watch that conversation.
|
|
50
|
+
|
|
51
|
+
**For Codex CLI versions earlier than 0.159, or Claude Code terminal controls, use tmux or Herdr.**
|
|
52
|
+
To use tmux, start the coding agent in your project:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
cd /absolute/path/to/project
|
|
56
|
+
tmux new-session -s akk-work -c "$(pwd -P)" codex
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Use `claude` instead of `codex` if preferred. Herdr users can follow the [Herdr quick start](docs/quickstart-herdr.md).
|
|
60
|
+
|
|
61
|
+
For this terminal setup, first send in OpenClaw:
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
/akk doctor
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
After `AKK doctor: ready`, send a separate message:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
/akk inspect this repository and summarize it
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
That is the terminal first-task flow. For terminal setup and multiple panes, see the [tmux quick start](docs/quickstart-tmux.md). Direct `/akk ...` commands need no OpenClaw tool-policy changes. For natural-language tool access and installation help, see the [OpenClaw guide](docs/openclaw-operations.md).
|
|
74
|
+
|
|
75
|
+
## Install for Pi
|
|
76
|
+
|
|
77
|
+
Pi can be the controller Host without OpenClaw. The current connector targets Pi `0.84.4`:
|
|
78
|
+
|
|
79
|
+
This connector currently depends on AKK `0.13.3`; the new 0.14 direct CLI and Desktop capabilities described above apply to the OpenClaw plugin. Follow the connector guide for its supported features.
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
npm install -g @earendil-works/pi-coding-agent@0.84.4
|
|
83
|
+
pi install npm:@scotthuang/agent-knock-knock-pi@next
|
|
84
|
+
pi
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Pi should show `AKK ready`. With Codex or Claude Code already running in tmux or Herdr, enter `/akk list`. The connector provides `/akk`, the complete capability-handshake-verified semantic tool catalog, the bundled `agent-knock-knock` skill, callbacks to the initiating Pi session, and native approval dialogs. See the [Pi connector guide](connectors/pi/README.md).
|
|
88
|
+
|
|
89
|
+
## Install for DeepSeek Harness
|
|
90
|
+
|
|
91
|
+
The connector supports DeepSeek Harness Web `0.1.1-rc.2`, `0.1.2-alpha.1`, and
|
|
92
|
+
`0.1.5-rc.2`:
|
|
93
|
+
|
|
94
|
+
This connector currently depends on AKK `0.13.3`; its supported features are documented separately from the OpenClaw plugin's 0.14 direct CLI and Desktop capabilities.
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
dsh plugin --profile web add @scotthuang/agent-knock-knock-deepseek-harness@next
|
|
98
|
+
dsh web
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Open a Web conversation and enter `/akk list`. The connector gives every conversation `/akk`, the same capability-handshake-verified semantic tool catalog, the bundled `agent-knock-knock` skill, and callbacks to the exact Harness Agent that initiated the work. See the [DeepSeek Harness connector guide](connectors/deepseek-harness/README.md).
|
|
102
|
+
|
|
103
|
+
## See It in Action
|
|
104
|
+
|
|
105
|
+
[](https://github.com/scotthuang/agent-knock-knock/blob/main/docs/assets/akk-tmux-handoff-demo.mp4)
|
|
106
|
+
|
|
107
|
+
*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 control. This demo uses tmux; supported Codex CLI and Desktop connections no longer need it. Click the preview for the full-quality video.*
|
|
108
|
+
|
|
109
|
+
## What AKK Gives You
|
|
110
|
+
|
|
111
|
+
AKK 0.14.0 introduces Codex CLI shared-backend control, Codex Desktop support, and exact-task recovery. Desktop includes discovery, task sending, Status, and exact task Watches. List follows saved Desktop sidebar membership and keeps unconnected entries visible; open a conversation in Desktop before sending to it. Desktop supports command/file approval decisions, blocking and asynchronous answers, per-conversation permissions, explicit model and Plan/default settings, and exact task cancellation. See [Desktop compatibility and usage](docs/codex-desktop-compatibility.md).
|
|
54
112
|
|
|
55
|
-
|
|
113
|
+
Codex CLI sessions connected to a shared backend can also be controlled directly, without tmux or Herdr. Native CLI rows support task sending, exact Watch and callbacks, command/file approvals, blocking and asynchronous answers, and per-thread permission settings. See the [CLI shared-backend guide](docs/codex-cli-native-compatibility.md).
|
|
56
114
|
|
|
57
|
-
|
|
58
|
-
local shared backend. No terminal container is required. An embedded backend
|
|
59
|
-
or unloaded history is not a direct-control target; see the
|
|
60
|
-
[CLI guide](docs/codex-cli-native-compatibility.md).
|
|
61
|
-
- **Codex Desktop:** open the intended local conversation in the reviewed app
|
|
62
|
-
build. A saved conversation with no verified live owner must be opened in
|
|
63
|
-
Desktop before AKK can send to it. See the [Desktop guide](docs/codex-desktop-compatibility.md).
|
|
64
|
-
- **Claude Code or Codex terminal control:** follow the [tmux](docs/quickstart-tmux.md)
|
|
65
|
-
or [Herdr](docs/quickstart-herdr.md) quick start, including `/akk doctor`.
|
|
115
|
+
AKK 0.14.3 also adds [Claude Code direct control](docs/claude-cli-direct.md): discover an already-open CLI, send tasks, read progress, and receive completion callbacks without tmux/Herdr, Claude plugins, or hooks. Live-tested on macOS with Claude Code `2.1.296`; requires Python 3 on the AKK side.
|
|
66
116
|
|
|
67
|
-
|
|
117
|
+
The existing terminal workflows remain available for Codex or Claude Code running in tmux or Herdr:
|
|
68
118
|
|
|
69
|
-
|
|
119
|
+
Codex CLI 0.158.0/0.159.0/0.159.2/0.159.3/0.160.0/0.162.1 supports exact paginated task Watches for ordinary terminal
|
|
120
|
+
Send, native question responses, and durable completion callbacks. The adapter
|
|
121
|
+
checks the foreground thread and required backend protocol before attaching; uncertain
|
|
122
|
+
answers are never automatically replayed. See the [0.162.1 review](docs/codex-0.162.1-compatibility.md)
|
|
123
|
+
and [earlier compatibility review](docs/codex-0.160.0-compatibility.md) for managed-session and already-open
|
|
124
|
+
question boundaries. Codex 0.157.x retains its [partial compatibility](docs/codex-0.157.1-compatibility.md).
|
|
125
|
+
|
|
126
|
+
- **Watch without babysitting.** Ask OpenClaw to Watch an ongoing CLI or Desktop task, or use `/akk watch <terminal>` for a terminal. Get a callback when it finishes, needs approval, or becomes blocked. You can leave the coding agent and continue from your phone or another chat client.
|
|
127
|
+
- **Send without typing in a tiny remote console.** Ask OpenClaw to send to a listed conversation, or use `/akk <selector>: <message>` for a terminal. Send attaches monitoring when the exact task can be verified; its receipt tells you whether a callback is expected. You do not need a second Watch for that same task. An explicit user Send has priority over stale AKK management state.
|
|
128
|
+
- **Identify an ambiguous Codex foreground explicitly.** When several rollout files or a recent `/clear` prevent durable attribution, an advertised foreground-identification action can inspect one exact idle pane without guessing which rollout is current.
|
|
129
|
+
- **Set Codex permissions before a task.** `/akk permissions <exact-terminal-id>` reads the current setting and native choices; `/akk set-permissions <exact-terminal-id> <advertised-mode-id>` applies your selected mode to that idle session and verifies it before Send. Full Access works like the other options; AKK handles its native confirmation automatically without an extra user prompt. See [Codex permissions](docs/codex-permissions.md).
|
|
130
|
+
- **Switch models through the native catalog.** `/akk models <exact-terminal-id>` lists the choices currently offered by one exact physical Codex or Claude Code pane; a Codex rollout/native-thread attribution is not required, so this also works before the first rollout materializes. `/akk set-model ...` consumes one exact advertised model/reasoning-effort tuple without accepting raw slash commands, keys, or menu indexes. Codex synchronizes the model and ordinary efforts through `max` to the current and future-session defaults; its `ultra` effort is current-session-only, and the native UI does not expose the exact non-Ultra effort chosen for future sessions, so AKK omits that unobservable field. Claude Code changes only the current session.
|
|
131
|
+
- **Continue or clear only a proven model-control residue.** If a failed model-control attempt in a reviewed Codex profile leaves an exact `/model` completion surface or bare `/model` Composer, a fresh List may advertise both `/akk models <exact-terminal-id>` and `/akk repair-model-control <exact-terminal-id>`. Models uses a separate residual-bound authority to continue that exact native slash command into read-only catalog discovery without retyping it. If the exact native picker is already open, List marks the pane non-idle and exposes repair where supported. Repair remains the cleanup-only escape hatch, never presses Enter, and must prove an empty Composer.
|
|
132
|
+
- **Inspect and recover.** `/akk status <turn-or-watch>` shows current state when a callback is delayed. Direct CLI and Desktop Status also include a short public progress summary. Send and Watch default to a 12-hour hard deadline; managed terminal tasks retain their separate 60-minute inactivity limit. Durable callback records and Watches provide a recovery path after transient Host failures. See [Backend Recovery](docs/backend-task-recovery.md).
|
|
133
|
+
- **Approve deliberately in supported conversations.** AKK can surface Codex or Claude Code permission requests and submit an explicit human decision. It preserves the coding agent's existing permission mode. Desktop exposes typed command/file approvals and blocking or asynchronous answers through the original conversation owner.
|
|
134
|
+
- **Hand control back and forth.** Return to the same Codex CLI, Desktop conversation, or tmux/Herdr pane whenever you want. AKK does not create a parallel hidden conversation.
|
|
135
|
+
|
|
136
|
+
For terminal workflows, common commands are shown below. Watch is for work
|
|
137
|
+
already running; model changes require an idle session. These are separate
|
|
138
|
+
actions, not a sequence to run before every Send. Direct CLI and Desktop users
|
|
139
|
+
can ask OpenClaw for the corresponding advertised action on their selected conversation.
|
|
70
140
|
|
|
71
141
|
```text
|
|
72
142
|
/akk list
|
|
143
|
+
/akk watch <exact-terminal-id>
|
|
144
|
+
/akk models <exact-terminal-id>
|
|
145
|
+
/akk set-model <exact-terminal-id> <advertised-model-id> <advertised-reasoning-effort>
|
|
146
|
+
/akk codex: run the tests and explain any failures
|
|
147
|
+
/akk status <turn-id-or-watch-id>
|
|
73
148
|
```
|
|
74
149
|
|
|
75
|
-
|
|
150
|
+
If List advertises `repair-model-control`, it is an alternative cleanup flow:
|
|
76
151
|
|
|
77
152
|
```text
|
|
78
|
-
|
|
79
|
-
|
|
153
|
+
/akk repair-model-control <exact-terminal-id>
|
|
154
|
+
/akk list
|
|
155
|
+
/akk models <exact-terminal-id>
|
|
156
|
+
/akk set-model <exact-terminal-id> <advertised-model-id> <advertised-reasoning-effort>
|
|
80
157
|
```
|
|
81
158
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
159
|
+
Use identifiers and actions from a fresh `/akk list`; do not guess or cache terminal IDs. Terminal model switching is fail-closed: the same exact physical pane/process must still be free of an active Turn or any input-owning approval, questionnaire/editor, or read-only viewer, and must show either an exact idle empty Composer or a supported profiled `/model` residual. A reviewed Codex profile may allow model control before the first rollout; Claude Code still requires its exact current native Session. When List advertises both actions for a Composer residual, `model_options` may continue it into the catalog while `repair_model_control` only clears it. If continuation, repair, or model switching reports `uncertain`, inspect the pane instead of retrying automatically. See the [operator guide](docs/operator-guide.md) for version-specific behavior.
|
|
160
|
+
|
|
161
|
+
## How It Works
|
|
162
|
+
|
|
163
|
+
```text
|
|
164
|
+
OpenClaw / Pi / DeepSeek Harness
|
|
165
|
+
│
|
|
166
|
+
AKK Host adapter
|
|
167
|
+
│
|
|
168
|
+
Session · Turn · Watch · Callback
|
|
169
|
+
│
|
|
170
|
+
┌──────────────┼─────────────────┐
|
|
171
|
+
Codex CLI backend Codex Desktop IPC tmux / Herdr
|
|
172
|
+
│ │ │
|
|
173
|
+
Original CLI Original Desktop Codex / Claude Code
|
|
174
|
+
conversation conversation
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
For Codex CLI, AKK prefers the shared backend when it verifies the exact live conversation. You select a conversation and an action; AKK selects the connection. Before dispatch, an unavailable backend or unsupported operation may use a verified terminal route. Busy, blocked, or uncertain results do not trigger a retry through another connection.
|
|
178
|
+
|
|
179
|
+
For a terminal-managed Send, AKK verifies the selected terminal and coding-agent process, writes one user request, monitors that exact Turn, and returns completion or attention callbacks to the initiating Host session. If stale AKK bookkeeping blocks an explicit Codex Send before terminal input, AKK can fall back to a verified one-time physical Send and attach a task Watch for callback and Status recovery.
|
|
87
180
|
|
|
88
|
-
|
|
89
|
-
work already running, ask OpenClaw to Watch that listed conversation. A
|
|
90
|
-
callback accepted by OpenClaw does not itself prove delivery to WeChat or
|
|
91
|
-
another downstream channel.
|
|
181
|
+
Desktop uses a separate adapter. It combines a read-only catalog with live owner discovery, verifies the exact thread, submits at most once, and records the accepted native task for monitoring. It does not start a CLI to replay Desktop history. An uncertain submission is reconciled from native evidence and never automatically resent.
|
|
92
182
|
|
|
93
|
-
|
|
183
|
+
Native Pi and DeepSeek Harness connectors accept the shared catalog through a
|
|
184
|
+
versioned, secretless Host Adapter capability handshake. Startup verifies the
|
|
185
|
+
ordered semantic tool registration and the bundled Skill against catalog and
|
|
186
|
+
Skill SHA-256 digests; an older, missing, or drifted handshake fails closed
|
|
187
|
+
instead of mounting a partial tool surface. Connector package versions remain
|
|
188
|
+
independent of one another.
|
|
94
189
|
|
|
95
|
-
|
|
190
|
+
An idle Codex pane with ambiguous foreground identity may advertise `identify_foreground`, which performs a bounded native `/status` inspection. List never types into terminals. Targeted operations, including conversation Status, may also use a protected `/status` inspection on an idle, empty terminal to establish its exact backend identity. They do not interrupt a working or blocked terminal to discover that identity. Task acceptance and completion still require evidence from the exact native task; a status card alone is not proof. See [CLI routing and identity](docs/codex-cli-native-compatibility.md#automatic-conversation-routing-2026-10-10).
|
|
96
191
|
|
|
97
|
-
|
|
192
|
+
AKK is local-first: there is no hosted control plane or telemetry. It stores only the local state needed for routing, lifecycle recovery, callback delivery, and idempotency.
|
|
193
|
+
|
|
194
|
+
## Compatibility
|
|
195
|
+
|
|
196
|
+
Codex CLI shared-backend connections and Codex Desktop work without tmux or Herdr
|
|
197
|
+
when the conditions below are met. Older CLI setups without a direct connection
|
|
198
|
+
can use a supported terminal route. Claude Code direct control is available under the separate boundary below.
|
|
199
|
+
|
|
200
|
+
| Component | Supported boundary |
|
|
98
201
|
| --- | --- |
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
operations
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
## Other controller Hosts
|
|
119
|
-
|
|
120
|
-
[Pi](connectors/pi/README.md) and [DeepSeek Harness](connectors/deepseek-harness/README.md)
|
|
121
|
-
have independent connector packages and installation guides. Their current
|
|
122
|
-
package manifests pin AKK **0.13.3**; their published capabilities must not be
|
|
123
|
-
inferred from this 0.14 README. See each guide for its reviewed
|
|
124
|
-
Host versions, callbacks, and upgrade procedure.
|
|
202
|
+
| Terminal hosts | tmux; local Herdr `0.8.0` protocol `19` |
|
|
203
|
+
| Codex Desktop | macOS app `26.1002.52244`, build `13536`; this **exact build**, plus an open connected conversation, is required for sending and other controls. Supports Status, exact Watch, approvals/answers, settings, and cancellation. |
|
|
204
|
+
| Codex CLI shared backend | Live-tested on macOS: CLI `0.162.1` + backend `0.162.1`, and previously `0.160.0` + `0.162.0`. Requires a loaded main CLI conversation and compatible live protocol. These are tested combinations, **not a numeric minimum**. |
|
|
205
|
+
| Claude Code direct connection | macOS, live-tested `2.1.296`, compatible native peer protocol `1`, and Python 3 available to AKK. Basic task sending, progress and completion observation; unsupported controls require the original terminal. See the [direct guide](docs/claude-cli-direct.md). |
|
|
206
|
+
| Terminal coding agents | Reviewed Codex profiles include `0.160.0` and `0.162.1`; Claude Code `2.1.285` was tested on macOS. Unknown versions may expose limited capabilities; native controls depend on the reviewed profile and current UI. |
|
|
207
|
+
| OpenClaw | `2026.6.5`+; plugin API and Gateway `2026.5.12`+ |
|
|
208
|
+
| Pi connector | Pi `0.84.4`; connector currently depends on AKK `0.13.3` |
|
|
209
|
+
| DeepSeek Harness connector | `0.1.1-rc.2`, `0.1.2-alpha.1`, and `0.1.5-rc.2`; connector currently depends on AKK `0.13.3` |
|
|
210
|
+
| Runtime | Node.js `22.19.0`+ on macOS or Linux |
|
|
211
|
+
|
|
212
|
+
The adjacent OpenClaw boundary `2026.5.10-beta.2` is intentionally unsupported. Herdr and Desktop controls depend on reviewed private protocol versions. Desktop catalog presence alone does not prove the conversation is open or controllable. See each connector guide and the Desktop guide for tested boundaries and limitations.
|
|
213
|
+
|
|
214
|
+
Codex CLI model changes and cancellation still require an eligible terminal.
|
|
215
|
+
New/clear/resume operations for paginated Codex CLI `0.158+`, and creating or
|
|
216
|
+
cold-loading Desktop conversations, remain unsupported. Desktop can set an
|
|
217
|
+
explicit model but cannot query a model catalog. See the
|
|
218
|
+
[0.162.1 verification record](docs/codex-0.162.1-compatibility.md) for tested
|
|
219
|
+
operations and remaining limits; a newer version alone is not a compatibility guarantee.
|
|
125
220
|
|
|
126
221
|
## Documentation
|
|
127
222
|
|
|
128
|
-
|
|
223
|
+
Choose the guide that matches what you are trying to do:
|
|
224
|
+
|
|
225
|
+
| Guide | Use it for |
|
|
129
226
|
| --- | --- |
|
|
130
|
-
| [
|
|
131
|
-
| [
|
|
132
|
-
| [Codex
|
|
133
|
-
| [
|
|
134
|
-
| [
|
|
135
|
-
| [
|
|
136
|
-
| [
|
|
137
|
-
| [
|
|
138
|
-
| [
|
|
139
|
-
| [
|
|
140
|
-
| [
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
227
|
+
| [tmux quick start](docs/quickstart-tmux.md) | First OpenClaw task, multiple panes, and selectors |
|
|
228
|
+
| [Herdr quick start](docs/quickstart-herdr.md) | Local Herdr discovery and exact-version checks |
|
|
229
|
+
| [Codex CLI direct control](docs/codex-cli-native-compatibility.md) | Connect without tmux/Herdr, select conversations, send tasks, and follow exact progress and completion |
|
|
230
|
+
| [Claude Code direct control](docs/claude-cli-direct.md) | Basic tasks without tmux/Herdr or Claude plugins, exact progress and completion, and terminal fallback boundaries |
|
|
231
|
+
| [Codex Desktop](docs/codex-desktop-compatibility.md) | Discover existing Desktop conversations, send and monitor exact tasks, respond to interactions, and change native settings |
|
|
232
|
+
| [Backend Recovery](docs/backend-task-recovery.md) | Recover monitoring, renew deadlines, close management, stop watching, and retry failed callbacks |
|
|
233
|
+
| [Pi connector](connectors/pi/README.md) | Pi installation, semantic tool catalog, bundled skill, native approval, callbacks, upgrade, and uninstall |
|
|
234
|
+
| [DeepSeek Harness connector](connectors/deepseek-harness/README.md) | Harness installation, approval contract, callbacks, upgrade, and troubleshooting |
|
|
235
|
+
| [Operator guide](docs/operator-guide.md) | Complete command reference, reliable Send, Watch, Status, approval, recovery, Sessions, and native threads |
|
|
236
|
+
| [OpenClaw operations](docs/openclaw-operations.md) | npm alternative, configuration, auto-approval policy, supervisor behavior, and troubleshooting |
|
|
237
|
+
| [Host Bridge and Profiles](docs/host-bridge-profiles.md) | Connect another controller Host through MCP/stdio and a declarative Profile |
|
|
238
|
+
| [Terminal handoff protocol](docs/bidirectional-agent-protocol.md) | Identity, Turn lifecycle, callback guarantees, safety fences, and handoff semantics |
|
|
239
|
+
| [Storage and logging](docs/storage-and-logging.md) | State directories, permissions, protocol migration, logs, and privacy |
|
|
240
|
+
| [Testing](docs/testing.md) | Test tiers, architecture checks, and evidence workflows |
|
|
241
|
+
| [Contributing](CONTRIBUTING.md) | Local development and contribution workflow |
|
|
242
|
+
|
|
243
|
+
## Installation Alternatives
|
|
244
|
+
|
|
245
|
+
OpenClaw users who prefer npm can install the same core package directly:
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
npm install -g @scotthuang/agent-knock-knock
|
|
249
|
+
agent-knock-knock install-openclaw --verify
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
ClawHub remains the recommended OpenClaw path. Do not install both variants into the same OpenClaw profile.
|
|
253
|
+
|
|
254
|
+
To build the repository locally, see [local development installation](docs/openclaw-operations.md#local-development-build):
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
npm install
|
|
258
|
+
npm run build
|
|
259
|
+
npm run test:fast
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Connector development uses `npm run pi:build` from the repository root, or `cd connectors/pi && npm run build`; DeepSeek Harness has the matching `npm run deepseek:build` script.
|
|
263
|
+
|
|
264
|
+
## Security and Privacy
|
|
265
|
+
|
|
266
|
+
AKK controls local coding-agent sessions, so treat installation as privileged local automation. Use an unprivileged OS account, restrict backend, tmux, Herdr, and Desktop IPC sockets, keep the state directory private, and review approval prompts before allowing input. Ordinary AKK Send does not change agent permissions or require YOLO mode. Desktop tasks inherit that conversation's current settings. Respond to supported approvals and questions through their advertised actions; unknown request forms remain manual. The explicit Codex permission tool applies only the user-selected native mode; model-facing tools never receive terminal-control tokens, callback credentials, Composer text, or approval fingerprints.
|
|
267
|
+
|
|
268
|
+
Report vulnerabilities privately using [GitHub Security Advisories](https://github.com/scotthuang/agent-knock-knock/security/advisories/new). Please do not include secrets, private terminal output, or credentials in a public issue.
|
|
269
|
+
|
|
270
|
+
## License
|
|
271
|
+
|
|
272
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { BackendRecoveryNotification } from "./backend-task-recovery.js";
|
|
2
|
+
type CallbackSummaryInput = {
|
|
3
|
+
callback_route?: unknown;
|
|
4
|
+
notifications: BackendRecoveryNotification[];
|
|
5
|
+
};
|
|
6
|
+
/** Task completion, controller acceptance and downstream channel delivery are independent facts. */
|
|
7
|
+
export declare function backendCallbackPublicProjection(task: CallbackSummaryInput, active: boolean, stopped: boolean): {
|
|
8
|
+
callback_state: string;
|
|
9
|
+
callback_delivery_scope: "controller_acceptance_only";
|
|
10
|
+
channel_delivery_state: "unknown";
|
|
11
|
+
callback_notifications: {
|
|
12
|
+
id: string;
|
|
13
|
+
notification_id: string;
|
|
14
|
+
status: string;
|
|
15
|
+
attempts: number;
|
|
16
|
+
controller_acceptance: string;
|
|
17
|
+
error_code?: string | undefined;
|
|
18
|
+
request_dispatched?: boolean | undefined;
|
|
19
|
+
request_phase?: string | undefined;
|
|
20
|
+
retry_budget_exhausted?: boolean | undefined;
|
|
21
|
+
max_delivery_attempts?: number | undefined;
|
|
22
|
+
next_attempt_at?: string | undefined;
|
|
23
|
+
automatic_retry_stopped?: boolean | undefined;
|
|
24
|
+
}[];
|
|
25
|
+
};
|
|
26
|
+
export declare function backendCallbackSummaryLines(result: Record<string, unknown>): string[];
|
|
27
|
+
export {};
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/** Task completion, controller acceptance and downstream channel delivery are independent facts. */
|
|
2
|
+
export function backendCallbackPublicProjection(task, active, stopped) {
|
|
3
|
+
return {
|
|
4
|
+
callback_state: callbackState(task, active, stopped),
|
|
5
|
+
callback_delivery_scope: "controller_acceptance_only",
|
|
6
|
+
channel_delivery_state: "unknown",
|
|
7
|
+
callback_notifications: task.notifications.map(notificationProjection)
|
|
8
|
+
};
|
|
9
|
+
}
|
|
10
|
+
function acceptanceConfirmed(note) {
|
|
11
|
+
return note.status === "accepted" && note.outcome?.disposition === "accepted";
|
|
12
|
+
}
|
|
13
|
+
function callbackState(task, active, stopped) {
|
|
14
|
+
if (!task.callback_route)
|
|
15
|
+
return "not_configured";
|
|
16
|
+
// A completed task or an accepted earlier interaction cannot hide an unresolved notification.
|
|
17
|
+
if (task.notifications.some(note => note.status === "uncertain" ||
|
|
18
|
+
note.status === "accepted" && !acceptanceConfirmed(note)))
|
|
19
|
+
return "uncertain";
|
|
20
|
+
if (task.notifications.some(note => note.status === "failed"))
|
|
21
|
+
return "failed";
|
|
22
|
+
for (const [status, label] of [["leased", "in_flight"], ["retry_wait", "retry_wait"], ["ready", "pending"]]) {
|
|
23
|
+
if (task.notifications.some(note => note.status === status))
|
|
24
|
+
return label;
|
|
25
|
+
}
|
|
26
|
+
if (active)
|
|
27
|
+
return "monitoring";
|
|
28
|
+
if (task.notifications.length && task.notifications.every(acceptanceConfirmed))
|
|
29
|
+
return "accepted";
|
|
30
|
+
return stopped ? "stopped" : "not_pending";
|
|
31
|
+
}
|
|
32
|
+
function notificationProjection(note) {
|
|
33
|
+
const evidence = note.outcome?.evidence;
|
|
34
|
+
const phase = evidence?.request_phase;
|
|
35
|
+
return {
|
|
36
|
+
id: note.id, notification_id: note.id, status: note.status, attempts: note.attempts,
|
|
37
|
+
controller_acceptance: acceptanceConfirmed(note) ? "confirmed" : "unconfirmed",
|
|
38
|
+
...(note.outcome && "error_code" in note.outcome ? { error_code: note.outcome.error_code } : {}),
|
|
39
|
+
...(typeof evidence?.request_dispatched === "boolean" ? { request_dispatched: evidence.request_dispatched } : {}),
|
|
40
|
+
...(typeof phase === "string" && ["connection_handshake", "before_dispatch", "submitted", "unknown"].includes(phase)
|
|
41
|
+
? { request_phase: phase } : {}),
|
|
42
|
+
...(typeof evidence?.retry_budget_exhausted === "boolean" ? { retry_budget_exhausted: evidence.retry_budget_exhausted } : {}),
|
|
43
|
+
...(Number.isSafeInteger(evidence?.max_delivery_attempts) && Number(evidence?.max_delivery_attempts) > 0
|
|
44
|
+
? { max_delivery_attempts: Number(evidence?.max_delivery_attempts) } : {}),
|
|
45
|
+
...(note.retry_at ? { next_attempt_at: note.retry_at } : {}),
|
|
46
|
+
...(note.status === "failed" && note.outcome?.disposition === "retryable_failure"
|
|
47
|
+
? { automatic_retry_stopped: true } : {})
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
export function backendCallbackSummaryLines(result) {
|
|
51
|
+
if (result.callback_delivery_scope !== "controller_acceptance_only")
|
|
52
|
+
return [];
|
|
53
|
+
return [
|
|
54
|
+
`callback state: ${typeof result.callback_state === "string" ? result.callback_state : "unknown"}`,
|
|
55
|
+
"Callback acceptance only confirms controller acceptance; user-channel delivery is unknown."
|
|
56
|
+
];
|
|
57
|
+
}
|
|
58
|
+
//# sourceMappingURL=backend-callback-public-projection.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"backend-callback-public-projection.js","sourceRoot":"","sources":["../../src/backend-callback-public-projection.ts"],"names":[],"mappings":"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"}
|
|
@@ -8,6 +8,8 @@ export interface BackendProgressItem {
|
|
|
8
8
|
delivery?: string | null;
|
|
9
9
|
status?: unknown;
|
|
10
10
|
exitCode?: unknown;
|
|
11
|
+
/** Fixed public action categories; never raw native tool names or arguments. */
|
|
12
|
+
actionKind?: "file_read" | "file_search" | "user_question";
|
|
11
13
|
/** Native item times only: never synthesize these from the read or turn time. */
|
|
12
14
|
startedAtMs?: number | null;
|
|
13
15
|
completedAtMs?: number | null;
|
|
@@ -60,7 +60,10 @@ function actionTitle(item) {
|
|
|
60
60
|
interrupted: "interrupted", declined: "declined", pending: "pending" };
|
|
61
61
|
const status = typeof item.status === "string" && Object.hasOwn(statuses, item.status) ? statuses[item.status] : "status unknown";
|
|
62
62
|
const exit = item.type === "commandExecution" && Number.isSafeInteger(item.exitCode) ? ` (exit ${item.exitCode})` : "";
|
|
63
|
-
|
|
63
|
+
const actionTitles = { file_read: "File read", file_search: "File search", user_question: "User question" };
|
|
64
|
+
const title = item.type === "dynamicToolCall" && item.actionKind && Object.hasOwn(actionTitles, item.actionKind)
|
|
65
|
+
? actionTitles[item.actionKind] : titles[item.type];
|
|
66
|
+
return `${title}: ${status}${exit}`;
|
|
64
67
|
}
|
|
65
68
|
function redactPublicCommentary(text) {
|
|
66
69
|
const withoutCode = text.replace(/```[^\n]*\n[\s\S]*?(?:```|$)/gu, "[code omitted]")
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"backend-public-progress.js","sourceRoot":"","sources":["../../src/backend-public-progress.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,wFAAwF;AACxF,MAAM,CAAC,MAAM,mCAAmC,GAAG,GAAG,CAAC;AACvD,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;
|
|
1
|
+
{"version":3,"file":"backend-public-progress.js","sourceRoot":"","sources":["../../src/backend-public-progress.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
import { resolveMonitorHardTimeoutMinutes } from "./monitor-deadline-policy.js";
|
|
2
|
+
import { backendCallbackSummaryLines } from "./backend-callback-public-projection.js";
|
|
2
3
|
import { pushOptional, requiredControllerSessionKey, requiredString } from "./semantic-tool-arguments.js";
|
|
3
4
|
import { isRecord, nonBlankString } from "./value-guards.js";
|
|
4
5
|
const commands = new Set(["renew", "close", "recover", "retry-callback"]);
|
|
5
|
-
const backendIdentity = /^(?:desktop|codex-cli):/u;
|
|
6
|
-
const backendWatchPrefix = /^(?:desktop-watch|codex-cli-watch):/u;
|
|
7
|
-
const backendWatch = /^(?:desktop-watch|codex-cli-watch):[A-Za-z0-9_-]{8,128}$/u;
|
|
6
|
+
const backendIdentity = /^(?:desktop|codex-cli|claude-cli):/u;
|
|
7
|
+
const backendWatchPrefix = /^(?:desktop-watch|codex-cli-watch|claude-cli-watch):/u;
|
|
8
|
+
const backendWatch = /^(?:desktop-watch|codex-cli-watch|claude-cli-watch):[A-Za-z0-9_-]{8,128}$/u;
|
|
8
9
|
export function isBackendTaskWatchId(value) {
|
|
9
10
|
return typeof value === "string" && backendWatch.test(value);
|
|
10
11
|
}
|
|
@@ -108,6 +109,6 @@ export function formatBackendRecoveryCommandResult(result, command) {
|
|
|
108
109
|
lines.push(`callback ${id}: ${status}`);
|
|
109
110
|
}
|
|
110
111
|
}
|
|
111
|
-
return [`AKK backend ${command}.`, ...lines].join("\n");
|
|
112
|
+
return [`AKK backend ${command}.`, ...lines, ...backendCallbackSummaryLines(result)].join("\n");
|
|
112
113
|
}
|
|
113
114
|
//# sourceMappingURL=backend-recovery-semantic.js.map
|