@venturewild/workspace 0.6.15 → 0.6.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venturewild/workspace",
-  "version": "0.6.15",
+  "version": "0.6.17",
   "description": "Claude Code Web — Replit/Lovable-style chat-first browser UI that wraps the AI agent already installed on your machine.",
   "license": "MIT",
   "bin": {

package/server/src/background-tasks.mjs

@@ -0,0 +1,322 @@
+// Background-task registry — the "what's running in the background" surface.
+//
+// WHY this exists: the agent can launch a long job with the Bash tool's
+// `run_in_background:true` (e.g. "run the scored-verdict audit in the background").
+// We verified empirically how `claude` behaves here:
+//   - The launch tool_result is text: `Command running in background with ID:
+//     <shellId>. Output is being written to: <file>. You will be notified…`.
+//   - The task OUTLIVES the `claude -p` turn that spawned it (it's detached) — the
+//     output file keeps growing on disk after the process exits.
+//   - BUT in our one-process-per-turn model there is NO completion event delivered
+//     back into the stream, and a resumed session can't re-poll the old shell. So
+//     "I'll be notified when it finishes" never actually fires for the user.
+//   - Completion IS visible IF the agent polls in the same turn: the poll tool
+//     (newer `TaskOutput` w/ `task_id`, older `BashOutput` w/ `bash_id`) returns
+//     `<status>completed</status>` + `<exit_code>N</exit_code>`.
+//
+// So this registry fuses two signals, both of which the server already sees or can
+// reach: (1) the agent's tool-use/tool-result chunk stream (launch + any polls) and
+// (2) the on-disk output file's size/mtime (process-independent liveness). It is the
+// single source of truth behind the chat's background-task card, the topbar activity
+// tray, and the canvas Tasks block.
+//
+// HONESTY (CLAUDE.md: never fake): we only assert `completed`/`failed` from an
+// authoritative poll result or an exit-code we actually observed. Without that, a
+// task is `running`, optionally flagged `quiet` when the output file has been
+// silent past a threshold — surfaced as "no output for Xm", never a false "done".
+
+import fs from 'node:fs';
+
+const DEFAULT_POLL_MS = 3000; // how often we stat each live task's output file
+const DEFAULT_QUIET_MS = 90_000; // silence past this → flag `quiet` (maybe stuck / maybe just slow)
+const DEFAULT_MAX_PER_WS = 40; // retained tasks per workspace (terminal ones pruned oldest-first)
+const TAIL_BYTES = 16 * 1024; // how much of the output file the tail endpoint returns
+
+const TERMINAL = new Set(['completed', 'failed', 'killed']);
+
+/** Parse a background-launch tool_result into { shellId, outputFile }. */
+export function parseLaunchResult(text) {
+  if (typeof text !== 'string') return null;
+  const idM = text.match(/background with ID:\s*([A-Za-z0-9_-]+)/i);
+  if (!idM) return null;
+  const fileM = text.match(/written to:\s*(\S+)/i);
+  let outputFile = fileM ? fileM[1] : null;
+  // The path is a contiguous no-space token; the sentence's trailing punctuation
+  // ("…/x.output. You will be notified") clings to it — strip it (output files end
+  // in letters, so this never eats a real filename char).
+  if (outputFile) outputFile = outputFile.replace(/[.,;:]+$/, '');
+  return { shellId: idM[1], outputFile: outputFile || null };
+}
+
+/** Parse a poll tool_result (`TaskOutput`/`BashOutput`) into { status, exitCode }. */
+export function parsePollResult(text) {
+  if (typeof text !== 'string') return null;
+  const sM = text.match(/<status>\s*([a-z_]+)\s*<\/status>/i);
+  if (!sM) return null;
+  const raw = sM[1].toLowerCase();
+  const eM = text.match(/<exit_code>\s*(-?\d+)\s*<\/exit_code>/i);
+  const exitCode = eM ? Number(eM[1]) : null;
+  let status = 'running';
+  if (raw === 'completed' || raw === 'done' || raw === 'finished') {
+    status = exitCode !== null && exitCode !== 0 ? 'failed' : 'completed';
+  } else if (raw === 'killed' || raw === 'stopped') {
+    status = 'killed';
+  } else if (raw === 'failed' || raw === 'error') {
+    status = 'failed';
+  }
+  return { status, exitCode };
+}
+
+// The shell id a poll/kill tool call targets, across the new + old vocabularies.
+function targetShellId(input) {
+  if (!input || typeof input !== 'object') return null;
+  return input.task_id || input.bash_id || input.shell_id || null;
+}
+
+const POLL_TOOLS = new Set(['TaskOutput', 'BashOutput']);
+const KILL_TOOLS = new Set(['TaskStop', 'KillShell', 'KillBash']);
+
+/**
+ * @param {object} opts
+ * @param {(task:object)=>void} [opts.broadcast]  called with the public task view on every change
+ * @param {()=>number}          [opts.now]
+ * @param {number}              [opts.pollMs]
+ * @param {number}              [opts.quietMs]
+ * @param {number}              [opts.maxPerWorkspace]
+ * @param {object}              [opts.fsImpl]      injectable fs (tests)
+ */
+export function createBackgroundTasks(opts = {}) {
+  const broadcast = typeof opts.broadcast === 'function' ? opts.broadcast : () => {};
+  const now = opts.now || Date.now;
+  const pollMs = opts.pollMs || DEFAULT_POLL_MS;
+  const quietMs = opts.quietMs || DEFAULT_QUIET_MS;
+  const maxPerWs = opts.maxPerWorkspace || DEFAULT_MAX_PER_WS;
+  const fsi = opts.fsImpl || fs;
+
+  // taskId (= the LAUNCH tool_use id) → task. Keying by the launch id (not the
+  // shellId) means the chat card, which is created at launch time and only knows the
+  // tool_use id, can correlate to live updates without a round-trip.
+  const tasks = new Map();
+  const byShell = new Map(); //  shellId → taskId  (for poll/kill correlation)
+  const pollTargets = new Map(); //  poll tool_use id → shellId  (result arrives later, idless)
+
+  let timer = null;
+
+  function publicView(t) {
+    return {
+      id: t.id,
+      shellId: t.shellId,
+      command: t.command,
+      description: t.description,
+      status: t.status,
+      exitCode: t.exitCode,
+      quiet: t.quiet,
+      startedAt: t.startedAt,
+      endedAt: t.endedAt,
+      lastOutputAt: t.lastOutputAt,
+      hasOutput: t.everExisted,
+      workspaceId: t.workspaceId,
+      threadId: t.threadId,
+      // NB: the absolute outputFile path is deliberately NOT exposed (it leaks the
+      // home dir — same rule the Logs route follows). Tail it via the by-id endpoint.
+    };
+  }
+
+  function emit(t) {
+    broadcast(publicView(t));
+  }
+
+  function prune(workspaceId) {
+    const ours = [...tasks.values()].filter((t) => t.workspaceId === workspaceId);
+    if (ours.length <= maxPerWs) return;
+    // Drop oldest TERMINAL tasks first; never evict something still running.
+    const terminal = ours.filter((t) => TERMINAL.has(t.status)).sort((a, b) => a.startedAt - b.startedAt);
+    let over = ours.length - maxPerWs;
+    for (const t of terminal) {
+      if (over <= 0) break;
+      tasks.delete(t.id);
+      if (t.shellId) byShell.delete(t.shellId);
+      over -= 1;
+    }
+  }
+
+  function startLaunch(workspaceId, threadId, chunk) {
+    const id = chunk.id;
+    if (!id || tasks.has(id)) return;
+    const input = chunk.input || {};
+    const t = {
+      id,
+      shellId: null,
+      outputFile: null,
+      command: String(input.command || '').slice(0, 2000),
+      description: String(input.description || '').slice(0, 300),
+      status: 'running',
+      exitCode: null,
+      quiet: false,
+      startedAt: now(),
+      endedAt: null,
+      lastOutputAt: null,
+      lastSize: 0,
+      everExisted: false,
+      workspaceId,
+      threadId: threadId || null,
+    };
+    tasks.set(id, t);
+    prune(workspaceId);
+    emit(t);
+    ensureTimer();
+  }
+
+  function fillLaunchResult(id, content) {
+    const t = tasks.get(id);
+    if (!t || t.shellId) return; // not a launch, or already resolved
+    const parsed = parseLaunchResult(content);
+    if (!parsed) return;
+    t.shellId = parsed.shellId;
+    t.outputFile = parsed.outputFile;
+    byShell.set(parsed.shellId, id);
+    emit(t);
+  }
+
+  function applyPoll(shellId, parsed) {
+    const id = byShell.get(shellId);
+    if (!id) return;
+    const t = tasks.get(id);
+    if (!t || TERMINAL.has(t.status)) return;
+    if (parsed.status === 'running') {
+      // A live poll proves it's alive right now — clears any `quiet` flag.
+      t.lastOutputAt = now();
+      if (t.quiet) { t.quiet = false; emit(t); }
+      return;
+    }
+    t.status = parsed.status;
+    t.exitCode = parsed.exitCode;
+    t.endedAt = now();
+    t.quiet = false;
+    emit(t);
+  }
+
+  function applyKill(shellId) {
+    const id = byShell.get(shellId);
+    if (!id) return;
+    const t = tasks.get(id);
+    if (!t || TERMINAL.has(t.status)) return;
+    t.status = 'killed';
+    t.endedAt = now();
+    t.quiet = false;
+    emit(t);
+  }
+
+  /**
+   * Fold one normalized chunk (from session.on('chunk')) into the registry. Only
+   * tool-use/tool-result chunks matter; everything else is ignored cheaply.
+   */
+  function observe(workspaceId, threadId, chunk) {
+    if (!chunk || !workspaceId) return;
+    if (chunk.type === 'tool-use') {
+      const name = chunk.name;
+      const input = chunk.input || {};
+      if (name === 'Bash' && input.run_in_background === true) {
+        startLaunch(workspaceId, threadId, chunk);
+      } else if (POLL_TOOLS.has(name)) {
+        const sid = targetShellId(input);
+        if (sid && chunk.id) pollTargets.set(chunk.id, sid);
+      } else if (KILL_TOOLS.has(name)) {
+        const sid = targetShellId(input);
+        if (sid) applyKill(sid);
+      }
+      return;
+    }
+    if (chunk.type === 'tool-result') {
+      const id = chunk.id;
+      if (!id) return;
+      if (tasks.has(id)) {
+        // The launching Bash's own result — carries the shell id + output path.
+        fillLaunchResult(id, chunk.content);
+      } else if (pollTargets.has(id)) {
+        const sid = pollTargets.get(id);
+        pollTargets.delete(id);
+        const parsed = parsePollResult(chunk.content);
+        if (parsed) applyPoll(sid, parsed);
+      }
+    }
+  }
+
+  // --- file-watcher: process-independent liveness for the gap between launch and
+  // the agent's next poll (which, in the per-turn model, may never come). -------
+  function tick() {
+    const t = now();
+    let anyLive = false;
+    for (const task of tasks.values()) {
+      if (TERMINAL.has(task.status)) continue;
+      anyLive = true;
+      if (!task.outputFile) continue;
+      let size = null;
+      try {
+        size = fsi.statSync(task.outputFile).size;
+      } catch {
+        size = null; // not created yet, or cleaned up after finishing
+      }
+      if (size !== null) {
+        if (!task.everExisted) task.everExisted = true;
+        if (size > task.lastSize) {
+          task.lastSize = size;
+          task.lastOutputAt = t;
+          if (task.quiet) { task.quiet = false; emit(task); }
+          continue;
+        }
+      }
+      // No new bytes this tick. Flag (or clear) the `quiet` hint honestly.
+      const idle = t - (task.lastOutputAt || task.startedAt);
+      const quiet = idle >= quietMs;
+      if (quiet !== task.quiet) { task.quiet = quiet; emit(task); }
+    }
+    if (!anyLive) stopTimer(); // nothing live → stop polling; observe() restarts it
+  }
+
+  function ensureTimer() {
+    if (timer) return;
+    timer = setInterval(tick, pollMs);
+    if (typeof timer.unref === 'function') timer.unref(); // never hold the process open
+  }
+  function stopTimer() {
+    if (timer) { clearInterval(timer); timer = null; }
+  }
+
+  return {
+    observe,
+    /** All tasks for a workspace, newest first. */
+    list(workspaceId) {
+      return [...tasks.values()]
+        .filter((t) => t.workspaceId === workspaceId)
+        .sort((a, b) => b.startedAt - a.startedAt)
+        .map(publicView);
+    },
+    /** Tail the output file for one task (best-effort; null if unavailable). */
+    tail(workspaceId, taskId, bytes = TAIL_BYTES) {
+      const t = tasks.get(taskId);
+      if (!t || t.workspaceId !== workspaceId || !t.outputFile) return null;
+      try {
+        const stat = fsi.statSync(t.outputFile);
+        const start = Math.max(0, stat.size - bytes);
+        const fd = fsi.openSync(t.outputFile, 'r');
+        try {
+          const len = stat.size - start;
+          const buf = Buffer.alloc(len);
+          fsi.readSync(fd, buf, 0, len, start);
+          return buf.toString('utf8');
+        } finally {
+          fsi.closeSync(fd);
+        }
+      } catch {
+        return null;
+      }
+    },
+    /** Test/diagnostic: the internal task (incl. outputFile). */
+    _get(taskId) {
+      return tasks.get(taskId) || null;
+    },
+    _tick: tick,
+    dispose: stopTimer,
+  };
+}

package/server/src/index.mjs

@@ -84,6 +84,7 @@ import { loadAccount } from './account.mjs';
 import { getOperatorToken } from './operator.mjs';
 import { runDoctor } from './doctor.mjs';
 import { appendLine, tailFile, logFile, listLogs, TAILABLE, globalDir } from './logpaths.mjs';
+import { createBackgroundTasks } from './background-tasks.mjs';
 import { SessionReporter } from './session-reporter.mjs';
 import { TranscriptRecorder } from './transcript.mjs';
 import { loadObservabilityConsent, setObservabilityConsent } from './observability.mjs';
@@ -578,6 +579,23 @@ export async function createServer(overrides = {}) {
     }
   }
 
