@volter/supercode-teams 0.3.96 → 0.3.97

package/live-sessions.mjs

@@ -14,7 +14,7 @@
 // - Messaging tools: the marker a `message mcp` server writes for its session process, with the server alive.
 import { EventEmitter } from 'node:events';
 import { execFile } from 'node:child_process';
-import { mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, watch, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, unlinkSync, watch, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { FrontendClient } from '@volter/supercode-frontend';
@@ -53,6 +53,15 @@ function linuxStart(pid) {
   } catch { return null; }
 }
 
+/** The parent of the live process `pid` (Linux's /proc, or one `ps` on macOS), or null when it cannot be read. */
+function parentOf(pid) {
+  if (process.platform === 'linux') {
+    try { const stat = readFileSync(`/proc/${pid}/stat`, 'utf8'); return Promise.resolve(Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1]) || null); } catch { return Promise.resolve(null); }
+  }
+  if (process.platform !== 'darwin') return Promise.resolve(null);
+  return new Promise((resolve) => execFile('ps', ['-o', 'ppid=', '-p', String(pid)], { timeout: 10_000 }, (error, stdout) => resolve(error ? null : Number(String(stdout).trim()) || null)));
+}
+
 /** `path` with its symlinks resolved, or null when it cannot be (gone, or not a string). */
 function realPath(path) { try { return typeof path === 'string' ? realpathSync(path) : null; } catch { return null; } }
 
@@ -210,7 +219,12 @@ export class LiveSessions extends EventEmitter {
   }
 
   /** A Claude process's entry let go, with what was read of its process's start (a new process may take its pid). */
-  #dropClaude(pid) { this.claude.delete(pid); }
+  #dropClaude(pid) {
+    this.claude.delete(pid);
+    // its messaging tools' marker goes with it when it has ended (step 4a: by its end, never a minute's sweep); an entry
+    // dropped for another reason (its home no longer declared, a parked process) keeps its marker for its return
+    if (this.markers.has(pid) && !alive(pid)) { this.markers.delete(pid); try { unlinkSync(join(this.markersDir, String(pid))); } catch { /* gone */ } }
+  }
 
   /** Every held process asked whether it is alive (signal 0): a dead one's entry goes. */
   #sweepDead() {
