@akshar5/cohall 0.4.6 → 0.4.8

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 (10) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/CONTRIBUTING.md +49 -0
  3. package/README.md +105 -235
  4. package/bin/cohall.js +25 -14
  5. package/bin/cohall.js.map +3 -3
  6. package/docs/install.md +117 -43
  7. package/docs/integrations.md +23 -24
  8. package/docs/releasing.md +3 -3
  9. package/docs/services.md +7 -9
  10. package/package.json +8 -7
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.4.8](https://github.com/AksharP5/cohall/compare/v0.4.7...v0.4.8) (2026-08-09)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * **docs:** make public onboarding concise and private-safe ([#38](https://github.com/AksharP5/cohall/issues/38)) ([d9bdd8a](https://github.com/AksharP5/cohall/commit/d9bdd8a6b866e3cc659a71c464b3c0580d272dec))
9
+
10
+ ## [0.4.7](https://github.com/AksharP5/cohall/compare/v0.4.6...v0.4.7) (2026-08-09)
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * **skill:** carry conversation context into handoffs ([#36](https://github.com/AksharP5/cohall/issues/36)) ([f96382f](https://github.com/AksharP5/cohall/commit/f96382ff2385b3825307cbf838dd3e805ce27d8b))
16
+
3
17
  ## [0.4.6](https://github.com/AksharP5/cohall/compare/v0.4.5...v0.4.6) (2026-08-08)
4
18
 
5
19
 
package/CONTRIBUTING.md ADDED
@@ -0,0 +1,49 @@
1
+ # Contributing to Cohall
2
+
3
+ Issues and focused pull requests are welcome.
4
+
5
+ ## Before opening an issue
6
+
7
+ - Search existing issues and confirm the problem still occurs on the latest
8
+ Cohall release.
9
+ - Include the operating system, Node.js version, Cohall version, relevant
10
+ command, expected behavior, and redacted output.
11
+ - Remove relay URLs, device names, workspace paths, tokens, provider session
12
+ IDs, and other private information.
13
+ - Report security vulnerabilities through [GitHub's private vulnerability
14
+ form](https://github.com/AksharP5/cohall/security/advisories/new), not a public
15
+ issue.
16
+
17
+ ## Development
18
+
19
+ Requirements:
20
+
21
+ - Node.js 24 or newer
22
+ - [Bun](https://bun.sh/) 1.3.13
23
+
24
+ Install dependencies and run the full local validation suite:
25
+
26
+ ```bash
27
+ bun install --frozen-lockfile
28
+ bun run check
29
+ ```
30
+
31
+ `bun run check` type-checks, lints, builds the npm executable, runs the relay,
32
+ device, CLI, provider, and MCP tests, and validates the package contents.
33
+
34
+ Format changed files with `bunx oxfmt <files>` and verify the patch with `git
35
+ diff --check`. Do not hand-edit generated files in `bin/`.
36
+
37
+ ## Pull requests
38
+
39
+ - Keep each pull request focused on one problem.
40
+ - Add high-signal tests for behavior changes and meaningful edge cases.
41
+ - Update relevant documentation when behavior or commands change.
42
+ - Do not include credentials, personal paths, service logs, or unrelated files.
43
+ - Use a Conventional Commit title such as `fix(device): reconnect after sleep`
44
+ or `feat(cli): add task filtering`.
45
+ - Explain the user problem first, then the solution and local validation.
46
+
47
+ Maintainers handle version bumps, changelog entries, tags, and npm publishing
48
+ through the Release Please pull request. Contributors should not edit them for a
49
+ normal change.
package/README.md CHANGED
@@ -1,89 +1,104 @@
1
1
  # Cohall
2
2
 
3
3
  Cohall lets agents on your own devices delegate work to each other. It is a
4
- headless interoperability layer, not another agent harness: use it from Codex,
5
- Claude Code, OpenCode, T3Code, Buzz, or any other tool that can run a command or
6
- connect to a stdio MCP server.
4
+ headless bridge, not another agent app: keep using any harness that can run a
5
+ command or connect to a stdio MCP server.
7
6
 
8
- One npm package provides:
7
+ One npm package provides a durable self-hosted relay, outbound-only device
8
+ workers, a CLI, an installable agent skill, an optional MCP server, and local
9
+ Codex, Claude Code, and OpenCode adapters.
9
10
 
10
- - a durable self-hosted relay;
11
- - an outbound-only device daemon;
12
- - a human and agent-friendly CLI;
13
- - one embedded, installable agent skill;
14
- - an optional stdio MCP server;
15
- - local Codex, Claude Code, and OpenCode execution adapters.
16
-
17
- There is no Cohall desktop or web app. Your existing harness remains the UI.
18
-
19
- ## Architecture
11
+ ## How it works
20
12
 
21
13
  ```text
22
- Codex / Claude Code / OpenCode / T3Code / Buzz
23
- CLI + skill or MCP
24
- |
25
- HTTPS / WSS
26
- |
27
- Cohall relay + SQLite
28
- / \
29
- Mac device daemon Linux device daemon
30
- local agent login local agent login
31
- browser / Xcode repos / Docker
14
+ Current agent
15
+ CLI + skill or MCP
16
+ |
17
+ HTTPS / WSS
18
+ |
19
+ Cohall relay + SQLite
20
+ / \
21
+ Mac agent Linux agent
22
+ Xcode Docker
23
+ browser repositories
32
24
  ```
33
25
 
34
- The relay stores task prompts, final results, thread history, and provider
35
- session IDs. It does not plan work, copy device credentials, or SSH into a
36
- machine. Each device runs its own provider CLI with its existing local login,
37
- configuration, skills, MCP servers, permissions, and workspace access.
26
+ The relay stores tasks, results, thread history, and provider session IDs. Each
27
+ device uses its own files, provider login, tools, skills, permissions, and
28
+ signed-in services. Cohall does not copy credentials or remotely control the
29
+ machine.
30
+
31
+ ## What you can do
32
+
33
+ After installing the skill, ask naturally:
38
34
 
39
- ## What to use it for
35
+ - “Ask `@macbook` to build the iOS app and diagnose the signing error.”
36
+ - “Have `@server` reproduce this failure against its Docker services.”
37
+ - “Use `@linux`'s signed-in browser to investigate this deployment.”
38
+ - “Queue the full test suite on `@server`; keep working here and report back.”
40
39
 
41
- Once the skill is installed, requests in an ordinary agent thread can be as
42
- direct as:
40
+ When a request depends on your current conversation, the sending agent
41
+ automatically includes a concise brief explaining why you are asking, relevant
42
+ facts and prior findings, constraints, and the decision you need. It does not
43
+ forward the raw transcript or unrelated private material.
43
44
 
44
- - “Ask `@macbook` to build the iOS app in Xcode and diagnose the signing error.”
45
- - “Have `@devbox` reproduce this failure against its Docker services.”
46
- - “Use `@archlinux`'s signed-in browser to inspect the failed deployment.”
47
- - “Queue the full test suite on `@devbox`; keep working here and report back.”
45
+ ## Get started with your agent
48
46
 
49
- The current agent turns that request into a focused Cohall task and incorporates
50
- the result when it returns. `@macbook` is a device selector understood through
51
- the installed skill, not special chat syntax built into your harness.
47
+ Paste this into an agent on the device you want to configure:
52
48
 
53
- T3 Connect is a remote interface to a T3 Code environment: use it when you want
54
- to browse that machine's projects, terminal, files, and diffs yourself. Cohall
55
- instead lets the agent in your current Codex, Claude Code, OpenCode, T3Code, or
56
- other harness delegate an outcome to an agent on another machine. It provides
57
- cross-harness CLI/MCP access, durable offline queues, resumable agent threads,
58
- and redacted task traces. The two tools can be used together.
49
+ ```text
50
+ Set up Cohall on this device using https://github.com/AksharP5/cohall. Read the current README and installation/service docs first. Detect this OS, package manager, installed provider CLIs, and suitable workspace roots. If no Cohall relay is configured, ask whether this device should host one or join an existing relay; do not guess a relay URL or token. Keep the relay private through Tailscale or HTTPS, never expose plain HTTP publicly, and keep every token out of command arguments, shell history, and logs. Install Cohall, pair or join this device, install its skill for the detected agent harnesses, configure autostart if this device should remain available, run cohall doctor, and report exactly what is working. Ask before making system-wide changes.
51
+ ```
52
+
53
+ The agent will ask for the relay address and one-time pairing token only when it
54
+ needs them.
59
55
 
60
56
  ## Quick start
61
57
 
62
- Run Cohall anywhere Node.js 24 or newer is installed. Use whichever JavaScript
63
- package manager is already available:
58
+ Cohall requires Node.js 24 or newer. Try it with your preferred package runner.
59
+ Each block is independently copyable.
60
+
61
+ **npm**
64
62
 
65
63
  ```bash
66
64
  npx -y @akshar5/cohall --version
65
+ ```
66
+
67
+ **Bun**
68
+
69
+ ```bash
67
70
  bunx @akshar5/cohall --version
71
+ ```
72
+
73
+ **pnpm**
74
+
75
+ ```bash
68
76
  pnpm dlx @akshar5/cohall --version
77
+ ```
78
+
79
+ **Yarn**
80
+
81
+ ```bash
69
82
  yarn dlx @akshar5/cohall --version
70
83
  ```
71
84
 
72
- The examples below use `npx`; the other runners are interchangeable.
85
+ The remaining examples use `npx`.
73
86
 
74
- Start a local relay with an explicit owner token:
87
+ ### 1. Start a relay
75
88
 
76
89
  ```bash
77
90
  export COHALL_TOKEN="$(openssl rand -hex 32)"
78
91
  npx -y @akshar5/cohall relay
79
92
  ```
80
93
 
81
- The relay binds only to `127.0.0.1` by default. To expose it through a private
82
- network or TLS reverse proxy, set `COHALL_RELAY_HOST=0.0.0.0` and explicitly opt
83
- in with `COHALL_RELAY_ALLOW_REMOTE=true`. Do not expose plain HTTP to the public
84
- internet.
94
+ The relay binds to `127.0.0.1` by default. For multiple devices, run it on an
95
+ always-on machine and expose it only through a private network such as Tailscale
96
+ or an HTTPS reverse proxy. See [service setup](docs/services.md).
97
+
98
+ ### 2. Pair a device
85
99
 
86
- Create a one-time pairing credential on an owner-authenticated machine:
100
+ On an owner-authenticated machine, create a token that expires after ten minutes
101
+ and one exchange:
87
102
 
88
103
  ```bash
89
104
  COHALL_RELAY_URL=https://cohall.example.com \
@@ -91,8 +106,7 @@ COHALL_TOKEN="$COHALL_TOKEN" \
91
106
  npx -y @akshar5/cohall pair --label "MacBook"
92
107
  ```
93
108
 
94
- Transfer the token to the machine being added through a private channel, then
95
- provide it on stdin so it never appears in process arguments or shell history:
109
+ Transfer the token privately. On the device being added:
96
110
 
97
111
  ```bash
98
112
  read -rsp 'Pairing token: ' pairing_token; printf '\n'
@@ -100,80 +114,46 @@ printf '%s' "$pairing_token" | npx -y @akshar5/cohall join \
100
114
  --relay https://cohall.example.com \
101
115
  --name macbook \
102
116
  --providers codex \
103
- --workspace "$HOME/dev" \
104
- --workspace "$HOME/.skillsync/repo"
117
+ --workspace "$HOME/dev"
105
118
  unset pairing_token
106
-
107
- npx -y @akshar5/cohall doctor
108
- npx -y @akshar5/cohall device
109
119
  ```
110
120
 
111
- `join` exchanges the one-time token for separate client and device credentials,
112
- then writes a per-user configuration file with Unix mode `0600`. Workspace roots
113
- must already exist and are resolved to canonical paths.
114
-
115
- ## Availability and restarts
116
-
117
- The relay must be reachable to accept new tasks or return status. Once accepted,
118
- a task is stored in SQLite and survives relay or target-device restarts. Work for
119
- an offline target waits on the relay and starts when that device reconnects.
120
- Interrupted running work is re-queued with at-least-once delivery, so prompts
121
- that cause external changes should be safe to retry.
122
-
123
- The packaged service definitions reconnect automatically:
124
-
125
- - the Linux relay starts at boot through systemd socket and service units;
126
- - a Linux device starts with its user service, or at boot when user lingering is
127
- enabled;
128
- - a macOS device starts when that user logs in through its LaunchAgent;
129
- - a Windows device starts at user logon through Task Scheduler.
130
-
131
- Powered-off devices do not run work. A powered-off relay cannot accept new work,
132
- but tasks already written to its persistent data directory remain there for its
133
- next start. See [service setup](docs/services.md) for installation and checks.
134
-
135
- ## Use from an agent
136
-
137
- Install the same embedded skill for Codex, Claude Code, and OpenCode:
121
+ ### 3. Install the skill and connect
138
122
 
139
123
  ```bash
140
124
  npx -y @akshar5/cohall skill install all
125
+ npx -y @akshar5/cohall doctor
126
+ npx -y @akshar5/cohall device
141
127
  ```
142
128
 
143
- Then delegate from any harness with shell access:
129
+ Use an operating-system service for an unattended relay or device worker. See
130
+ [service setup](docs/services.md).
131
+
132
+ ## Delegate work
144
133
 
145
134
  ```bash
146
- npx -y @akshar5/cohall devices
147
135
  npx -y @akshar5/cohall delegate \
148
136
  --target @macbook \
149
- --provider codex \
150
- --workspace /Users/me/dev/project \
137
+ --workspace "$HOME/dev/project" \
151
138
  --prompt 'Inspect the signed-in dashboard and identify why deployment 184 failed.' \
152
- --context 'Focus on events after 15:00 UTC and return supporting links.'
139
+ --context 'Why: the deployment failed after local checks passed. Need: root cause, evidence, and recommended next step.'
153
140
  ```
154
141
 
155
- The command waits by default and returns JSON. For asynchronous work:
142
+ The command waits for a result by default. Queue longer work with `--no-wait`,
143
+ then inspect it later:
156
144
 
157
145
  ```bash
158
- npx -y @akshar5/cohall delegate --target @linux --no-wait \
159
- --prompt 'Run the test suite and report failures.'
160
146
  npx -y @akshar5/cohall wait <task-id> --timeout 1800
161
- npx -y @akshar5/cohall cancel <task-id>
162
147
  npx -y @akshar5/cohall trace <task-id> --follow
163
- npx -y @akshar5/cohall thread <thread-id>
164
148
  ```
165
149
 
166
- Follow-ups using the same `thread_id` resume the provider session on the target
167
- device. Active cancellation remains `cancelling` until the target acknowledges
168
- that its local process stopped. `trace` reports the durable relay and device
169
- lifecycle without prompts, results, credentials, or provider session IDs.
170
- `--follow` emits changed snapshots as newline-delimited JSON until the task is
171
- terminal.
150
+ Reuse the returned `thread_id` for follow-ups so the target resumes its provider
151
+ session.
172
152
 
173
153
  ## Optional MCP
174
154
 
175
- The MCP subprocess uses the current user's stored Cohall client configuration.
176
- For clients that accept the common `mcpServers` JSON shape, paste:
155
+ CLI plus skill is the recommended integration. For a client that accepts the
156
+ common `mcpServers` format, paste:
177
157
 
178
158
  ```json
179
159
  {
@@ -186,138 +166,28 @@ For clients that accept the common `mcpServers` JSON shape, paste:
186
166
  }
187
167
  ```
188
168
 
189
- Codex:
190
-
191
- ```bash
192
- codex mcp add cohall -- npx -y @akshar5/cohall mcp
193
- ```
194
-
195
- Claude Code, available in every project for the current user:
196
-
197
- ```bash
198
- claude mcp add --transport stdio --scope user cohall -- \
199
- npx -y @akshar5/cohall mcp
200
- ```
201
-
202
- OpenCode `opencode.json`:
203
-
204
- ```json
205
- {
206
- "$schema": "https://opencode.ai/config.json",
207
- "mcp": {
208
- "cohall": {
209
- "type": "local",
210
- "command": ["npx", "-y", "@akshar5/cohall", "mcp"],
211
- "enabled": true
212
- }
213
- }
214
- }
215
- ```
216
-
217
- Run `npx -y @akshar5/cohall integrations` to print these command components.
218
- The MCP server exposes:
219
-
220
- - `list_devices`
221
- - `delegate`
222
- - `task_status`
223
- - `task_trace`
224
- - `wait_task`
225
- - `cancel_task`
226
- - `thread_context`
227
-
228
- CLI plus skill and MCP create the same tasks. Configure one or the other in a
229
- given harness; do not submit the same work through both.
169
+ CLI and MCP create the same tasks; use one entry point per task. See
170
+ [agent integrations](docs/integrations.md) for Codex, Claude Code, and OpenCode
171
+ configuration.
230
172
 
231
- See [integration examples](docs/integrations.md), [installation](docs/install.md),
232
- and [service setup](docs/services.md).
173
+ ## Reliability and security
233
174
 
234
- ## Provider behavior
175
+ - Accepted tasks persist in SQLite while a target is offline.
176
+ - Interrupted work is re-queued with at-least-once delivery; consequential work
177
+ should be safe to retry.
178
+ - The relay must be reachable to submit new work, but persisted tasks survive a
179
+ relay restart.
180
+ - Paired clients can ask a device's local provider to act with that user's normal
181
+ authority. Pair only devices and users you trust.
182
+ - Workspace roots are enforced after resolving symlinks, credentials are
183
+ role-separated, and task traces omit prompts, results, tokens, and provider
184
+ session IDs.
235
185
 
236
- Target devices advertise provider executables they actually have. Authentication
237
- is checked when delegated work starts. Restrict a device to providers you have
238
- configured locally:
239
-
240
- ```bash
241
- cohall configure --providers codex,claude-code
242
- cohall configure --providers auto
243
- ```
244
-
245
- | Provider | Required command | Session continuation |
246
- | ----------- | ---------------- | ------------------------ |
247
- | Codex | `codex` | `codex exec resume` |
248
- | Claude Code | `claude` | `claude --resume` |
249
- | OpenCode | `opencode` | `opencode run --session` |
250
-
251
- Cohall does not bypass provider permissions. A paired client is authorized to
252
- ask the local provider to act with that user account's normal authority, so do
253
- not pair mutually untrusted users. Provider output and task backlogs are
254
- bounded, one task runs at a time per device, and configured workspace roots are
255
- enforced after resolving symlinks.
256
-
257
- ## Configuration
258
-
259
- `npx -y @akshar5/cohall config` shows the active stored configuration without
260
- printing tokens. `npx -y @akshar5/cohall configure` changes relay, name,
261
- workspaces, enabled providers, model, or Codex sandbox.
262
- `npx -y @akshar5/cohall doctor` checks relay reachability, this device's relay
263
- status, provider selection, executable paths, and version information.
264
-
265
- For a global installation used by services, `cohall upgrade` updates through
266
- the same npm, Bun, or pnpm installation and restarts only active Cohall relay
267
- and device jobs. Active jobs restart even when the installed files are already
268
- current, ensuring an older loaded process is replaced. Cohall refuses to restart
269
- a service configured to use a different global installation; run that service's
270
- executable directly or update its service definition first.
271
-
272
- - `cohall upgrade --dry-run` previews the plan.
273
- - `cohall upgrade --no-restart` updates files without restarting services.
274
-
275
- Linux relays can use the packaged systemd socket unit so new connections remain
276
- available while the relay process is replaced; see [service setup](docs/services.md).
277
- Environment variables override stored values:
278
-
279
- | Variable | Purpose |
280
- | ----------------------------------------- | ---------------------------------------------- |
281
- | `COHALL_CONFIG` | Configuration file override |
282
- | `COHALL_RELAY_URL` | Relay URL for CLI, MCP, and device |
283
- | `COHALL_CLIENT_TOKEN` | Client credential override |
284
- | `COHALL_DEVICE_TOKEN` | Device credential override |
285
- | `COHALL_TOKEN` | Relay owner credential |
286
- | `COHALL_DEVICE_ID` | Stable device ID override |
287
- | `COHALL_DEVICE_NAME` | Advertised device name |
288
- | `COHALL_DEVICE_PROVIDERS` | Provider allowlist or `auto` |
289
- | `COHALL_DEVICE_WORKSPACES` | Comma-separated workspace roots |
290
- | `COHALL_DEVICE_WORKSPACES_JSON` | JSON workspace roots; supports commas in paths |
291
- | `COHALL_MODEL` | Target provider model override |
292
- | `COHALL_SANDBOX` | Codex sandbox override |
293
- | `COHALL_THREAD_ID` | Inherited Cohall thread for nested delegation |
294
- | `COHALL_DATA_DIR` | Relay database and owner-token directory |
295
- | `COHALL_RELAY_HOST` / `COHALL_RELAY_PORT` | Relay listener |
296
- | `COHALL_RELAY_ALLOW_REMOTE` | Explicit non-loopback binding opt-in |
297
-
298
- The owner token can create pairing credentials, list sessions, and revoke them.
299
- `cohall forget <device-id>` removes an offline device from discovery after
300
- confirming it has no outstanding tasks, revokes its device credential, and
301
- preserves its completed task history. On the relay host, owner commands read the
302
- protected local owner-token file automatically; remote owner commands require
303
- `COHALL_TOKEN`.
304
- Ordinary client and device credentials are role-separated, device-bound where
305
- applicable, expiring, and stored only as SHA-256 hashes by the relay.
306
-
307
- ## Development
308
-
309
- ```bash
310
- bun install
311
- bun run check
312
- ```
186
+ ## Documentation
313
187
 
314
- `bun run check` type-checks, lints, builds the npm executable, and tests the full
315
- relay/device/CLI/MCP path with fake provider executables. GitHub Actions is
316
- deliberately low-frequency because this is a private repository. See [release
317
- operations](docs/releasing.md).
188
+ - [Installation, pairing, providers, and upgrades](docs/install.md)
189
+ - [Agent skill and MCP integrations](docs/integrations.md)
190
+ - [Linux, macOS, and Windows services](docs/services.md)
191
+ - [Contributing](CONTRIBUTING.md)
318
192
 
319
- The relay guarantees durable at-least-once task delivery. Task assignment and
320
- terminal events are idempotent; interrupted running tasks are re-queued after a
321
- device or relay restart. A device accepts at most 100 outstanding tasks and
322
- executes them one at a time. Thread context returns a byte-bounded recent window
323
- and sets `truncated` when older content exists.
193
+ Cohall is licensed under the [MIT License](LICENSE).
package/bin/cohall.js CHANGED
@@ -17,7 +17,7 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
17
17
 
18
18
  // packages/protocol/src/index.ts
19
19
  import { Schema } from "effect";
20
- var version = "0.4.6", bounded = (maxLength) => Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(maxLength)), optionalText = (maxLength) => Schema.String.check(Schema.isMaxLength(maxLength)), boundedArray = (schema, maxLength) => Schema.Array(schema).check(Schema.isMaxLength(maxLength)), uuid = (name) => Schema.String.check(Schema.isUUID(4)).pipe(Schema.brand(name)), isoTimestamp = (name) => Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/, {
20
+ var version = "0.4.8", bounded = (maxLength) => Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(maxLength)), optionalText = (maxLength) => Schema.String.check(Schema.isMaxLength(maxLength)), boundedArray = (schema, maxLength) => Schema.Array(schema).check(Schema.isMaxLength(maxLength)), uuid = (name) => Schema.String.check(Schema.isUUID(4)).pipe(Schema.brand(name)), isoTimestamp = (name) => Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/, {
21
21
  expected: "an ISO-8601 UTC timestamp"
22
22
  })).pipe(Schema.brand(name)), DeviceId, ThreadId, MessageId, TaskId, AuthSessionId, Timestamp, Platform, Provider, DeviceStatus, TaskStatus, TaskTraceEventKind, MessageRole, ConnectionRole, AuthSession, CreatePairingInput, PairingCredential, ExchangePairingInput, SessionCredential, PairingResult, Capability, Workspace, Device, Thread, Message, Task, TaskTraceEvent, TaskTrace, ThreadContext, CreateTaskInput, SocketEvent, ErrorResponse, terminalTaskStatuses, isTerminalTask = (task) => terminalTaskStatuses.has(task.status), now = () => Timestamp.make(new Date().toISOString()), makeDeviceId = () => DeviceId.make(crypto.randomUUID()), makeThreadId = () => ThreadId.make(crypto.randomUUID()), makeMessageId = () => MessageId.make(crypto.randomUUID()), makeTaskId = () => TaskId.make(crypto.randomUUID()), makeAuthSessionId = () => AuthSessionId.make(crypto.randomUUID()), decodeCreatePairingInput, decodeExchangePairingInput, decodeCreateTaskInput, decodeDevice, decodeSocketEvent;
23
23
  var init_src = __esm(() => {
@@ -2215,7 +2215,7 @@ import { dirname as dirname3, join as join4 } from "node:path";
2215
2215
  // skills/cohall/SKILL.md
2216
2216
  var SKILL_default = `---
2217
2217
  name: cohall
2218
- description: Delegate work to an agent on another user-owned device through the Cohall CLI. Use when a task needs machine-local state or capabilities such as a signed-in browser, Xcode, a simulator, Docker, deployment access, a repository checkout, or tools unavailable on the current device.
2218
+ description: Delegate work to an agent on another user-owned device through the Cohall CLI. Use when the user asks to run, research, or check something on another device, names a Cohall target such as @macbook or @server, or needs machine-local state or capabilities such as a signed-in browser, Xcode, Docker, deployment access, a repository checkout, or unavailable tools. Carry the relevant current-conversation context into the handoff automatically.
2219
2219
  ---
2220
2220
 
2221
2221
  # Cohall
@@ -2230,7 +2230,7 @@ Use the installed \`cohall\` executable when it is available. Fall back to
2230
2230
 
2231
2231
  ## Recognize cross-device requests
2232
2232
 
2233
- Treat phrases such as “run this on my Mac,” “ask \`@devbox\`,” or “have the Linux
2233
+ Treat phrases such as “run this on my Mac,” “ask \`@server\`,” or “have the Linux
2234
2234
  machine check this” as target intent. The \`@name\` form is a Cohall device
2235
2235
  selector, not chat syntax supplied by the harness. Resolve it with \`cohall
2236
2236
  devices\`, then delegate the smallest useful outcome.
@@ -2255,25 +2255,36 @@ Do not delegate ordinary local work when the other device provides no advantage.
2255
2255
  2. Choose a target whose provider, workspaces, platform, and capabilities fit
2256
2256
  the task. Stay local when another device offers no material advantage.
2257
2257
 
2258
- 3. Delegate one concrete outcome. Send only the context the target needs:
2258
+ 3. Build the handoff from the current conversation. Do not ask the user to
2259
+ repeat information already visible. Write:
2260
+ - a concrete \`--prompt\` describing the target's task;
2261
+ - a concise \`--context\` explaining why the user is asking, relevant facts and
2262
+ prior findings, constraints, and the decision or evidence they need.
2263
+
2264
+ When a request depends on the conversation, including references such as
2265
+ “this,” “that,” or “look into it,” always supply \`--context\`. Omit it only
2266
+ when the prompt is genuinely self-contained. Distill the context; never
2267
+ forward the raw transcript or unrelated private material.
2268
+
2269
+ 4. Delegate one concrete outcome:
2259
2270
 
2260
2271
  \`\`\`bash
2261
2272
  cohall delegate \\
2262
2273
  --target @macbook \\
2263
2274
  --provider codex \\
2264
- --workspace /Users/me/dev/project \\
2265
- --prompt 'Inspect the authenticated dashboard and identify why deployment 184 failed.' \\
2266
- --context 'Focus on events after 15:00 UTC. Return evidence and source URLs.'
2275
+ --workspace "$HOME/dev/project" \\
2276
+ --prompt 'Research whether the deployment failure matches the reported provider outage.' \\
2277
+ --context 'Why: deployment 184 failed after 15:00 UTC. Known: local checks passed and the provider status page reported elevated errors. Need: determine whether the outage explains our failure, with primary-source links and contrary evidence.'
2267
2278
  \`\`\`
2268
2279
 
2269
2280
  Providers are \`codex\`, \`claude-code\`, and \`opencode\`. Omit \`--provider\` to
2270
2281
  use Codex. Omit \`--target\` only when Cohall may choose a matching device.
2271
2282
 
2272
- 4. The command waits by default and returns JSON. Treat work as successful only
2283
+ 5. The command waits by default and returns JSON. Treat work as successful only
2273
2284
  when \`status\` is \`completed\`; use \`result\` in the current task. Report a
2274
2285
  \`failed\`, \`cancelled\`, or \`cancelling\` state accurately.
2275
2286
 
2276
- 5. Reuse \`thread_id\` for related follow-ups so the target provider can resume
2287
+ 6. Reuse \`thread_id\` for related follow-ups so the target provider can resume
2277
2288
  its local session:
2278
2289
 
2279
2290
  \`\`\`bash
@@ -2289,8 +2300,8 @@ ordinary shell or a separate agent turn.
2289
2300
 
2290
2301
  ## Context and safety
2291
2302
 
2292
- - Include the goal, constraints, relevant prior findings, and expected evidence.
2293
- - Do not paste a full private transcript when a short brief is sufficient.
2303
+ - Preserve the meaning and motivation of the current conversation, not its raw wording.
2304
+ - Add new relevant developments to \`--context\` when following up from another chat.
2294
2305
  - Never send provider credentials, Cohall tokens, cookies, or browser-profile data.
2295
2306
  - Request a path only when the target advertises a matching workspace root.
2296
2307
  - Use the same thread for clarification instead of creating duplicate tasks.
@@ -3936,12 +3947,12 @@ var runMcp = async (configuration) => {
3936
3947
  }, async () => output(await Effect7.runPromise(client2.devices())));
3937
3948
  server.registerTool("delegate", {
3938
3949
  title: "Delegate work to another device",
3939
- description: "Send focused work to another Cohall device. Include only relevant context; Cohall cannot read the host transcript. Reuse thread_id for related follow-ups.",
3950
+ description: "Send focused work to another Cohall device. When the request depends on the current conversation, distill its motivation, relevant facts, prior findings, constraints, and desired decision into context; Cohall cannot read the host transcript. Never forward unrelated transcript content. Reuse thread_id for related follow-ups.",
3940
3951
  inputSchema: {
3941
3952
  prompt: z.string().min(1).max(131072),
3942
3953
  target: z.string().optional().describe("Device name, @name, hostname, or ID"),
3943
3954
  provider: z.enum(["codex", "claude-code", "opencode"]).default("codex"),
3944
- context: z.string().max(131072).optional(),
3955
+ context: z.string().max(131072).optional().describe("Distilled context the target needs: why the user is asking, relevant facts and prior findings, constraints, and the intended decision. The calling agent must supply this when the prompt depends on its conversation; omit it only for a self-contained task."),
3945
3956
  thread_id: z.string().uuid().optional(),
3946
3957
  workspace: z.string().max(4096).optional(),
3947
3958
  wait: z.boolean().default(true),
@@ -4033,4 +4044,4 @@ await main().catch((cause) => {
4033
4044
  process.exitCode = 1;
4034
4045
  });
4035
4046
 
4036
- //# debugId=0FE6295B18AAAAEC64756E2164756E21
4047
+ //# debugId=DD6CA056CEE6744B64756E2164756E21