flow-agent-bridge 0.37.3 → 0.37.5

package/dist/bridge.js

@@ -14,7 +14,7 @@ import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { defaultVoiceConfig, mentionChainLimit, resolveWorkspace } from './config.js';
-import { accountLines, addressIn, FlowApi } from './api.js';
+import { accountLines, addressIn, FlowApi, FlowApiError } from './api.js';
 import { attachmentFilename, formatAttachments } from './attachments.js';
 import { openFlowSocket } from './gateway.js';
 import { ChannelIndicatorLeases, ProgressReporter } from './progress.js';
@@ -23,6 +23,13 @@ import { SessionManager } from './session.js';
 import { EXIT_RESTART, EXIT_UPDATE } from './supervisor.js';
 import { currentVersion, isOutdated, latestPublishedVersion } from './version.js';
 import { HuddleVoiceManager } from './huddle-voice.js';
+import { CATCH_UP_TYPES, catchUp, ensureSubscription, HandledMessages, jobsSpec, subscriptionName } from './catch-up.js';
+/** How often the socket's latest cursor is acked to the bridge's subscription. */
+const CURSOR_ACK_MS = 30_000;
+/** A wake job's lease is renewed this often while its turn runs (the server's lease is 10 minutes). */
+export const JOB_EXTEND_MS = 5 * 60_000;
+/** A job whose turn never got to run (a `/reset` dropped it, say) is reported failed after this long. */
+const JOB_WAIT_MAX_MS = 6 * 3_600_000;
 const THINKING_PREFIX = '🤖 *thinking…*';
 /** The loop breaker's visible notice (#583). Never counts toward a chain, never wakes anyone. */
 const LOOP_BREAKER_PREFIX = '⚡ loop breaker:';
