@obtoai/agent-bridge 0.1.0-beta.2 → 0.1.0-beta.4

package/cli/status.js

@@ -1,7 +1,7 @@
 'use strict';
 
-// `obto-bridge status` — read local state.json and print thread→session bindings.
-// Read-only; useful for "did the daemon ever drive this thread?"
+// `obto-bridge status` — read local state.json and print thread→session
+// bindings. Read-only. v1.1: a thread keeps one session per agent.
 
 const fs = require('fs');
 const path = require('path');
@@ -29,20 +29,33 @@ if (threads.length === 0) {
 const fmtAge = (iso) => {
   if (!iso) return '?';
   const ms = Date.now() - new Date(iso).getTime();
-  if (ms < 60_000) return Math.floor(ms / 1000) + 's ago';
-  if (ms < 3_600_000) return Math.floor(ms / 60_000) + 'm ago';
-  if (ms < 86_400_000) return Math.floor(ms / 3_600_000) + 'h ago';
-  return Math.floor(ms / 86_400_000) + 'd ago';
+  if (ms < 60000) return Math.floor(ms / 1000) + 's ago';
+  if (ms < 3600000) return Math.floor(ms / 60000) + 'm ago';
+  if (ms < 86400000) return Math.floor(ms / 3600000) + 'h ago';
+  return Math.floor(ms / 86400000) + 'd ago';
 };
 
-console.log('Thread                               Session ID                            Last drive');
-console.log('-'.repeat(95));
+console.log('Thread                               Agent   Session ID                            Last drive');
+console.log('-'.repeat(100));
 threads.forEach((t) => {
-  const b = bindings[t];
-  const sid = (b.sessionId || '').slice(0, 36);
-  console.log(t.padEnd(36) + ' ' + sid.padEnd(38) + ' ' + fmtAge(b.lastDriveAt));
+  const b = bindings[t] || {};
+  // v1.1 per-agent sessions; tolerate a stray un-migrated v1 flat binding.
+  const sessions = b.sessions && typeof b.sessions === 'object'
+    ? b.sessions
+    : (b.sessionId ? { claude: b } : {});
+  const agents = Object.keys(sessions);
+  if (agents.length === 0) {
+    console.log(t.padEnd(36) + ' (no session yet)');
+    return;
+  }
+  agents.forEach((agent, i) => {
+    const s = sessions[agent] || {};
+    const sid = String(s.sessionId || '').slice(0, 36);
+    console.log(
+      (i === 0 ? t : '').padEnd(36) + ' ' +
+      agent.padEnd(7) + ' ' +
+      sid.padEnd(38) + ' ' +
+      fmtAge(s.lastDriveAt),
+    );
+  });
 });
-console.log('');
-console.log('JSONLs at: ' + (bindings[threads[0]] && bindings[threads[0]].projectDir
-  ? '~/.claude/projects/' + bindings[threads[0]].projectDir.replace(/\//g, '-') + '/'
-  : 'unknown'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obtoai/agent-bridge",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "Local consumer for the OBTO Agent Bridge. Receives bridge events over SSE and drives a coding agent (Claude Code or OpenAI Codex) on your machine.",
   "license": "Apache-2.0",
   "author": "OBTO Inc.",
@@ -32,6 +32,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.126",
-    "@openai/codex-sdk": "^0.130.0"
+    "@openai/codex-sdk": "^0.130.0",
+    "@opencode-ai/sdk": "^1.16.1"
   }
 }

package/src/bridge-http.js

@@ -78,10 +78,18 @@ const getMessages = (threadId, sinceCursor) => {
 const postAgentActivity = (threadId, state) =>
   postJson('/api/bridge/agent-activity', { threadId, state });
 
+// Phase 2b — atomic first-touch claim. Called by the daemon when it sees a
+// reply event for a thread whose `agentId` is null (unrouted). The bridge's
+// claimThread does a conditional Mongo update — only one daemon wins.
+// Returns { ok, won, winner }: `won` is the only thing the caller acts on.
+const claimThread = (threadId, agentId) =>
+  postJson('/api/bridge/thread/claim', { threadId, agentId });
+
 module.exports = {
   getCfg,
   buildHeaders,
   postMessage,
   getMessages,
   postAgentActivity,
+  claimThread,
 };

package/src/capabilities.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// Phase 2b — what this machine can drive. The Claude Agent SDK is a hard
+// dependency of the daemon (declared in package.json), so `claude` is always
+// available. `codex` and `opencode` need their respective CLIs on PATH —
+// we probe with `which` (POSIX) or `where` (Windows).
+//
+// Sent to the bridge as `?capabilities=claude,codex,...` on SSE connect; the
+// bridge records them in `agent_bridge_daemons` so the UI picker can offer
+// only what's actually installable across the account's machines.
+
+const { spawnSync } = require('child_process');
+
+const onPath = (cmd) => {
+  try {
+    const tool = process.platform === 'win32' ? 'where' : 'which';
+    const r = spawnSync(tool, [cmd], { stdio: 'ignore' });
+    return r.status === 0;
+  } catch (_) {
+    return false;
+  }
+};
+
+const detect = () => {
+  const out = ['claude']; // bundled SDK; always advertised
+  if (onPath('codex')) out.push('codex');
+  if (onPath('opencode')) out.push('opencode');
+  return out;
+};
+
+module.exports = { detect, onPath };

package/src/daemon.js

@@ -2,9 +2,10 @@
 
 const { loadConfig } = require('./config');
 const { startStream } = require('./stream-client');
-const { loadState, saveState, getBinding, setBinding } = require('./state');
-const { drive, tryResolvePermission, activeAgent } = require('./driver');
-const { postAgentActivity } = require('./bridge-http');
+const { loadState, saveState, getAgentSession, setAgentSession } = require('./state');
+const { drive, tryResolvePermission, agentFor } = require('./driver');
+const { postAgentActivity, claimThread } = require('./bridge-http');
+const { detect: detectCapabilities } = require('./capabilities');
 
 const log = (level, msg, data) => {
   const line = { ts: new Date().toISOString(), level, msg };
@@ -67,12 +68,46 @@ const handleEvent = async (sseEvent) => {
     return;
   }
 
-  const binding = getBinding(state, threadId);
+  // Phase 2b — multi-daemon race check. The thread's target machine is
+  // included on the event when known (postReply publishes it). If it's set
+  // and isn't us, skip. If null, attempt the atomic first-touch claim — only
+  // the winning daemon handles the event; the rest skip cleanly.
+  const targetAgentId = payload.agentId ? String(payload.agentId).trim() : null;
+  if (targetAgentId && targetAgentId !== cfg.agentId) {
+    log('event', 'skip — claimed by other daemon', {
+      threadId,
+      targetAgentId,
+      messageId: payload.messageId,
+    });
+    return;
+  }
+  if (!targetAgentId) {
+    try {
+      const r = await claimThread(threadId, cfg.agentId);
+      if (!r || !r.ok || !r.data || !r.data.won) {
+        log('info', 'claim lost or failed', {
+          threadId,
+          winner: r && r.data && r.data.winner,
+          status: r && r.status,
+        });
+        return;
+      }
+      log('info', 'claim won', { threadId, agentId: cfg.agentId });
+    } catch (e) {
+      log('error', 'claim threw', { threadId, error: e && e.message });
+      return; // conservative — skip on uncertainty rather than double-drive
+    }
+  }
+
+  // v1.1 — which agent this thread is bound to (server-set, on the event).
+  const agent = agentFor(payload);
+  const session = getAgentSession(state, threadId, agent);
   log('event', 'reply received', {
     threadId,
+    agent,
     author: payload.author,
     messageId: payload.messageId,
-    hasBinding: !!binding,
+    hasSession: !!session,
   });
 
   // Permission-relay replies: resolve the pending request inside the driver and
@@ -85,10 +120,13 @@ const handleEvent = async (sseEvent) => {
   // indicator drops whether the turn succeeds, skips, or throws.
   emitActivity(threadId, 'working');
   try {
+    // The driver receives a flat per-agent session as `binding` — the v1
+    // driver contract is unchanged. v1.1 just keeps one such session per
+    // agent on the thread, so a claude<->codex switch resumes each side.
     const result = await drive({
       threadId,
       projectDir: cfg.projectDir,
-      binding,
+      binding: session,
       payload,
       log,
     });
@@ -96,22 +134,27 @@ const handleEvent = async (sseEvent) => {
     if (
       result &&
       result.sessionId &&
-      (!binding || binding.sessionId !== result.sessionId)
+      (!session || session.sessionId !== result.sessionId)
     ) {
-      setBinding(state, threadId, {
-        sessionId: result.sessionId,
-        projectDir: result.projectDir,
-        jsonlPath: result.jsonlPath,
-        lastJsonlMtimeMs: result.lastJsonlMtimeMs || null,
-        agentId: cfg.agentId,
-        createdAt: new Date().toISOString(),
-        lastDriveAt: new Date().toISOString(),
-      });
-      log('info', 'binding created', { threadId, sessionId: result.sessionId });
-    } else if (binding && !result.skipped) {
-      binding.lastDriveAt = new Date().toISOString();
+      setAgentSession(
+        state,
+        threadId,
+        agent,
+        {
+          sessionId: result.sessionId,
+          projectDir: result.projectDir,
+          jsonlPath: result.jsonlPath,
+          lastJsonlMtimeMs: result.lastJsonlMtimeMs || null,
+          createdAt: new Date().toISOString(),
+          lastDriveAt: new Date().toISOString(),
+        },
+        { agentId: cfg.agentId },
+      );
+      log('info', 'session bound', { threadId, agent, sessionId: result.sessionId });
+    } else if (session && !result.skipped) {
+      session.lastDriveAt = new Date().toISOString();
       if (result && result.lastJsonlMtimeMs) {
-        binding.lastJsonlMtimeMs = result.lastJsonlMtimeMs;
+        session.lastJsonlMtimeMs = result.lastJsonlMtimeMs;
       }
       saveState(state);
     }
@@ -126,16 +169,23 @@ const handleEvent = async (sseEvent) => {
 };
 
 const start = () => {
+  // Phase 2b — advertise capabilities to the bridge on connect so the UI
+  // picker can offer just the agents that are actually installable here.
+  const capabilities = detectCapabilities();
+
   log('info', 'starting daemon', {
     baseUrl: cfg.baseUrl,
     accountId: cfg.accountId,
     agentId: cfg.agentId,
-    agent: activeAgent(),
+    capabilities,
     projectDir: cfg.projectDir,
     boundThreads: Object.keys(state.bindings || {}),
   });
 
-  const url = cfg.baseUrl.replace(/\/$/, '') + '/api/bridge/stream';
+  const url = cfg.baseUrl.replace(/\/$/, '') +
+    '/api/bridge/stream' +
+    '?agentId=' + encodeURIComponent(cfg.agentId) +
+    '&capabilities=' + encodeURIComponent(capabilities.join(','));
   stream = startStream({
     url,
     // Re-read config on every (re)connect so a rotated token (via

package/src/driver.js

@@ -1,47 +1,72 @@
 'use strict';
 
-// Agent-agnostic driver selector. The daemon drives whichever coding agent the
-// operator configured — Claude (via the Claude Agent SDK) or Codex (via the
-// Codex SDK) — chosen by `agent` in config.json / the BRIDGE_AGENT env var.
-// Everything else in the daemon (SSE, state, the bridge HTTP client) is
-// agent-neutral; only the driver differs.
+// Dual-driver dispatch (v1.1).
 //
-// The codex driver is require()d lazily, so a Claude-only install never loads
-// @openai/codex-sdk (and vice versa).
+// v1 resolved ONE agent at startup and drove only that. v1.1 makes the daemon
+// agent-agnostic per event: it can drive BOTH Claude (Claude Agent SDK) and
+// Codex (Codex SDK), and routes each bridge event to the right driver by the
+// thread's `agent` field (`payload.agent`, set server-side from the thread's
+// routing record).
+//
+// Drivers are require()d lazily and cached — a machine that only ever runs
+// Claude threads never pays to load @openai/codex-sdk, and vice versa.
 
 const { loadConfig } = require('./config');
 
-let resolved = null;
+const KNOWN_AGENTS = ['claude', 'codex', 'opencode'];
+
+const cache = {};
 
-const pick = () => {
-  if (resolved) return resolved;
-  let agent = 'claude';
+const loadDriver = (name) => {
+  if (cache[name]) return cache[name];
+  let mod;
+  if (name === 'codex') mod = require('./codex-driver');
+  else if (name === 'opencode') mod = require('./opencode-driver');
+  else mod = require('./claude-driver');
+  cache[name] = mod;
+  return mod;
+};
+
+// Fallback agent for events that arrive without an explicit `agent` — an
+// older bridge, or a thread created before v1.1. Reads config.agent (the v1
+// init choice), else 'claude'.
+let fallbackAgent = null;
+const getFallbackAgent = () => {
+  if (fallbackAgent) return fallbackAgent;
+  let a = 'claude';
   try {
-    agent = (loadConfig().agent || 'claude').toLowerCase();
+    a = (loadConfig().agent || 'claude').toLowerCase();
   } catch (_) {
     // config unreadable — default to claude
   }
-  if (agent === 'codex') {
-    resolved = { name: 'codex', mod: require('./codex-driver') };
-  } else {
-    resolved = { name: 'claude', mod: require('./claude-driver') };
-  }
-  return resolved;
+  fallbackAgent = KNOWN_AGENTS.indexOf(a) !== -1 ? a : 'claude';
+  return fallbackAgent;
 };
 
-const drive = (params) => pick().mod.drive(params);
+// Resolve which agent a bridge event targets.
+const agentFor = (payload) => {
+  const a = payload && payload.agent ? String(payload.agent).toLowerCase() : '';
+  if (KNOWN_AGENTS.indexOf(a) !== -1) return a;
+  return getFallbackAgent();
+};
+
+// Drive one bridge event with the agent its thread is bound to.
+const drive = (params) => {
+  const name = agentFor(params && params.payload);
+  return loadDriver(name).drive(params);
+};
 
-// Permission relay is Claude-only — Codex exposes no per-tool callback. For a
-// Codex daemon this is always a no-op so the reply path goes straight to
-// drive(); for Claude it delegates to the real relay resolver.
+// Permission relay is Claude-only — the Codex SDK exposes no per-tool callback.
+// We delegate to the claude driver's resolver regardless of the thread's agent:
+// it keys on threadId against its own pending-request map, so a codex thread
+// (which never has a pending claude request) simply returns false and the
+// reply falls through to drive().
 const tryResolvePermission = (threadId, body, log) => {
-  const p = pick();
-  if (typeof p.mod.tryResolvePermission === 'function') {
-    return p.mod.tryResolvePermission(threadId, body, log);
+  const claude = loadDriver('claude');
+  if (typeof claude.tryResolvePermission === 'function') {
+    return claude.tryResolvePermission(threadId, body, log);
   }
   return false;
 };
 
-const activeAgent = () => pick().name;
-
-module.exports = { drive, tryResolvePermission, activeAgent };
+module.exports = { drive, tryResolvePermission, agentFor, KNOWN_AGENTS };

package/src/opencode-driver.js

@@ -0,0 +1,220 @@
+'use strict';
+
+// Opencode driver — drives an opencode session per bridge thread, the
+// opencode counterpart of codex-driver.js. Selected when payload.agent ===
+// 'opencode'. Same capture-model shape as Codex: opencode runs the turn, this
+// driver posts the agent's final response to the bridge on its behalf.
+//
+// Why this is shaped like the Codex driver (and not Claude):
+//
+//   • No bridge MCP tool exposed to opencode. Easiest path is the SDK's
+//     session.prompt() and concatenating returned text parts as the answer.
+//
+//   • No fine-grained permission relay. opencode's SDK gives a single
+//     prompt-in / parts-out call per turn. tryResolvePermission() is a no-op.
+//
+// SDK-specific calls are isolated in runOpencode(), verified against
+// @opencode-ai/sdk@^1.16 (Node SDK docs as of 2026-05-21).
+
+const { loadConfig } = require('./config');
+const { buildEnvelope } = require('./claude-driver');
+const bridgeHttp = require('./bridge-http');
+
+// Per-thread promise queue — concurrent replies on one thread are serialized
+// so first-touch completes before any resume. Mirrors codex-driver.
+const queues = new Map();
+
+// Defaults can be overridden per-machine via env. Anthropic Claude is the
+// default because users running opencode usually already have Claude auth.
+const DEFAULT_PROVIDER = process.env.BRIDGE_OPENCODE_PROVIDER || 'anthropic';
+const DEFAULT_MODEL = process.env.BRIDGE_OPENCODE_MODEL || 'claude-sonnet-4-5';
+
+const buildOpencodePrompt = (payload, isFirst) => {
+  const head = buildEnvelope(payload);
+  if (!isFirst) return head;
+  return head +
+    '\n\n---\n' +
+    'You are an opencode session spawned by the OBTO Agent Bridge to handle ' +
+    'thread "' + payload.threadId + '". The human who sent the message above ' +
+    'is on the OBTO bridge web UI — they do NOT see your terminal, your tool ' +
+    'calls, or any intermediate output. They see ONLY your final response, ' +
+    'delivered to them verbatim.\n\n' +
+    'Therefore: do the requested work, then make your final response a ' +
+    'complete, self-contained answer addressed to that human. Markdown is ' +
+    'supported. If you need information you do not have, make your final ' +
+    'response a single clear question. Now handle the message above.';
+};
+
+// Best-effort extraction of the assistant's final text from an opencode
+// prompt result. The SDK returns `{ parts: [...] }` or `{ data: { parts } }`
+// depending on the call; we tolerate both and concatenate every text part.
+const extractFinalResponse = (result) => {
+  if (!result) return '';
+  const parts = (result && result.parts) ||
+    (result && result.data && result.data.parts) ||
+    [];
+  if (!Array.isArray(parts)) return '';
+  return parts
+    .filter((p) => p && (p.type === 'text' || typeof p.text === 'string'))
+    .map((p) => String(p.text || ''))
+    .join('\n')
+    .trim();
+};
+
+// ── SDK boundary ──────────────────────────────────────────────────────────
+// All @opencode-ai/sdk calls. The SDK spawns a local opencode HTTP server;
+// we tear it down at the end of every turn (cheap, simple, no shared state).
+const runOpencode = async ({ prompt, projectDir, resumeId }) => {
+  const { createOpencode } = await import('@opencode-ai/sdk');
+  const handle = await createOpencode({ directory: projectDir });
+  const client = handle.client;
+  const closeHandle = handle.close || (handle.server && handle.server.close);
+
+  try {
+    let sessionId = resumeId;
+    if (!sessionId) {
+      const created = await client.session.create({
+        body: { title: 'obto-bridge' },
+      });
+      sessionId = (created && created.id) ||
+        (created && created.data && created.data.id) ||
+        null;
+    }
+
+    const result = await client.session.prompt({
+      path: { id: sessionId },
+      body: {
+        model: { providerID: DEFAULT_PROVIDER, modelID: DEFAULT_MODEL },
+        parts: [{ type: 'text', text: prompt }],
+      },
+    });
+
+    return {
+      sessionId: sessionId || (result && result.sessionId) || null,
+      finalResponse: extractFinalResponse(result),
+    };
+  } finally {
+    try { if (typeof closeHandle === 'function') await closeHandle(); } catch (_) {}
+  }
+};
+// ──────────────────────────────────────────────────────────────────────────
+
+const postToBridge = async ({ threadId, body, kind, log }) => {
+  try {
+    const r = await bridgeHttp.postMessage({
+      threadId,
+      body,
+      kind: kind || 'result',
+      author: 'opencode-bridge',
+      role: 'agent',
+    });
+    if (!r.ok) {
+      log('error', 'opencode bridge post failed', { threadId, status: r.status });
+    }
+    return !!r.ok;
+  } catch (e) {
+    log('error', 'opencode bridge post threw', {
+      threadId,
+      error: e && e.message ? e.message : String(e),
+    });
+    return false;
+  }
+};
+
+const driveTurn = async ({ threadId, projectDir, resumeId, payload, log }) => {
+  const isFirst = !resumeId;
+  log('info', isFirst ? 'opencode first-touch spawn' : 'opencode resume', {
+    threadId,
+    projectDir,
+    resumeId: resumeId || undefined,
+    provider: DEFAULT_PROVIDER,
+    model: DEFAULT_MODEL,
+    messageId: payload.messageId,
+  });
+
+  const startedAt = Date.now();
+  let sessionId = resumeId || null;
+  let finalResponse = '';
+  let failure = null;
+
+  try {
+    const res = await runOpencode({
+      prompt: buildOpencodePrompt(payload, isFirst),
+      projectDir,
+      resumeId,
+    });
+    sessionId = res.sessionId || sessionId;
+    finalResponse = res.finalResponse;
+  } catch (e) {
+    failure = e && e.message ? e.message : String(e);
+  }
+
+  // Capture model — the driver delivers opencode's output.
+  if (failure) {
+    await postToBridge({ threadId, kind: 'error', body: 'Opencode run failed: ' + failure, log });
+  } else if (finalResponse) {
+    await postToBridge({ threadId, kind: 'result', body: finalResponse, log });
+  } else {
+    await postToBridge({
+      threadId,
+      kind: 'error',
+      body: 'Opencode completed the turn but produced no final response.',
+      log,
+    });
+  }
+
+  log('info', isFirst ? 'opencode first-touch done' : 'opencode resume done', {
+    threadId,
+    sessionId,
+    ok: !failure && !!finalResponse,
+    assistantTextChars: finalResponse.length,
+    durationMs: Date.now() - startedAt,
+  });
+
+  if (failure && !sessionId) {
+    throw new Error('opencode run failed before a session id was assigned: ' + failure);
+  }
+
+  // jsonlPath/lastJsonlMtimeMs are Claude-specific — null keeps the binding
+  // shape consistent for daemon.js / state.js.
+  return {
+    sessionId,
+    projectDir,
+    jsonlPath: null,
+    lastJsonlMtimeMs: null,
+    stopReason: failure ? 'error' : 'done',
+    assistantTextChars: finalResponse.length,
+  };
+};
+
+const drive = (params) => {
+  const key = params.threadId;
+  const prev = queues.get(key) || Promise.resolve();
+  const next = prev
+    .then(() => {
+      const binding = params.binding;
+      const resuming = binding && binding.sessionId;
+      return driveTurn({
+        threadId: params.threadId,
+        projectDir: resuming ? binding.projectDir : params.projectDir,
+        resumeId: resuming ? binding.sessionId : null,
+        payload: params.payload,
+        log: params.log,
+      });
+    })
+    .catch((err) => {
+      params.log('error', 'opencode drive failed', {
+        threadId: params.threadId,
+        error: err && err.message ? err.message : String(err),
+      });
+      throw err;
+    });
+  queues.set(key, next);
+  return next;
+};
+
+// Opencode has no per-tool permission callback exposed by the SDK — there is
+// nothing to relay, same shape as the Codex driver.
+const tryResolvePermission = () => false;
+
+module.exports = { drive, tryResolvePermission };

package/src/state.js

@@ -13,18 +13,48 @@ const ensureDir = () => {
   } catch (_) {}
 };
 
-// Schema:
+// Schema (v1.1 — per-agent sessions):
 // {
 //   "bindings": {
 //     "<threadId>": {
-//       "sessionId": "<uuid>",
-//       "projectDir": "/abs/path",
-//       "jsonlPath": "/.../<sid>.jsonl",
 //       "createdAt": "iso-ts",
-//       "lastDriveAt": "iso-ts"
+//       "agentId": "<machine id>",
+//       "sessions": {
+//         "claude": { "sessionId", "projectDir", "jsonlPath", "lastJsonlMtimeMs", "lastDriveAt" },
+//         "codex":  { "sessionId", "projectDir", "lastDriveAt" }
+//       }
 //     }, ...
 //   }
 // }
+// A thread keeps one session PER agent, so switching claude<->codex and back
+// resumes each engine's own context. v1 flat bindings are migrated on load.
+
+// Migrate a v1 flat binding ({ sessionId, projectDir, ... }) into the v1.1
+// per-agent shape. The flat session is filed under 'claude' — the v1 default
+// agent. A v1 codex daemon's threads simply first-touch codex fresh after the
+// upgrade, which is acceptable (a switch is a fresh first-touch anyway).
+const migrateBinding = (b) => {
+  if (!b || typeof b !== 'object') {
+    return { createdAt: null, agentId: null, sessions: {} };
+  }
+  if (b.sessions && typeof b.sessions === 'object') return b; // already v1.1
+  const out = {
+    createdAt: b.createdAt || null,
+    agentId: b.agentId || null,
+    sessions: {},
+  };
+  if (b.sessionId) {
+    out.sessions.claude = {
+      sessionId: b.sessionId,
+      projectDir: b.projectDir,
+      jsonlPath: b.jsonlPath,
+      lastJsonlMtimeMs: b.lastJsonlMtimeMs || null,
+      lastDriveAt: b.lastDriveAt || null,
+    };
+  }
+  return out;
+};
+
 const loadState = () => {
   let raw;
   try {
@@ -35,6 +65,10 @@ const loadState = () => {
   if (!raw.bindings || typeof raw.bindings !== 'object') {
     raw.bindings = {};
   }
+  // Migrate any v1 flat bindings to the per-agent shape.
+  for (const tid of Object.keys(raw.bindings)) {
+    raw.bindings[tid] = migrateBinding(raw.bindings[tid]);
+  }
   return raw;
 };
 
@@ -43,12 +77,33 @@ const saveState = (state) => {
   fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), 'utf8');
 };
 
+// The full per-thread binding ({ createdAt, agentId, sessions }), or null.
 const getBinding = (state, threadId) =>
   state.bindings && state.bindings[threadId] ? state.bindings[threadId] : null;
 
-const setBinding = (state, threadId, info) => {
-  state.bindings[threadId] = info;
+// One agent's session record on a thread, or null. The driver consumes this
+// flat shape directly — same contract as the v1 binding.
+const getAgentSession = (state, threadId, agent) => {
+  const b = getBinding(state, threadId);
+  if (!b || !b.sessions) return null;
+  return b.sessions[agent] || null;
+};
+
+// Store/replace one agent's session on a thread. Creates the binding if absent.
+const setAgentSession = (state, threadId, agent, session, meta) => {
+  let b = state.bindings[threadId];
+  if (!b || !b.sessions) {
+    b = {
+      createdAt: new Date().toISOString(),
+      agentId: (meta && meta.agentId) || null,
+      sessions: {},
+    };
+    state.bindings[threadId] = b;
+  }
+  if (meta && meta.agentId) b.agentId = meta.agentId;
+  b.sessions[agent] = session;
   saveState(state);
+  return b;
 };
 
 module.exports = {
@@ -57,5 +112,6 @@ module.exports = {
   loadState,
   saveState,
   getBinding,
-  setBinding,
+  getAgentSession,
+  setAgentSession,
 };