clay-server 5.3.0-beta.6 → 5.3.0

package/lib/sdk-message-processor.js

@@ -229,7 +229,8 @@ function attachMessageProcessor(ctx) {
       // only clears ambient watchers must not rebroadcast the session list.
       var previousBackgroundTaskCount = backgroundTaskTiming.countUserTasks(session.activeBackgroundTasks);
       session.activeBackgroundTasks = [];
-      sendToSession(session, { type: "active_background_tasks", tasks: [] });
+      session.backgroundTaskCatalog = null;
+      sendToSession(session, { type: "active_background_tasks", tasks: [], catalog: [] });
       if (previousBackgroundTaskCount !== 0) sm.broadcastSessionList();
       var fsSkills = discoverSkillDirs(getSessionSkillOptions(session));
       session.skillNames = Array.from(mergeSkills(parsed.skills, fsSkills));
@@ -463,6 +464,7 @@ function attachMessageProcessor(ctx) {
 
     } else if (parsed.yokeType === "subagent_message") {
       // Sub-agent messages: extract tool_use blocks for activity display
+      require("./project-background-tasks").observeMessage(session, parsed, sendToSession);
       processSubagentMessage(session, parsed);
 
     } else if (parsed.yokeType === "message") {
@@ -864,7 +866,8 @@ function attachMessageProcessor(ctx) {
         Array.isArray(parsed.tasks) ? parsed.tasks : []
       );
       session.activeBackgroundTasks = activeBackgroundTasks;
-      sendToSession(session, { type: "active_background_tasks", tasks: activeBackgroundTasks });
+      var taskCatalog = require("./project-background-tasks").remember(session, activeBackgroundTasks);
+      sendToSession(session, { type: "active_background_tasks", tasks: activeBackgroundTasks, catalog: taskCatalog });
       if (previousBackgroundTaskCount !== backgroundTaskTiming.countUserTasks(activeBackgroundTasks)) {
         sm.broadcastSessionList();
       }

package/lib/server-storage.js

@@ -6,6 +6,21 @@ function attachStorage(ctx) {
   var progress = null;
   var expires = 0;
   var failed = false;
+  var scanIdentity = null;
+  function projectIdentity() {
+    return JSON.stringify((ctx.getProjects ? ctx.getProjects() : []).map(function (project) { return [project.slug, project.path, project.projectOwnerId, project.isMate]; }));
+  }
+  function targetProject(slug) {
+    return (ctx.getProjects ? ctx.getProjects() : []).find(function (project) { return project.slug === slug && !project.isMate && !/^mate-/.test(slug); });
+  }
+  function usageReply(req, res, result, slug) {
+    if (!authorized(req, res)) return;
+    if (!slug) { reply(res, result.scanning ? 202 : 200, result); return; }
+    if (!targetProject(slug)) { reply(res, 404, { error: 'Project is no longer registered.' }); return; }
+    if (scanIdentity !== projectIdentity()) { reply(res, 409, { error: 'Project registration changed. Refresh usage.' }); return; }
+    var usage = (result.projects || []).find(function (project) { return project.slug === slug; });
+    reply(res, result.scanning ? 202 : 200, { slug: slug, scanning: !!result.scanning, partial: !!result.partial, checkedAt: result.checkedAt || null, usage: usage || null });
+  }
   function reply(res, status, data) {
     res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
     res.end(JSON.stringify(data));
@@ -19,14 +34,23 @@ function attachStorage(ctx) {
     return true;
   }
   function handleRequest(req, res, url) {
-    if (url.split('?')[0] !== '/api/server/storage') return false;
+    var pathname = url.split('?')[0];
+    var match = /^\/api\/server\/storage\/project\/([^/]+)$/.exec(pathname);
+    if (pathname !== '/api/server/storage' && !match) return false;
+    var slug = null;
     var refresh = new URL(url, 'http://localhost').searchParams.get('refresh') === '1';
     if (!authorized(req, res)) return true;
     if (req.method !== 'GET') { reply(res, 405, { error: 'Method not allowed.' }); return true; }
+    if (match) {
+      try { slug = decodeURIComponent(match[1]); } catch (error) { reply(res, 400, { error: 'Invalid project.' }); return true; }
+      if (!targetProject(slug)) { reply(res, 404, { error: 'Project not found.' }); return true; }
+    }
+    if (!pending && scanIdentity !== projectIdentity()) { cached = null; failed = false; }
     if (failed && Date.now() < expires) { reply(res, 500, { error: 'Disk usage could not be measured. Try again in a few seconds.' }); return true; }
-    if (!pending && !refresh && cached && Date.now() < expires) { reply(res, 200, cached); return true; }
+    if (!pending && !refresh && cached && Date.now() < expires) { usageReply(req, res, cached, slug); return true; }
     if (!pending) {
       progress = null; failed = false;
+      scanIdentity = projectIdentity();
       var users = ctx.users.getAllUsers();
       var projects = ctx.getProjects ? ctx.getProjects() : [];
       if (!ctx.users.isMultiUser() && users.length <= 1) {
@@ -45,7 +69,7 @@ function attachStorage(ctx) {
       timer = setTimeout(function () { resolve(progress || { scanning: true }); }, 750);
     })]).then(function (result) {
       clearTimeout(timer);
-      if (!res.destroyed && authorized(req, res)) reply(res, result.scanning ? 202 : 200, result);
+      if (!res.destroyed) usageReply(req, res, result, slug);
     }).catch(function () {
       clearTimeout(timer);
       if (!res.destroyed) reply(res, 500, { error: 'Disk usage could not be measured. Try refreshing.' });

package/lib/server.js

@@ -519,7 +519,7 @@ function createServer(opts) {
     } : null;
     var payload = JSON.stringify(seed).replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
     var script = '<script>window.__clayAppearanceSeed=' + payload + ';</script>';
-    return html.replace('<script src="appearance-bootstrap.js"></script>', script + '<script src="appearance-bootstrap.js"></script>');
+    return html.replace(/<script src="\/?appearance-bootstrap.js"><\/script>/, function (tag) { return script + tag; });
   }
 
   function sendAppShell(req, res, slug) {
@@ -1103,8 +1103,10 @@ function createServer(opts) {
       if (!httpUser || !canUserAccessSlug(httpUser.id, slug)) {
         var overview = httpUser && administrativeMetadata(httpUser.id, slug);
         if (overview && req.method === "GET" && (projectUrlForAuth === "/" || projectUrlForAuth === "/index.html")) {
+          var overviewAppearance = null;
+          try { overviewAppearance = settings.getInitialAppearance(req); } catch (error) {}
           res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
-          res.end(projectAdminOverview.page(overview, getVisibleProjects(httpUser.id)));
+          res.end(injectAppearanceSeed(projectAdminOverview.page(overview, getVisibleProjects(httpUser.id)), overviewAppearance));
           return;
         }
         res.writeHead(403, { "Content-Type": "application/json", "Cache-Control": "no-store" });

package/lib/sessions.js

@@ -886,7 +886,7 @@ function createSessionManager(opts) {
     if (session.isProcessing) {
       _send({ type: "status", status: "processing" });
     }
-    _send({ type: "active_background_tasks", tasks: session.activeBackgroundTasks || [] });
+    _send({ type: "active_background_tasks", tasks: session.activeBackgroundTasks || [], catalog: session.backgroundTaskCatalog && session.backgroundTaskCatalog.tasks || [] });
 
     // Re-send any pending permission requests
     var pendingIds = Object.keys(session.pendingPermissions);

package/lib/storage-usage.js

@@ -39,10 +39,26 @@ async function scanStorage(options) {
     if (identity && !owners.get(identity.uid)) rows[index].mapped = false;
   });
   var projectRoots = new Map();
+  var projectUsage = [];
+  var usageRoots = new Map();
   var projectErrors = 0;
   for (var project of projects) {
+    var usage = { slug: project.slug, available: false, bytes: 0, files: 0, capacityBytes: null, availableBytes: null };
+    if (!project.isMate && project.slug) projectUsage.push(usage);
     try {
       var projectPath = await fs.realpath(project.path);
+      usage.available = true;
+      if (usageRoots.has(projectPath)) {
+        var priorUsage = usageRoots.get(projectPath);
+        if (priorUsage) priorUsage.available = false;
+        usage.available = false;
+        usageRoots.set(projectPath, null);
+      } else usageRoots.set(projectPath, project.isMate ? null : usage);
+      try {
+        var volume = await fs.statfs(projectPath);
+        usage.capacityBytes = volume.blocks * volume.bsize;
+        usage.availableBytes = volume.bavail * volume.bsize;
+      } catch (error) { /* Volume capacity can be unavailable independently of allocation. */ }
       var row = rows.find(function (item) { return item.id === project.projectOwnerId; }) || null;
       if (row) row.projects++;
       if (projectRoots.has(projectPath) && projectRoots.get(projectPath) !== row) row = null;
@@ -50,21 +66,20 @@ async function scanStorage(options) {
     } catch (error) { projectErrors++; }
   }
   var orderedProjects = Array.from(projectRoots.keys()).sort(function (a, b) { return b.length - a.length; });
-  function projectOwner(filePath) {
-    var root = orderedProjects.find(function (candidate) { return filePath === candidate || filePath.indexOf(candidate + path.sep) === 0; });
-    return root ? projectRoots.get(root) : null;
+  function projectRoot(filePath) {
+    return orderedProjects.find(function (candidate) { return filePath === candidate || filePath.indexOf(candidate + path.sep) === 0; });
   }
   var roots = orderedProjects.concat(options.projectPaths || []);
   identities.forEach(function (identity) { if (identity) roots.push(identity.home); });
   roots.push(options.configDir);
-  var report = { attribution: projectMode ? "project" : "filesystem", users: rows, totalBytes: 0, totalFiles: 0, unattributedBytes: 0, unattributedFiles: 0,
+  var report = { attribution: projectMode ? "project" : "filesystem", users: rows, projects: projectUsage, totalBytes: 0, totalFiles: 0, unattributedBytes: 0, unattributedFiles: 0,
     partial: false, errors: projectErrors + users.filter(function (user, index) { return !projectMode && options.platform === 'linux' && user.linuxUser && !identities[index]; }).length, skippedLinks: 0, skippedMounts: 0, scannedEntries: 0, roots: 0, platform: options.platform };
   var lastProgress = 0;
   function progress() {
     if (!options.onProgress || Date.now() - lastProgress < 500) return;
     lastProgress = Date.now();
     options.onProgress(Object.assign({}, report, { scanning: true, checkedAt: new Date().toISOString(),
-      users: rows.map(function (row) { return Object.assign({}, row); }) }));
+      users: rows.map(function (row) { return Object.assign({}, row); }), projects: projectUsage.map(function (row) { return Object.assign({}, row); }) }));
   }
   progress();
   var seen = new Map();
@@ -118,9 +133,15 @@ async function scanStorage(options) {
     if (stat.isSymbolicLink()) { report.skippedLinks++; return; }
     if (stat.dev !== device) { report.skippedMounts++; return; }
     var key = stat.dev + ':' + stat.ino;
-    var owner = projectMode ? projectOwner(filePath) : owners.get(stat.uid);
+    var usageRoot = projectRoot(filePath);
+    var owner = projectMode ? projectRoots.get(usageRoot) : owners.get(stat.uid);
+    var usage = usageRoot && usageRoots.get(usageRoot);
     if (seen.has(key)) {
       var previous = seen.get(key);
+      if (stat.isFile() && previous.project && usage && previous.project !== usage) {
+        previous.project.bytes -= previous.bytes; previous.project.files--;
+        previous.project = null;
+      }
       if (projectMode && stat.isFile() && previous.owner && previous.owner !== owner) {
         previous.owner.bytes -= previous.bytes; previous.owner.files--;
         report.unattributedBytes += previous.bytes; report.unattributedFiles++;
@@ -132,7 +153,8 @@ async function scanStorage(options) {
     if (!stat.isDirectory() && !stat.isFile()) return;
     var bytes = typeof stat.blocks === 'number' ? stat.blocks * 512 : stat.size;
     // Only directories and multiply-linked files need identity deduplication.
-    if (stat.isDirectory() || stat.nlink > 1) seen.set(key, { owner: owner, bytes: bytes });
+    if (stat.isDirectory() || stat.nlink > 1) seen.set(key, { owner: owner, project: usage, bytes: bytes });
+    if (usage) { usage.bytes += bytes; if (stat.isFile()) usage.files++; }
     report.totalBytes += bytes;
     if (stat.isFile()) report.totalFiles++;
     if (owner) { owner.bytes += bytes; if (stat.isFile()) owner.files++; }

package/lib/terminal-manager.js

@@ -136,9 +136,9 @@ function createTerminalManager(opts) {
       sendTo(ws, { type: "term_output", id: id, data: replay });
     }
 
-    // Send current terminal dimensions so the client renders at the correct size
+    // This snapshot may arrive after the attaching client has fitted a new viewport.
     if (!alreadySubscribed && session.cols && session.rows) {
-      sendTo(ws, { type: "term_resized", id: id, cols: session.cols, rows: session.rows });
+      sendTo(ws, { type: "term_resized", id: id, cols: session.cols, rows: session.rows, initial: true });
     }
 
     // If already exited, notify

package/lib/worker-message-previews.js

@@ -0,0 +1,50 @@
+// Bounded, exact-owner message previews use the Worker reader's existing authority.
+function latest(history) {
+  var found = null;
+  for (var i = history.length - 1, stop = Math.max(0, history.length - 1000); i >= stop; i--) {
+    var entry = history[i];
+    if (entry && (entry.type === 'delta' || entry.type === 'assistant_message') && typeof entry.text === 'string' && entry.text.trim()) {
+      var index = i, text = entry.text;
+      while (index > stop && history[index - 1].type === 'delta' && entry.type === 'delta' ) { index--; text = (history[index].text + text).slice(0, 1200); }
+      found = { id: String(index), text: text.slice(0, 1200), timestamp: history[index]._ts || null }; break;
+    }
+  }
+  return found;
+}
+function attach(ctx) {
+  var subscriptions = new WeakMap();
+  function release(ws) {
+    var old = subscriptions.get(ws); if (!old) return;
+    subscriptions.delete(ws); old.entries.forEach(function (entry) { clearTimeout(entry.timer); if (entry.release) entry.release(); });
+    if (ws.removeListener) ws.removeListener('close', old.close);
+  }
+  function handleMessage(ws, msg) {
+    if (msg.type !== 'split_worker_preview_request') return false;
+    release(ws);
+    if (typeof msg.requestId !== 'string' || msg.requestId.length > 160 || !Array.isArray(msg.targets) || msg.targets.length > 32) return true;
+    var state = { entries: [], close: function () { release(ws); } }; subscriptions.set(ws, state);
+    msg.targets.forEach(function (target) {
+      var pair = ctx.resolve(ws, target); if (!pair || state.entries.some(function (entry) { return entry.worker === pair.worker; })) return;
+      var entry = { worker: pair.worker, timer: null, last: null };
+      function send(live) {
+        var current = ctx.resolve(ws, target);
+        if (subscriptions.get(ws) !== state || ws.readyState !== 1 || !current || current.driver !== pair.driver || current.worker !== pair.worker) { if (entry.release) entry.release(); return; }
+        var preview = latest(pair.worker.history || []); if (!preview) return;
+        preview.vendor = pair.worker.vendor || null;
+        if (entry.last === JSON.stringify(preview)) return;
+        entry.last = JSON.stringify(preview);
+        ctx.send(ws, { type: 'split_worker_message_preview', requestId: msg.requestId, parentSessionOriginId: target.parentSessionOriginId,
+          workerSessionOriginId: target.workerSessionOriginId, generation: target.generation, live: live, preview: preview });
+      }
+      entry.release = ctx.sm.subscribeSession(pair.worker.localId, function (event) {
+        if (!event || ['delta', 'assistant_message'].indexOf(event.type) < 0 || entry.timer) return;
+        entry.timer = setTimeout(function () { entry.timer = null; send(true); }, 60);
+      });
+      state.entries.push(entry); send(false);
+    });
+    if (ws.once) ws.once('close', state.close);
+    return true;
+  }
+  return { handleMessage: handleMessage };
+}
+module.exports = { attach: attach, latest: latest };

package/lib/ws-schema.js

@@ -24,7 +24,7 @@ var schema = {
   "switch_session":           { direction: "c2s", handler: "lib/project-sessions.js", description: "Switch the active session by local ID" },
   "resume_tui_session":       { direction: "c2s", handler: "lib/project-sessions.js", description: "Spawn the claude --resume PTY for a TUI session shown read-only (lazy resume)" },
   "suspend_tui_session":      { direction: "c2s", handler: "lib/project-sessions.js", description: "Close a live TUI session's PTY now but keep it resumable (explicit Close)" },
-  "new_session":              { direction: "c2s", handler: "lib/project-sessions.js", description: "Create a new blank session (opts: vendor, mode, sessionVisibility, dangerouslySkipPermissions)" },
+  "new_session":              { direction: "c2s", handler: "lib/project-sessions.js", description: "Create a blank session; correlated ordinary-project requests may use activate:false to preserve the current View selection" },
   "new_session_result":       { direction: "s2c", handler: "lib/public/modules/scheduled-tasks.js", description: "Correlated result for a requested new session" },
   "delete_session":           { direction: "c2s", handler: "lib/project-sessions.js", description: "Delete a session by ID" },
   "rename_session":           { direction: "c2s", handler: "lib/project-sessions.js", description: "Rename a session" },

package/lib/yoke/adapters/claude-worker.js

@@ -97,6 +97,8 @@ function applyWorkerClaudeBinary(options) {
 // --- State ---
 var sdkModule = null;
 var queryInstance = null;
+var taskReader = null;
+var taskReaderModule = require("../claude-task-reader");
 var messageQueue = null;
 var abortController = null;
 var pendingPermissions = {};  // requestId -> resolve
@@ -284,6 +286,9 @@ function handleMessage(msg) {
     case "set_permission_mode":
       handleSetPermissionMode(msg);
       break;
+    case "read_background_task":
+      taskReaderModule.respond(taskReader, msg, sendToDaemon);
+      break;
     case "stop_task":
       handleStopTask(msg);
       break;
@@ -598,6 +603,8 @@ async function handleQueryStart(msg) {
       prompt: messageQueue,
       options: options,
     });
+    if (taskReader) taskReader.close();
+    taskReader = taskReaderModule.createReader(getSDK, function () { return queryInstance; }, options.cwd);
     perf("query instance created");
   } catch (e) {
     sendToDaemon({ type: "query_error", error: "Failed to create query: " + (e.message || e), exitCode: null, stderr: null });
@@ -618,6 +625,7 @@ async function handleQueryStart(msg) {
     var firstText = true;
     var eventCounts = {};
     for await (var event of queryInstance) {
+      taskReader.observe(event);
       var etype = (event && event.type || "?");
       var esubtype = (event && event.subtype || "");
       eventCounts[etype] = (eventCounts[etype] || 0) + 1;

package/lib/yoke/adapters/claude.js

@@ -18,6 +18,7 @@ var claudeUserInput = require("../claude-user-input");
 var claudeCorrelation = require("../claude-message-correlation");
 var claudeContextUsage = require("../claude-context-usage");
 var claudeModelSwitch = require("../claude-model-switch");
+var taskReaderModule = require("../claude-task-reader");
 
 // SDK-specific knowledge stays in the adapter (not the relay): the host dialog
 // kinds this client can render, declared to the SDK when an onUserDialog
@@ -580,6 +581,8 @@ function normalizeBackgroundTasks(tasks) {
       task_id: task && task.task_id,
       task_type: taskType,
       description: (task && task.description) || "",
+      run_id: task && task.run_id || null,
+      parent_task_id: task && task.parent_task_id || null,
       // Housekeeping the CLI does not surface as user work (skip_transcript
       // tasks, auto-started live-update watchers). Clay keeps these out of its
       // activity indicators and lists them as a subdued secondary group.
@@ -597,7 +600,8 @@ function normalizeBackgroundTasks(tasks) {
 // --- QueryHandle ---
 // Wraps a raw SDK query object with the YOKE QueryHandle interface.
 // Events are flattened via flattenEvent before yielding.
-function createQueryHandle(rawQuery, messageQueue, abortController) {
+function createQueryHandle(rawQuery, messageQueue, abortController, cwd) {
+  var taskReader = taskReaderModule.createReader(loadSDK, function () { return closed ? null : rawQuery; }, cwd);
   var correlation = claudeCorrelation.createCorrelation();
   var closed = false;
   var removeAbort = function () {};
@@ -615,6 +619,7 @@ function createQueryHandle(rawQuery, messageQueue, abortController) {
           return rawIter.next().then(function(result) {
             if (result.done) { closed = true; removeAbort(); resolveStopped(); }
             if (result.done) return result;
+            taskReader.observe(result.value);
             return { value: correlation.result(result.value, flattenEvent(result.value)), done: false };
           }, function(err) {
             closed = true;
@@ -676,6 +681,8 @@ function createQueryHandle(rawQuery, messageQueue, abortController) {
       return Promise.resolve();
     },
 
+    readBackgroundTask: taskReader.read,
+
     stopTask: function(taskId) {
       if (rawQuery && typeof rawQuery.stopTask === "function") {
         return rawQuery.stopTask(taskId);
@@ -1107,6 +1114,7 @@ function serializeWorkerValue(value, seen) {
 function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool, onUserDialog, onUserInputRequest, onModelSwitch, preToolUsePolicy) {
   var interactionAbort = new AbortController();
   var contextRequests = claudeContextUsage.createRequests(worker);
+  var taskRequests = taskReaderModule.createRequests(worker);
   var correlation = claudeCorrelation.createCorrelation();
   // Async iterable state
   var iterQueue = [];
@@ -1153,6 +1161,7 @@ function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool,
   function endIter() {
     interactionAbort.abort();
     contextRequests.close();
+    taskRequests.close();
     if (iterEnded) return;
     iterEnded = true;
     if (iterWaiting) {
@@ -1165,6 +1174,7 @@ function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool,
   function errorIter(err) {
     interactionAbort.abort();
     contextRequests.close();
+    taskRequests.close();
     if (iterEnded) return;
     iterEnded = true;
     iterError = err;
@@ -1292,6 +1302,9 @@ function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool,
       case "model_switched":
         if (onModelSwitch) onModelSwitch(msg.change);
         break;
+      case "background_task_response":
+        taskRequests.receive(msg);
+        break;
       case "context_usage_response":
         contextRequests.receive(msg);
         break;
@@ -1458,6 +1471,8 @@ function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool,
       });
     },
 
+    readBackgroundTask: function(input) { return iterEnded ? Promise.reject(new Error("Task connection closed.")) : taskRequests.request(input); },
+
     stopTask: function(taskId) {
       worker.send({ type: "stop_task", taskId: taskId });
       return Promise.resolve();
@@ -1821,7 +1836,7 @@ function createClaudeAdapter(opts) {
 
       claudeModelSwitch.attach(sdkOptions, queryOpts.onModelSwitch);
       var rawQuery = sdk.query({ prompt: mq, options: sdkOptions });
-      return createQueryHandle(rawQuery, mq, ac);
+      return createQueryHandle(rawQuery, mq, ac, sdkOptions.cwd || _cwd);
     },
 
     createOneShotQuery: async function(queryOpts) {

package/lib/yoke/claude-task-reader.js

@@ -0,0 +1,94 @@
+// Native task inspection stays inside the process and OS identity owning the query.
+var crypto = require('crypto');
+function validId(value) { return typeof value === 'string' && /^[a-zA-Z0-9_-]{1,160}$/.test(value); }
+function createReader(loadSdk, getQuery, dir) {
+  var sessionId = null, tasks = new Map(), closed = false;
+  function observe(event) {
+    if (!event) return;
+    if (event.session_id && !event.parent_tool_use_id) sessionId = event.session_id;
+    if (event.type !== 'system') return;
+    if (event.subtype === 'background_tasks_changed') {
+      tasks.forEach(function (task) { task.active = false; });
+      (event.tasks || []).slice(0, 128).forEach(function (task) {
+        if (!validId(task.task_id)) return;
+        var old = tasks.get(task.task_id);
+        if (old && String(old.run_id || '') === String(task.run_id || '') && old.task_type === task.task_type) Object.assign(old, task, { active: true });
+        else tasks.set(task.task_id, Object.assign({}, task, { active: true }));
+      });
+    }
+    if (event.subtype === 'task_notification') {
+      var old = tasks.get(event.task_id);
+      if (old && (!event.run_id || old.run_id === event.run_id)) old.active = false;
+    }
+    while (tasks.size > 128) tasks.delete(tasks.keys().next().value);
+  }
+  async function read(input) {
+    var task = tasks.get(input.taskId), query = getQuery(), parent = sessionId;
+    if (closed || !query || !task || !validId(input.taskId) || String(task.run_id || '') !== String(input.runId || '')) throw new Error('Task binding is unavailable.');
+    var offset = Number.isInteger(input.offset) && input.offset >= 0 && input.offset <= 10000 ? input.offset : 0;
+    function current() { if (closed || query !== getQuery() || parent !== sessionId || tasks.get(input.taskId) !== task) throw new Error('Task binding changed.'); }
+    var result;
+    if (task.task_type === 'local_agent') {
+      if (!parent || !dir) throw new Error('Task transcript is not ready.');
+      var sdk = await loadSdk(); current();
+      var agents = await sdk.listSubagents(parent, { dir: dir }); current();
+      // Never guess a sibling agent from its name, ordering or filesystem path.
+      if (agents.indexOf(task.task_id) < 0) throw new Error('Task transcript is not available yet.');
+      var messages = await sdk.getSubagentMessages(parent, task.task_id, { dir: dir, offset: offset, limit: 101 }); current();
+      result = { kind: 'agent', messages: projectMessages(messages.slice(0, 100), offset), offset: offset, hasMore: messages.length > 100, active: task.active };
+    } else {
+      if (typeof query.getTaskOutput !== 'function') throw new Error('This runtime does not expose task output.');
+      var output = await query.getTaskOutput(task.task_id); current();
+      result = { kind: 'shell', output: String(output.output || '').slice(-8192), truncated: !!output.truncated, active: task.active };
+    }
+    return result;
+  }
+  return { observe: observe, read: read, close: function () { closed = true; tasks.clear(); } };
+}
+function projectMessages(messages, offset) {
+  var rows = [], budget = 180000;
+  messages.forEach(function (message, index) {
+    var content = message.message && message.message.content;
+    if (typeof content === 'string') content = [{ type: 'text', text: content }];
+    if (!Array.isArray(content)) return;
+    content.slice(0, 100).forEach(function (block, blockIndex) {
+      if (budget <= 0) return;
+      var text, role = message.type === 'user' ? 'user' : 'assistant', type = block.type;
+      if (type === 'text') text = block.text;
+      else if (type === 'tool_use') { role = 'tool'; text = block.name + '\n' + JSON.stringify(block.input || {}); }
+      else if (type === 'tool_result') { role = 'tool'; text = typeof block.content === 'string' ? block.content : JSON.stringify(block.content || []); }
+      else return;
+      if (typeof text !== 'string') return;
+      text = text.slice(0, Math.min(16000, budget)); budget -= text.length;
+      rows.push({ role: role, text: text, recordIndex: ((offset || 0) + index) * 100 + blockIndex, recordType: type, toolName: block.name, toolId: block.id || block.tool_use_id, isError: !!block.is_error });
+    });
+  });
+  return rows;
+}
+function createRequests(worker) {
+  var pending = new Map();
+  function close() { pending.forEach(function (entry) { clearTimeout(entry.timer); entry.reject(new Error('Task connection closed.')); }); pending.clear(); }
+  return {
+    close: close,
+    request: function (input) {
+      if (pending.size >= 8) return Promise.reject(new Error('Task reader is busy.'));
+      return new Promise(function (resolve, reject) {
+        var id = crypto.randomUUID();
+        var timer = setTimeout(function () { pending.delete(id); reject(new Error('Task read timed out.')); }, 15000);
+        pending.set(id, { resolve: resolve, reject: reject, timer: timer });
+        try { if (worker.send({ type: 'read_background_task', requestId: id, input: input }) !== true) throw new Error('Task connection closed.'); }
+        catch (error) { pending.delete(id); clearTimeout(timer); reject(error); }
+      });
+    },
+    receive: function (message) {
+      var entry = pending.get(message.requestId); if (!entry) return;
+      pending.delete(message.requestId); clearTimeout(entry.timer);
+      if (message.error) entry.reject(new Error(message.error)); else entry.resolve(message.data);
+    }
+  };
+}
+async function respond(reader, message, send) {
+  try { if (!reader) throw new Error('Task query is unavailable.'); var data = await reader.read(message.input || {}); send({ type: 'background_task_response', requestId: message.requestId, data: data }); }
+  catch (error) { send({ type: 'background_task_response', requestId: message.requestId, error: error.message }); }
+}
+module.exports = { createReader: createReader, createRequests: createRequests, respond: respond, projectMessages: projectMessages };

package/lib/yoke/interface.js

@@ -198,6 +198,7 @@ var INITIALIZE_TIMEOUT_MS = 90000;
  *   .setModel(model)
  *   .setEffort(effort)
  *   .setToolPolicy(policy)    - "ask" | "allow-all"
+ *   .readBackgroundTask({ taskId, runId, offset }) - optional bounded native transcript/output read
  *   .stopTask(taskId)
  *   .getContextUsage()        - Promise<object|null>
  *   .endInput()               - stop accepting turns after queued input drains

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clay-server",
-  "version": "5.3.0-beta.6",
+  "version": "5.3.0",
   "description": "Self-hosted team workspace for Claude Code and Codex. Multi-user, browser-based, with persistent AI mates.",
   "bin": {
     "clay-server": "./bin/cli.js"