@akshar5/cohall 0.4.7 → 0.4.9

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 +112 -244
  4. package/bin/cohall.js +371 -121
  5. package/bin/cohall.js.map +13 -13
  6. package/docs/install.md +121 -44
  7. package/docs/integrations.md +21 -28
  8. package/docs/releasing.md +3 -3
  9. package/docs/services.md +13 -12
  10. package/package.json +10 -9
package/docs/install.md CHANGED
@@ -1,26 +1,62 @@
1
1
  # Install Cohall
2
2
 
3
- ## Run with a package runner
3
+ Cohall requires Node.js 24 or newer. It is a standard public npm package with no
4
+ bundled agent harness.
4
5
 
5
- Cohall is a public npm package and requires Node.js 24 or newer. Nothing from
6
- Buzz, T3Code, Codex, Claude Code, or OpenCode is bundled or required.
6
+ ## Package runners
7
+
8
+ Use one command. The documentation uses `npx` in later examples.
9
+
10
+ **npm**
7
11
 
8
12
  ```bash
9
13
  npx -y @akshar5/cohall --version
14
+ ```
15
+
16
+ **Bun**
17
+
18
+ ```bash
10
19
  bunx @akshar5/cohall --version
20
+ ```
21
+
22
+ **pnpm**
23
+
24
+ ```bash
11
25
  pnpm dlx @akshar5/cohall --version
26
+ ```
27
+
28
+ **Yarn**
29
+
30
+ ```bash
12
31
  yarn dlx @akshar5/cohall --version
13
32
  ```
14
33
 
15
- The package follows the standard npm package format, so npm, Bun, pnpm, and Yarn
16
- can install it too. The documentation uses `npx` as the common default. An
17
- unattended relay or device service may install the package globally so its
18
- executable path remains fixed across restarts:
34
+ ## Global installation for services
35
+
36
+ An unattended relay or device worker needs a stable executable path. Install it
37
+ globally with the package manager that will own the service.
38
+
39
+ **npm**
19
40
 
20
41
  ```bash
21
42
  npm install --global @akshar5/cohall
22
- # or: bun add --global @akshar5/cohall
23
- # or: pnpm add --global @akshar5/cohall
43
+ ```
44
+
45
+ **Bun**
46
+
47
+ ```bash
48
+ bun add --global @akshar5/cohall
49
+ ```
50
+
51
+ **pnpm**
52
+
53
+ ```bash
54
+ pnpm add --global @akshar5/cohall
55
+ ```
56
+
57
+ Then verify:
58
+
59
+ ```bash
24
60
  cohall --version
25
61
  ```
26
62
 
@@ -29,25 +65,30 @@ cohall --version
29
65
  The relay owner creates a token valid for ten minutes and one exchange:
30
66
 
31
67
  ```bash
68
+ read -rsp 'Owner token: ' owner_token; printf '\n'
32
69
  COHALL_RELAY_URL=https://cohall.example.com \
33
- COHALL_TOKEN=owner-token \
34
- npx -y @akshar5/cohall pair --label "Linux workstation"
70
+ COHALL_TOKEN="$owner_token" \
71
+ npx -y @akshar5/cohall pair --label "Workstation"
72
+ unset owner_token
35
73
  ```
36
74
 
37
- Transfer it privately, then enter it without placing it in process arguments or
38
- shell history:
75
+ Transfer it privately. On the machine being added, provide it through stdin so
76
+ it does not appear in process arguments or shell history:
39
77
 
40
78
  ```bash
41
79
  read -rsp 'Pairing token: ' pairing_token; printf '\n'
42
80
  printf '%s' "$pairing_token" | npx -y @akshar5/cohall join \
43
81
  --relay https://cohall.example.com \
44
- --name linux \
82
+ --name workstation \
45
83
  --providers codex \
46
84
  --workspace "$HOME/dev"
47
85
  unset pairing_token
48
86
  ```
49
87
 
50
- For a client-only machine that submits work but never runs a device daemon:
88
+ Workspace roots must already exist. Cohall resolves them to canonical paths and
89
+ rejects delegated work outside them.
90
+
91
+ For a client that submits work but never runs a device worker:
51
92
 
