@luckydraw/cumulus 1.0.7 → 1.0.9

package/dist/gateway/server.js

@@ -20,7 +20,7 @@ import * as fs from 'fs';
 import * as http from 'http';
 import * as os from 'os';
 import * as path from 'path';
-import { loadGlobalConfig, loadThreadConfig, mergeConfigs, saveThreadConfig, setConfigThreadsDir, } from '../lib/config.js';
+import { loadGlobalConfig, loadThreadConfig, loadThreadConfigExact, mergeConfigs, resolveCoThreadMaster, saveThreadConfig, setConfigThreadsDir, } from '../lib/config.js';
 import { loadEmbeddings, generateMissingEmbeddings } from '../lib/embeddings.js';
 import { sendMessage, getOrCreateThread, clearThreadCache, canRunBackgroundWork, getActiveSubprocessCount, setGatewayThreadsDir, } from '../lib/gateway.js';
 import { verifyLicense, majorOf, LICENSE_CONTACT } from '../lib/license.js';
@@ -28,6 +28,7 @@ import { getPromptsDirForThreadPath, isValidCaptureId, readPromptCapture, } from
 import { catchUpSegmentation, loadSegmentBoundaries, saveSegmentBoundaries, } from '../lib/segments.js';
 import { listTemplates, scaffoldFromTemplate } from '../lib/templates.js';
 import { checkForUpdate, getCurrentVersion, performUpdate, readChangelog, } from '../lib/version-check.js';
+import { coThreadOverlaps, coThreadStatus, ensureCoThreadWorktree, mergeCoThread, removeCoThreadWorktree, resolveThreadCwd, } from '../lib/worktree.js';
 import { serveStaticFile, getMediaDir } from './adapters/webchat.js';
 import { authenticate, getPresentedKey } from './auth.js';
 import { BridgeGateway } from './bridge/gateway.js';
@@ -40,6 +41,98 @@ import { isAutomatedSender } from './senders.js';
 import { validateTranscriptFlush, ingestTranscriptFlush } from './transcript-ingest.js';
 const threadQueues = new Map();
 const threadBusy = new Map();