+  // Background-task frames are WORKSPACE-scoped but THREAD-agnostic: a job the agent
+  // launched in chat A is still "running in this workspace", so the topbar tray and
+  // the canvas Tasks block (which span threads) must see it. Sent to every socket on
+  // the workspace, regardless of which chat thread it's bound to.
+  function broadcastTask(task) {
+    if (!task || !task.workspaceId) return;
+    const data = JSON.stringify({ type: 'task', task });
+    for (const ws of chatClients) {
+      if (ws.readyState !== ws.OPEN) continue;
+      if (ws._wsWorkspaceId !== task.workspaceId) continue;
+      ws.send(data);
+    }
+  }
+  // The registry persists ACROSS turns (a background job outlives the `claude -p`
+  // process that spawned it), so it lives here in server scope — never per-session.
+  const bgTasks = createBackgroundTasks({ broadcast: broadcastTask });
+
   /**
    * Run one chat turn: spawn the agent, stream every chunk to every chat
    * client, and persist the resulting session id so the next turn resumes it.
@@ -644,6 +662,10 @@ export async function createServer(overrides = {}) {
           return;
         }
         if (chunk.type === 'error') sawError = true;
+        // Track background jobs (Bash run_in_background:true + any TaskOutput/BashOutput
+        // polls) so the chat card, topbar tray, and Tasks block can show live status.
+        // Cheap no-op for every other chunk type.
+        bgTasks.observe(workspace.id, threadId, chunk);
         broadcastChat({ type: 'chunk', messageId: id, chunk }, workspace.id, threadId);
         activityBus.publish({ type: 'chat-stream', messageId: id, chunk });
         // Surface the turn's token/cost totals so the activity bar can show
@@ -2554,6 +2576,27 @@ export async function createServer(overrides = {}) {
     return c.json({ name, lines, body: tailFile(logFile(name), lines) });
   });
 
+  // Background tasks (the agent's run_in_background jobs) — what's running, finished,
+  // or gone quiet. Owner-only (fileTree): these expose the commands the agent ran on
+  // the host, which a share-link viewer must not see (same posture as Logs). The
+  // absolute output-file path is never returned (it would leak the home dir); tail it
+  // by id instead.
+  app.get('/api/workspace/tasks', (c) => {
+    const forbidden = require(c, 'fileTree');
+    if (forbidden) return forbidden;
+    return c.json({ tasks: bgTasks.list(workspaceFor(c).id) });
+  });
+
+  app.get('/api/workspace/tasks/:id/output', (c) => {
+    const forbidden = require(c, 'fileTree');
+    if (forbidden) return forbidden;
+    const id = c.req.param('id');
+    const bytes = Math.min(Number(c.req.query('bytes')) || 16384, 200_000);
+    const output = bgTasks.tail(workspaceFor(c).id, id, bytes);
+    if (output === null) return c.json({ error: 'no-output', id }, 404);
+    return c.json({ id, output });
+  });
+
   // --- component inbox ---
   app.get('/api/inbox', async (c) => {
     // Enforce the `inbox` capability (partner-only). It existed in the matrix