52
93
  ```bash
53
94
  npx -y @akshar5/cohall pair --client-only --label "Automation client"
@@ -58,9 +99,33 @@ printf '%s' "$pairing_token" | npx -y @akshar5/cohall join \
58
99
  unset pairing_token
59
100
  ```
60
101
 
61
- For automation, place the token in a mode-`0600` file and use
62
- `npx -y @akshar5/cohall join --token-file /path/to/token`. Pairing tokens expire
63
- after ten minutes and can be exchanged once.
102
+ Automation may use a mode-`0600` token file with `join --token-file
103
+ /path/to/token`.
104
+
105
+ ## Providers
106
+
107
+ Target devices advertise provider executables they can find. Authentication is
108
+ checked when delegated work starts.
109
+
110
+ | Provider | Required command | Session continuation |
111
+ | ----------- | ---------------- | ------------------------ |
112
+ | Codex | `codex` | `codex exec resume` |
113
+ | Claude Code | `claude` | `claude --resume` |
114
+ | OpenCode | `opencode` | `opencode run --session` |
115
+
116
+ Limit a device to providers configured for that user:
117
+
118
+ ```bash
119
+ cohall configure --providers codex,claude-code
120
+ cohall configure --providers auto
121
+ ```
122
+
123
+ ## Configuration
124
+
125
+ `cohall config` shows stored configuration without tokens. `cohall configure`
126
+ changes the relay URL, device name, workspace roots, providers, model, or Codex
127
+ sandbox. `cohall doctor` checks the effective configuration, relay connection,
128
+ provider executables, authentication readiness, and versions.
64
129
 
65
130
  Configuration locations:
66
131
 
@@ -68,38 +133,50 @@ Configuration locations:
68
133
  - macOS: `~/Library/Application Support/Cohall/config.json`
69
134
  - Windows: `%APPDATA%\Cohall\config.json`
70
135
 
71
- Use `COHALL_CONFIG` to override the path. On Unix, Cohall enforces directory
72
- mode `0700` and file mode `0600`.
73
-
74
- The relay must be reachable to submit new work or read its status. A target
75
- device only needs to be online while accepting or running work; accepted tasks
76
- wait durably on the relay while it is offline. Accepted tasks also survive a
77
- relay restart when its data directory is persistent. A client cannot submit a
78
- new task while the relay itself is offline.
79
-
80
- `--providers` is an optional comma-separated allowlist. It prevents an installed
81
- but unauthenticated provider executable from being advertised. Run `cohall
82
- configure --providers auto` to return to executable auto-detection.
136
+ Use `COHALL_CONFIG` to override the path. On Unix, Cohall enforces directory mode
137
+ `0700` and file mode `0600`.
138
+
139
+ Environment variables override stored values:
140
+
141
+ | Variable | Purpose |
142
+ | ----------------------------------------- | ---------------------------------------------- |
143
+ | `COHALL_CONFIG` | Configuration file override |
144
+ | `COHALL_RELAY_URL` | Relay URL for CLI, MCP, and device |
145
+ | `COHALL_CLIENT_TOKEN` | Client credential override |
146
+ | `COHALL_DEVICE_TOKEN` | Device credential override |
147
+ | `COHALL_TOKEN` | Relay owner credential |
148
+ | `COHALL_DEVICE_ID` | Stable device ID override |
149
+ | `COHALL_DEVICE_NAME` | Advertised device name |
150
+ | `COHALL_DEVICE_PROVIDERS` | Provider allowlist or `auto` |
151
+ | `COHALL_DEVICE_WORKSPACES` | Comma-separated workspace roots |
152
+ | `COHALL_DEVICE_WORKSPACES_JSON` | JSON workspace roots; supports commas in paths |
153
+ | `COHALL_MODEL` | Target provider model override |
154
+ | `COHALL_SANDBOX` | Codex sandbox override |
155
+ | `COHALL_THREAD_ID` | Inherited thread for nested delegation |
156
+ | `COHALL_DATA_DIR` | Relay database and owner-token directory |
157
+ | `COHALL_RELAY_HOST` / `COHALL_RELAY_PORT` | Relay listener |
158
+ | `COHALL_RELAY_ALLOW_REMOTE` | Explicit non-loopback binding opt-in |
159
+ | `COHALL_HISTORY_TASK_LIMIT` | Terminal tasks retained; default `1000` |
160
+
161
+ The relay must be reachable to submit work or read status. Accepted tasks wait
162
+ durably while a target is offline and survive relay restarts when its data
163
+ directory is persistent.
83
164
 