@@ -141,10 +148,33 @@ export class AgentBridge {
     taskSock = null;
     huddleVoice = null;
     logStream = null;
+    /** The messages answered lately, across restarts (catch-up.ts), so a catch-up never answers one twice. */
+    handled;
+    /** Messages answered since start: the catch-up's "answered M". */
+    answered = 0;
+    /** The bridge's subscription in this organization (catch-up.ts), and how far it is acked. */
+    subscription = null;
+    /** The latest `cursor` frame, to ack every 30 s and at shutdown. */
+    latestCursor = 0;
+    cursorTimer = null;
+    /** Wake jobs taken (platform.md §5.2, phase 2.4), across restarts, so a job delivered again or replayed runs once. */
+    handledJobs;
+    /** Jobs whose ack is in flight, so two copies of one `agent.job` arriving together are taken once. */
+    takingJobs = new Set();
+    /** The `bridge-jobs:` socket subscription, whose poke means an `agent.job` came; one read at a time. */
+    jobsSub = null;
+    jobsReading = false;
+    jobsAgain = false;
+    /** A job's turn, by its synthetic message's id: the client that marks its requests, and how the turn ended. */
+    jobTurns = new Map();
+    /** convKey → the job whose turn is running there, which the MCP server asks for (`/job` on the task IPC). */
+    activeJobs = new Map();
     constructor(cfg) {
         this.cfg = cfg;
         this.api = new FlowApi(cfg.serverUrl, cfg.agentToken);
         this.sem = new Semaphore(cfg.concurrency);
+        this.handled = new HandledMessages(cfg.stateFile ?? null, (m) => this.log(m));
+        this.handledJobs = new HandledMessages(cfg.stateFile ?? null, (m) => this.log(m), undefined, 'handledJobIds');
         this.sessions = new SessionManager({
             cfg: cfg.runtime,
             idleMs: cfg.runtime.sessionIdleSec * 1000,
@@ -219,22 +249,227 @@ export class AgentBridge {
             `voice=${voiceState} cwd=${this.cfg.runtime.cwd}`);
         for (const line of accountLines(this.me, workspaces))
             this.log(line);
+        const since = await this.catchUp();
+        if (since !== null)
+            await this.ensureJobsSubscription();
         this.socket = openFlowSocket({
             serverUrl: this.cfg.serverUrl,
             token: this.cfg.agentToken,
             // one process, one workspace (#357) — so tell the server, or it lights
             // our presence dot in every workspace we belong to (#364)
             workspaces: [this.workspace.id],
-            onEvent: (ev) => this.handleEvent(ev),
+            onEvent: (ev) => void this.handleEvent(ev),
             onOpen: () => { void this.huddleVoice?.refreshContext(); },
             log: (m) => this.log(m),
+            // What happened between the catch-up's read and the socket's hello comes as the socket's backlog.
+            ...(since !== null ? { since } : {}),
+            onCursor: (seq) => { this.latestCursor = Math.max(this.latestCursor, seq); },
+            onSubscription: (id) => void this.readJobs(id),
         });
         this.socket.connect();
+        if (this.subscription) {
+            this.cursorTimer = setInterval(() => void this.ackCursor(), CURSOR_ACK_MS);
+            this.cursorTimer.unref();
+        }
         this.startTaskIpc();
         // Best-effort staleness check — never blocks startup or crashes on failure.
         void this.checkVersion();
         void this.reportRelaunch();
     }
+    /**
+     * Before the socket opens: what this organization's log holds for the bridge's subscription since it last ran, fed
+     * through the path live events take. Returns the cursor reached (the socket's `since`), or null when the server has
+     * no subscriptions (an older server), which leaves the bridge on live events alone.
+     */
+    async catchUp() {
+        let sub;
+        try {
+            sub = await ensureSubscription(this.api, this.workspace.id, this.me.id);
+        }
+        catch (err) {
+            this.log(`no event subscription (${err.message}) — live events only`);
+            return null;
+        }
+        this.subscription = { id: sub.id, acked: sub.cursor };
+        this.latestCursor = sub.cursor;
+        const before = this.answered;
+        try {
+            const out = await catchUp(this.api, this.workspace.id, sub, (ev) => this.handleEvent(ev), (m) => this.log(m), (e) => this.handleJob(e));
+            this.subscription.acked = out.next;
+            this.latestCursor = Math.max(this.latestCursor, out.next);
+            this.log(`caught up: ${out.events} events, answered ${this.answered - before}`);
+            if (sub.outdated)
+                await this.replaceSubscription(sub.id);
+            return out.next;
+        }
+        catch (err) {
+            this.log(`catch-up failed (${err.message}) — continuing with live events`);
+            return this.subscription.acked;
+        }
+    }
+    /** An older bridge's subscription, caught up: replaced by one with today's types (`agent.job`), starting at the head. */
+    async replaceSubscription(oldId) {
+        try {
+            const fresh = await this.api.createSubscription(this.workspace.id, { name: subscriptionName(this.me.id), filter: { types: CATCH_UP_TYPES }, delivery: 'pull' });
+            await this.api.deleteSubscription(this.workspace.id, oldId).catch((err) => this.log(`old subscription not deleted: ${err.message}`));
+            this.subscription = { id: fresh.id, acked: fresh.cursor };
+            this.latestCursor = Math.max(this.latestCursor, fresh.cursor);
+            this.log('event subscription renewed with agent.job');
+        }
+        catch (err) {
+            this.log(`event subscription not renewed: ${err.message}`);
+        }
+    }
+    /** The socket subscription that pokes when a wake job comes (catch-up.ts `jobsSpec`). Without it jobs still come, late. */
+    async ensureJobsSubscription() {
+        try {
+            this.jobsSub = { id: (await ensureSubscription(this.api, this.workspace.id, this.me.id, jobsSpec(this.me.id))).id };
+        }
+        catch (err) {
+            this.log(`no job subscription (${err.message}) — wake jobs arrive with the next catch-up or delivery`);
+        }
+    }
+    /** A poke for the job subscription: read it until empty, taking each job, acking as it goes. */
+    async readJobs(id) {
+        if (!this.jobsSub || id !== this.jobsSub.id)
+            return;
+        if (this.jobsReading) {
+            this.jobsAgain = true;
+            return;
+        }
+        this.jobsReading = true;
+        try {
+            do {
+                this.jobsAgain = false;
+                await catchUp(this.api, this.workspace.id, { id, cursor: 0 }, () => { }, (m) => this.log(m), (e) => this.handleJob(e));
+            } while (this.jobsAgain);
+        }
+        catch (err) {
+            this.log(`job subscription read failed: ${err.message}`);
+        }
+        finally {
+            this.jobsReading = false;
+        }
+    }
+    /**
+     * An `agent.job` event (live or from a catch-up): acked as this agent, then run as a turn the way `start_task` runs
+     * one. Taken once: a job id already taken (state.json) or being taken is passed over. A job the server no longer
+     * offers (409) is remembered and dropped; an ack that failed otherwise is left for the server's next delivery.
+     */
+    async handleJob(e) {
+        const d = e.data;
+        const jobId = d?.jobId;
+        if (!jobId || !d.prompt)
+            return;
+        if (this.handledJobs.has(jobId) || this.takingJobs.has(jobId)) {
+            this.log(`job ${jobId} already taken — skipping the copy`);
+            return;
+        }
+        this.takingJobs.add(jobId);
+        try {
+            const api = this.api.withJob(jobId);
+            try {
+                await api.jobStep(this.workspace.id, jobId, 'ack');
+            }
+            catch (err) {
+                if (err instanceof FlowApiError && (err.status === 409 || err.status === 404))
+                    this.handledJobs.add(jobId);
+                this.log(`job ${jobId}: ack failed (${err.message})`);
+                return;
+            }
+            this.handledJobs.add(jobId);
+            this.log(`job ${jobId}: acked, running`);
+            void this.runJob(jobId, d, api);
+        }
+        finally {
+            this.takingJobs.delete(jobId);
+        }
+    }
+    /**
+     * The job's turn: in its channel (joined first when public), or a new `job-<id>` channel of its own, as a task run
+     * there (`startTask`), every request of it marked with the job (`x-flow-job`). The lease is extended every 5 minutes
+     * while it runs; at the end the job is reported done or failed with a line about it.
+     */
+    async runJob(jobId, d, api) {
+        let outcome = { ok: false, note: '' };
+        const msgId = `job-${jobId}`;
+        const extend = setInterval(() => {
+            void api.jobStep(this.workspace.id, jobId, 'extend').catch((err) => this.log(`job ${jobId}: extend failed: ${err.message}`));
+        }, this.jobExtendMs);
+        extend.unref();
+        try {
+            const channelId = await this.jobChannel(jobId, d.channelId, api);
+            const ended = new Promise((settle) => {
+                let done = false;
+                const once = (r) => { if (!done) {
+                    done = true;
+                    settle(r);
+                } };
+                this.jobTurns.set(msgId, { jobId, api, settle: once });
+                setTimeout(() => once({ ok: false, note: 'the turn never ran' }), JOB_WAIT_MAX_MS).unref();
+            });
+            this.taskChannels.add(channelId);
+            this.enqueue(this.taskMessage(msgId, channelId, this.me.id, d.prompt));
+            outcome = await ended;
+        }
+        catch (err) {
+            outcome = { ok: false, note: err.message };
+        }
+        finally {
+            clearInterval(extend);
+            this.jobTurns.delete(msgId);
+        }
+        const note = oneLine(outcome.note) || (outcome.ok ? 'done' : 'failed');
+        await api.jobStep(this.workspace.id, jobId, 'done', { ok: outcome.ok, note })
+            .catch((err) => this.log(`job ${jobId}: done not reported: ${err.message}`));
+        this.log(`job ${jobId}: ${outcome.ok ? 'done' : 'failed'} — ${note}`);
+        return { ok: outcome.ok, note };
+    }
+    /** Where a job runs: its channel, which the agent must be in (a public one it joins), or a new one named for the job. */
+    async jobChannel(jobId, channelId, api) {
+        if (channelId) {
+            if (!this.channels.has(channelId))
+                await this.refreshDirectory().catch((err) => this.log(`directory refresh failed: ${err.message}`));
+            const chan = this.channels.get(channelId);
+            if (!chan)
+                throw new Error('no such channel');
+            if (!chan.isMember) {
+                if (chan.kind !== 'standard' || chan.isPrivate)
+                    throw new Error('not a member of that channel');
+                await api.joinChannel(channelId);
+                this.channels.set(channelId, { ...chan, isMember: true });
+            }
+            return channelId;
+        }
+        const name = `job-${jobId.slice(0, 8)}`;
+        try {
+            const chan = await api.createChannel(this.workspace.id, { name, topic: `Wake job ${jobId}` });
+            this.channels.set(chan.id, chan);
+            return chan.id;
+        }
+        catch (err) {
+            if (!(err instanceof FlowApiError && err.status === 409))
+                throw err;
+            await this.refreshDirectory();
+            const found = [...this.channels.values()].find((c) => c.name === name);
+            if (!found)
+                throw err;
+            return found.id;
+        }
+    }
+    /** The socket's latest cursor, acked to the subscription: the next start replays only what came after. */
+    async ackCursor() {
+        const sub = this.subscription;
+        if (!sub || this.latestCursor <= sub.acked)
+            return;
+        const to = this.latestCursor;
+        try {
+            sub.acked = Math.max(sub.acked, await this.api.ackSubscription(this.workspace.id, sub.id, to));
+        }
+        catch (err) {
+            this.log(`subscription ack failed: ${err.message}`);
+        }
+    }
     /** After a `/update` / `/restart` relaunch, confirm we're back — in the
      * conversation that asked, with the version the update actually landed on. */
     async reportRelaunch() {
@@ -281,7 +516,7 @@ export class AgentBridge {
                 fs.rmSync(sock, { force: true }); // stale socket from a previous run
             }
             const server = http.createServer((req, res) => {
-                if (req.method !== 'POST' || req.url !== '/task') {
+                if (req.method !== 'POST' || (req.url !== '/task' && req.url !== '/job')) {
                     res.writeHead(404).end();
                     return;
                 }
@@ -293,6 +528,18 @@ export class AgentBridge {
                 });
                 req.on('end', () => {
                     void (async () => {
+                        if (req.url === '/job') {
+                            // The MCP server's question before each request: is a wake job's turn running in this conversation?
+                            let jobId = null;
+                            try {
+                                const q = JSON.parse(body);
+                                jobId = this.activeJobs.get(`${q.channelId ?? ''}|${q.threadRootId ?? ''}`) ?? null;
+                            }
+                            catch { /* no job */ }
+                            res.writeHead(200, { 'content-type': 'application/json' });
+                            res.end(JSON.stringify({ jobId }));
+                            return;
+                        }
                         let out;
                         try {
                             out = await this.startTask(JSON.parse(body));
@@ -345,13 +592,18 @@ export class AgentBridge {
                 `${requester !== this.me.id ? ` for <@${requester}>` : ''}.`)
                 .catch((err) => this.log(`task kickoff post failed: ${err.message}`));
         }
-        this.enqueue({
-            id: `task-${randomUUID()}`,
+        this.enqueue(this.taskMessage(`task-${randomUUID()}`, channelId, requester, prompt));
+        return { ok: true, note: `task run queued in ${this.channelLabel(channelId)}` };
+    }
+    /** A run's opening message: what a task run (or a wake job) is asked, as if posted to its channel. */
+    taskMessage(id, channelId, userId, body) {
+        return {
+            id,
             channelId,
-            userId: requester,
+            userId,
             threadRootId: null,
-            clientMsgId: `task-${randomUUID()}`,
-            body: prompt,
+            clientMsgId: id,
+            body,
             createdAt: new Date().toISOString(),
             editedAt: null,
             deletedAt: null,
@@ -365,8 +617,7 @@ export class AgentBridge {
             reactions: [],
             files: [],
             unfurls: [],
-        });
-        return { ok: true, note: `task run queued in ${this.channelLabel(channelId)}` };
+        };
     }
     /**
      * On startup, compare our installed version with the latest on npm. If we're
@@ -397,6 +648,10 @@ export class AgentBridge {
     }
     async stop() {
         this.socket?.close();
+        if (this.cursorTimer)
+            clearInterval(this.cursorTimer);
+        this.cursorTimer = null;
+        const acked = this.ackCursor();
         this.ipcServer?.close();
         this.ipcServer = null;
         if (this.taskSock && process.platform !== 'win32')
@@ -413,6 +668,7 @@ export class AgentBridge {
         await Promise.all([...new Set([...this.conversations.values()].map((c) => c.channelId))].map((id) => this.clearIndicator(id)));
         await this.huddleVoice?.stop();
         this.huddleVoice = null;
+        await acked;
         if (this.refreshTimer)
             clearTimeout(this.refreshTimer);
         this.logStream?.end();
@@ -476,6 +732,7 @@ export class AgentBridge {
         this.log(`removed from workspace ${this.workspace.name} — no longer serving it ` +
             `(ask an admin to re-invite this agent, then restart the bridge)`);
     }
+    /** Live events and the catch-up's alike; a message's promise settles once it is queued or passed over. */
     handleEvent(ev) {
         // One process, one workspace (#357). The socket carries every workspace the
         // agent belongs to, so anything from elsewhere belongs to a sibling process
@@ -528,7 +785,7 @@ export class AgentBridge {
         }
         if (ev.type !== 'message.created' && ev.type !== 'thread.reply')
             return;
-        void this.handleMessage(ev.data);
+        return this.handleMessage(ev.data);
     }
     /**
      * The Interrupt button: 🛑 on a thinking row stops the turn that row belongs
@@ -593,6 +850,13 @@ export class AgentBridge {
         }
         if (!(await this.inScope(msg)))
             return;
+        // Answered once, across restarts too: a catch-up, or a socket's backlog, can bring a message we already took.
+        // Marked before the commands, so a replayed `/restart` cannot restart us again.
+        if (!this.handled.add(msg.id)) {
+            this.log(`already answered ${msg.id} — skipping the replay`);
+            return;
+        }
+        this.answered++;
         // Bridge commands, not runtime turns. A leading mention of us is stripped
         // first, so "@Bot /update" works in a channel (where the mention is what
         // put the message in scope at all).
@@ -608,6 +872,8 @@ export class AgentBridge {
             return;
         this.enqueue(msg);
     }
+    /** How often a job's lease is extended; swappable in tests. */
+    jobExtendMs = JOB_EXTEND_MS;
     /** Swappable in tests — the real thing takes the process down. */
     exitProcess = (code) => process.exit(code);
     /** Swappable in tests — the real thing asks the npm registry. */
@@ -913,7 +1179,12 @@ export class AgentBridge {
         // — targets the same thread (a new one when we're answering a top-level
         // channel message).
         const replyRoot = this.replyRoot(msg);
-        const progress = new ProgressReporter(this.api, this.socket, this.cfg.progress, this.cfg.relayText, msg.channelId, replyRoot, (m) => this.log(m), this.indicatorLeases);
+        // A wake job's turn: every request of it carries the job (x-flow-job), the MCP server's too (via `activeJobs`).
+        const job = this.jobTurns.get(msg.id);
+        const api = job?.api ?? this.api;
+        if (job)
+            this.activeJobs.set(key, job.jobId);
+        const progress = new ProgressReporter(api, this.socket, this.cfg.progress, this.cfg.relayText, msg.channelId, replyRoot, (m) => this.log(m), this.indicatorLeases);
         // The persistent session owns its own MCP config for as long as its process
         // lives; only the one-shot path writes (and deletes) one per turn.
         const persistent = this.cfg.runtime.kind === 'claude';
@@ -969,20 +1240,22 @@ export class AgentBridge {
                 this.log('run stopped by request');
                 if (result.sawSession)
                     conv.started = true;
-                await this.api.sendMessage(msg.channelId, interruptReply(result, live.stoppedBy), replyRoot).catch(() => { });
+                await api.sendMessage(msg.channelId, interruptReply(result, live.stoppedBy), replyRoot).catch(() => { });
                 if (replyRoot)
                     this.threadParticipation.set(replyRoot, true);
+                job?.settle({ ok: false, note: 'stopped by request' });
                 return;
             }
             if (result.ok) {
                 conv.started = true;
                 const text = result.text.trim();
                 if (text.length > 0) {
-                    await this.api.sendMessage(msg.channelId, text, replyRoot);
+                    await api.sendMessage(msg.channelId, text, replyRoot);
                     // We've now spoken here — every later reply in this thread is ours to answer.
                     if (replyRoot)
                         this.threadParticipation.set(replyRoot, true);
                 }
+                job?.settle({ ok: true, note: text || 'done' });
             }
             else {
                 this.log(`runtime error: ${result.error ?? 'unknown'}`);
@@ -1007,10 +1280,17 @@ export class AgentBridge {
                     this.log(`codex resume of ${conv.codexSessionId} failed — next turn starts a fresh session`);
                     conv.codexSessionId = undefined;
                 }
-                await this.api.sendMessage(msg.channelId, failureReply(result), replyRoot).catch(() => { });
+                await api.sendMessage(msg.channelId, failureReply(result), replyRoot).catch(() => { });
+                job?.settle({ ok: false, note: result.error ?? 'runtime error' });
             }
         }
+        catch (err) {
+            job?.settle({ ok: false, note: err.message });
+            throw err;
+        }
         finally {
+            if (job && this.activeJobs.get(key) === job.jobId)
+                this.activeJobs.delete(key);
             if (this.liveRuns.get(key) === live)
                 this.liveRuns.delete(key);
             await progress.finish().catch(() => { });
@@ -1264,4 +1544,9 @@ export class AgentBridge {
         return p;
     }
 }
+/** The first line of a turn's text or error, short enough for a job's note. */
+function oneLine(text) {
+    const line = text.split('\n').map((l) => l.trim()).find(Boolean) ?? '';
+    return line.length > 200 ? `${line.slice(0, 199)}…` : line;
+}
 //# sourceMappingURL=bridge.js.map