@volter/supercode-orchestrator 0.5.64 → 0.5.66

package/adapters/jira-comments.mjs

@@ -0,0 +1,157 @@
+// A Jira site's ticket comments as a channel (company RFC 0026 decision 3): the client's comments on the tickets a JQL
+// finds reach an agent's mailbox through `AgentMailboxBridge`, and the agent's answers are posted back as comments on
+// the same ticket. The three-method trait every adapter has: `connect(emit)` / `send(target, content)` / `close()`.
+//
+// A ticket is a thread. Its root is the first comment this adapter saw on it; every later comment on that ticket replies
+// to it, so a ticket's conversation is one mailbox thread. Comments are paged past the page a search embeds (a long
+// thread is never cut). What was on a ticket before the first connect is the baseline and is not filed; what the
+// credential's own account posts (the agent's answers) is `is_me`. A ticket that comes into the JQL's scope later is
+// baselined the same way when it is first seen. Seen comments and roots are kept in `statePath`.
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const DEFAULT_POLL_MS = 60_000;
+
+/** ADF (Jira's rich text) to plain text: paragraphs and line breaks kept, marks dropped. */
+export function adfText(node) {
+  if (node == null) return '';
+  if (typeof node === 'string') return node;
+  if (Array.isArray(node)) return node.map(adfText).join('');
+  if (node.type === 'text') return String(node.text ?? '');
+  if (node.type === 'hardBreak') return '\n';
+  if (node.type === 'mention') return String(node.attrs?.text ?? '@someone');
+  const inner = adfText(node.content ?? []);
+  return ['paragraph', 'heading', 'listItem', 'codeBlock', 'blockquote'].includes(node.type) ? `${inner}\n` : inner;
+}
+
+/** Plain text to ADF: one paragraph per line. */
+export function textAdf(text) {
+  return { type: 'doc', version: 1, content: String(text).split('\n').map((line) => ({ type: 'paragraph', content: line ? [{ type: 'text', text: line }] : [] })) };
+}
+
+export class JiraCommentsAdapter {
+  /**
+   * @param {object} o
+   * @param {string} o.site      the site (`https://<site>.atlassian.net`, or a Jira twin's URL)
+   * @param {string} o.jql       which tickets are this channel's
+   * @param {string} o.authorization  the request's Authorization header (Basic email:token, or Bearer)
+   */
+  constructor({ site, jql, authorization, statePath = null, pollMs = DEFAULT_POLL_MS, fetchImpl = fetch, log = () => {}, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+    if (!site || !jql || !authorization) throw new Error('JiraCommentsAdapter needs a site, a JQL and an authorization');
+    this.platform = 'jira';
+    this.site = site.replace(/\/+$/, '');
+    this.jql = jql;
+    this.authorization = authorization;
+    this.statePath = statePath;
+    this.pollMs = pollMs;
+    this.fetch = fetchImpl;
+    this.log = log;
+    this.sleep = sleep;
+    this.running = false;
+    /** ticket key -> { root: comment id | null, seen: comment ids } */
+    this.tickets = {};
+    this.baselined = false;
+    this.me = null;
+    if (statePath) {
+      try {
+        const state = JSON.parse(readFileSync(statePath, 'utf8'));
+        this.tickets = state.tickets ?? {};
+        this.baselined = state.baselined === true;
+      } catch { /* a first run */ }
+    }
+  }
+
+  save() {
+    if (!this.statePath) return;
+    mkdirSync(dirname(this.statePath), { recursive: true });
+    const tmp = `${this.statePath}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ baselined: this.baselined, tickets: this.tickets }));
+    renameSync(tmp, this.statePath);
+  }
+
+  async call(method, path, body) {
+    const res = await this.fetch(`${this.site}${path}`, {
+      method, headers: { authorization: this.authorization, accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await res.text();
+    if (res.status >= 300) throw new Error(`jira: ${method} ${path.split('?')[0]} answered ${res.status}${text ? ` — ${text.slice(0, 200)}` : ''}`);
+    return text ? JSON.parse(text) : {};
+  }
+
+  /** Every comment of a ticket, in order, paged past the page a search embeds. */
+  async comments(key) {
+    const all = [];
+    for (let startAt = 0; ; ) {
+      const page = await this.call('GET', `/rest/api/3/issue/${encodeURIComponent(key)}/comment?startAt=${startAt}&maxResults=100&orderBy=created`);
+      const rows = page.comments ?? [];
+      all.push(...rows);
+      startAt += rows.length;
+      if (rows.length === 0 || startAt >= (page.total ?? 0)) return all;
+    }
+  }
+
+  /** The tickets the JQL finds now. */
+  async keys() {
+    const keys = [];
+    for (let token; ; ) {
+      const params = new URLSearchParams({ jql: this.jql, fields: 'summary', maxResults: '100', ...(token ? { nextPageToken: token } : {}) });
+      const page = await this.call('GET', `/rest/api/3/search/jql?${params}`);
+      keys.push(...(page.issues ?? []).map((issue) => String(issue.key)));
+      if (!page.nextPageToken || (page.issues ?? []).length === 0) return keys;
+      token = page.nextPageToken;
+    }
+  }
+
+  async poll() {
+    for (const key of await this.keys()) {
+      // A ticket new to this channel (the first poll, or one that comes into the JQL's scope later) is its own baseline:
+      // what was on it before is not filed, only what is posted after.
+      const fresh = !this.tickets[key];
+      const ticket = (this.tickets[key] ??= { root: null, seen: [] });
+      const seen = new Set(ticket.seen);
+      for (const c of await this.comments(key)) {
+        const id = String(c.id ?? '');
+        if (!id || seen.has(id)) continue;
+        seen.add(id);
+        if (!this.baselined || fresh) continue;
+        const mine = this.me !== null && c.author?.accountId === this.me;
+        const root = ticket.root;
+        if (root === null && !mine) ticket.root = id;
+        this.emit?.({
+          key: { platform: 'jira', chat_id: key, thread_id: root ?? undefined, kind: 'group' },
+          sender: c.author?.accountId ?? null, sender_name: c.author?.displayName ?? null, is_me: mine, is_bot: false,
+          message_id: id, at: c.created ?? null, text: adfText(c.body).trim(),
+        });
+      }
+      ticket.seen = [...seen];
+    }
+    this.baselined = true;
+    this.save();
+  }
+
+  async connect(emit) {
+    this.emit = emit;
+    this.me = (await this.call('GET', '/rest/api/3/myself')).accountId ?? null;
+    this.running = true;
+    await this.poll().catch((error) => this.log('warn', `jira: ${error.message}`));
+    this.loop = (async () => {
+      while (this.running) {
+        await this.sleep(this.pollMs);
+        if (!this.running) break;
+        await this.poll().catch((error) => this.log('warn', `jira: ${error.message}`));
+      }
+    })();
+  }
+
+  /** An answer, posted as a comment on the ticket its thread is about. */
+  async send(target, content) {
+    const key = String(target.chat_id);
+    const posted = await this.call('POST', `/rest/api/3/issue/${encodeURIComponent(key)}/comment`, { body: textAdf(content.text ?? '') });
+    const id = String(posted.id ?? '');
+    if (id) { const ticket = (this.tickets[key] ??= { root: null, seen: [] }); ticket.seen.push(id); this.save(); }
+    return { message_id: id || null };
+  }
+
+  async close() { this.running = false; await this.loop; }
+}

package/bin/agent-channel.mjs

@@ -1,5 +1,12 @@
 // `supercode-orchestrator agent-channel --agent <name>`: an agent's account Room, carried to its one mailbox
-// (docs/adr/0008-agent-mailbox.md, decisions 24-25). The Room sits on the organization's floor (the RH2 bot's
+// (docs/adr/0008-agent-mailbox.md, decisions 24-25). With `--platform slack` or `--platform jira` it carries another
+// channel to that mailbox instead, through the same bridge (company RFC 0026 decision 3: an engagement's Slack channel
+// and its client's ticket comments are channels of its account manager):
+//   --platform slack --slack-channel <id>[,<id>]   the Chat SDK's Slack (Socket Mode), SLACK_BOT_TOKEN and SLACK_APP_TOKEN
+//                                                   from the environment; only the named channels' lines are filed
+//   --platform jira --site <url> --jql <jql>        the tickets' comments (adapters/jira-comments.mjs), JIRA_EMAIL and
+//                                                   JIRA_API_TOKEN (or JIRA_TOKEN) from the environment
+// The RH2 account Room: the Room sits on the organization's floor (the RH2 bot's
 // organization), with the agent as its one participant: every line a person posts there is filed as mail to the agent,
 // and every answer is posted back anchored at its thread's root, by `AgentMailboxBridge` over the RH2 adapter.
 //
@@ -24,17 +31,50 @@ import { join } from 'node:path';
 import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
 import { Rh2Adapter } from '../adapters/rh2.mjs';
 import { AgentMailboxBridge } from '../adapters/agent-mailbox.mjs';
+import { JiraCommentsAdapter } from '../adapters/jira-comments.mjs';
+import { ChatSdkAdapter } from '../adapters/chat-sdk.mjs';
 import { installedApps } from '../installed-apps.mjs';
 
 const { values } = parseArgs({
   args: process.argv.slice(3),
-  options: { agent: { type: 'string' }, root: { type: 'string' }, room: { type: 'string' }, 'room-key': { type: 'string' }, 'room-name': { type: 'string' }, principal: { type: 'string' }, state: { type: 'string' }, help: { type: 'boolean' } },
+  options: { agent: { type: 'string' }, root: { type: 'string' }, room: { type: 'string' }, 'room-key': { type: 'string' }, 'room-name': { type: 'string' }, principal: { type: 'string' }, state: { type: 'string' }, platform: { type: 'string' }, site: { type: 'string' }, jql: { type: 'string' }, 'slack-channel': { type: 'string' }, help: { type: 'boolean' } },
 });
 if (values.help || !values.agent) {
-  console.log('supercode-orchestrator agent-channel --agent <name> [--root <home>] [--room <id> | --room-key <key> --principal <rh2 principal id> [--room-name <name>]] [--state <file>]');
+  console.log('supercode-orchestrator agent-channel --agent <name> [--root <home>] [--room <id> | --room-key <key> --principal <rh2 principal id> [--room-name <name>]] [--state <file>]\n       supercode-orchestrator agent-channel --agent <name> --platform slack --slack-channel <id>[,<id>] [--state <file>]\n       supercode-orchestrator agent-channel --agent <name> --platform jira --site <url> --jql <jql> [--state <file>]');
   process.exit(values.help ? 0 : 2);
 }
 const log = (level, line) => (level === 'debug' ? undefined : console.error(`${new Date().toISOString()} ${level} ${line}`));
+if (values.platform && values.platform !== 'rh2') {
+  const statePath = (name) => values.state ?? join(homedir(), '.config', 'supercode', 'agent-channels', `${values.agent}.${name}.json`);
+  let adapter;
+  if (values.platform === 'jira') {
+    if (!values.site || !values.jql) { console.error('agent-channel: --platform jira needs --site and --jql'); process.exit(2); }
+    const authorization = process.env.JIRA_EMAIL && process.env.JIRA_API_TOKEN
+      ? `Basic ${Buffer.from(`${process.env.JIRA_EMAIL}:${process.env.JIRA_API_TOKEN}`).toString('base64')}`
+      : process.env.JIRA_TOKEN ? `Bearer ${process.env.JIRA_TOKEN}` : null;
+    if (!authorization) { console.error('agent-channel: --platform jira needs JIRA_EMAIL and JIRA_API_TOKEN (or JIRA_TOKEN) in its environment'); process.exit(2); }
+    adapter = new JiraCommentsAdapter({ site: values.site, jql: values.jql, authorization, statePath: `${statePath('jira')}.comments`, log });
+  } else if (values.platform === 'slack') {
+    const channels = new Set(String(values['slack-channel'] ?? '').split(',').map((c) => c.trim()).filter(Boolean));
+    if (!channels.size) { console.error('agent-channel: --platform slack needs --slack-channel <id>: an agent is carried only the channels named'); process.exit(2); }
+    if (!process.env.SLACK_BOT_TOKEN || !process.env.SLACK_APP_TOKEN) { console.error('agent-channel: --platform slack needs SLACK_BOT_TOKEN and SLACK_APP_TOKEN in its environment'); process.exit(2); }
+    // The Slack SDK adapter is built here, in Socket Mode, from this process's own environment: the wrapper's own path
+    // reads a profile's .env, and a channel process has no profile folder. SLACK_API_URL (a twin's) is honoured.
+    let createSlackAdapter;
+    try { ({ createSlackAdapter } = await import('@chat-adapter/slack')); } catch (error) { console.error(`agent-channel: @chat-adapter/slack is not installed (${error.message})`); process.exit(2); }
+    const sdkAdapter = createSlackAdapter({ botToken: process.env.SLACK_BOT_TOKEN, appToken: process.env.SLACK_APP_TOKEN, mode: 'socket', ...(process.env.SLACK_API_URL ? { apiUrl: process.env.SLACK_API_URL } : {}) });
+    const slack = new ChatSdkAdapter({ platform: 'slack', profile: values.agent, channel: { enabled: true, extra: {} }, sdkAdapter, log });
+    // Only the named channels' lines reach the mailbox; answers go back through the same adapter.
+    adapter = { platform: 'slack', connect: (emit) => slack.connect((event) => { if (channels.has(String(event.key?.chat_id))) emit(event); }), send: (target, content) => slack.send(target, content), close: () => slack.close?.() };
+  } else { console.error(`agent-channel: --platform is rh2, slack or jira (got ${values.platform})`); process.exit(2); }
+  const client = new SupercodeHarnessClient(process.env.SUPERCODE_BIN ? { command: process.env.SUPERCODE_BIN } : {});
+  const bridge = new AgentMailboxBridge({ adapter, client, agent: values.agent, platform: values.platform, fromName: `${values.platform}-${values.agent}`, log, statePath: statePath(values.platform) });
+  await bridge.start();
+  log('info', `${values.agent}: ${values.platform} is carried to its mailbox`);
+  const stop = async () => { await bridge.stop(); await adapter.close?.(); await client.close?.(); process.exit(0); };
+  process.on('SIGTERM', stop);
+  process.on('SIGINT', stop);
+} else {
 const root = values.root ?? process.env.HERMES_HOME;
 const apps = root ? installedApps(root).filter((app) => app.profile === values.agent) : [];
 const installation = apps.find((app) => app.app === 'rh2-agent') ?? apps.find((app) => app.app === 'room-chat');
@@ -114,3 +154,4 @@ const rebinding = setInterval(() => { void bindDm().catch((error) => log('warn',
 const stop = async () => { clearInterval(rebinding); await bridge.stop(); await client.close?.(); process.exit(0); };
 process.on('SIGTERM', stop);
 process.on('SIGINT', stop);
+}

package/board/dispatch.mjs

@@ -850,6 +850,42 @@ export async function startCard(board, id, { roles = ['manager'], lanes, setting
 
 /** Reconcile durable close intent and ended runs, including old unverified closed_at records.
  * Reads and process I/O stay outside the writer. An active successor owns its pane until it ends. */
+/** Why the close of an ended run's live session waits, or null when nothing would be cut. Read last, just before the
+ *  kill and outside any write: a pane's by the harness session under its process (whatever session it is: an id the run
+ *  never learned, a harness its record does not name), a session in no pane by its own id. Only a session read idle, or
+ *  stopped, or no harness session in the pane at all, is closed; working, waiting on input, a turn the harness does not
+ *  publish (unknown) and a reading that fails all wait a round. The card's move never does. */
+// The programs a harness pane runs in its foreground: Claude Code's, Codex's, and node (the daemon's Codex pane host,
+// a harness installed through npm). A pane running one of these runs a harness session, read or not.
+const HARNESS_COMMANDS = new Set(['claude', 'claude.exe', 'codex', 'codex.exe', 'node']);
+function turnAtClose(session, pane = null) {
+  const machine = session.machine ?? localMachine();
+  let activity;
+  if (pane?.pid) {
+    const r = doorOn(machine, 'harness.v1.sessions.activity_under', { pids: [pane.pid] }, { timeout: NATIVE_DISCOVERY_MS });
+    const page = r.code === 0 ? lastJson(r.stdout) : null;
+    if (!Array.isArray(page?.activities)) return `the session in pane ${session.pane} could not be read just now (${(r.stderr || r.stdout).trim().slice(-160)})`;
+    activity = page.activities.find((item) => item.pid === pane.pid)?.activity ?? null;
+    // No session read under the pane is no absence (a registry it could not read, another config home, a failed process
+    // read): the pane's own foreground program says whether a harness runs there. Only a pane running none is closed.
+    if (!activity) {
+      const command = String(pane.command ?? '').split(/[\\/]/).pop().toLowerCase();
+      return command && !HARNESS_COMMANDS.has(command) ? null : `pane ${session.pane} runs ${command || 'a program it does not name'}, whose session could not be read`;
+    }
+  } else if (pane) {
+    return `pane ${session.pane} names no process to read`;
+  } else {
+    if (!session.session_id) return 'its session is not known yet';
+    try { activity = nativeReading(discoverNative(machine, session.harness ?? 'claude-code', session.session_id), session).row?.activity ?? null; }
+    catch (error) { return `its session could not be read just now (${String(error.message).slice(0, 160)})`; }
+    if (!activity) return `its session ${addressOf(session)} is not in its machine's discovery`;
+  }
+  if (activity.presence && activity.presence !== 'running') return null;
+  if (activity.turn === 'idle') return null;
+  const who = activity.session_id ? `sc:${normalMachine(machine)}:${activity.harness ?? session.harness}:${activity.session_id}` : addressOf(session);
+  return `its session ${who} is in a turn (${activity.turn ?? 'unknown'}); it closes once the turn ends`;
+}
+
 export function closeRequested(board, report, { taskId = null, caller = null, ttl = null, fleet = null } = {}) {
   const rows = view(board, (db) => db.prepare(`SELECT id, task_id, ended_at, metadata FROM task_runs
     WHERE metadata IS NOT NULL ${taskId ? 'AND task_id = ?' : ''}`).all(...(taskId ? [taskId] : [])));
@@ -941,13 +977,14 @@ export function closeRequested(board, report, { taskId = null, caller = null, tt
         if (reading.alive) {
           const protectedNow = active.some(r => addressOf(json(r.metadata, {})?.supercode) === addressOf(session));
           if (protectedNow) throw new Error('close deferred: native session is owned by an unended run');
+          if (row.ended_at) { const inTurn = turnAtClose(session); if (inTurn) throw new Error(`close deferred: ${inTurn}`); }
           stopSession(board, session);
         }
       } else {
       if (!panes.has(machine)) {
         const r = doorOn(machine, 'harness.v1.panes.list',{}, { timeout: 60_000, as: boardAddress(board.label) });
         const list = r.code === 0 ? json(r.stdout.trim(), null) : null;
-        panes.set(machine, Array.isArray(list) ? { live: new Set(list.filter(p => !p.dead).map((p) => p.pane)) } : { error: `cannot read panes on ${machine}: ${(r.stderr || r.stdout).trim().slice(-300)}` });
+        panes.set(machine, Array.isArray(list) ? { live: new Map(list.filter(p => !p.dead).map((p) => [p.pane, { pid: p.pid ?? null, command: p.activeCommand ?? null }])) } : { error: `cannot read panes on ${machine}: ${(r.stderr || r.stdout).trim().slice(-300)}` });
       }
       const observed = panes.get(machine);
       if (observed.error) throw new Error(`close deferred: ${observed.error}`); // an unread pane list is no verdict on the pane
@@ -955,6 +992,9 @@ export function closeRequested(board, report, { taskId = null, caller = null, tt
         const protectedNow = view(board, (db) => db.prepare(`SELECT metadata FROM task_runs r WHERE r.ended_at IS NULL OR EXISTS (SELECT 1 FROM tasks t WHERE t.current_run_id = r.id)`).all())
           .some((r) => { const s = json(r.metadata, {})?.supercode; return s?.pane === session.pane && normalMachine(s.machine) === normalMachine(session.machine); });
         if (protectedNow) throw new Error(`close deferred: pane ${session.pane} is owned by an unended run`);
+        // An ended run's session is closed only between its turns, read last, after the claim and the pane list (a pane
+        // already gone is settled above with no reading; t_f34710bc's coder was cut mid-proof at 15:01:13Z, 2026-10-04).
+        if (row.ended_at) { const inTurn = turnAtClose(session, observed.live.get(session.pane)); if (inTurn) throw new Error(`close deferred: ${inTurn}`); }
         stopSession(board, session); observed.live.delete(session.pane);
       }
       }
@@ -2426,7 +2466,8 @@ function turnInFlight(board, id, fleet) {
   if (!session?.session_id || session.surface === 'headless' || session.close_requested) return null;
   let turn = fleet.sessions?.find((x) => x.address === addressOf(session))?.turn ?? null;
   if (turn == null && session.surface === 'native') try { turn = nativeReading(nativeSessions(session.machine, session.harness ?? 'claude-code', session.session_id), session).row?.activity?.turn ?? null; } catch { /* unread: waits on nothing */ }
-  return turn === 'working' ? `its session ${addressOf(session)} is in a turn; the review is requested once the turn ends` : null;
+  // a turn stopped on a permission or a question (needs_input) is a turn not finished, as one still working is
+  return ['working', 'needs_input'].includes(turn) ? `its session ${addressOf(session)} is in a turn (${turn}); the review is requested once the turn ends` : null;
 }
 
 async function activatePullRequestReviews(board, entry, report, effects, { only = null, dry = false, fleet = null } = {}) {

package/index.mjs

@@ -23,6 +23,7 @@ export { ChatSdkAdapter, toInbound, toAttachment, chatType, CHAT_SDK_VERSION, CH
 export { ApiServerAdapter, DEFAULT_HOST as API_SERVER_HOST, DEFAULT_PORT as API_SERVER_PORT } from './adapters/api-server.mjs';
 export { Rh2Adapter } from './adapters/rh2.mjs';
 export { AgentMailboxBridge } from './adapters/agent-mailbox.mjs';
+export { JiraCommentsAdapter, adfText, textAdf } from './adapters/jira-comments.mjs';
 export { TOOLS, TOOL_NAMES, SERVER_NAME, PROTOCOL_VERSION } from './mcp/tools.mjs';
 export { mountOrchestratorMcp, doorFor, MCP_DOORS, SERVER_PATH } from './mcp/mount.mjs';
 export { startBridge } from './mcp/bridge.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.64",
+  "version": "0.5.66",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@volter/supercode-harness-sdk": "^0.3.60",
-    "@volter/teams": "0.2.19",
+    "@volter/teams": "0.2.20",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },