agent-relay-server 0.3.11 → 0.4.0

package/README.md

@@ -20,6 +20,8 @@ You're running three Claude Code sessions: one debugging a backend, another writ
 - **Claim-based tasks**: post a task, exactly one agent grabs it (atomic, no duplicates)
 - **Threading**: full conversation chains between agents
 - **Live dashboard**: agents, messages, and stats in real time
+- **Closed-loop tasks**: external systems can create deduped work items agents
+  claim, progress, resolve, and report back through callbacks
 
 ## Quick Start
 
@@ -32,6 +34,25 @@ bunx agent-relay-server@latest
 
 Dashboard at `http://localhost:4850`.
 
+Localhost is intentionally frictionless. If you bind the relay to a non-loopback
+address, set `AGENT_RELAY_TOKEN` first:
+
+```bash
+AGENT_RELAY_TOKEN="$(openssl rand -hex 24)" HOST=0.0.0.0 bunx agent-relay-server@latest
+```
+
+For an always-on local relay, use the setup + daemon commands instead:
+
+```bash
+bun install -g agent-relay-server@latest
+agent-relay setup --yes
+agent-relay daemon install --binary "$(command -v agent-relay)" --enable --start --yes
+```
+
+`setup` creates a managed env file with a generated token, loopback bind, and a
+durable SQLite path. `daemon install` auto-detects systemd user services on
+Linux and LaunchAgents on macOS.
+
 ### 2. Install the Claude Code plugin
 
 Requires **Claude Code 2.1.105+** (native plugin monitors).
@@ -77,21 +98,29 @@ codex-relay
 incoming messages as live turns, and cleans up sidecar processes when Codex
 exits.
 
+The normal hook path attaches to the Codex thread that was just launched. If the
+launcher has to use its fallback sidecar because the hook did not report in
+time, it starts a new thread by default to avoid surprising cwd-based attachment
+to an unrelated loaded session. Use `codex-relay --thread-mode auto` or
+`AGENT_RELAY_CODEX_FALLBACK_THREAD_MODE=auto` when you deliberately want the
+fallback sidecar to attach to the newest loaded thread for the current cwd.
+
 ### Codex approval mode
 
 Replying to relay messages is usually done with a shell command (`curl` to
 `/api/messages`), so Codex may prompt for approval in stricter modes.
 
-By default, `codex-relay` starts Codex with
-`--dangerously-bypass-approvals-and-sandbox` so relay turns do not get stuck on
-approval prompts. If you pass an explicit Codex runtime mode, `codex-relay`
+By default, `codex-relay` starts Codex with `--ask-for-approval never --sandbox
+workspace-write` so relay replies do not get stuck on approval prompts while
+still keeping Codex inside workspace boundaries. If you pass an explicit Codex
+runtime mode, `codex-relay`
 leaves it alone and forwards it to the sidecar, including `--ask-for-approval`,
 `--sandbox`, `--full-auto`, and `--yolo`.
 
 Useful setups:
 
 ```bash
-# default: no approval prompts, no Codex sandbox
+# default: no approval prompts, workspace sandbox
 codex-relay
 ```
 
@@ -100,6 +129,11 @@ codex-relay
 codex-relay -- --ask-for-approval never --sandbox workspace-write
 ```
 
+```bash
+# trusted private rig only: no approval prompts, no Codex sandbox
+codex-relay -- --dangerously-bypass-approvals-and-sandbox
+```
+
 ```python
 # ~/.codex/rules/default.rules
 # allow only relay message sends without repeated prompts
@@ -114,6 +148,7 @@ Use a remote relay server by setting:
 
 ```bash
 export AGENT_RELAY_URL=http://100.x.y.z:4850
+export AGENT_RELAY_TOKEN=your-shared-token
 bunx -p agent-relay-server@latest codex-relay
 ```
 
