@orchbee/cli-win32-x64 0.0.0-stage → 0.1.0-beta.2

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.
Files changed (44) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +4 -2
  3. package/package.json +22 -5
  4. package/release/agent-observation-adapters/.agents/plugins/marketplace.json +12 -0
  5. package/release/agent-observation-adapters/.claude-plugin/marketplace.json +13 -0
  6. package/release/agent-observation-adapters/README.md +363 -0
  7. package/release/agent-observation-adapters/bundle/.claude-plugin/plugin.json +8 -0
  8. package/release/agent-observation-adapters/bundle/.codex-plugin/plugin.json +7 -0
  9. package/release/agent-observation-adapters/bundle/.grok-plugin/plugin.json +7 -0
  10. package/release/agent-observation-adapters/bundle/.plugin/plugin.json +7 -0
  11. package/release/agent-observation-adapters/bundle/cline/orchbee-agent-observation.js +187 -0
  12. package/release/agent-observation-adapters/bundle/gemini/gemini-extension.json +5 -0
  13. package/release/agent-observation-adapters/bundle/gemini/hooks/hooks.json +118 -0
  14. package/release/agent-observation-adapters/bundle/hermes/plugin.py +40 -0
  15. package/release/agent-observation-adapters/bundle/hooks/codex.json +142 -0
  16. package/release/agent-observation-adapters/bundle/hooks/copilot.json +114 -0
  17. package/release/agent-observation-adapters/bundle/hooks/grok.json +170 -0
  18. package/release/agent-observation-adapters/bundle/hooks/hooks.json +244 -0
  19. package/release/agent-observation-adapters/bundle/kilo/orchbee-agent-observation.mjs +3 -0
  20. package/release/agent-observation-adapters/bundle/omp/orchbee-agent-observation.cjs +4 -0
  21. package/release/agent-observation-adapters/bundle/omp/orchbee-agent-observation.mjs +117 -0
  22. package/release/agent-observation-adapters/bundle/opencode/orchbee-agent-observation.mjs +13 -0
  23. package/release/agent-observation-adapters/bundle/package.json +25 -0
  24. package/release/agent-observation-adapters/bundle/pi/orchbee-agent-observation.cjs +4 -0
  25. package/release/agent-observation-adapters/bundle/pi/orchbee-agent-observation.mjs +112 -0
  26. package/release/agent-observation-adapters/bundle/qwen-code/qwen-extension.json +232 -0
  27. package/release/agent-observation-adapters/bundle/scripts/forward-hook.mjs +33 -0
  28. package/release/agent-observation-adapters/bundle/scripts/hook-sanitizers.mjs +571 -0
  29. package/release/agent-observation-adapters/bundle/scripts/observation-transport.mjs +549 -0
  30. package/release/agent-observation-adapters/bundle/scripts/opencode-family-observation.mjs +350 -0
  31. package/release/agent-observation-adapters/capsule.json +4 -0
  32. package/release/cohort.json +1 -0
  33. package/release/conpty/Microsoft.ConPTY-LICENSE.txt +21 -0
  34. package/release/conpty/OpenConsole.exe +0 -0
  35. package/release/conpty/conpty.dll +0 -0
  36. package/release/licenses/agent-detection/LICENSE +201 -0
  37. package/release/licenses/agent-detection/NOTICE +20 -0
  38. package/release/orchbee-launcher.exe +0 -0
  39. package/release/orchbee-server.exe +0 -0
  40. package/release/orchbee-terminal-host.exe +0 -0
  41. package/release/orchbee-worker.exe +0 -0
  42. package/release/orchbee.exe +4 -0
  43. package/release/release.json +1 -0
  44. package/release/release.json.sig +1 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Orchbee contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,5 @@