84
165
  ## Upgrade
85
166
 
86
- Package runners such as `npx`, `bunx`, and `pnpm dlx` already resolve a current
87
- release. Upgrade a global installation and its running services with:
167
+ Package runners resolve a current release. Upgrade a global installation and
168
+ its active services with:
88
169
 
89
170
  ```bash
90
171
  cohall upgrade
91
172
  ```
92
173
 
93
174
  Cohall uses the package manager and global prefix that installed it, verifies
94
- the installed version, then restarts only active Cohall relay and device
95
- services. Active services restart even when the package files are already
96
- current, so a process left on old code by a direct package-manager update is
97
- replaced. If a service points to a different global installation, Cohall stops
98
- with its executable path instead of reporting a misleading successful restart.
99
- Run that executable's `upgrade` command or update the service definition. Choose
100
- an exact version with `cohall upgrade --to 1.2.3`. Use `--dry-run` to inspect the
101
- plan or `--no-restart` to leave active services pending a manual restart.
102
-
103
- Back up the data directory before upgrading a production relay; SQLite schema
104
- migrations run in place. A system-level relay may require running the command
105
- with the same privileges used to install and manage that service.
175
+ the new version, and restarts only active Cohall services. If a service points
176
+ to another global installation, Cohall stops and reports the correct executable
177
+ instead of restarting the wrong job.
178
+
179
+ Use `cohall upgrade --to 1.2.3` for an exact version, `--dry-run` to inspect the
180
+ plan, or `--no-restart` to leave services pending a manual restart. Back up a
181
+ production relay's data directory before an upgrade because SQLite migrations
182
+ run in place.
package/docs/integrations.md CHANGED
@@ -1,7 +1,8 @@
1
- # Agent harness integrations
1
+ # Agent integrations
2
2
 
3
- CLI plus skill is the recommended integration. MCP is available for hosts that
4
- prefer native tool discovery. Both use the same relay and device protocol.
3
+ CLI plus skill is the recommended integration. MCP is available for harnesses
4
+ that prefer native tool discovery. Both create the same relay tasks; use one
5
+ entry point per task.
5
6
 
6
7
  ## CLI plus skill
7
8
 
@@ -10,22 +11,20 @@ npx -y @akshar5/cohall skill install all
10
11
  npx -y @akshar5/cohall doctor
11
12
  ```
12
13
 
13
- This installs the same embedded `SKILL.md` into:
14
+ This installs the embedded skill into:
14
15
 
15
16
  - `~/.agents/skills/cohall` for Codex-compatible skill loaders;
16
17
  - `~/.claude/skills/cohall` for Claude Code;
17
18
  - `~/.config/opencode/skills/cohall` for OpenCode.
18
19
 
19
- T3Code, Buzz, and other harnesses can run `npx -y @akshar5/cohall` from their
20
- normal shell/tool environment. `bunx @akshar5/cohall`, `pnpm dlx
21
- @akshar5/cohall`, and `yarn dlx @akshar5/cohall` are equivalent. No
22
- Cohall-specific UI extension is required.
20
+ Any other harness with shell access can invoke the CLI directly. No Cohall UI
21
+ extension is required.
23
22
 
24
- When delegating from a conversation, the invoking agent must distill the reason
25
- for the request, relevant facts and prior findings, constraints, and intended
23
+ When delegating from a conversation, the sending agent must distill why the user
24
+ is asking, relevant facts and prior findings, constraints, and the intended
26
25
  decision into Cohall's `context` field. Cohall cannot read the harness transcript
27
- itself. Send a focused brief rather than the raw chat; omit context only when the
28
- task is self-contained.
26
+ itself. Send a focused brief rather than the raw chat; omit context only for a
27
+ self-contained task.
29
28
 
30
29
  ## Codex MCP
31
30
 
@@ -33,7 +32,7 @@ task is self-contained.
33
32
  codex mcp add cohall -- npx -y @akshar5/cohall mcp
34
33
  ```