@@ -149,6 +184,15 @@ curl -fsSL https://unpkg.com/agent-relay-server@latest/codex/install-codex.sh |
 $env:AGENT_RELAY_CODEX_ALIAS = "1"; irm https://unpkg.com/agent-relay-server@latest/codex/install-codex.ps1 | iex
 ```
 
+Uninstall Codex support:
+
+```bash
+agent-relay-codex uninstall
+```
+
+This removes the Codex SessionStart hook, local plugin marketplace files, and
+launcher shims. It leaves shell profile PATH edits visible for manual cleanup.
+
 ## What the Agent Sees
 
 For Claude Code sessions, the plugin monitor registers the agent and outputs its
@@ -179,21 +223,132 @@ Example incoming relay message:
 | Label | `"label:test writer"` | All agents with that human-set label |
 | Broadcast | `"broadcast"` | Everyone |
 
+## Mental Model
+
+Agent Relay is a small trusted-network message bus:
+
+- **Server**: one Bun process with SQLite state and an HTTP API.
+- **Agent registration**: each Claude/Codex session registers an agent card with
+  id, labels, tags, capabilities, status, and readiness.
+- **Delivery**: Claude receives monitor notifications; Codex receives live turns
+  through the app-server sidecar.
+- **Routing**: direct ids target one session; tags/capabilities/labels fan out;
+  claimable messages are tasks where one matching agent claims before acting.
+- **Threads**: replies set `replyTo`; the server keeps a thread id so the
+  dashboard/API can show the conversation chain.
+- **Read state**: read markers are per agent. Deleting a message removes it from
+  history, so prefer retention settings over manual deletion for cleanup.
+- **Tasks**: integrations create durable work items. New open tasks also create
+  claimable system messages so one agent can pick up the work.
+- **Callbacks**: integrations can receive task lifecycle webhooks for closed-loop
+  automation.
+
+## Integrations And Tasks
+
+Agent Relay can act as a secure ingress layer for scripts, monitoring systems,
+CI jobs, and support tools. External tools should use integration tokens instead
+of the full `AGENT_RELAY_TOKEN`.
+
+Configure integrations with `AGENT_RELAY_INTEGRATIONS`:
+
+```bash
+export AGENT_RELAY_INTEGRATIONS='[
+  {
+    "name": "ops-monitor",
+    "token": "ops-secret",
+    "scopes": ["tasks:create"],
+    "targets": ["cap:ops"],
+    "channels": ["alerts"],
+    "callbackUrl": "https://ops.example/agent-relay/callback"
+  },
+  {
+    "name": "support-desk",
+    "token": "support-secret",
+    "scopes": ["tasks:create"],
+    "targets": ["cap:support"],
+    "channels": ["support"]
+  }
+]'
+```
+
+Create or update a task:
+
+```bash
+curl -sS -X POST "$AGENT_RELAY_URL/api/integrations/events" \
+  -H "Authorization: Bearer ops-secret" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "alarm",
+    "severity": "critical",
+    "dedupeKey": "prod-api:5xx-rate",
+    "title": "prod-api 5xx rate high",
+    "body": "5xx rate is above 8% for 5 minutes",
+    "target": "cap:ops",
+    "channel": "alerts",
+    "externalUrl": "https://grafana.example/d/prod-api",
+    "metadata": { "service": "prod-api", "value": 0.084 }
+  }'
+```
+
+`dedupeKey` gives predictable update semantics: if the same source posts the same
+dedupe key while the task is active, Agent Relay increments `occurrenceCount`,
+updates `lastSeenAt`, records a task event, and does not spam agents with another
+claimable message. Posting `"status": "resolved"` marks the active task `done`.
+
+When an integration has `callbackUrl`, Agent Relay records and attempts a
+best-effort `POST` on task creation, claim, and status changes:
+
+```json
+{
+  "event": "task.status",
+  "task": {
+    "id": 42,
+    "status": "done",
+    "result": "Rolled back bad deploy"
+  }
+}
+```
+
+Callback attempts are written to SQLite before delivery so failed deliveries are
+auditable during practical testing.
+
+Task lifecycle API:
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/integrations/events` | Scoped integration ingress; creates or dedupes tasks |
+| `GET` | `/tasks` | List tasks (`?status=`, `?source=`, `?target=`, `?limit=`) |
+| `GET` | `/tasks/:id` | Get one task |
+| `GET` | `/tasks/:id/events` | Get task event history |
+| `POST` | `/tasks/:id/claim` | Claim a task as an agent |
+| `PATCH` | `/tasks/:id/status` | Update status/result/progress |
+
+Example connectors live under `examples/integrations/`:
+
+- `ops-alert.sh`: simple shell event producer.
+- `support-ticket.sh`: simple support ticket producer.
+- `prometheus-alertmanager.ts`: reads an Alertmanager webhook payload from stdin.
+- `github-issue.ts`: reads a GitHub issue webhook payload from stdin.
+
 ## Deployment
 
 Single process, embedded SQLite, no external dependencies beyond Bun.
 
 ```bash
 bunx agent-relay-server@latest                         # localhost only
-PORT=8080 HOST=0.0.0.0 bunx agent-relay-server@latest  # remote access
+AGENT_RELAY_TOKEN=... PORT=8080 HOST=0.0.0.0 bunx agent-relay-server@latest  # remote access
 ```
 
 For multi-machine setups, run the server on one machine and set `AGENT_RELAY_URL` on the others (works great over [Tailscale](https://tailscale.com)):
 
 ```bash
 export AGENT_RELAY_URL=http://100.x.y.z:4850
+export AGENT_RELAY_TOKEN=your-shared-token
 ```
 
+Do not expose Agent Relay directly to the public internet. It is designed for a
+trusted localhost/VPN/LAN boundary, not as a multi-tenant public service.
+
 ### Server environment variables
 
 | Variable | Default | Purpose |
@@ -205,39 +360,74 @@ export AGENT_RELAY_URL=http://100.x.y.z:4850
 | `OFFLINE_PRUNE_MS` | `86400000` | Delete offline agents older than this |
 | `REAP_INTERVAL_MS` | `60000` | Reaper cadence for stale/offline cleanup |
 | `RETENTION_DAYS` | `30` | Auto-prune messages older than this |
+| `AGENT_RELAY_TOKEN` | unset | Shared bearer token required for non-loopback binds |
+| `AGENT_RELAY_CORS_ORIGINS` | same-origin only | Comma-separated browser origins, or `*` |
+| `AGENT_RELAY_ALLOW_UNAUTH` | unset | Set `1` to allow unauthenticated non-loopback binds |
+| `AGENT_RELAY_INTEGRATIONS` | `[]` | JSON integration token/scopes/target/callback config |
+| `AGENT_RELAY_INTEGRATION_RATE_LIMIT_PER_MINUTE` | `120` | Per-integration event ingress limit |
 
 ### Plugin environment variables
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
 | `AGENT_RELAY_URL` | `http://localhost:4850` | Relay server URL |
+| `AGENT_RELAY_TOKEN` | unset | Token sent by Codex/dashboard/API clients |
 | `AGENT_RELAY_CAPS` | `chat` | Comma-separated agent capabilities |
 
 Agent IDs are deterministic: `{hostname}-{rig}-{project}-{pid-hash}`.
 
-### Running as a systemd service
+### Managed daemon
+
+Agent Relay can install itself as a user-level daemon and load on computer
+restart. The installer chooses the safest supported backend:
+
+- Linux with `systemctl`: systemd user service by default.
+- macOS: launchd LaunchAgent.
+- Unsupported environments: prints a manual command instead of guessing.
+
+Recommended first-time setup:
+
+```bash
+# inspect what will be written
+agent-relay setup --dry-run
+
+# write the env file with a generated AGENT_RELAY_TOKEN
+agent-relay setup --yes
+
+# install, enable at login/boot, and start now
+agent-relay daemon install --binary "$(command -v agent-relay)" --enable --start --yes
+```
+
+Lifecycle commands:
 
 ```bash
-# create user service
-mkdir -p ~/.config/systemd/user
-cat > ~/.config/systemd/user/agent-relay.service << 'EOF'
-[Unit]
-Description=Agent Relay
-After=network.target
+agent-relay daemon status
+agent-relay daemon logs
+agent-relay daemon restart
+agent-relay daemon stop
+agent-relay daemon start
+agent-relay daemon disable
+agent-relay daemon enable
+agent-relay daemon uninstall
+```
 
-[Service]
-ExecStart=%h/.bun/bin/bunx agent-relay-server@latest
-Environment=HOST=0.0.0.0
-Restart=always
+Useful options:
 
-[Install]
-WantedBy=default.target
-EOF
+```bash
+# preview service files/commands without changing the machine
+agent-relay daemon install --dry-run --enable --start
+
+# remote/VPN bind; setup will still generate a token
+agent-relay setup --host 0.0.0.0 --yes
+agent-relay daemon install --binary "$(command -v agent-relay)" --enable --start --yes
 
-systemctl --user daemon-reload
-systemctl --user enable --now agent-relay
+# use a known stable binary/script path in the service file
+agent-relay daemon install --binary ~/.bun/bin/agent-relay --enable --start
 ```
 
+Daemon install/uninstall refuses to overwrite or remove service files that do
+not contain Agent Relay's managed marker unless `--force` is passed.
+
 ### Version compatibility
 
 The plugin checks the server version on startup and warns if they diverge. Both packages share version numbers. Update them together:
@@ -254,6 +444,16 @@ claude plugin update agent-relay@agent-relay
 
 Base URL: `http://localhost:4850/api`
 
+When `AGENT_RELAY_TOKEN` is set, pass it with either header:
+
+```bash
+curl -H "Authorization: Bearer $AGENT_RELAY_TOKEN" http://localhost:4850/api/stats
+curl -H "X-Agent-Relay-Token: $AGENT_RELAY_TOKEN" http://localhost:4850/api/stats
+```
+
+The dashboard asks for the token on first 401 and stores it in browser
+`localStorage` for that origin.
+
 ### Agents
 
 | Method | Path | Purpose |
@@ -279,6 +479,17 @@ Base URL: `http://localhost:4850/api`
 | `DELETE` | `/messages/:id` | Delete message |
 | `GET` | `/messages/cursor` | Latest message ID (for poller bootstrap) |
 
+### Tasks
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/integrations/events` | Integration event ingress |
+| `GET` | `/tasks` | List tasks |
+| `GET` | `/tasks/:id` | Get one task |
+| `GET` | `/tasks/:id/events` | Get task event history |
+| `POST` | `/tasks/:id/claim` | Claim a task |
+| `PATCH` | `/tasks/:id/status` | Update task status/result |
+
 ### Server-Sent Events
 
 | Method | Path | Purpose |
@@ -297,14 +508,18 @@ Events: `message.new`, `message.claimed`, `message.deleted`, `agent.status`, `ag
 
 ```
 src/
+├── cli.ts        # server CLI, setup, daemon commands
+├── daemon.ts     # OS daemon planning/execution
 ├── index.ts      # Bun.serve entry, static files, CORS
+├── setup.ts      # onboarding env-file generation
 ├── routes.ts     # HTTP router and API handlers
 ├── db.ts         # SQLite schema, queries, CRUD
 ├── sse.ts        # Server-Sent Events
 └── types.ts      # TypeScript interfaces
 
 public/
-└── index.html    # Dashboard SPA (Alpine.js + Tabler)
+├── index.html    # Dashboard markup
+└── dashboard.js  # Dashboard Alpine model and behavior
 
 claude/                              # Claude Code plugin
 ├── .claude-plugin/plugin.json

package/bin/agent-relay-codex.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { appendFileSync, chmodSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -55,11 +55,12 @@ function usage(exitCode = 0): never {
 Usage:
   agent-relay-codex [--relay-url URL] [--listen ws://127.0.0.1:PORT] [-- <codex args...>]
   agent-relay-codex install [--alias|--no-alias]
+  agent-relay-codex uninstall
   agent-relay-codex alias install
   agent-relay-codex alias remove
   agent-relay-codex doctor
-  agent-relay-codex start [--relay-url URL] [--listen ws://127.0.0.1:PORT] [-- <codex args...>]
-  codex-relay [--relay-url URL] [--listen ws://127.0.0.1:PORT] [-- <codex args...>]
+  agent-relay-codex start [--relay-url URL] [--listen ws://127.0.0.1:PORT] [--thread-mode auto|resume|start] [-- <codex args...>]
+  codex-relay [--relay-url URL] [--listen ws://127.0.0.1:PORT] [--thread-mode auto|resume|start] [-- <codex args...>]
 
 With no subcommand, this launches Codex with live Agent Relay support.`);
   process.exit(exitCode);
@@ -165,7 +166,9 @@ async function getRelayStats(relayUrl: string): Promise<RelayStats | null> {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 1500);
   try {
-    const response = await fetch(new URL("/api/stats", relayUrl), { signal: controller.signal });
+    const headers: Record<string, string> = {};
+    if (process.env.AGENT_RELAY_TOKEN) headers["X-Agent-Relay-Token"] = process.env.AGENT_RELAY_TOKEN;
+    const response = await fetch(new URL("/api/stats", relayUrl), { signal: controller.signal, headers });
     if (!response.ok) return null;
     return (await response.json()) as RelayStats;
   } catch {
@@ -328,6 +331,35 @@ timeout = 10
   else writeFileSync(hooksPath, `${JSON.stringify(hooksJson, null, 2)}\n`);
 }
 
+function removeHook(): void {
+  const configPath = join(home, ".codex", "config.toml");
+  if (existsSync(configPath)) {
+    const cleaned = removeAgentRelaySessionStartToml(readFileSync(configPath, "utf8"));
+    if (cleaned.trim()) writeFileSync(configPath, cleaned);
+    else rmSync(configPath, { force: true });
+  }
+
+  const hooksPath = join(home, ".codex", "hooks.json");
+  if (!existsSync(hooksPath)) return;
+
+  const hooksJson = readJsonFile<HooksJson>(hooksPath, { hooks: {} });
+  hooksJson.hooks ??= {};
+  hooksJson.hooks.SessionStart = (hooksJson.hooks.SessionStart ?? [])
+    .map((group) => ({
+      ...group,
+      hooks: (group.hooks ?? []).filter((hook) => {
+        if (hook.type !== "command" || typeof hook.command !== "string") return true;
+        return !isAgentRelaySessionStartCommand(hook.command);
+      }),
+    }))
+    .filter((group) => (group.hooks ?? []).length > 0);
+
+  if (hooksJson.hooks.SessionStart.length === 0) delete hooksJson.hooks.SessionStart;
+
+  if (Object.keys(hooksJson.hooks).length === 0) rmSync(hooksPath, { force: true });
+  else writeFileSync(hooksPath, `${JSON.stringify(hooksJson, null, 2)}\n`);
+}
+
 async function pickLoopbackUrl(): Promise<string> {
   const port = await new Promise<number>((resolvePort, reject) => {
     const server = net.createServer();
@@ -406,7 +438,7 @@ function spawnFallbackSidecar(runDir: string, env: Record<string, string | undef
 
   const sidecarEnv: Record<string, string | undefined> = {
     ...env,
-    CODEX_THREAD_MODE: "auto",
+    CODEX_THREAD_MODE: env.AGENT_RELAY_CODEX_FALLBACK_THREAD_MODE || env.CODEX_THREAD_MODE || "start",
     CODEX_LIVE_CWD: process.cwd(),
     CODEX_LIVE_STATE_PATH: join(autoDir, "live-state.json"),
   };
@@ -519,6 +551,24 @@ function cleanupRun(runDir: string, appServer: ReturnType<typeof Bun.spawn> | nu
   }
 }
 
+function stopRuntimeSidecars(): void {
+  if (!existsSync(runtimeRoot)) return;
+  for (const entry of readdirSync(runtimeRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const pidsPath = join(runtimeRoot, entry.name, "sidecar-pids.txt");
+    if (!existsSync(pidsPath)) continue;
+    for (const line of readFileSync(pidsPath, "utf8").split("\n")) {
+      const pid = Number(line.trim());
+      if (!Number.isFinite(pid) || pid <= 0) continue;
+      try {
+        process.kill(pid, "SIGTERM");
+      } catch {
+        // Sidecar already exited.
+      }
+    }
+  }
+}
+
 function installCodexSupport(quiet = false): void {
   if (!commandExists("bun")) throw new Error("Bun is required: https://bun.sh");
   findCodexBinary();
@@ -634,6 +684,7 @@ async function start(args: string[]): Promise<void> {
 
   let relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
   let listenUrl = process.env.CODEX_APP_SERVER_URL || "";
+  let threadMode = process.env.CODEX_THREAD_MODE || "start";
   const codexArgs: string[] = [];
 
   for (let index = 0; index < args.length; index += 1) {
@@ -650,11 +701,20 @@ async function start(args: string[]): Promise<void> {
       listenUrl = args[++index] || listenUrl;
       continue;
     }
+    if (arg === "--thread-mode") {
+      threadMode = args[++index] || threadMode;
+      if (!["auto", "resume", "start"].includes(threadMode)) {
+        throw new Error("--thread-mode must be one of: auto, resume, start");
+      }
+      continue;
+    }
     codexArgs.push(arg);
   }
 
   if (!listenUrl) listenUrl = await pickLoopbackUrl();
-  if (!hasCodexPermissionMode(codexArgs)) codexArgs.unshift("--dangerously-bypass-approvals-and-sandbox");
+  if (!hasCodexPermissionMode(codexArgs)) {
+    codexArgs.unshift("--ask-for-approval", "never", "--sandbox", "workspace-write");
+  }
   const permissions = resolveSessionPermissions(codexArgs);
 
   mkdirSync(runtimeRoot, { recursive: true });
@@ -669,6 +729,7 @@ async function start(args: string[]): Promise<void> {
     AGENT_RELAY_CODEX_RUN_ID: runId,
     AGENT_RELAY_CODEX_RUNTIME_DIR: runDir,
     CODEX_APP_SERVER_URL: listenUrl,
+    CODEX_THREAD_MODE: threadMode,
     CODEX_LIVE_APPROVAL_POLICY: permissions.approvalPolicy,
     CODEX_LIVE_SANDBOX: permissions.sandbox,
   };
@@ -785,10 +846,22 @@ async function install(args: string[]): Promise<void> {
   }
 }
 
+function uninstall(): void {
+  stopRuntimeSidecars();
+  removeHook();
+  removeLauncherShim("codex");
+  removeLauncherShim("codex-relay");
+  rmSync(marketplaceRoot, { recursive: true, force: true });
+  rmSync(installedPackageRoot, { recursive: true, force: true });
+  console.log("Uninstalled Agent Relay Codex hook, plugin marketplace files, and launcher shims.");
+  console.log(`PATH entries are left untouched; remove ${aliasBinDir} from your shell profile if you no longer want it there.`);
+}
+
 async function main(): Promise<void> {
   const [command, ...args] = process.argv.slice(2);
   if (command === "help" || command === "--help" || command === "-h") usage(0);
   if (command === "install") return install(args);
+  if (command === "uninstall") return uninstall();
   if (command === "alias" && args[0] === "install") {
     installCodexSupport(false);
     return installCodexAlias();

package/codex/README.md

@@ -57,9 +57,10 @@ and kills sidecars plus the app-server when Codex exits.
 Relay replies are usually sent with a shell command (`curl` to
 `/api/messages`), so Codex can prompt for approval in stricter modes.
 
-By default, `codex-relay` starts Codex with
-`--dangerously-bypass-approvals-and-sandbox` so relay turns do not get stuck on
-approval prompts. If you pass an explicit Codex runtime mode, `codex-relay`
+By default, `codex-relay` starts Codex with `--ask-for-approval never --sandbox
+workspace-write` so relay turns do not get stuck on approval prompts while
+still keeping Codex inside workspace boundaries. If you pass an explicit Codex
+runtime mode, `codex-relay`
 leaves it alone and forwards it to the sidecar, including `--ask-for-approval`,
 `--sandbox`, `--full-auto`, and `--yolo`.
 
@@ -75,6 +76,19 @@ Example: no prompt loop, still workspace sandboxing:
 codex-relay -- --ask-for-approval never --sandbox workspace-write
 ```
 
+Trusted private rig only:
+
+```bash
+codex-relay -- --dangerously-bypass-approvals-and-sandbox
+```
+
+Thread attachment defaults are conservative. The SessionStart hook resumes the
+actual launched Codex thread when Codex provides a thread id. If the launcher has
+to use the fallback sidecar because the hook does not report in time, it starts a
+new thread by default instead of attaching to whichever loaded thread happens to
+match the cwd. Set `AGENT_RELAY_CODEX_FALLBACK_THREAD_MODE=auto` or run
+`codex-relay --thread-mode auto` if you explicitly want cwd-based attachment.
+
 If you prefer prompts for everything else but want relay sends auto-approved,
 add a rule in `~/.codex/rules/default.rules` (adjust URL when using a remote relay):
 
@@ -96,6 +110,7 @@ bun run codex:smoke:fallback
 Useful environment variables:
 
 - `AGENT_RELAY_URL`
+- `AGENT_RELAY_TOKEN`
 - `AGENT_RELAY_CAPS`
 - `AGENT_RELAY_CODEX_HOOK_TIMEOUT_MS` (launcher wait for SessionStart handshake, default `5000`)
 - `CODEX_APP_SERVER_URL`

package/codex/hooks/session-start.ts

@@ -115,7 +115,7 @@ const spawnEnv: Record<string, string | undefined> = {
   ...process.env,
   AGENT_RELAY_URL: relayUrl,
   CODEX_APP_SERVER_URL: appServerUrl,
-  CODEX_THREAD_MODE: threadId ? "resume" : "auto",
+  CODEX_THREAD_MODE: threadId ? "resume" : process.env.CODEX_THREAD_MODE || "start",
   CODEX_LIVE_CWD: cwd,
   CODEX_LIVE_STATE_PATH: statePath,
   CODEX_MODEL: input.model || process.env.CODEX_MODEL || "",
@@ -173,4 +173,4 @@ const identity = buildAgentIdentity({
   appServerUrl,
 });
 
-outputContext(`Agent Relay active. Agent ID: ${identity.id}. Relay URL: ${relayUrl}. Incoming messages will arrive as live user turns. To reply or send a message, POST JSON to ${relayUrl}/api/messages with from="${identity.id}", to, subject, and body.`);
+outputContext(`Agent Relay active. Agent ID: ${identity.id}. Relay URL: ${relayUrl}. Incoming messages will arrive as live user turns. To reply or send a message, POST JSON to ${relayUrl}/api/messages with from="${identity.id}", to, subject, and body. If AGENT_RELAY_TOKEN is set, include it as the X-Agent-Relay-Token header. Message etiquette: acknowledge incoming agent messages briefly unless they are obvious noise. Anti-loop rule: do not auto-reply to pure acknowledgements/thanks/received messages; acknowledge once, then follow up only when there is new work, a decision, or a deliverable.`);

package/codex/live-sidecar.ts

@@ -524,6 +524,7 @@ function formatRelayPrompt(messages: RelayMessage[]): string {
       message.body,
       "",
       "Treat this as a live incoming message from another agent. Respond or act on it as appropriate.",
+      "If AGENT_RELAY_TOKEN is set, include it as the X-Agent-Relay-Token header when calling the relay API.",
       `To reply, POST JSON to ${process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850"}/api/messages with from set to your Agent Relay ID, to set to ${JSON.stringify(message.from)}, and replyTo set to ${message.id}.`,
     );
     return lines.join("\n");
@@ -550,6 +551,7 @@ function formatRelayPrompt(messages: RelayMessage[]): string {
 
   lines.push(
     "Treat these as live incoming messages from other agents. Synthesize them into one coherent response or action.",
+    "If AGENT_RELAY_TOKEN is set, include it as the X-Agent-Relay-Token header when calling the relay API.",
     `To reply, POST JSON to ${process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850"}/api/messages with from set to your Agent Relay ID and replyTo set to the message you are answering.`,
   );
   return lines.join("\n");

package/codex/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Agent Relay integration for Codex sessions",
   "author": {
     "name": "Edin Mujkanovic"

package/codex/plugin/skills/agent-relay/SKILL.md

@@ -17,6 +17,7 @@ Use the relay API at `${AGENT_RELAY_URL:-http://127.0.0.1:4850}`:
 
 ```bash
 curl -sS -X POST "${AGENT_RELAY_URL:-http://127.0.0.1:4850}/api/messages" \
+  ${AGENT_RELAY_TOKEN:+-H "X-Agent-Relay-Token: ${AGENT_RELAY_TOKEN}"} \
   -H 'Content-Type: application/json' \
   -d '{"from":"<this-agent-id>","to":"<target>","subject":"<subject>","body":"<message>"}'
 ```

package/codex/relay.ts

@@ -77,7 +77,7 @@ export class RelayClient {
     url.searchParams.set("for", agentId);
     url.searchParams.set("unread", "true");
     if (sinceId > 0) url.searchParams.set("sinceId", String(sinceId));
-    const response = await fetch(url);
+    const response = await fetch(url, { headers: this.headers() });
     if (!response.ok) {
       throw new Error(`relay poll failed: ${response.status} ${response.statusText}`);
     }
@@ -87,7 +87,7 @@ export class RelayClient {
   async claimMessage(messageId: number, agentId: string): Promise<boolean> {
     const response = await fetch(new URL(`/api/messages/${messageId}/claim`, this.baseUrl), {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: this.headers({ "Content-Type": "application/json" }),
       body: JSON.stringify({ agentId }),
     });
 
@@ -104,7 +104,7 @@ export class RelayClient {
   private async json(method: string, path: string, body?: unknown): Promise<unknown> {
     const response = await fetch(new URL(path, this.baseUrl), {
       method,
-      headers: { "Content-Type": "application/json" },
+      headers: this.headers({ "Content-Type": "application/json" }),
       body: body === undefined ? undefined : JSON.stringify(body),
     });
 
@@ -117,4 +117,9 @@ export class RelayClient {
     if (response.status === 204) return null;
     return response.json().catch(() => null);
   }
+
+  private headers(base: Record<string, string> = {}): Record<string, string> {
+    const token = process.env.AGENT_RELAY_TOKEN;
+    return token ? { ...base, "X-Agent-Relay-Token": token } : base;
+  }
 }