1
- # Temporary Holding Version
1
+ # Orchbee program for one system
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ This package carries the signed Orchbee program for one operating system and processor. Do not
4
+ install it directly: install [`orchbee`](https://www.npmjs.com/package/orchbee), which selects the
5
+ right one.
package/package.json CHANGED
@@ -1,6 +1,23 @@
1
1
  {
2
- "name": "@orchbee/cli-win32-x64",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@orchbee/cli-win32-x64",
3
+ "version": "0.1.0-beta.2",
4
+ "description": "Orchbee for Windows x64; install orchbee instead",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/i-need-token/orchbee.git"
9
+ },
10
+ "os": [
11
+ "win32"
12
+ ],
13
+ "cpu": [
14
+ "x64"
15
+ ],
16
+ "files": [
17
+ "release"
18
+ ],
19
+ "publishConfig": {
20
+ "access": "public",
21
+ "tag": "next"
22
+ }
23
+ }
@@ -0,0 +1,12 @@
1
+ {
2
+ "name": "orchbee-local",
3
+ "owner": { "name": "Orchbee" },
4
+ "plugins": [
5
+ {
6
+ "description": "Locally sanitizes terminal Agent lifecycle events for Orchbee status observation",
7
+ "name": "orchbee-agent-observation",
8
+ "source": "./bundle",
9
+ "version": "0.4.17"
10
+ }
11
+ ]
12
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "description": "Explicitly installed Orchbee integrations for terminal Agent observation",
3
+ "name": "orchbee-local",
4
+ "owner": { "name": "Orchbee" },
5
+ "plugins": [
6
+ {
7
+ "description": "Locally sanitizes terminal Agent lifecycle events for Orchbee status observation",
8
+ "name": "orchbee-agent-observation",
9
+ "source": "./bundle",
10
+ "version": "0.4.17"
11
+ }
12
+ ]
13
+ }
@@ -0,0 +1,363 @@
1
+ # Agent observation adapters
2
+
3
+ This Capsule contains twenty explicitly installed, provider-bound observation adapters for
4
+ Claude Code, Codex, Grok, OpenCode, Kilo, Cursor, Qoder CLI, Antigravity CLI, Mastracode, Droid, Kimi, Letta, Devin, Hermes, Pi, OMP, Gemini CLI, GitHub Copilot CLI, Cline, and Qwen Code.
5
+ Each adapter validates its own upstream event contract and emits the same content-free normalized
6
+ facts through Orchbee's shared local socket/pipe plus private-APC correlation transport. The
7
+ Server's closed adapter registry, not an adapter payload, grants provider identity, accepted
8
+ events, and maximum capabilities. The [integration writer](../README.md) owns this source and
9
+ installs it; native staging and Desktop packaging copy it into each cohort.
10
+
11
+ ## Windows Codex transport
12
+
13
+ The native Windows cohort uses the same v1 rich-envelope/private-APC join. The capsule
14
+ supplies Codex `commandWindows` hooks. Codex 0.167 runs them through the session shell:
15
+ PowerShell with `-NoProfile -Command`, or `cmd.exe /C` when it detects no shell. Each hook is
16
+ therefore the fixed base64 Node bootstrap described for Grok, which runs unchanged in
17
+ PowerShell 5.1, PowerShell 7 and cmd. It reads `PLUGIN_ROOT` as data, accepts the verbatim
18
+ `\\?\` spelling Codex gives it under an explicit `CODEX_HOME`, sets the literal script and
19
+ provider arguments, and stays silent when the root or script is absent. The Windows x64 cohort must include its pinned ConPTY runtime: the inbox ConHost may
20
+ consume private APC sequences. Windows does not gain Unix remote discovery or
21
+ additional provider installation support through this adapter change. Native managed
22
+ enable/disable and start/prompt remain separate CLI obligations.
23
+
24
+ | Field | Contract |
25
+ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
+ | Problem and owner | Codex command hooks in an Orchbee ConPTY must reach the native Server's existing observation ingress. The shared adapter owns delivery; Server/Host retain envelope validation, generation identity and the exact join. |
27
+ | Inputs and reference | Allowlisted normalized Codex events, the inherited `ORCHBEE_AGENT_OBSERVATION_SOCKET` and the provider-supplied plugin root. Codex 0.167.0's Windows hook contract accepts `commandWindows` and runs it in the session shell, but with `CREATE_NO_WINDOW`, so the hook has its own hidden console and its correlation hint never reaches the Agent's terminal. Environment strings never grant Agent or terminal identity. |
28
+ | Endpoint policy | Admit only the exact local pipe spelling `\\.\pipe\orchbee-<32-lowercase-hex>-observation`. Missing, malformed, remote UNC and non-observation targets produce no delivery. Windows never scans pipes, files or Unix SSH forwards. The injected endpoint and native Server ACL provide routing; the adapter does not claim to inspect pipe ownership. |
29
+ | Correlation target | Use only the literal device `\\.\CONOUT$`, opened with read/write access and verified as a character device before writing. Never use a relative `CONOUT$`, environment-selected device, stdout or stderr. Direct visibility remains unknown. Missing console means no hint; no fallback may redirect the hint into a file. |
30
+ | Workflow and transitions | Validate observation → resolve exact endpoint and fixed console target → send bounded content-free envelope → wait for exact bounded ACK → write the matching private APC → close the console handle. Missing endpoint, invalid input, timeout, rejected ACK and open/write failure stop the affected delivery. Rich-only events expire under the existing ingress rules. |
31
+ | Invariants and effects | No prompt/output/path content enters the envelope; no APC precedes acceptance; neither half alone binds an Agent; no hook installs configuration or launches a Session. Windows never unlinks a pipe. The provider hook exits successfully on absent Node/runtime or transport failure. Socket and console handles remain locally owned and close on completion/failure. |
32
+ | Rollout and recovery | Publish a new immutable Capsule version and matching resource/consumer versions. Git preserves LF bytes across Windows checkouts for the hashed payload. Preserve older Capsules and provider declarations until an explicit managed action replaces them. The Unix command field and existing Unix transport behavior remain available. The adapter adds no dependency or wire version; Windows cohort delivery additionally requires the pinned Host ConPTY runtime. |
33
+ | Evidence and limits | Deterministic admission/ACK-order cases, real Windows named-pipe ACK cases, silent bounded command-hook process cases and an isolated native Server/ConPTY delivery witness. Transport evidence does not prove managed installation, real Agent task completion, physical TUI interaction or every provider's Windows support. Same-author challenge only; TLA execution remains deferred by user instruction. |
34
+
35
+ ## Supported contracts
36
+
37
+ | Adapter | Reference version | Integration surface | Maximum status evidence |
38
+ | ------------------ | --------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ |
39
+ | Claude Code | Current documented hook/plugin contract | Command-hook plugin | Session, Turn, tool, question, approval, compaction, subagent, completion, failure |
40
+ | Codex | `0.150.1` (Unix), `0.167.0` (Windows) | Command-hook plugin | Session, Turn, tool, question, approval, compaction, subagent, completion |
41
+ | Grok | `1.0.5` | Command-hook plugin | Session, Turn, tool, approval, compaction, subagent, idle, completion, failure, cancellation, interruption |
42
+ | OpenCode | `1.3.4`–`1.18.30`; `2.2.5` Windows TUI | JavaScript plugin events | Session, busy/retry/idle, tool, question, approval, error (1.x); displayed root session, busy/idle (2.x) |
43
+ | Kilo | `cb67014f` | JavaScript plugin events | Session, busy/retry/idle/offline question, chat, tool, question, approval, error |
44
+ | Pi | `0.84.4` | Extension API | Session, Agent start/settled, blocking UI prompt, tool, compaction |
45
+ | OMP | `18.0.10` | Extension API | Session, Agent start/end, Ask tool, tool approval, tool, compaction, retry |
46
+ | Gemini CLI | `20f70757` | Command-hook extension | Session, Agent start/end, tool, question, permission, compaction, completion |
47
+ | GitHub Copilot CLI | `1.0.81` | Command-hook plugin | Session, Turn, actual question/permission prompt, tool result, compaction, completion, unrecoverable failure |
48
+ | Cline | `3.0.60` | Plugin runtime API | Run/Turn, tool, question, completion, failure, interruption |
49
+ | Qwen Code | `c3a4058a` | Command-hook extension | Session, Turn, tool, question, permission, compaction, subagent, completion, failure |
50
+
51
+ These are separate compatibility contracts. Pi and OMP deliberately do not share an adapter;
52
+ Gemini CLI and Qwen Code likewise retain separate manifests and event interpretation. Versions
53
+ outside the matrix are unsupported until their event fixtures and capability grants are reviewed.
54
+
55
+ ## Explicit setup
56
+
57
+ ### Execution host
58
+
59
+ Install the selected adapter on every machine where that Agent process runs. For
60
+ Orchbee → SSH → remote tmux/Zellij → Agent, installation therefore occurs on the remote host, and
61
+ an OpenSSH reverse Unix-socket forward provides transport only. Orchbee currently sets up no such
62
+ forward, so a remote adapter finds no endpoint. Orchbee never installs or changes an adapter
63
+ automatically. On the local machine, the user may explicitly enable or disable Orchbee's exact
64
+ entry with `orchbee agent integration enable` or `disable`, or through Desktop Settings, which
65
+ runs the same Worker operation. Orchbee never copies this resource to another host, edits remote
66
+ Agent configuration, or runs remote setup; remote installation remains manual.
67
+
68
+ Use a durable standalone copy of this directory as `<adapter-root>`. Do not persist a path into an
69
+ Orchbee application bundle: deleting or replacing the application must not break Agent startup.
70
+ A managed enable first publishes a validated Capsule under
71
+ `internal/integrations/agent-observation/<version>` in its environment's data root (`~/.orchbee`
72
+ for release) and points the provider's entry at that durable copy. Provider-local module entries
73
+ catch a missing Capsule, shell command hooks test that their runtime still exists, and Gemini/Qwen entries
74
+ are self-contained copies. An uninstaller must retain every Capsule still referenced by any
75
+ provider declaration; explicit disable owns removal of the corresponding provider entry.
76
+
77
+ Local Claude and Copilot inspection verifies both the exact plugin and its marketplace source;
78
+ Grok inspection verifies the copied plugin's recorded source and version. A sibling Capsule version
79
+ under the same installation parent reads as `update-required`, not an enabled current adapter, and
80
+ changes only through an explicit enable. Any same-named entry with a different source remains an
81
+ untouched conflict.
82
+
83
+ The [integration writer](../README.md) defines the managed transaction, exact managed entries,
84
+ conflict handling, and rollback, and the
85
+ [Windows integration contract](../../../apps/orchbee/docs/windows-agent-integrations.md) records
86
+ Windows paths and evidence. The commands below remain the manual setup path and are always
87
+ required on remote hosts.
88
+
89
+ ### Claude Code
90
+
91
+ ```sh
92
+ claude plugin marketplace add <adapter-root>
93
+ claude plugin install orchbee-agent-observation@orchbee-local
94
+ claude plugin enable orchbee-agent-observation@orchbee-local
95
+ ```
96
+
97
+ Disable or uninstall that fully qualified plugin to roll back. Merely adding the marketplace does
98
+ not enable observation.
99
+
100
+ ### Codex
101
+
102
+ ```sh
103
+ codex plugin marketplace add <adapter-root>
104
+ codex plugin add orchbee-agent-observation@orchbee-local
105
+ ```
106
+
107
+ Codex runs the bundled hooks only after you trust them in its Hooks review (`/hooks`). Use
108
+ `codex plugin remove orchbee-agent-observation@orchbee-local` to roll back.
109
+
110
+ ### Grok
111
+
112
+ ```sh
113
+ grok plugin install <adapter-root>/bundle
114
+ ```
115
+
116
+ Review the plugin before accepting installation. Disable or uninstall
117
+ `orchbee-agent-observation` to roll back. A managed disable uninstalls only a source-proven
118
+ Orchbee copy.
119
+
120
+ ### OpenCode
121
+
122
+ On OpenCode 1.3.4 or later, add the absolute entry path
123
+ `<adapter-root>/bundle/opencode/orchbee-agent-observation.mjs` as a local plugin. Keep the durable
124
+ standalone root in place because the entry imports the shared transport beside it, and remove the
125
+ configured path to roll back. OpenCode 2.x admits only a directory as a configured plugin, so use a
126
+ managed enable there. A managed enable writes a provider-local guarded bootstrap into the
127
+ discovered `plugins` directory and, on Windows, the `orchbee-agent-observation-tui` client
128
+ directory whose TUI entry observes OpenCode 2.x; if the Capsule is later unavailable, each
129
+ bootstrap catches the failed import and returns no hooks or output.
130
+
131
+ ### Pi
132
+
133
+ ```sh
134
+ pi install <adapter-root>/bundle/pi/orchbee-agent-observation.cjs
135
+ ```
136
+
137
+ Use `pi remove` with the same local source to roll back. Pi `0.84.4` is the compatibility floor for
138
+ the required `agent_settled` and `ui_prompt_*` events.
139
+
140
+ ### OMP
141
+
142
+ For one explicit run:
143
+
144
+ ```sh
145
+ omp --extension <adapter-root>/bundle/omp/orchbee-agent-observation.cjs
146
+ ```
147
+
148
+ For persistent opt-in, add that absolute entry to OMP's configured extensions. Remove the
149
+ configured path to roll back.
150
+
151
+ ### Gemini CLI
152
+
153
+ For manual setup, copy a self-contained extension after confirming that the target does not already
154
+ exist:
155
+
156
+ ```sh
157
+ mkdir -p ~/.gemini/extensions/orchbee-agent-observation
158
+ cp -R <adapter-root>/bundle/gemini/. ~/.gemini/extensions/orchbee-agent-observation/
159
+ cp -R <adapter-root>/bundle/scripts ~/.gemini/extensions/orchbee-agent-observation/scripts
160
+ ```
161
+
162
+ Remove only that exact copied extension to roll back. A managed enable publishes and fingerprints
163
+ the same bounded self-contained layout atomically; modified, expanded, or unmarked directories remain
164
+ untouched conflicts.
165
+
166
+ ### GitHub Copilot CLI
167
+
168
+ ```sh
169
+ copilot plugins marketplace add <adapter-root>
170
+ copilot plugins install orchbee-agent-observation@orchbee-local
171
+ ```
172
+
173
+ Use `copilot plugins disable orchbee-agent-observation@orchbee-local --plugin` to disable, and the
174
+ matching `enable` command to restore it. Orchbee does not register `PreToolUse` or
175
+ `PermissionRequest`: those hooks run before Copilot's permission policy is resolved and therefore
176
+ cannot prove that a user-facing wait occurred.
177
+
178
+ ### Cline
179
+
180
+ ```sh
181
+ cline plugin install <adapter-root>/bundle --json
182
+ ```
183
+
184
+ Use `cline plugin uninstall orchbee-agent-observation --json` to roll back. Read-only inspection is
185
+ bounded to Cline's official local-install layout and requires Orchbee's exact package marker; an
186
+ unmarked same-named entry is a conflict, not an Orchbee-owned installation.
187
+
188
+ ### Qwen Code
189
+
190
+ For manual setup, copy a self-contained extension after confirming that the target does not already
191
+ exist:
192
+
193
+ ```sh
194
+ mkdir -p ~/.qwen/extensions/orchbee-agent-observation
195
+ cp -R <adapter-root>/bundle/qwen-code/. ~/.qwen/extensions/orchbee-agent-observation/
196
+ cp -R <adapter-root>/bundle/scripts ~/.qwen/extensions/orchbee-agent-observation/scripts
197
+ ```
198
+
199
+ Remove only that exact copied extension to roll back. A managed enable publishes and fingerprints
200
+ the same bounded self-contained layout atomically; modified, expanded, or unmarked directories remain
201
+ untouched conflicts.
202
+
203
+ ## Status fidelity
204
+
205
+ An adapter emits only evidence its upstream surface actually provides. OpenCode, Pi, and OMP
206
+ settlement becomes affirmative `Ready` without inventing a successful outcome, so it emits no
207
+ success notification. Copilot enters attention only for its actual `permission_prompt` or
208
+ `elicitation_dialog` notifications. Qwen starts a user Turn only when `submitted_prompt` proves user
209
+ provenance; its continuation callbacks are ignored. Cline intentionally claims no session
210
+ lifecycle, approval, or subagent capability because its plugin runtime does not prove those facts.
211
+ Exact errors remain failures where available. Cline keys every event by the root session id its
212
+ plugin `setup` context reports (`ctx.session.sessionId`), which is the id `cline --id` resumes.
213
+ Each sandboxed plugin instance serves one root session; if `setup` is absent, reports no valid id,
214
+ or reports a different id later, the adapter falls back for good to the run snapshot's
215
+ `conversationId`, which no resume accepts. Events whose snapshot names a non-empty
216
+ `parentAgentId` are subagent runs and are dropped, so they never appear as extra root sessions.
217
+ Cline records a completion before delivery and suppresses later events for that exact session and
218
+ run while its tombstone remains retained. The bounded cache keeps the 64 newest completed runs for
219
+ each of at most 128 tracked sessions. Run tombstones use completion-order FIFO eviction, and a new
220
+ completion refreshes its session before the least recently completed session is evicted. Either
221
+ eviction permits an older identity to be observed again rather than retaining unbounded plugin
222
+ state.
223
+ `ClineObservationOrdering` checks completion-before-start, duplicate completion, activity, session
224
+ isolation, and bounded eviction with two conversations and a two-run retention bound. Grok
225
+ cancellation is scoped by `promptId`, preventing a delayed cancellation report from ending a newer
226
+ Turn. Missing events, disabled hooks, unsupported versions, transport failure, and a fully
227
+ disconnected SSH path degrade to stale or unknown rather than guessed completion.
228
+
229
+ ## Security and failure boundary
230
+
231
+ The Worker injects only `ORCHBEE_AGENT_OBSERVATION_SOCKET` into the terminals it launches, through
232
+ a non-persistent environment overlay. Before transport, each entry selects only bounded event, session, Turn,
233
+ tool-operation, and subagent identifiers and discards prompts, questions, tool input/output,
234
+ transcript paths, working directories, error text, notification text, and unknown fields. When the
235
+ Agent inherited a well-formed `ORCHBEE_RUN_TOKEN` from its managed launch command, the envelope
236
+ carries it as the optional `runToken`; a missing or malformed value is omitted.
237
+
238
+ Publishing adds the owner record `bundle/scripts/environment.json`,
239
+ `{"environment":"<stem>","version":1}`, which names the environment that installed the Capsule
240
+ and travels with every copy a provider makes of `bundle/`. Before any transport, a hook acts only
241
+ when the inherited `ORCHBEE_ENVIRONMENT` equals that environment, or when the variable is absent
242
+ and the environment is release (`orchbee`). A Capsule without the record is release's. Otherwise,
243
+ or when the record cannot be read, the hook exits silently and successfully, so an Agent reports
244
+ only to the environment whose terminal runs it. The rich
245
+ half goes to same-user private Unix-domain sockets or the injected native Windows observation pipe. A local process uses only the exact endpoint in
246
+ its environment; only a remote process without that overlay discovers same-user forwarded
247
+ candidates, and discovery requires an inherited non-empty `SSH_CONNECTION`, `SSH_CLIENT`, or
248
+ `SSH_TTY` marker. An ordinary local terminal without the exact overlay performs no socket scan.
249
+ The envelope, its observation, and the correlation half carry the Capsule's one `agent-hook`
250
+ generation, currently 1. Only after an endpoint returns that generation's exact bounded
251
+ acknowledgement does the adapter write one content-free private APC correlation half directly to
252
+ each resolved outer TTY. With no exact acknowledgement, including from a Server whose window no
253
+ longer admits the generation, the adapter writes no terminal control sequence and the hook still
254
+ ends successfully. The Server requires an exact
255
+ event/correlation join for a live terminal generation, so neither half can associate and authorize
256
+ rich state alone; unmatched envelopes sent to another live instance expire without canonical
257
+ effect.
258
+ On Unix, every TTY candidate must be a lexically normalized path below `/dev`; the writer opens it
259
+ nonblocking without following symlinks, verifies a character device, and requires same-user
260
+ ownership except for the kernel-owned `/dev/tty` alias. A resolver cannot redirect a hint into a
261
+ regular file or another user's terminal.
262
+
263
+ The Unix resolver supports direct terminals, every attached tmux client, conservative Zellij
264
+ client visibility, and nested mux environments. It asserts `hidden` only when an attached mux
265
+ client is showing another pane; direct and active-pane routes remain `unknown` because the hook
266
+ cannot prove application-window visibility. Orchbee currently ships no shell integration that adds
267
+ the mode-`0600` remote Unix socket an OpenSSH reverse forward would carry. There is no
268
+ HTTP listener, TCP port, Bearer token, inherited terminal secret, automatic remote installation, or
269
+ durable remote cache. Every adapter is passive, writes no shell output, and fails open on missing
270
+ configuration, invalid input, timeout, resolver failure, or listener failure. Persisted command
271
+ hooks first test for Node and their readable runtime and always end successfully if either is gone.
272
+ Orchbee never uses OSC 9, OSC 777, OSC 99, OSC 1337, BEL, or provider notification hooks as its
273
+ correlation channel, so unrelated terminals such as Warp do not turn observation into user-facing
274
+ notification popups.
275
+
276
+ ## Verification
277
+
278
+ From the repository root:
279
+
280
+ ```sh
281
+ claude plugin validate crates/agent-integration-writer/agent-observation-adapters --strict
282
+ grok plugin validate crates/agent-integration-writer/agent-observation-adapters/bundle
283
+ pnpm test:agent-observation-adapters
284
+ ```
285
+
286
+ The Server's [Agent observation model](../../../apps/orchbee-server/docs/agent-canonical-model.md)
287
+ owns the ingress, the join, and transport admission.
288
+
289
+ ## Claude direct execution
290
+
291
+ The capsule launches Claude hooks with `node` plus an explicit argument vector, following the [upstream exec contract](https://code.claude.com/docs/en/hooks#exec-form-and-shell-form). A fixed module expression imports the literal plugin script path through pathToFileURL and catches import failures. Script removal and malformed input remain silent; Node itself must exist on the provider PATH. If Node cannot start, Claude may display its non-blocking diagnostic. The integration never produces a tool permission decision.
292
+
293
+ This shared declaration allows native Windows onboarding without a shell dependency. Existing events, hook deadlines, input bounds, sanitization and transport ownership are unchanged. The [native Windows contract](../../../apps/orchbee/docs/windows-agent-integrations.md) owns installation and controlled Windows evidence; this change does not establish authenticated Agent task completion or new macOS/Linux workflow support. Old capsules remain immutable and explicit repair installs the current payload.
294
+
295
+ ## Copilot direct execution
296
+
297
+ The capsule uses the [Copilot exec hook contract](https://docs.github.com/en/copilot/reference/hooks-reference) with Node. The fixed import guard reads COPILOT_PLUGIN_ROOT directly from the provider child environment, checks that it is absolute, and passes its joined script path through pathToFileURL. It emits no output when the root or script is absent. Node is a prerequisite; an unavailable executable is a provider launch error, not a delivered observation. PascalCase event names retain the documented VS Code compatible input fields used by the existing sanitizer. No shell interprets the path. Windows onboarding uses the separately verified current plugin command/JSON contract.
298
+
299
+ ### Grok command bootstrap
300
+
301
+ The capsule keeps Grok's command-only hook contract with a fixed base64-encoded Node bootstrap. The decoded code reads GROK_PLUGIN_ROOT as data, sets the literal script/provider arguments, and performs a guarded dynamic import; it never inserts a user path into shell syntax. PowerShell 5.1/7 preserve redirected JSON stdin through this command. Node is a prerequisite; missing Node is a provider command error, while missing roots/scripts remain silent. Grok's existing camelCase event inputs, sanitizer, deadlines and observation transport are unchanged. The encoding protects shell quoting, not secrets. Windows local installation state is read separately from the provider-owned TOML configuration; it does not establish effective project policy or an active session's reload.
302
+
303
+ ## OpenCode-family Windows onboarding
304
+
305
+ The capsule adds Kilo and shares its event normalizer with OpenCode. The shared factory admits lifecycle identities from sessionID or legacy info.id, rejecting disagreement. A `session.created` or `session.updated` event whose `info` carries a valid `id` and a non-empty `parentID` marks a child (subagent) session; the factory remembers at most 256 child ids, first in, first out, and drops every observation for them, including the child's own session start. A child created before the plugin loaded stays unknown and reads as a second root session. Callback arguments and outputs remain private. Delivery retains at most 64 outstanding sanitized events, in order; overflow/dispose stops new admission and drops the queued suffix until reload, while an in-flight send may finish. Transport failures are silent. Windows native onboarding installs discoverable .js bootstraps and preserves foreign/newer entries.
306
+
307
+ Both entries export one plugin definition, `orchbeeAgentObservationPlugin`, that both loader generations accept once the managed bootstrap default-exports it: an `id`, the `server` factory that OpenCode 1.3.4+ and Kilo call, and the `setup` that OpenCode 2.x validates and awaits. OpenCode 1.3.4+ also admits the entry directly, since it accepts an exported object with a `server` function. OpenCode 1.0–1.3.3 call every export as a plugin function, so no single file serves them and 2.x together; they are unsupported. OpenCode 2.x runs plugins in a server process that never shares the Agent's console: a detached shared service by default, or a hidden standalone child with its own console. The private correlation hint cannot reach the Agent's terminal from there, so `setup` subscribes to nothing. The OpenCode entry also exports `orchbeeAgentObservationClientPlugin`, the `{ id, setup }` definition of the Windows client directory. Loaded as a server plugin its setup does nothing; loaded as a TUI plugin, in the TUI process that owns the Agent's console, it reads that TUI's route and session data at setup and then once a second, and reports only the root of the session the TUI displays: started when first displayed, ended when another root replaces it, never again once left, with busy and idle from its status. It remembers at most 256 left roots, first in, first out, and shares the same bounded delivery. The bootstrap delegates each entry to the Capsule's definition, so a later Capsule can change either without a new bootstrap; the named-export bootstrap earlier releases wrote reads as update-required. See the [owning Windows model](../../../apps/orchbee/docs/windows-agent-integrations.md#kilo-windows-integration-and-shared-event-model) for paths, transitions and evidence.
308
+
309
+ ## Gemini and Qwen command roots
310
+
311
+ The capsule executes fixed Node guards using ORCHBEE_AGENT_EXTENSION_ROOT in the provider's per-hook environment. Gemini supplies the value by recursively hydrating its external hook file; Qwen supplies it through recursively hydrated inline hooks in qwen-extension.json. Substitution affects an environment value, never command source. Both entries import their self-contained scripts and keep existing content-free event/transport bounds. Windows native onboarding and doctor share provider-specific directory overrides and refuse invalid explicit roots. Windows directory ownership checks retain exact marker and file-digest validation; unrecognized entry contracts remain refused. See the [Windows extension model](../../../apps/orchbee/docs/windows-agent-integrations.md#gemini-and-qwen-windows-extensions).
312
+
313
+ The Cursor adapter emits session-identified from consistent session/conversation identity aliases. It never derives working/idle or permission decisions. Windows native JSON onboarding installs the fixed encoded launcher; no authenticated provider execution is implied.
314
+
315
+ Qoder CLI uses qodercli identity-only observations for exact SessionStart/session_id input. The Windows native manager installs its encoded command group; Node is required and hook output remains an empty JSON object.
316
+
317
+ Antigravity CLI admits only conversationId from PreInvocation as session-identified; antigravity-cli is the adapter ID and antigravity is the canonical provider. Named Windows hooks return an empty JSON object and make no lifecycle or permission claims.
318
+
319
+ Mastracode admits content-free run, tool, approval and subagent facts from its ten selected hooks. AgentEnd alone determines the terminal outcome; suspended does not imply completion. See the [Windows contract](../../../apps/orchbee/docs/windows-agent-integrations.md#mastracode-windows-lifecycle-hooks).
320
+
321
+ Droid admits only SessionStart/session_id as session-identified, including resume and compaction. Its Windows manager edits the active configuration source; the adapter never infers idle or readiness.
322
+
323
+ Kimi admits exact SessionStart/SessionEnd with valid session_id as session-identified/session-ended. No turn completion is inferred from the blockable Stop hook. Native Windows owns the two-rule TOML installation.
324
+
325
+ Letta accepts exact SessionStart event_type and conversation_id. Default conversations require agent_id and become default:<agent_id>; only session identity is observed. Its Windows launcher emits no prompt feedback.
326
+
327
+ Devin accepts six exact hook_event_name values and valid session_id, emitting session-identified only. Prompt, tool and permission contents are discarded; Stop does not prove completion.
328
+
329
+ Hermes supplies a stdlib-only Python plugin that registers three identity callbacks and invokes the shared Node transport without a shell. It excludes noninteractive platforms and callback content, and returns no context or permission decisions.
330
+
331
+ ## Packaged payload identity
332
+
333
+ The current Capsule uses contract version 1. Its manifest contains exactly
334
+ `{contractVersion: 1, payloadSha256: "<64 lowercase hex>"}`. Its identity is the digest. Its
335
+ installation folder is named by `bundle/package.json`'s `version`, so a person reads which Capsule
336
+ an Agent entry runs: `<data root>/internal/integrations/agent-observation/<version>`, where a
337
+ name already holding a different payload takes `-2`, `-3`, and so on.
338
+
339
+ Compute SHA-256 over the UTF-8 encoding of `JSON.stringify(entries)`. Entries use
340
+ `/`-separated relative paths, ordered by UTF-16 code units; directories serialize
341
+ as `{kind,path}`, files as `{kind,path,sha256,size}` in that member order. Exclude
342
+ only `capsule.json` and the owner record `bundle/scripts/environment.json`; include both
343
+ documentation files and every other packaged file and directory. Every byte change, including formatting, requires recomputing
344
+ `payloadSha256` over the final tree. The Rust writer and native staging recompute
345
+ this digest before admitting the payload, with the same bounds and required files.
346
+
347
+ Doctor verifies installed bytes against their manifest, then compares that verified
348
+ identity with the current adjacent sidecar. An unstaged development binary uses
349
+ its embedded sidecar identity. A different digest is `update-required`; corrupt
350
+ bytes and uninspectable reads retain their distinct existing outcomes. Integration
351
+ CLI documents expose `capsule.payloadSha256`. Reinstall explicitly with
352
+ `orchbee agent integration enable --provider codex` (select the relevant provider).
353
+ After a completed enable or disable, the writer removes every other version folder of its own
354
+ Capsule folder when a fresh inspection shows that no Agent entry can name one: no provider reads
355
+ `update-required`, and every provider whose command is on PATH was inspected. Otherwise it keeps
356
+ them all, and it always keeps the current version. Disable removes provider entries under their
357
+ existing ownership guards. Another environment's Capsules, and the folders of
358
+ `~/.orchbee/agent-observation-adapters` where every environment installed before each kept its
359
+ own, are never swept. Non-current capsule metadata is
360
+ diagnosed as outdated only after verifying its actual digest, required runtime
361
+ files and named Orchbee package marker. This read-only diagnosis never admits a
362
+ non-current source as ready or authorizes replacing unknown files. There is no
363
+ automatic migration or background cleanup.
@@ -0,0 +1,8 @@
1
+ {
2
+ "author": { "name": "Orchbee" },
3
+ "defaultEnabled": false,
4
+ "displayName": "Orchbee Agent Observation",
5
+ "name": "orchbee-agent-observation",
6
+ "version": "0.4.17",
7
+ "description": "Locally sanitizes Claude Code lifecycle hooks for Orchbee Agent status observation"
8
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "author": { "name": "Orchbee" },
3
+ "description": "Locally sanitizes Codex lifecycle hooks for Orchbee Agent status observation",
4
+ "hooks": "./hooks/codex.json",
5
+ "name": "orchbee-agent-observation",
6
+ "version": "0.4.17"
7
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "author": { "name": "Orchbee" },
3
+ "description": "Locally sanitizes Grok lifecycle hooks for Orchbee Agent status observation",
4
+ "hooks": "./hooks/grok.json",
5
+ "name": "orchbee-agent-observation",
6
+ "version": "0.4.17"
7
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "author": { "name": "Orchbee" },
3
+ "description": "Locally sanitizes GitHub Copilot CLI lifecycle hooks for Orchbee Agent status observation",
4
+ "hooks": "./hooks/copilot.json",
5
+ "name": "orchbee-agent-observation",
6
+ "version": "0.4.17"
7
+ }