@orchbee/cli-win32-x64 0.0.0-stage → 0.1.0-beta.10
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/LICENSE +21 -0
- package/README.md +4 -2
- package/package.json +22 -5
- package/release/agent-observation-adapters/.agents/plugins/marketplace.json +12 -0
- package/release/agent-observation-adapters/.claude-plugin/marketplace.json +13 -0
- package/release/agent-observation-adapters/README.md +363 -0
- package/release/agent-observation-adapters/bundle/.claude-plugin/plugin.json +8 -0
- package/release/agent-observation-adapters/bundle/.codex-plugin/plugin.json +7 -0
- package/release/agent-observation-adapters/bundle/.grok-plugin/plugin.json +7 -0
- package/release/agent-observation-adapters/bundle/.plugin/plugin.json +7 -0
- package/release/agent-observation-adapters/bundle/cline/orchbee-agent-observation.js +187 -0
- package/release/agent-observation-adapters/bundle/gemini/gemini-extension.json +5 -0
- package/release/agent-observation-adapters/bundle/gemini/hooks/hooks.json +118 -0
- package/release/agent-observation-adapters/bundle/hermes/plugin.py +40 -0
- package/release/agent-observation-adapters/bundle/hooks/codex.json +142 -0
- package/release/agent-observation-adapters/bundle/hooks/copilot.json +114 -0
- package/release/agent-observation-adapters/bundle/hooks/grok.json +170 -0
- package/release/agent-observation-adapters/bundle/hooks/hooks.json +244 -0
- package/release/agent-observation-adapters/bundle/kilo/orchbee-agent-observation.mjs +3 -0
- package/release/agent-observation-adapters/bundle/omp/orchbee-agent-observation.cjs +4 -0
- package/release/agent-observation-adapters/bundle/omp/orchbee-agent-observation.mjs +117 -0
- package/release/agent-observation-adapters/bundle/opencode/orchbee-agent-observation.mjs +13 -0
- package/release/agent-observation-adapters/bundle/package.json +25 -0
- package/release/agent-observation-adapters/bundle/pi/orchbee-agent-observation.cjs +4 -0
- package/release/agent-observation-adapters/bundle/pi/orchbee-agent-observation.mjs +112 -0
- package/release/agent-observation-adapters/bundle/qwen-code/qwen-extension.json +232 -0
- package/release/agent-observation-adapters/bundle/scripts/forward-hook.mjs +33 -0
- package/release/agent-observation-adapters/bundle/scripts/hook-sanitizers.mjs +571 -0
- package/release/agent-observation-adapters/bundle/scripts/observation-transport.mjs +549 -0
- package/release/agent-observation-adapters/bundle/scripts/opencode-family-observation.mjs +350 -0
- package/release/agent-observation-adapters/capsule.json +4 -0
- package/release/cohort.json +1 -0
- package/release/conpty/Microsoft.ConPTY-LICENSE.txt +21 -0
- package/release/conpty/OpenConsole.exe +0 -0
- package/release/conpty/conpty.dll +0 -0
- package/release/licenses/agent-detection/LICENSE +201 -0
- package/release/licenses/agent-detection/NOTICE +20 -0
- package/release/orchbee-desktop-launcher.exe +0 -0
- package/release/orchbee-launcher.exe +0 -0
- package/release/orchbee-server.exe +0 -0
- package/release/orchbee-terminal-host.exe +0 -0
- package/release/orchbee-worker.exe +0 -0
- package/release/orchbee.exe +4 -0
- package/release/release.json +1 -0
- 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
|
-
#
|
|
1
|
+
# Orchbee program for one system
|
|
2
2
|
|
|
3
|
-
This
|
|
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
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "@orchbee/cli-win32-x64",
|
|
3
|
+
"version": "0.1.0-beta.10",
|
|
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
|
+
}
|