35
34
 
36
- Or configure `~/.codex/config.toml`:
35
+ Equivalent `~/.codex/config.toml`:
37
36
 
38
37
  ```toml
39
38
  [mcp_servers.cohall]
@@ -48,7 +47,7 @@ claude mcp add --transport stdio --scope user cohall -- \
48
47
  npx -y @akshar5/cohall mcp
49
48
  ```
50
49
 
51
- Or use the standard JSON form in a project `.mcp.json`:
50
+ Equivalent project `.mcp.json`:
52
51
 
53
52
  ```json
54
53
  {
@@ -63,7 +62,7 @@ Or use the standard JSON form in a project `.mcp.json`:
63
62
 
64
63
  ## OpenCode MCP
65
64
 
66
- Add this to `opencode.json`:
65
+ Add to `opencode.json`:
67
66
 
68
67
  ```json
69
68
  {
@@ -78,19 +77,13 @@ Add this to `opencode.json`:
78
77
  }
79
78
  ```
80
79
 
81
- ## Environment
80
+ ## Isolated environments
82
81
 
83
- The MCP subprocess reads the normal per-user Cohall configuration. If a harness
84
- uses an isolated environment, pass only:
82
+ The MCP subprocess reads the current user's Cohall configuration. If a harness
83
+ uses an isolated environment, pass `COHALL_CONFIG` with an absolute path to that
84
+ configuration file. Alternatively pass `COHALL_RELAY_URL` and
85
+ `COHALL_CLIENT_TOKEN` directly.
85
86
 
86
- ```text
87
- COHALL_CONFIG=/absolute/path/to/config.json
88
- ```
89
-
90
- Or pass `COHALL_RELAY_URL` and `COHALL_CLIENT_TOKEN` directly. Never place an
91
- owner or device token in an MCP client configuration.
92
-
93
- CLI and MCP are equivalent entry points. Use one per delegated task.
94
- Both expose redacted task tracing through `cohall trace <task-id>` and the
87
+ Never place an owner or device token in an MCP configuration. Both integrations
88
+ provide redacted task tracing through `cohall trace <task-id>` or the
95
89
  `task_trace` MCP tool.
96
- Use `bunx @akshar5/cohall` with Bun. Use `pnpm dlx @akshar5/cohall` with pnpm.
package/docs/releasing.md CHANGED
@@ -11,9 +11,9 @@ bun run check
11
11
  npm pack --dry-run
12
12
  ```
13
13
 
14
- The Check workflow runs only when manually dispatched or when a non-draft pull
15
- request is opened or marked ready for review. Synchronizing commits does not
16
- automatically consume another private-repository runner allocation.
14
+ The Check workflow runs when manually dispatched or when a non-draft pull
15
+ request is opened or marked ready for review. Synchronizing later commits does
16
+ not start another run automatically.
17
17
 
18
18
  After releasable conventional commits reach `main`, Release Please opens or
19
19
  updates one release pull request. Merging it creates the version tag and GitHub
package/docs/services.md CHANGED
@@ -52,13 +52,14 @@ loginctl show-user "$USER" -p Linger
52
52
 
53
53
  Create a dedicated `cohall` user, install the npm package globally so
54
54
  `command -v cohall` returns `/usr/local/bin/cohall`, and place the relay
55
- environment at `/etc/cohall/relay.env` with mode `0600`:
55
+ environment at `/etc/cohall/relay.env` with mode `0600`. Generate the token with
56
+ `openssl rand -hex 32`; do not use the placeholder literally.
56
57
 
57
58
  ```dotenv
58
59
  COHALL_RELAY_HOST=0.0.0.0
59
60
  COHALL_RELAY_PORT=8787
60
61
  COHALL_RELAY_ALLOW_REMOTE=true
61
- COHALL_TOKEN=replace-with-a-random-owner-token
62
+ COHALL_TOKEN=replace-with-the-output-of-openssl-rand-hex-32
62
63
  COHALL_DATA_DIR=/var/lib/cohall
63
64
  ```
64
65
 
@@ -121,7 +122,9 @@ Run `npm install --global @akshar5/cohall`, pair and verify the machine from
121
122
  PowerShell, then run:
122
123
 
123
124
  ```powershell
124
- powershell -ExecutionPolicy Bypass -File deploy\windows\install-device.ps1
125
+ $packageRoot = Join-Path (npm root --global) "@akshar5/cohall"
126
+ powershell -ExecutionPolicy Bypass -File `
127
+ (Join-Path $packageRoot "deploy/windows/install-device.ps1")
125
128
  ```
126
129
 
127
130
  The script registers a per-user scheduled task that starts `cohall device` at
@@ -131,16 +134,14 @@ logon and restarts it after failures. It does not run before that user logs on.
131
134
 
132
135
  Run `cohall upgrade` from a global npm, Bun, or pnpm installation. It updates
133
136
  that installation and restarts only active managed Cohall services, with relays
134
- restarted before device daemons. Active services restart even when the installed
135
- files already match the requested version. A systemd relay installed with the
136
- packaged socket unit keeps accepting new connections while its process restarts.
137
- A delegated upgrade can finish after
138
- restarting its own device daemon: a durable receipt records the restart attempt,
139
- and a delegated caller leaves that marker for the replacement task to consume
140
- after reconnecting, even when a service manager returns before ending the old process.
137
+ restarted before device workers. Active services restart even when the installed
138
+ files already match the requested version. Socket-activated relays keep accepting
139
+ new connections while their process is replaced, and delegated upgrades finish
140
+ through durable restart recovery.
141
+
141
142
  Before changing files, Cohall verifies that active systemd and launchd jobs use
142
- the same global installation as the invoked CLI. If they differ, run the
143
- executable named in the error or update the service definition first.
143
+ the same global installation as the invoked CLI. If they differ, use the
144
+ executable named in the error or update the service definition.
144
145
 
145
146
  Direct `npm install --global`, `bun add --global`, or `pnpm add --global`
146
147
  replaces files on disk but cannot replace code already loaded by a running Node
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@akshar5/cohall",
3
- "version": "0.4.7",
3
+ "version": "0.4.9",
4
4
  "description": "Let coding agents delegate work across your own devices.",
5
5
  "keywords": [
6
6
  "agents",
@@ -31,6 +31,7 @@
31
31
  "deploy",
32
32
  "docs",
33
33
  "CHANGELOG.md",
34
+ "CONTRIBUTING.md",
34
35
  "LICENSE",
35
36
  "README.md"
36
37
  ],
@@ -50,8 +51,8 @@
50
51
  "typecheck": "bunx tsc -b",
51
52
  "test": "bun run build:package && vitest run",
52
53
  "lint": "bunx oxlint . --deny-warnings",
53
- "format": "bunx oxfmt .",
54
- "format:check": "bunx oxfmt --check .",
54
+ "format": "bunx oxfmt . '!CHANGELOG.md'",
55
+ "format:check": "bunx oxfmt --check . '!CHANGELOG.md'",
55
56
  "package:check": "npm pack --dry-run --ignore-scripts",
56
57
  "check": "bun run typecheck && bun run lint && bun run test && bun run package:check",
57
58
  "prepack": "bun run build:package"
@@ -59,21 +60,21 @@
59
60
  "dependencies": {
60
61
  "@modelcontextprotocol/sdk": "^1.30.0",
61
62
  "effect": "4.0.0-beta.102",
62
- "ws": "^8.21.2",
63
+ "ws": "^8.21.3",
63
64
  "zod": "^4.4.3"
64
65
  },
65
- "overrides": {
66
- "fast-uri": "^3.1.5",
67
- "hono": "^4.12.34"
68
- },
69
66
  "devDependencies": {
70
67
  "@types/node": "^24.13.3",
71
68
  "@types/ws": "^8.18.1",
72
69
  "oxfmt": "^0.44.0",
73
- "oxlint": "^1.56.0",
70
+ "oxlint": "^1.77.0",
74
71
  "typescript": "^6.0.0",
75
72
  "vitest": "^4.1.10"
76
73
  },
74
+ "overrides": {
75
+ "fast-uri": "^3.1.5",
76
+ "hono": "^4.12.34"
77
+ },
77
78
  "engines": {
78
79
  "node": ">=24"
79
80
  },