@@ -365,9 +379,21 @@ export class LiveSessions extends EventEmitter {
     if (!Number.isInteger(pid)) return;
     let server = null;
     try { server = Number(readFileSync(join(this.markersDir, name), 'utf8').trim()); } catch { /* removed */ }
-    if (Number.isInteger(server) && server > 0) this.markers.set(pid, server); else this.markers.delete(pid);
+    // a marker whose server has ended names no tools: removed (read at start, and as each is written or changed)
+    if (Number.isInteger(server) && server > 0 && !alive(server)) { try { unlinkSync(join(this.markersDir, name)); } catch { /* gone */ } server = null; }
+    if (!(Number.isInteger(server) && server > 0)) { if (this.markers.delete(pid)) this.#changed(); return; }
+    this.markers.set(pid, server);
+    // its server is the session's own child (a harness starts its MCP servers so), checked once per marker: a server pid
+    // used again by another process names no tools (mail_route.rs `has_message_tools` read it so)
+    void parentOf(server).then((parent) => {
+      if (parent == null || parent === pid || this.markers.get(pid) !== server) return;
+      this.markers.delete(pid);
+      try { unlinkSync(join(this.markersDir, name)); } catch { /* gone */ }
+      this.#changed();
+    });
   }
 
+
   #readUserHook() {
     let text = '';
     try { text = readFileSync(this.codexHooks, 'utf8'); } catch { /* none */ }

package/machine.mjs

@@ -39,6 +39,7 @@ import { MailReads, panePrompt } from './mail/reads.mjs';
 import { render } from './mail/envelope.mjs';
 import { Agents } from './mail/agents.mjs';
 import { Relays } from './mail/relay.mjs';
+import { serveRelayEndpoint } from './mail/relay-endpoint.mjs';
 import { MailSend } from './mail/send.mjs';
 import { AgentVerbs } from './mail/verbs.mjs';
 import { deliverToRuntime } from './mail/runtime.mjs';
@@ -653,6 +654,9 @@ export class TeamsMachine extends MachineCore {
   // ---- this machine's mail (mail/; docs/architecture/overview.md, "The mail operations") ---------------------------
   #startMail() {
     const mailRoot = join(supercodeHome(this.env), 'mail');
+    // the Messages API a Claude relay talks to (step 4a: the daemon's, in process; the native watch served it)
+    this.relayEndpoint = serveRelayEndpoint(mailRoot, { log: (line) => this.emit('mail-log', line) })
+      .catch((error) => { this.emit('mail-log', `relay endpoint: not served (${error.message}); a Claude session cannot be sent mail until the daemon starts again`); return null; });
     this.mailStore = new MailStore({ mailRoot, machine: machineName(this.env), log: (line) => this.emit('records-log', line) }).start();
     // the session index's rows by address (its descriptors, as the records' index subscription hands them over)
     this.sessionDescriptors = new Map();
@@ -678,6 +682,7 @@ export class TeamsMachine extends MachineCore {
     this.relays = new Relays({ mailRoot, machine, supercodeBin: this.supercodeBin, serve: (method, params, timeoutMs) => this.#serveRequest(method, params, timeoutMs),
       runtimeOf: (harness, id) => live.runtimeReceipt(harness, id), runtimeNamed: (receiptId) => live.receiptNamed(receiptId),
       runtimesIn: (harness, cwd) => live.runtimesIn(harness, cwd),
+      endpointOf: async () => (await this.relayEndpoint)?.url ?? null,
       log: (line) => this.emit('mail-log', line) });
     this.mailSend = new MailSend({ machine, mailRoot, live, store: this.mailStore, agents: this.agents, relays: this.relays,
       // a send waits on its receiver's door there (a relay's receipt takes up to 90 s), never past MAIL_SEND_MS
@@ -700,6 +705,21 @@ export class TeamsMachine extends MachineCore {
     // the names sessions ran under (`<mail>/names.json`): a name an agent was given reaches the same session after it
     // runs under another, kept from the map's changes (at most once a second)
     let naming = null;
+    // a session that has ended has its relay retired (step 4a: by its end, never a minute's sweep); the relays of
+    // sessions that ended while no daemon ran are retired once, at start, when the live sessions are known
+    let wasLive = new Map(live.sessions().map((row) => [row.address, row.name]));
+    live.on('changed', () => {
+      // while the Codex sessions are not known (a start, a serve restart) a Codex session missing has not ended: the last
+      // known view stands until they are known again
+      if (!live.codexKnown) return;
+      const now = new Map(live.sessions().map((row) => [row.address, row.name]));
+      for (const [address, name] of wasLive) if (!now.has(address)) void this.relays.retire(address, name).catch(() => {});
+      wasLive = now;
+    });
+    void live.whenCodexKnown(120_000).then((known) => {
+      if (!known) { this.emit('mail-log', 'relays: the live sessions were not known within two minutes of start; relays of ended sessions are retired at their next end'); return; }
+      return this.relays.sweepAtStart((address) => live.sessions().some((row) => row.address === address));
+    }).catch((error) => this.emit('mail-log', `relays: the start sweep failed: ${error.message}`));
     live.on('changed', () => {
       if (naming) return;
       naming = setTimeout(() => { naming = null; try { this.mailSend.rememberNames(live.sessions()); } catch { /* kept at the next change */ } }, 1000);
@@ -999,6 +1019,7 @@ export class TeamsMachine extends MachineCore {
     this.jobs?.stopAll();
     this.stoppingMailWatch = true;
     this.mailWatch?.kill('SIGTERM');
+    void this.relayEndpoint?.then((endpoint) => endpoint?.close()).catch(() => {});
     this.stoppingServe = true;
     clearTimeout(this.serveRestart);
     // said, so a stop reads as one in the log and never as a serve that broke

package/mail/relay-endpoint.mjs

@@ -0,0 +1,120 @@
+// The Messages API a Claude relay talks to: deterministic, no model (docs/architecture/overview.md, step 4a; the native
+// watch served it before, and its answers are kept byte for byte).
+//
+// A relay (relay.mjs) is a real Claude Code process, because only a live Claude peer's `SendMessage` gets a Claude
+// session's reply back. What it asks its model is always the same: send the queued message. So a relay's
+// `ANTHROPIC_BASE_URL` points here, and this endpoint answers as the model would, from the relay's own queue:
+// - a send turn gets one `SendMessage` tool call carrying the queued `to` and `message`, byte for byte;
+// - the turn after a tool result, or with nothing queued, gets RELAY_STATUS_LINE and ends.
+// No model runs and nothing is billed. The gate hook still checks every tool call against the queue, and the receipt is
+// still Claude's own `SendMessage` result. A relay's API key names its folder under `<mail root>/relays/`. The machine
+// daemon serves it on loopback, on the port recorded in `<mail root>/relay-endpoint.json` (a restarted daemon binds the
+// same port again).
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The text every relay turn ends with. Claude quotes a session's last line in its idle notices, so this is where the
+ *  correction reaches the agent. */
+export const RELAY_STATUS_LINE = "relay, not the session's status";
+
+const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
+const newId = () => `m-${randomBytes(12).toString('hex')}`;
+
+/**
+ * Serve the endpoint for `mailRoot`'s relays: answers `{ url, close() }` once it listens. The port the record names is
+ * taken again when it is free, so relays started before a restart keep reaching it.
+ */
+export async function serveRelayEndpoint(mailRoot, { log = () => {} } = {}) {
+  const record = join(mailRoot, 'relay-endpoint.json');
+  const server = createServer((request, response) => {
+    const chunks = [];
+    request.on('data', (chunk) => chunks.push(chunk));
+    request.on('error', () => {});
+    request.on('end', () => {
+      const [status, type, body] = answer(mailRoot, request, Buffer.concat(chunks));
+      response.writeHead(status, { 'content-type': type, 'content-length': Buffer.byteLength(body) });
+      response.end(body);
+    });
+  });
+  server.on('clientError', (_error, socket) => { try { socket.destroy(); } catch { /* gone */ } });
+  const listen = (port) => new Promise((resolve, reject) => {
+    const failed = (error) => { server.off('listening', done); reject(error); };
+    const done = () => { server.off('error', failed); resolve(); };
+    server.once('error', failed); server.once('listening', done);
+    server.listen(port, '127.0.0.1');
+  });
+  const recorded = readJson(record)?.port;
+  try { await listen(Number.isInteger(recorded) ? recorded : 0); }
+  catch (error) {
+    if (!Number.isInteger(recorded)) throw error;
+    log(`relay endpoint: its recorded port ${recorded} is taken (${error.code ?? error.message}); listening on another, so relays started before this daemon start again`);
+    await listen(0);
+  }
+  const port = server.address().port;
+  mkdirSync(mailRoot, { recursive: true });
+  const staging = `${record}.tmp`;
+  writeFileSync(staging, JSON.stringify({ port }));
+  renameSync(staging, record);
+  return { url: `http://127.0.0.1:${port}`, port, close: () => new Promise((resolve) => server.close(() => resolve())) };
+}
+
+/** The relay folder an API key names, when it is one. */
+function relayFolder(mailRoot, request) {
+  const key = request.headers['x-api-key'];
+  if (typeof key !== 'string' || !key || !/^[0-9a-fA-F]+$/.test(key)) return null;
+  const folder = join(mailRoot, 'relays', key);
+  try { return statSync(folder).isDirectory() ? folder : null; } catch { return null; }
+}
+
+/** One request's answer: `[status, content type, body]`. */
+function answer(mailRoot, request, raw) {
+  const error = (status, message) => [status, 'application/json', JSON.stringify({ type: 'error', error: { type: 'invalid_request_error', message } })];
+  if (request.method !== 'POST') return error(404, 'not found');
+  const folder = relayFolder(mailRoot, request);
+  if (!folder) return error(401, 'not a supercode relay');
+  const path = String(request.url ?? '').split('?')[0];
+  if (path.endsWith('/v1/messages/count_tokens')) return [200, 'application/json', JSON.stringify({ input_tokens: 1 })];
+  if (!path.endsWith('/v1/messages')) return error(404, 'not found');
+  let body;
+  try { body = JSON.parse(raw.toString('utf8')); } catch { return error(400, 'unreadable request'); }
+  const queued = readJson(join(folder, 'queue.json'));
+  const content = queued && typeof queued.to === 'string' && typeof queued.message === 'string' && !afterToolResult(body)
+    ? { type: 'tool_use', id: `toolu_${newId()}`, name: 'SendMessage', input: { to: queued.to, message: queued.message } }
+    : { type: 'text', text: RELAY_STATUS_LINE };
+  const model = body?.model ?? null;
+  return body?.stream === true
+    ? [200, 'text/event-stream', stream(model, content)]
+    : [200, 'application/json', JSON.stringify(message(model, content))];
+}
+
+/** Whether the conversation's last turn carries a tool result: the send happened (or was denied), and the turn ends. */
+function afterToolResult(body) {
+  const messages = Array.isArray(body?.messages) ? body.messages : [];
+  const last = messages[messages.length - 1]?.content;
+  return Array.isArray(last) && last.some((block) => block?.type === 'tool_result');
+}
+
+const stopReason = (content) => (content.type === 'tool_use' ? 'tool_use' : 'end_turn');
+
+function message(model, content) {
+  return { id: `msg_${newId()}`, type: 'message', role: 'assistant', model, content: [content], stop_reason: stopReason(content), stop_sequence: null, usage: { input_tokens: 1, output_tokens: 1 } };
+}
+
+/** The same message as the server-sent events a streaming request expects. */
+function stream(model, content) {
+  const start = { ...message(model, content), content: [], stop_reason: null };
+  const [opening, delta] = content.type === 'tool_use'
+    ? [{ ...content, input: {} }, { type: 'input_json_delta', partial_json: JSON.stringify(content.input) }]
+    : [{ type: 'text', text: '' }, { type: 'text_delta', text: content.text }];
+  const events = [
+    ['message_start', { type: 'message_start', message: start }],
+    ['content_block_start', { type: 'content_block_start', index: 0, content_block: opening }],
+    ['content_block_delta', { type: 'content_block_delta', index: 0, delta }],
+    ['content_block_stop', { type: 'content_block_stop', index: 0 }],
+    ['message_delta', { type: 'message_delta', delta: { stop_reason: stopReason(content), stop_sequence: null }, usage: { output_tokens: 1 } }],
+    ['message_stop', { type: 'message_stop' }],
+  ];
+  return events.map(([name, data]) => `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`).join('');
+}

package/mail/relay.mjs

@@ -7,7 +7,7 @@
 // doors, run by the relay's Claude (docs/architecture/overview.md, "Pinned native doors"). Its folder is the native
 // sender's own (`<mail>/relays/<blake3(name)[..24]>/`, its record, settings and send log), so the native `message
 // watch`, which retires relays until step 4, reads what the daemon writes.
-import { mkdirSync, readFileSync, rmSync, watch, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, watch, writeFileSync } from 'node:fs';
 import { connect } from 'node:net';
 import { join } from 'node:path';
 import { blake3Hex } from './envelope.mjs';
@@ -25,6 +25,9 @@ export const MAX_RELAYED_BYTES = 100_000;
 /** How many relays run at once, the most recently used (a relay runtime is some hundreds of MB; 10 held 2.1 GB on one
  *  machine): beyond them a relay's runtime is closed (its folder kept: it starts again when next needed). */
 export const RELAYS_RUNNING = 4;
+/** How long a relay speaking for a sender on another machine is kept after its last send (it carries that sender's
+ *  mail while it is in use; retired after every send, each message from it started a relay). */
+const REMOTE_RELAY_KEPT_MS = 60 * 60_000;
 /** How long a relay whose runtime start lost its answer is looked at for a runtime that start left running. */
 const LOST_START_KEPT_MS = 5 * 60_000;
 
@@ -63,9 +66,10 @@ export class Relays {
    * id)` the live-runtime receipt the live-session map holds for a runtime id (its file read whole), or null;
    * `runtimeNamed(receiptId)` one receipt read by its own name.
    */
-  constructor({ mailRoot, machine, supercodeBin, serve, runtimeOf, runtimeNamed = () => null, runtimesIn = () => [], log = () => {} }) {
-    Object.assign(this, { mailRoot, machine, supercodeBin, serve, runtimeOf, runtimeNamed, runtimesIn, log });
+  constructor({ mailRoot, machine, supercodeBin, serve, runtimeOf, runtimeNamed = () => null, runtimesIn = () => [], endpointOf = async () => null, log = () => {} }) {
+    Object.assign(this, { mailRoot, machine, supercodeBin, serve, runtimeOf, runtimeNamed, runtimesIn, endpointOf, log });
     this.lost = new Map(); // relay folder → when a start of its runtime lost its answer (the runtime may run, unnamed)
+    this.remoteKept = new Map(); // relay folder of a sender on another machine → the timer that retires it
     this.sending = new Map(); // relay folder → the send in progress through it (one at a time per relay)
     this.running = new Map(); // relay folder → { connection, runtime_id, usedAt }: the relays this daemon runs
   }
@@ -103,6 +107,79 @@ export class Relays {
     }
   }
 
+  /**
+   * The relay that speaks for `represented` (known as `name`), retired: its runtime closed and its folder removed, under
+   * its own lock (as the native watch's minute sweep did, by event here: the session's end, or a remote
+   * sender's quiet hour). A board's or an operator's relay is kept: nothing ends it. Answers whether it was retired.
+   */
+  async retire(represented, name) {
+    const parsed = String(represented).split(':');
+    if (parsed[2] === 'board' || parsed[2] === 'operator') return false;
+    // a folder is named by its sender's name, not its address: it is retired only while it still represents this ended
+    // address (another live session of that name, or one renamed since, may hold it now)
+    return this.#retireFolder(this.spec(represented, name).directory, represented);
+  }
+
+  /** The address a relay folder speaks for, as its inbound hook names it (its settings), or null. */
+  #representedOf(directory) {
+    try { return /relay-inbound '([^']+)'/.exec(readFileSync(join(directory, 'settings.json'), 'utf8'))?.[1] ?? null; } catch { return null; }
+  }
+
+  async #retireFolder(directory, expected = null) {
+    try { statSync(directory); } catch { return false; }
+    if (expected && this.#representedOf(directory) !== expected) return false;
+    return this.#locked(directory, async () => {
+      // read again under its lock: a send that ran meanwhile writes its own sender's settings
+      if (expected && this.#representedOf(directory) !== expected) return false;
+      const record = readJson(join(directory, 'relay.json'));
+      if (record?.runtime_id) {
+        try { await this.serve('harness.v1.runtimes.close', { connection: record.connection ?? '', runtime_id: record.runtime_id }, 15_000); }
+        catch (error) {
+          // a runtime still live that could not be closed keeps its folder: it is retired again at the next end or start
+          if (this.runtimeOf('claude-code', record.runtime_id)) { this.log(`relay ${directory.split(/[\\/]/).pop()} was not retired: ${error.message}`); return false; }
+        }
+      }
+      this.running.delete(directory); this.lost.delete(directory);
+      clearTimeout(this.remoteKept.get(directory)); this.remoteKept.delete(directory);
+      try { rmSync(directory, { recursive: true, force: true }); } catch (error) { this.log(`relay ${directory.split(/[\\/]/).pop()}: its folder was not removed: ${error.message}`); return false; }
+      return true;
+    });
+  }
+
+  /** A relay speaking for a sender on another machine is retired REMOTE_RELAY_KEPT_MS after its last send. */
+  #keepRemote(directory, quietSinceMs = Date.now()) {
+    clearTimeout(this.remoteKept.get(directory));
+    const timer = setTimeout(() => { this.remoteKept.delete(directory); void this.#retireFolder(directory); }, Math.max(0, quietSinceMs + REMOTE_RELAY_KEPT_MS - Date.now()));
+    timer.unref?.();
+    this.remoteKept.set(directory, timer);
+  }
+
+  /**
+   * At a daemon's start, once its live sessions are known: the relays whose sessions ended while no daemon ran are
+   * retired, and a remote sender's relay is kept for the rest of its hour (one read of the relays folder, at start only).
+   * `running(address)` says whether a session here runs.
+   */
+  async sweepAtStart(running) {
+    let folders = [];
+    try { folders = readdirSync(join(this.mailRoot, 'relays')); } catch { return; }
+    let retired = 0;
+    for (const folder of folders) {
+      const directory = join(this.mailRoot, 'relays', folder);
+      const represented = this.#representedOf(directory);
+      if (!represented) continue;
+      const [, machine, harness] = represented.split(':');
+      if (harness === 'board' || harness === 'operator') continue;
+      if (machine !== this.machine) {
+        let last = 0; try { last = statSync(join(directory, 'receipt.json')).mtimeMs; } catch { /* never sent */ }
+        if (Date.now() - last < REMOTE_RELAY_KEPT_MS) { this.#keepRemote(directory, last); continue; }
+      } else if (harness !== 'claude-code' || running(represented)) continue;
+      // only a Claude session is provably ended when the map does not hold it (its registry lists every live Claude
+      // process); a sender of another harness the map may not see (Grok, Gemini, a Codex session idle a day) is kept
+      if (await this.#retireFolder(directory, represented)) retired++;
+    }
+    if (retired) this.log(`relays: ${retired} of sessions that ended while no daemon ran retired`);
+  }
+
   /** `work` run under the relay folder's lock: one send, or one close, at a time per relay, in arrival order. */
   async #locked(directory, work) {
     const previous = this.sending.get(directory) ?? Promise.resolve();
@@ -129,13 +206,8 @@ export class Relays {
     };
   }
 
-  /** The relay endpoint's base URL, when it answers (claude_relay.rs `relay_endpoint`; the native watch serves it until
-   *  step 4, its port in `<mail>/relay-endpoint.json`). */
-  async endpoint() {
-    const port = readJson(join(this.mailRoot, 'relay-endpoint.json'))?.port;
-    if (!Number.isInteger(port)) return null;
-    return (await answers(port)) ? `http://127.0.0.1:${port}` : null;
-  }
+  /** The relay endpoint's base URL: this daemon's own (relay-endpoint.mjs), or null when it is not served. */
+  async endpoint() { return this.endpointOf(); }
 
   /** Settings installing a relay's hooks: its gate on every tool, its receipt on SendMessage and on a turn's end, and its
    *  inbound filing (claude_relay.rs `relay_settings`). */
@@ -168,7 +240,7 @@ export class Relays {
   async #ensure(spec, step = () => {}) {
     const endpoint = await this.endpoint();
     step('relay endpoint');
-    if (!endpoint) throw new Error('the relay endpoint is not answering; the machine daemon\'s `supercode message watch` serves it (see mail/machine-daemon.log)');
+    if (!endpoint) throw new Error('the relay endpoint is not served by this machine\'s daemon (its log says why); a Claude session can be sent mail once the daemon starts again');
     // written on every send: Claude Code reloads a changed settings file, so a running relay takes the hooks this
     // supercode installs
     writeFileSync(spec.settings, JSON.stringify(this.#settings(spec), null, 2));
@@ -252,7 +324,10 @@ export class Relays {
     mkdirSync(spec.directory, { recursive: true });
     const asked = performance.now();
     try { return await this.#locked(spec.directory, () => this.#send(spec, receiver, message, messageId, asked)); }
-    finally { this.#cap(); }
+    finally {
+      if (String(sender).split(':')[1] !== this.machine) this.#keepRemote(spec.directory);
+      this.#cap();
+    }
   }
 
   async #send(spec, receiver, message, messageId, asked) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-teams",
-  "version": "0.3.96",
+  "version": "0.3.97",
   "type": "module",
   "description": "A machine daemon serving this machine's doors, and a local or remote Teams server for shared session discovery, OpenTelemetry ingestion and access to enrolled machines.",
   "license": "MIT",