+const userQueues = new Map();
+let userQueueDelivery;
+export function setUserQueueDelivery(fn) {
+    userQueueDelivery = fn;
+}
+/** Queue a deferred user message. Returns the full pending list for the thread. */
+export function enqueueUserMessage(threadName, msg) {
+    const queue = userQueues.get(threadName) ?? [];
+    queue.push({ ...msg, id: msg.id ?? `q_${Math.random().toString(36).slice(2, 10)}` });
+    userQueues.set(threadName, queue);
+    console.log(`[Gateway] User message queued for busy thread "${threadName}" (position ${queue.length})`);
+    return queue;
+}
+/** Pending deferred user messages for a thread (empty array when none). */
+export function getUserQueue(threadName) {
+    return userQueues.get(threadName) ?? [];
+}
+/** Edit a queued message's text in place. Returns the updated pending list. */
+export function editUserMessage(threadName, id, text) {
+    const queue = userQueues.get(threadName) ?? [];
+    const item = queue.find(m => m.id === id);
+    if (item)
+        item.text = text;
+    return queue;
+}
+/**
+ * Remove one queued message and return it — the shared half of "cancel" and
+ * "send now". Send-now is cancel plus an ordinary send, so it cannot leave a
+ * copy behind in the queue.
+ */
+export function takeUserMessage(threadName, id) {
+    const queue = userQueues.get(threadName) ?? [];
+    const idx = queue.findIndex(m => m.id === id);
+    const taken = idx >= 0 ? queue.splice(idx, 1)[0] : undefined;
+    if (queue.length === 0)
+        userQueues.delete(threadName);
+    return { taken, remaining: queue };
+}
+/**
+ * Render a drained batch as the text of one turn.
+ *
+ * A single message delivers as its bare text — indistinguishable from one sent
+ * normally, because on the common case a wrapper is pure noise. Several deliver
+ * as one turn (Karl's choice over one-at-a-time: the model sees the whole
+ * picture before it starts answering).
+ *
+ * Deliberately carries no `[sender → recipient]` framing and no reply hint:
+ * this is the user talking, not an agent.
+ */
+export function formatQueuedUserBatch(batch) {
+    if (batch.length === 1)
+        return batch[0].text;
+    const lines = [
+        `[${batch.length} messages queued while you were responding — all from the user, in order]`,
+        '',
+    ];
+    batch.forEach((m, i) => {
+        lines.push(`(${i + 1}) ${m.text}`);
+        lines.push('');
+    });
+    return lines.join('\n').trimEnd();
+}
+/**
+ * Attempt a drain outside the busy→idle transition.
+ *
+ * Needed because delivery can decline: with no client watching the thread there
+ * is nobody to stream the turn to, so the batch is put back. Without this, those
+ * messages would wait for the *next* busy→idle — which may never come on an
+ * idle thread. A client re-opening the thread calls this.
+ */
+export function flushUserQueue(threadName) {
+    return drainUserQueue(threadName);
+}
+/**
+ * Deliver every pending user message for a thread as one turn.
+ *
+ * Returns true when it took the thread — the caller must NOT also drain the
+ * agent queue, or the two turns run concurrently (the task 120 class).
+ */
+function drainUserQueue(threadName) {
+    const queue = userQueues.get(threadName);
+    if (!queue || queue.length === 0)
+        return false;
+    if (threadBusy.get(threadName))
+        return false;
+    if (!userQueueDelivery)
+        return false;
+    userQueues.delete(threadName);
+    console.log(`[Gateway] Draining ${queue.length} queued user message(s) for "${threadName}"`);
+    userQueueDelivery(threadName, queue);
+    return true;
+}
 const bridgeContexts = new Map();
 async function buildBridgeContextBlock(threadName, executorUrl) {
     const ctx = bridgeContexts.get(threadName);
@@ -108,7 +201,15 @@ export function markThreadBusy(threadName, busy) {
     // User-queued messages take priority: their drain pass toggles busy and
     // lands back here when the user queue is empty.
     const pendingUser = threadQueues.get(threadName);
-    if (!pendingUser?.length && agentPipelineOpts) {
+    if (pendingUser?.length)
+        return;
+    // Deferred user messages (task 144) outrank agent messages for the same
+    // reason the SSE queue does. If this takes the thread it returns true, and we
+    // must NOT also start an agent turn — that is two concurrent turns on one
+    // thread (task 120).
+    if (drainUserQueue(threadName))
+        return;
+    if (agentPipelineOpts) {
         drainAgentQueue(threadName, agentPipelineOpts);
     }
 }
@@ -718,6 +819,28 @@ export function formatAgentMessageForRecipient(messageText, senderName, recipien
         : automatedNote;
     return `${prefix}\n${messageText}\n\n${replyHint}`;
 }
+/**
+ * Render several drained agent messages as one turn.
+ *
+ * Exported because the widget has to RECOGNISE this shape to render it as an
+ * agent message rather than a user bubble (task 144) — and a hand-copied
+ * fixture of it is exactly what task 103 got wrong: the tests passed against a
+ * shape that never occurs in production. The widget test drives this function.
+ */
+export function formatAgentBatch(queue) {
+    const lines = [`[While you were busy, ${queue.length} messages arrived]\n`];
+    for (const msg of queue) {
+        const time = new Date(msg.timestamp).toLocaleTimeString();
+        // Task 110: don't call a script an agent
+        const kind = isAgentSender(msg.sender) ? 'agent' : 'automated sender';
+        lines.push(`[From ${kind} "${msg.sender}"] (${time}):`);
+        lines.push(msg.text);
+        lines.push('');
+    }
+    lines.push('(Review the above messages. Reply only if actionable work is needed.');
+    lines.push('Use send_to_agent("name", response) to respond to a specific agent — automated senders are scripts and cannot be replied to.)');
+    return lines.join('\n');
+}
 function drainAgentQueue(threadName, pipelineOpts) {
     // Another turn may have grabbed the thread between busy→false and this call
     if (threadBusy.get(threadName))
@@ -739,18 +862,7 @@ function drainAgentQueue(threadName, pipelineOpts) {
         });
     }
     else {
-        const lines = [`[While you were busy, ${queue.length} messages arrived]\n`];
-        for (const msg of queue) {
-            const time = new Date(msg.timestamp).toLocaleTimeString();
-            // Task 110: don't call a script an agent
-            const kind = isAgentSender(msg.sender) ? 'agent' : 'automated sender';
-            lines.push(`[From ${kind} "${msg.sender}"] (${time}):`);
-            lines.push(msg.text);
-            lines.push('');
-        }
-        lines.push('(Review the above messages. Reply only if actionable work is needed.');
-        lines.push('Use send_to_agent("name", response) to respond to a specific agent — automated senders are scripts and cannot be replied to.)');
-        formatted = lines.join('\n');
+        formatted = formatAgentBatch(queue);
     }
     // Fire-and-forget: send the batched message as a new turn
     threadBusy.set(threadName, true);
@@ -973,6 +1085,15 @@ async function handleListThreads(res, scopeNs, namespaces) {
             if (tc.projectDir) {
                 entry.projectDir = tc.projectDir;
             }
+            // Co-thread membership, so the sidebar can nest (task 143). Deliberately
+            // the authoritative predicate and NOT a name-prefix test: every visitor
+            // thread (`pursuit-<deviceId>`) looks like a co-thread by name, and
+            // grouping those under their app would claim a relationship that does
+            // not exist. `resolveCoThreadMaster` requires actual membership.
+            const master = resolveCoThreadMaster(name);
+            if (master) {
+                entry.master = master;
+            }
             threads.push(entry);
         }
         // Sort by last activity descending
@@ -1001,6 +1122,24 @@ async function handleDeleteThread(threadName, req, res) {
         return;
     }
     try {
+        // A co-thread's private worktree is a sidecar like any other: remove it with
+        // the thread, or it lingers on disk registered to a repo forever (task 143 p4).
+        const deletedThreadMaster = resolveCoThreadMaster(threadName);
+        if (deletedThreadMaster) {
+            try {
+                await removeCoThreadWorktree(threadName, await projectDirFor(deletedThreadMaster));
+                // Deregister, or the name stays listed as a co-thread forever: creation
+                // short-circuits on an already-registered name, so recreating it would
+                // report success and never rebuild the history file.
+                const masterConfig = await loadThreadConfigExact(deletedThreadMaster);
+                await saveThreadConfig(deletedThreadMaster, {
+                    coThreads: (masterConfig.coThreads ?? []).filter(n => n !== threadName),
+                });
+            }
+            catch (err) {
+                console.warn(`[Gateway] worktree cleanup failed for ${threadName}:`, err);
+            }
+        }
         // Clear from cache
         clearThreadCache(threadName);
         threadQueues.delete(threadName);
@@ -1355,6 +1494,160 @@ async function handleUpdatePipeline(threadName, req, res) {
         jsonResponse(res, 500, { error: String(err) });
     }
 }
+// ─── Co-thread handlers (task 143) ─────────────────────────
+/** A co-thread label: one path-safe segment, no separators of its own. */
+const CO_THREAD_LABEL = /^[a-zA-Z0-9_]+$/;
+/** The project directory a thread's work belongs to (the master's, for a co-thread). */
+async function projectDirFor(threadName) {
+    const merged = mergeConfigs(await loadGlobalConfig(), await loadThreadConfig(threadName));
+    return merged.projectDir;
+}
+async function handleListCoThreads(threadName, res) {
+    try {
+        // The set belongs to the MASTER, so a co-thread asking has to read it from
+        // there — its own exact config is deliberately absent (that absence is what
+        // preserves task 098 inheritance), which is why this used to answer a
+        // co-thread with an empty list. Task 143 phase 5: visibility is not
+        // authority — create and merge stay master-only and still refuse with 409.
+        const master = resolveCoThreadMaster(threadName);
+        const owner = master ?? threadName;
+        const config = await loadThreadConfigExact(owner);
+        const names = config.coThreads ?? [];
+        const masterDir = await projectDirFor(owner);
+        // Report each co-thread's private tree so the set can see who has
+        // uncommitted work and who has commits waiting to be merged.
+        const status = await Promise.all(names.map(n => coThreadStatus(n, masterDir)));
+        jsonResponse(res, 200, {
+            thread: threadName,
+            master: master ?? null,
+            coThreads: names,
+            worktrees: status,
+            overlaps: coThreadOverlaps(status),
+        });
+    }
+    catch (err) {
+        jsonResponse(res, 500, { error: String(err) });
+    }
+}
+/**
+ * Merge a co-thread's branch into the master's working tree.
+ *
+ * Master-only, mirroring creation: the co-thread does not decide when its work
+ * lands, and the master's checkout has exactly one thread able to move it.
+ */
+async function handleMergeCoThread(threadName, label, res) {
+    try {
+        if (resolveCoThreadMaster(threadName)) {
+            jsonResponse(res, 409, {
+                error: `"${threadName}" is itself a co-thread. Merging is done from the master.`,
+            });
+            return;
+        }
+        const coThreadName = label.includes('-') ? label : `${threadName}-${label}`;
+        const config = await loadThreadConfigExact(threadName);
+        if (!(config.coThreads ?? []).includes(coThreadName)) {
+            jsonResponse(res, 404, { error: `"${coThreadName}" is not a co-thread of "${threadName}".` });
+            return;
+        }
+        const result = await mergeCoThread(coThreadName, await projectDirFor(threadName));
+        jsonResponse(res, result.error ? 409 : 200, { thread: coThreadName, ...result });
+    }
+    catch (err) {
+        jsonResponse(res, 500, { error: String(err) });
+    }
+}
+/**
+ * Create a co-thread of `threadName`: a sibling that shares this thread's
+ * content store but keeps its own conversation history.
+ *
+ * Creation is MASTER-ONLY (Karl, 2026-08-16). A co-thread cannot mint siblings,
+ * so the tree stays exactly one level deep and ownership of the project
+ * checkout is never ambiguous.
+ */
+async function handleCreateCoThread(threadName, req, res, jobs) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        jsonResponse(res, 400, { error: 'Invalid JSON body' });
+        return;
+    }
+    const label = (body.label ?? '').trim();
+    if (!label || !CO_THREAD_LABEL.test(label)) {
+        jsonResponse(res, 400, {
+            error: 'label must be letters, numbers or underscores (no hyphens, spaces or slashes)',
+        });
+        return;
+    }
+    const master = resolveCoThreadMaster(threadName);
+    if (master) {
+        jsonResponse(res, 409, {
+            error: `"${threadName}" is itself a co-thread of "${master}". Co-threads are created from the master only.`,
+        });
+        return;
+    }
+    const coThreadName = `${threadName}-${label}`;
+    const coThreadPath = path.join(THREADS_DIR, `${coThreadName}.jsonl`);
+    try {
+        const config = await loadThreadConfigExact(threadName);
+        const existing = config.coThreads ?? [];
+        if (existing.includes(coThreadName)) {
+            jsonResponse(res, 200, { created: false, thread: coThreadName, master: threadName });
+            return;
+        }
+        if (fs.existsSync(coThreadPath)) {
+            jsonResponse(res, 409, {
+                error: `Thread "${coThreadName}" already exists and is not a co-thread. Pick another label.`,
+            });
+            return;
+        }
+        // Register FIRST: an unregistered thread that already has a history file
+        // would come up with a private store, and its first turn's memory would
+        // land somewhere the master can never see.
+        await saveThreadConfig(threadName, { coThreads: [...existing, coThreadName] });
+        // The thread exists once its history file does — that is what every
+        // listing (`/api/threads`, `/api/agents`, the web UI) enumerates.
+        fs.mkdirSync(THREADS_DIR, { recursive: true });
+        fs.writeFileSync(coThreadPath, '', { flag: 'a' });
+        // Drop any cached state so the next turn resolves the shared store.
+        clearThreadCache(coThreadName);
+        // Give it a private checkout so it cannot overwrite its siblings (phase 4).
+        // Best-effort: a non-git project still gets a working co-thread, sharing the
+        // checkout exactly as it did before this shipped.
+        const masterDir = await projectDirFor(threadName);
+        const wt = await ensureCoThreadWorktree(coThreadName, masterDir);
+        // A fresh worktree has the tracked files and nothing else. Run the project's
+        // setup command through the job system (task 139) so creation does not block
+        // on it and the co-thread is woken when its tree is actually usable.
+        let setupJob;
+        if (jobs && wt.worktree && config.worktreeSetup && (await threadCanRunJobs(coThreadName))) {
+            try {
+                setupJob = jobs.create({
+                    thread: coThreadName,
+                    command: config.worktreeSetup,
+                    label: 'worktree setup',
+                    cwd: wt.cwd,
+                }).id;
+            }
+            catch (err) {
+                console.warn(`[Gateway] worktree setup failed to start for ${coThreadName}:`, err);
+            }
+        }
+        jsonResponse(res, 201, {
+            created: true,
+            thread: coThreadName,
+            master: threadName,
+            cwd: wt.cwd,
+            worktree: wt.worktree ?? null,
+            sharedCheckout: wt.fellBackTo?.reason ?? null,
+            setupJob: setupJob ?? null,
+        });
+    }
+    catch (err) {
+        jsonResponse(res, 500, { error: String(err) });
+    }
+}
 // ─── Schedule handlers ─────────────────────────────────────
 async function handleListSchedules(threadName, res) {
     try {
@@ -1487,7 +1780,12 @@ async function handleCreateJob(threadName, req, res, jobs, projectRoot) {
     if (!cwd) {
         try {
             const merged = mergeConfigs(await loadGlobalConfig(), await loadThreadConfig(threadName));
-            cwd = merged.projectDir;
+            // Task 143 phase 4: for a co-thread that is the PRIVATE WORKTREE, not the
+            // master's checkout. Resolving only the config here would build and test a
+            // tree the thread never edits — the same-tree invariant above, broken
+            // silently. One resolver, both cwd sites (task 113).
+            const resolved = await resolveThreadCwd(threadName, merged.projectDir);
+            cwd = resolved.cwd || merged.projectDir;
         }
         catch {
             /* fall through to the defaults below */
@@ -2227,6 +2525,28 @@ export async function startGatewayServer(options) {
                 await handleUpdatePipeline(params.name, req, res);
                 return;
             }
+            // GET /api/thread/:name/co-threads — list co-threads (task 143)
+            if (routePath === '/api/thread/:name/co-threads' && req.method === 'GET') {
+                await handleListCoThreads(params.name, res);
+                return;
+            }
+            // POST /api/thread/:name/co-threads — create a co-thread (master only)
+            if (routePath === '/api/thread/:name/co-threads' && req.method === 'POST') {
+                await handleCreateCoThread(params.name, req, res, jobRegistry);
+                return;
+            }
+            // POST /api/thread/:name/co-threads/:label/merge — fold a co-thread's
+            // branch into the master's tree (task 143 phase 4, master only)
+            if (routePath.startsWith('/api/thread/:name/co-threads/') && req.method === 'POST') {
+                const rest = routePath.replace('/api/thread/:name/co-threads/', '');
+                if (rest.endsWith('/merge')) {
+                    const label = decodeURIComponent(rest.slice(0, -'/merge'.length));
+                    if (label) {
+                        await handleMergeCoThread(params.name, label, res);
+                        return;
+                    }
+                }
+            }
             // GET /api/thread/:name/schedules — list schedules
             if (routePath === '/api/thread/:name/schedules' && req.method === 'GET') {
                 await handleListSchedules(params.name, res);