@akshar5/cohall 0.3.0 → 0.3.2

package/deploy/launchd/com.cohall.device.plist

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.cohall.device</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/cohall</string>
+    <string>device</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>NetworkState</key>
+    <true/>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>3</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+</dict>
+</plist>

package/deploy/systemd/cohall-device.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=Cohall device agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+Environment=PATH=%h/.local/bin:%h/.npm-global/bin:%h/.bun/bin:%h/.local/share/pnpm:/usr/local/bin:/usr/bin:/bin
+ExecStart=%h/.local/bin/cohall device
+Restart=always
+RestartSec=3
+UMask=0077
+NoNewPrivileges=true
+PrivateTmp=true
+
+[Install]
+WantedBy=default.target

package/deploy/systemd/cohall-relay.service

@@ -0,0 +1,30 @@
+[Unit]
+Description=Cohall relay
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=cohall
+Group=cohall
+EnvironmentFile=/etc/cohall/relay.env
+ExecStart=/usr/local/bin/cohall relay
+Restart=on-failure
+RestartSec=3
+UMask=0077
+StateDirectory=cohall
+StateDirectoryMode=0700
+NoNewPrivileges=true
+PrivateTmp=true
+PrivateDevices=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/cohall
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+
+[Install]
+WantedBy=multi-user.target

package/deploy/windows/install-device.ps1

@@ -0,0 +1,21 @@
+$ErrorActionPreference = "Stop"
+
+$cohall = (Get-Command cohall -ErrorAction Stop).Source
+$action = New-ScheduledTaskAction -Execute $cohall -Argument "device"
+$trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME
+$settings = New-ScheduledTaskSettingsSet `
+  -ExecutionTimeLimit (New-TimeSpan -Days 3650) `
+  -RestartCount 999 `
+  -RestartInterval (New-TimeSpan -Minutes 1) `
+  -MultipleInstances IgnoreNew
+
+Register-ScheduledTask `
+  -TaskName "Cohall Device" `
+  -Description "Connect this device to the configured Cohall relay" `
+  -Action $action `
+  -Trigger $trigger `
+  -Settings $settings `
+  -Force | Out-Null
+
+Start-ScheduledTask -TaskName "Cohall Device"
+Write-Output "Cohall Device scheduled task installed."

package/docs/install.md

@@ -0,0 +1,87 @@
+# Install Cohall
+
+## Run with a package runner
+
+Cohall is a public npm package and requires Node.js 24 or newer. Nothing from
+Buzz, T3Code, Codex, Claude Code, or OpenCode is bundled or required.
+
+```bash
+npx -y @akshar5/cohall --version
+bunx @akshar5/cohall --version
+pnpm dlx @akshar5/cohall --version
+yarn dlx @akshar5/cohall --version
+```
+
+The package follows the standard npm package format, so npm, Bun, pnpm, and Yarn
+can install it too. The documentation uses `npx` as the common default. An
+unattended relay or device service may install the package globally so its
+executable path remains fixed across restarts:
+
+```bash
+npm install --global @akshar5/cohall
+# or: bun add --global @akshar5/cohall
+# or: pnpm add --global @akshar5/cohall
+cohall --version
+```
+
+## Pair a machine
+
+The relay owner creates a token valid for ten minutes and one exchange:
+
+```bash
+COHALL_RELAY_URL=https://cohall.example.com \
+COHALL_TOKEN=owner-token \
+npx -y @akshar5/cohall pair --label "Linux workstation"
+```
+
+Transfer it privately, then enter it without placing it in process arguments or
+shell history:
+
+```bash
+read -rsp 'Pairing token: ' pairing_token; printf '\n'
+printf '%s' "$pairing_token" | npx -y @akshar5/cohall join \
+  --relay https://cohall.example.com \
+  --name linux \
+  --providers codex \
+  --workspace "$HOME/dev"
+unset pairing_token
+```
+
+For a client-only machine that submits work but never runs a device daemon:
+
+```bash
+npx -y @akshar5/cohall pair --client-only --label "Automation client"
+read -rsp 'Pairing token: ' pairing_token; printf '\n'
+printf '%s' "$pairing_token" | npx -y @akshar5/cohall join \
+  --relay https://cohall.example.com \
+  --client-only
+unset pairing_token
+```
+
+For automation, place the token in a mode-`0600` file and use
+`npx -y @akshar5/cohall join --token-file /path/to/token`. Pairing tokens expire
+after ten minutes and can be exchanged once.
+
+Configuration locations:
+
+- Linux: `${XDG_CONFIG_HOME:-~/.config}/cohall/config.json`
+- macOS: `~/Library/Application Support/Cohall/config.json`
+- Windows: `%APPDATA%\Cohall\config.json`
+
+Use `COHALL_CONFIG` to override the path. On Unix, Cohall enforces directory
+mode `0700` and file mode `0600`.
+
+The relay must stay online so devices and clients can reach it. A target device
+must be online only while it is accepting or running work; queued tasks remain
+durable on the relay while it is offline.
+
+`--providers` is an optional comma-separated allowlist. It prevents an installed
+but unauthenticated provider executable from being advertised. Run `cohall
+configure --providers auto` to return to executable auto-detection.
+
+## Upgrade
+
+`npx -y @akshar5/cohall` resolves the current npm release. For a globally
+installed service, stop it, run `npm install --global @akshar5/cohall@latest`,
+verify `cohall doctor`, and restart it. Back up the relay data directory before
+upgrading a production relay; SQLite schema migrations run in place.

package/docs/integrations.md

@@ -0,0 +1,92 @@
+# Agent harness integrations
+
+CLI plus skill is the recommended integration. MCP is available for hosts that
+prefer native tool discovery. Both use the same relay and device protocol.
+
+## CLI plus skill
+
+```bash
+npx -y @akshar5/cohall skill install all
+npx -y @akshar5/cohall doctor
+```
+
+This installs the same embedded `SKILL.md` into:
+
+- `~/.agents/skills/cohall` for Codex-compatible skill loaders;
+- `~/.claude/skills/cohall` for Claude Code;
+- `~/.config/opencode/skills/cohall` for OpenCode.
+
+T3Code, Buzz, and other harnesses can run `npx -y @akshar5/cohall` from their
+normal shell/tool environment. `bunx @akshar5/cohall`, `pnpm dlx
+@akshar5/cohall`, and `yarn dlx @akshar5/cohall` are equivalent. No
+Cohall-specific UI extension is required.
+
+## Codex MCP
+
+```bash
+codex mcp add cohall -- npx -y @akshar5/cohall mcp
+```
+
+Or configure `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.cohall]
+command = "npx"
+args = ["-y", "@akshar5/cohall", "mcp"]
+```
+
+## Claude Code MCP
+
+```bash
+claude mcp add --transport stdio --scope user cohall -- \
+  npx -y @akshar5/cohall mcp
+```
+
+Or use the standard JSON form in a project `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cohall": {
+      "command": "npx",
+      "args": ["-y", "@akshar5/cohall", "mcp"]
+    }
+  }
+}
+```
+
+## OpenCode MCP
+
+Add this to `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "cohall": {
+      "type": "local",
+      "command": ["npx", "-y", "@akshar5/cohall", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+## Environment
+
+The MCP subprocess reads the normal per-user Cohall configuration. If a harness
+uses an isolated environment, pass only:
+
+```text
+COHALL_CONFIG=/absolute/path/to/config.json
+```
+
+Or pass `COHALL_RELAY_URL` and `COHALL_CLIENT_TOKEN` directly. Never place an
+owner or device token in an MCP client configuration.
+
+CLI and MCP are equivalent entry points. Use one per delegated task.
+Both expose redacted task tracing through `cohall trace <task-id>` and the
+`task_trace` MCP tool.
+Replace the `npx`, `-y`, `@akshar5/cohall` command prefix with `bunx`,
+`@akshar5/cohall` or `pnpm`, `dlx`, `@akshar5/cohall` when that better matches
+the host.

package/docs/releasing.md

@@ -0,0 +1,33 @@
+# Release operations
+
+Cohall publishes publicly to npm as `@akshar5/cohall`. Releases use Release
+Please and npm trusted publishing; no long-lived npm token is stored in GitHub.
+
+Before merging a release:
+
+```bash
+bun install --frozen-lockfile
+bun run check
+bun run check
+npm pack --dry-run
+```
+
+The Check workflow runs only when manually dispatched or when a non-draft pull
+request is opened or marked ready for review. Synchronizing commits does not
+automatically consume another private-repository runner allocation.
+
+After releasable conventional commits reach `main`, Release Please opens or
+updates one release pull request. Merging it creates the version tag and GitHub
+release; the same workflow then publishes that exact version to npm through
+GitHub Actions OIDC.
+
+The initial `0.2.0` release was published manually and tagged as the automation
+baseline. npm trusted publishing is configured for:
+
+- npm package: `@akshar5/cohall`
+- repository: `AksharP5/cohall`
+- workflow: `release.yml`
+- environment: none
+
+Publishing uses GitHub Actions OIDC. Do not add `NPM_TOKEN` or `NODE_AUTH_TOKEN`
+to the workflow.

package/docs/services.md

@@ -0,0 +1,103 @@
+# Run Cohall as a service
+
+Interactive use should use `npx -y @akshar5/cohall`. Unattended services
+install the same npm package so the operating system has a stable executable
+path.
+
+## Linux device daemon
+
+Install and pair as the user that will run the daemon:
+
+```bash
+npm install --global --prefix "$HOME/.local" @akshar5/cohall
+npx -y @akshar5/cohall doctor
+```
+
+Copy the service shipped in the globally installed package, then start it:
+
+```bash
+package_root="$(npm root --global --prefix "$HOME/.local")/@akshar5/cohall"
+install -Dm644 "$package_root/deploy/systemd/cohall-device.service" \
+  "$HOME/.config/systemd/user/cohall-device.service"
+systemctl --user daemon-reload
+systemctl --user enable --now cohall-device
+journalctl --user -u cohall-device -f
+loginctl enable-linger "$USER"
+```
+
+Linger is optional; it keeps the daemon running after logout.
+
+## Linux relay
+
+Create a dedicated `cohall` user, install the npm package globally so
+`command -v cohall` returns `/usr/local/bin/cohall`, and place the relay
+environment at `/etc/cohall/relay.env` with mode `0600`:
+
+```dotenv
+COHALL_RELAY_HOST=0.0.0.0
+COHALL_RELAY_PORT=8787
+COHALL_RELAY_ALLOW_REMOTE=true
+COHALL_TOKEN=replace-with-a-random-owner-token
+COHALL_DATA_DIR=/var/lib/cohall
+```
+
+Install `deploy/systemd/cohall-relay.service`, then:
+
+```bash
+systemctl daemon-reload
+systemctl enable --now cohall-relay
+journalctl -u cohall-relay -f
+```
+
+Expose the relay only through a private network such as Tailscale or an HTTPS
+reverse proxy. Device connections are outbound WebSockets.
+
+## macOS
+
+Run `npm install --global @akshar5/cohall`, copy the packaged launch agent, then
+update its executable path to match `command -v cohall`:
+
+```bash
+package_root="$(npm root --global)/@akshar5/cohall"
+mkdir -p "$HOME/Library/LaunchAgents"
+cp "$package_root/deploy/launchd/com.cohall.device.plist" \
+  "$HOME/Library/LaunchAgents/com.cohall.device.plist"
+cohall_path="$(command -v cohall)"
+/usr/libexec/PlistBuddy -c "Set :ProgramArguments:0 $cohall_path" \
+  "$HOME/Library/LaunchAgents/com.cohall.device.plist"
+launchctl bootstrap gui/"$(id -u)" ~/Library/LaunchAgents/com.cohall.device.plist
+launchctl kickstart -k gui/"$(id -u)"/com.cohall.device
+```
+
+The relay and device worker may run on the same machine. Configure the worker
+with the relay's private Tailscale URL and install both services independently.
+
+## Windows
+
+Run `npm install --global @akshar5/cohall`, pair and verify the machine from
+PowerShell, then run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File deploy\windows\install-device.ps1
+```
+
+The script registers a per-user scheduled task that starts `cohall device` at
+logon and restarts it after failures.
+
+## Troubleshooting
+
+Start with `cohall doctor`. It reports relay reachability, device connectivity,
+provider selection, executable discovery, and version information without
+printing credentials.
+
+Inspect a task's redacted lifecycle, including dispatches, reconnect-driven
+requeues, execution, cancellation, and completion:
+
+```bash
+cohall trace <task-id>
+cohall trace <task-id> --follow
+```
+
+Use `journalctl --user -u cohall-device -f` for a Linux device and
+`journalctl -u cohall-relay -f` for a system relay. The trace is durable and
+portable; service logs remain machine-local.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akshar5/cohall",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Let coding agents delegate work across your own devices.",
   "keywords": [
     "agents",
@@ -28,6 +28,8 @@
   ],
   "files": [
     "bin",
+    "deploy",
+    "docs",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"