@mclean-capital/neura 3.5.2 → 3.5.4

package/core/server.bundled.mjs

@@ -8013,6 +8013,7 @@ __export(work_item_queries_exports, {
   deleteWorkItem: () => deleteWorkItem,
   getOpenWorkItems: () => getOpenWorkItems,
   getWorkItem: () => getWorkItem,
+  getWorkItemByWorkerId: () => getWorkItemByWorkerId,
   getWorkItems: () => getWorkItems,
   updateWorkItem: () => updateWorkItem
 });
@@ -8051,6 +8052,13 @@ async function getWorkItem(db, id) {
   const result = await db.query("SELECT * FROM work_items WHERE id = $1", [id]);
   return result.rows.length > 0 ? mapWorkItem(result.rows[0]) : null;
 }
+async function getWorkItemByWorkerId(db, workerId) {
+  const result = await db.query(
+    "SELECT * FROM work_items WHERE worker_id = $1 LIMIT 1",
+    [workerId]
+  );
+  return result.rows.length > 0 ? mapWorkItem(result.rows[0]) : null;
+}
 async function createWorkItem(db, title, priority, options) {
   const id = crypto3.randomUUID();
   await db.query(
@@ -73035,7 +73043,9 @@ function loadNeuraSkills(options = {}) {
   const repoLocal = resolve(cwd, ".neura", "skills");
   const global2 = options.globalSkillsDir ?? resolve(homedir2(), ".neura", "skills");
   const explicit = options.explicitPaths ?? [];
-  const skillPaths = [repoLocal, global2, ...explicit];
+  const skillPaths = [repoLocal, global2];
+  if (options.bundledSkillsDir) skillPaths.push(options.bundledSkillsDir);
+  skillPaths.push(...explicit);
   log12.info("loading Neura skills (repo-local \u2192 global \u2192 explicit, pi defaults excluded)", {
     cwd,
     skillPaths
@@ -73142,6 +73152,7 @@ var SkillWatcher = class {
   registry;
   cwd;
   globalSkillsDir;
+  bundledSkillsDir;
   explicitPaths;
   debounceMs;
   onReload;
@@ -73153,6 +73164,7 @@ var SkillWatcher = class {
     this.registry = options.registry;
     this.cwd = options.cwd ?? process.cwd();
     this.globalSkillsDir = options.globalSkillsDir ?? resolve2(homedir3(), ".neura", "skills");
+    this.bundledSkillsDir = options.bundledSkillsDir;
     this.explicitPaths = options.explicitPaths ?? [];
     this.debounceMs = options.debounceMs ?? 200;
     this.onReload = options.onReload;
@@ -73165,7 +73177,9 @@ var SkillWatcher = class {
     if (this.watcher) return;
     this.reload();
     const repoLocal = resolve2(this.cwd, ".neura", "skills");
-    const paths = [repoLocal, this.globalSkillsDir, ...this.explicitPaths];
+    const paths = [repoLocal, this.globalSkillsDir];
+    if (this.bundledSkillsDir) paths.push(this.bundledSkillsDir);
+    paths.push(...this.explicitPaths);
     log13.info("starting skill watcher", { paths, debounceMs: this.debounceMs });
     this.watcher = chokidar.watch(paths, {
       ignoreInitial: true,
@@ -73241,6 +73255,7 @@ var SkillWatcher = class {
       const result = loadNeuraSkills({
         cwd: this.cwd,
         globalSkillsDir: this.globalSkillsDir,
+        bundledSkillsDir: this.bundledSkillsDir,
         explicitPaths: this.explicitPaths
       });
       this.registry.replaceAll(result.skills);
@@ -76084,6 +76099,18 @@ var MEMORY_NAMES = /* @__PURE__ */ new Set([
   "memory_stats"
 ]);
 
+// src/tools/voice-redact.ts
+function redactTaskForVoice(task) {
+  const { workerId, ...rest } = task;
+  return { ...rest, hasActiveWorker: workerId !== null };
+}
+function redactCommentForVoice(comment) {
+  if (comment.author.startsWith("worker:")) {
+    return { ...comment, author: "worker" };
+  }
+  return comment;
+}
+
 // src/tools/task-tools.ts
 var log15 = new Logger("tool:task");
 var ALL_STATUSES = [
@@ -76099,7 +76126,6 @@ var ALL_STATUSES = [
 ];
 var COMMENT_TYPES = [
   "progress",
-  "heartbeat",
   "clarification_request",
   "approval_request",
   "clarification_response",
@@ -76199,7 +76225,7 @@ var taskToolDefs = [
   {
     type: "function",
     name: "update_task",
-    description: "Update a task: field changes, status transitions, and/or comment appends (unified with the worker protocol). Workers use this for report_progress / heartbeat / request_clarification / request_approval / complete_task / fail_task. Orchestrator uses it for user responses (clarification_response / approval_response) and field edits.",
+    description: "Update a task: field changes, status transitions, and/or comment appends (unified with the worker protocol). Workers use this for report_progress / request_clarification / request_approval / complete_task / fail_task. Orchestrator uses it for user responses (clarification_response / approval_response) and field edits.",
     parameters: {
       type: "object",
       properties: {
@@ -76325,7 +76351,12 @@ async function handleTaskTool(name, args, ctx) {
               goal: t2.goal,
               source: t2.source,
               version: t2.version,
-              workerId: t2.workerId
+              // workerId deliberately omitted from the voice-facing
+              // listing — TTS reads UUIDs letter-by-letter. Callers
+              // that need the worker id should go through
+              // list_active_workers (which runs internal tool calls
+              // that don't narrate).
+              hasActiveWorker: t2.workerId !== null
             }))
           }
         };
@@ -76337,14 +76368,25 @@ async function handleTaskTool(name, args, ctx) {
         if (!task) return { result: { found: false } };
         let comments = [];
         try {
-          comments = await ctx.taskTools.listTaskComments(task.id, { limit: 50 });
+          const recentDesc = await ctx.taskTools.listTaskComments(task.id, {
+            limit: 50,
+            order: "desc",
+            excludeTypes: ["heartbeat"]
+          });
+          comments = recentDesc.reverse();
         } catch (err) {
-          log15.warn("failed to load task comments for get_task", {
+          log15.error("failed to load task comments for get_task", {
             taskId: task.id,
             err: String(err)
           });
         }
-        return { result: { found: true, task, comments } };
+        return {
+          result: {
+            found: true,
+            task: redactTaskForVoice(task),
+            comments: comments.map(redactCommentForVoice)
+          }
+        };
       }
       case "update_task": {
         if (!ctx.taskTools) return { error: "Task system not available" };
@@ -76923,6 +76965,8 @@ import {
   SessionManager
 } from "@mariozechner/pi-coding-agent";
 var log19 = new Logger("pi-runtime");
+var ALIVE_PULSE_THROTTLE_MS = 3e4;
+var ALIVE_INTERVAL_MS = 6e4;
 var BRIDGE_EVENT_TYPES = /* @__PURE__ */ new Set([
   "agent_start",
   "agent_end",
@@ -76993,6 +77037,15 @@ var PiRuntime = class {
   handleAgentEvent(workerId, event) {
     const worker = this.active.get(workerId);
     if (!worker) return;
+    const now = Date.now();
+    if (now - worker.lastAliveAt >= ALIVE_PULSE_THROTTLE_MS) {
+      worker.lastAliveAt = now;
+      try {
+        worker.callbacks.onAlive?.();
+      } catch (err) {
+        log19.warn("onAlive callback threw", { workerId, err: String(err) });
+      }
+    }
     if (event.type === "agent_start") {
       worker.callbacks.onStatusChange?.("running");
     } else if (event.type === "agent_end") {
@@ -77026,6 +77079,10 @@ var PiRuntime = class {
       worker.callbacks.onStatusChange?.(finalStatus);
       worker.callbacks.onComplete?.(result);
       worker.resolveDone(result);
+      if (worker.aliveInterval) {
+        clearInterval(worker.aliveInterval);
+        worker.aliveInterval = void 0;
+      }
       if (finalStatus !== "idle_partial") {
         this.active.delete(workerId);
       } else {
@@ -77034,6 +77091,28 @@ var PiRuntime = class {
     }
     return result;
   }
+  /**
+   * Start the defense-in-depth interval that refreshes the worker's
+   * lease on a timer, independent of pi's event stream. Pi's bash
+   * tool (and any custom tool that doesn't stream) can go silent for
+   * minutes between `tool_execution_start` and `_end`; without this
+   * pulse the lease would expire and crash-recovery could kill a
+   * perfectly healthy worker that's just waiting on a subprocess.
+   * `unref()` so the timer doesn't keep the process alive on its own.
+   */
+  startAliveInterval(worker) {
+    worker.aliveInterval = setInterval(() => {
+      try {
+        worker.callbacks.onAlive?.();
+      } catch (err) {
+        log19.warn("interval onAlive callback threw", {
+          workerId: worker.workerId,
+          err: String(err)
+        });
+      }
+    }, ALIVE_INTERVAL_MS);
+    worker.aliveInterval.unref?.();
+  }
   /**
    * Authoritative `stopReason` → `WorkerStatus` mapping. Matches the
    * table in docs/phase6-os-core.md exactly:
@@ -77084,9 +77163,11 @@ var PiRuntime = class {
       resolveDone,
       idleWaiters: [],
       pendingPause: false,
-      callbacks
+      callbacks,
+      lastAliveAt: 0
     };
     this.active.set(workerId, worker);
+    this.startAliveInterval(worker);
     session.prompt(task.description).then(() => {
       const stopReason = this.extractStopReasonFromSession(session);
       this.finalizeWorker(workerId, stopReason);
@@ -77120,9 +77201,11 @@ var PiRuntime = class {
       resolveDone,
       idleWaiters: [],
       pendingPause: false,
-      callbacks
+      callbacks,
+      lastAliveAt: 0
     };
     this.active.set(workerId, worker);
+    this.startAliveInterval(worker);
     session.prompt(resumePrompt).then(() => {
       const stopReason = this.extractStopReasonFromSession(session);
       this.finalizeWorker(workerId, stopReason);
@@ -77395,6 +77478,7 @@ async function insertComment(db, opts) {
 }
 async function listComments(db, opts) {
   const limit2 = opts.limit ?? 500;
+  const order = opts.order ?? "asc";
   const filters = ["task_id = $1"];
   const values = [opts.taskId];
   let idx = 2;
@@ -77403,6 +77487,10 @@ async function listComments(db, opts) {
     const placeholders = types3.map(() => `$${idx++}`).join(", ");
     filters.push(`type IN (${placeholders})`);
     values.push(...types3);
+  } else if (opts.excludeTypes && opts.excludeTypes.length > 0) {
+    const placeholders = opts.excludeTypes.map(() => `$${idx++}`).join(", ");
+    filters.push(`type NOT IN (${placeholders})`);
+    values.push(...opts.excludeTypes);
   }
   if (opts.since) {
     filters.push(`created_at > $${idx++}`);
@@ -77411,7 +77499,7 @@ async function listComments(db, opts) {
   const result = await db.query(
     `SELECT * FROM task_comments
      WHERE ${filters.join(" AND ")}
-     ORDER BY created_at ASC
+     ORDER BY created_at ${order === "desc" ? "DESC" : "ASC"}
      LIMIT $${idx}`,
     [...values, limit2]
   );
@@ -77665,6 +77753,7 @@ var WorktreeManager = class {
 
 // src/workers/agent-worker.ts
 var log23 = new Logger("agent-worker");
+var LEASE_WINDOW_MS = 15 * 6e4;
 var CANONICAL_WORKER_SYSTEM_PROMPT = `You are a Neura worker \u2014 a capable engineering agent executing a task dispatched by the Neura orchestrator. The orchestrator is a voice-first assistant that briefed this task with the user, confirmed intent, and handed it off to you.
 
 Your posture: be decisive. You have full tool access \u2014 Read, Write, Edit, Bash \u2014 scoped to an isolated worktree directory (your cwd). Make progress. Don't ask the user to double-check obvious things. Don't propose a plan and wait for approval when the path is clear.
@@ -77689,12 +77778,13 @@ Actions inside your worktree (creating new files, editing files you created, run
 Communication protocol \u2014 use these tools to report back, not prose:
 
 - \`report_progress(message)\` \u2014 brief status updates. Surfaces to the user as ambient voice. Use sparingly: one update per meaningful step, not one per tool call.
-- \`heartbeat(note?)\` \u2014 signal you're alive on long tasks. Emit at least every 2 minutes when you expect to run longer than that, or the orchestrator will treat you as crashed.
 - \`request_clarification(question, context?, urgency?)\` \u2014 ask the user a blocking question. Returns their answer. Only escalate when you genuinely cannot resolve ambiguity from the task context. Try to answer from context first.
 - \`request_approval(action, rationale?, urgency?)\` \u2014 mandatory before destructive actions (see reversibility rule above).
 - \`complete_task(summary)\` \u2014 mark the task done. Include a short summary of what you did, keyed to the acceptance criteria. The invariant layer will reject this if any clarification or approval is still unresolved.
 - \`fail_task(reason, reason_code)\` \u2014 mark the task failed. Use the right reason_code: \`impossible\` (missing precondition), \`already_done\` (no-op), \`user_aborted\` (user stopped you), \`hard_error\` (exception/timeout).
 
+You do not need to emit keepalives or heartbeats. The runtime observes your activity through the tool-call stream and refreshes your lease automatically.
+
 Escalation discipline: escalate sparingly. The orchestrator is mediating a voice conversation with a human \u2014 every clarification interrupts it. Only escalate when:
 - You cannot determine which of several paths the user wants (and context doesn't make it obvious).
 - You hit a blocker that requires user authorization (destructive action, external side effect).
@@ -77920,6 +78010,16 @@ var AgentWorker = class {
         callbacks.onStatusChange?.(status);
       },
       onProgress: callbacks.onProgress,
+      onAlive: () => {
+        void this.refreshTaskLease(task.id).catch((err) => {
+          log23.warn("failed to refresh task lease", {
+            workerId,
+            taskId: task.id,
+            err: String(err)
+          });
+        });
+        callbacks.onAlive?.();
+      },
       onComplete: (result) => {
         void this.persistTerminalResult(workerId, result).catch((err) => {
           log23.warn("failed to persist terminal result", {
@@ -77960,6 +78060,10 @@ var AgentWorker = class {
     if (!row.sessionFile) {
       throw new Error(`resume: worker ${workerId} has no session_file`);
     }
+    const linkedTask = await getWorkItemByWorkerId(this.db, workerId);
+    if (linkedTask) {
+      this.workerTaskIds.set(workerId, linkedTask.id);
+    }
     const wrapped = {
       onStatusChange: (status) => {
         void updateWorker(this.db, workerId, { status }).catch((err) => {
@@ -77968,6 +78072,16 @@ var AgentWorker = class {
         callbacks.onStatusChange?.(status);
       },
       onProgress: callbacks.onProgress,
+      onAlive: linkedTask ? () => {
+        void this.refreshTaskLease(linkedTask.id).catch((err) => {
+          log23.warn("failed to refresh task lease on resume", {
+            workerId,
+            taskId: linkedTask.id,
+            err: String(err)
+          });
+        });
+        callbacks.onAlive?.();
+      } : callbacks.onAlive,
       onComplete: (result) => {
         void this.persistTerminalResult(workerId, result).catch((err) => {
           log23.warn("failed to persist terminal result", {
@@ -78077,6 +78191,29 @@ var AgentWorker = class {
   get activeCount() {
     return this.cancellation.activeCount;
   }
+  /**
+   * Refresh a task's lease. Called from the `onAlive` callback the
+   * runtime fires (throttled) on every pi event. Replaces the explicit
+   * `heartbeat` tool the worker used to emit — pi's event stream is a
+   * stronger signal than a self-reported ping and removes a verb from
+   * the worker protocol prompt.
+   *
+   * Terminal tasks are skipped. Pi emits trailing events (agent_end,
+   * final tool_execution_end) after `complete_task`/`fail_task`; without
+   * this guard the lease bump would rewrite `leaseExpiresAt` on a
+   * `done`/`failed`/`cancelled` row and inflate `version`/`updated_at`,
+   * causing spurious optimistic-lock conflicts for the orchestrator's
+   * next edit.
+   */
+  async refreshTaskLease(taskId) {
+    const task = await getWorkItem(this.db, taskId);
+    if (!task) return;
+    if (task.status === "done" || task.status === "failed" || task.status === "cancelled") {
+      return;
+    }
+    const newLease = new Date(Date.now() + LEASE_WINDOW_MS).toISOString();
+    await updateWorkItem(this.db, taskId, { leaseExpiresAt: newLease });
+  }
   /**
    * Persist a terminal result to the workers table. Called by the
    * callbacks wrapper on `onComplete`. Maps the WorkerResult into the
@@ -78201,8 +78338,10 @@ var ClarificationBridge = class {
         if (signal) {
           const onAbort = () => {
             const idx = this.pending.indexOf(pending);
-            if (idx >= 0) this.pending.splice(idx, 1);
-            reject(new Error("clarification aborted"));
+            if (idx >= 0) {
+              this.pending.splice(idx, 1);
+              reject(new Error("clarification aborted"));
+            }
           };
           if (signal.aborted) {
             onAbort();
@@ -78234,9 +78373,13 @@ var ClarificationBridge = class {
    * clarifications are waiting, the turn is ignored (the user is just
    * talking to Grok normally).
    *
-   * Returns true if the turn was consumed by a pending clarification,
-   * false otherwise — callers can use this to decide whether to also
-   * forward the turn to the normal voice session flow.
+   * Returns `true` synchronously when a pending clarification was
+   * found; `false` when nothing was pending. When `true`, the
+   * response persistence (via `onAnswer`) is in flight and the
+   * worker's `askUser` Promise resolves only after the persistence
+   * completes — so `complete_task`'s open-request gate sees the
+   * committed response comment. Callers use the boolean to decide
+   * whether to forward the turn to the normal voice session flow.
    */
   notifyUserTurn(text) {
     const next = this.pending.shift();
@@ -78246,14 +78389,21 @@ var ClarificationBridge = class {
       textPreview: text.slice(0, 80)
     });
     if (next.onAnswer) {
-      void Promise.resolve(next.onAnswer(text)).catch((err) => {
-        log24.warn("onAnswer persistence hook threw", {
-          workerId: next.workerId,
-          err: String(err)
-        });
-      });
+      void (async () => {
+        try {
+          await Promise.resolve(next.onAnswer(text));
+        } catch (err) {
+          log24.warn("onAnswer persistence hook threw", {
+            workerId: next.workerId,
+            err: String(err)
+          });
+        } finally {
+          next.resolve(text);
+        }
+      })();
+    } else {
+      next.resolve(text);
     }
-    next.resolve(text);
     return true;
   }
   /** How many clarifications are currently waiting for a user turn. */
@@ -78334,7 +78484,6 @@ var ORCHESTRATOR_ALLOWED_FROM = {
 };
 var WORKER_ALLOWED_COMMENT_TYPES = /* @__PURE__ */ new Set([
   "progress",
-  "heartbeat",
   "clarification_request",
   "approval_request",
   "error",
@@ -78472,17 +78621,9 @@ async function resolveTask(store, idOrTitle) {
 
 // src/workers/worker-protocol-tools.ts
 var log25 = new Logger("worker-protocol-tools");
-var LEASE_WINDOW_MS = 5 * 6e4;
 var ReportProgressParams = Type.Object({
   message: Type.String({ description: "Short status update the user may hear read aloud." })
 });
-var HeartbeatParams = Type.Object({
-  note: Type.Optional(
-    Type.String({
-      description: "Optional short note. Heartbeats are pruned after your next real comment."
-    })
-  )
-});
 var RequestClarificationParams2 = Type.Object({
   question: Type.String({ description: "Plain-language question to ask the user." }),
   context: Type.Optional(
@@ -78576,26 +78717,6 @@ function buildWorkerProtocolTools(options) {
       });
     }
   });
-  tools.push({
-    name: "heartbeat",
-    label: "Heartbeat",
-    description: "Signal that you're still alive on a long-running task. Refreshes the worker's lease. Emit at least every 2 minutes when you expect to run long so the orchestrator doesn't treat you as crashed.",
-    parameters: HeartbeatParams,
-    execute: async (_toolCallId, rawParams) => {
-      const params = rawParams;
-      const newLease = new Date(Date.now() + LEASE_WINDOW_MS).toISOString();
-      const result = await taskTools.updateTask(taskId, {
-        comment: { type: "heartbeat", content: params.note ?? "still working" },
-        fields: { leaseExpiresAt: newLease }
-      });
-      if (!result) throw new Error(`heartbeat: task ${taskId} not found`);
-      return textResult("Heartbeat recorded.", {
-        taskId,
-        workerId,
-        leaseExpiresAt: newLease
-      });
-    }
-  });
   tools.push({
     name: "request_clarification",
     label: "Request Clarification",
@@ -78964,22 +79085,40 @@ async function handleWorkerControlTool(name, args, ctx) {
       case "pause_worker": {
         const workerId = args.worker_id;
         const result = await ctx.workerControl.pauseWorker(workerId);
-        return { result };
+        return {
+          result: { paused: result.paused, ...result.reason ? { reason: result.reason } : {} }
+        };
       }
       case "resume_worker": {
         const workerId = args.worker_id;
         const message = args.message;
         const result = await ctx.workerControl.resumeWorker(workerId, message);
-        return { result };
+        return {
+          result: { resumed: result.resumed, ...result.reason ? { reason: result.reason } : {} }
+        };
       }
       case "cancel_worker": {
         const workerId = args.worker_id;
         const result = await ctx.workerControl.cancelWorker(workerId);
-        return { result };
+        return {
+          result: {
+            cancelled: result.cancelled,
+            ...result.reason ? { reason: result.reason } : {}
+          }
+        };
       }
       case "list_active_workers": {
         const workers = await ctx.workerControl.listActive();
-        return { result: { count: workers.length, workers } };
+        return {
+          result: {
+            count: workers.length,
+            workers: workers.map((w) => ({
+              status: w.status,
+              skillName: w.skillName,
+              startedAt: w.startedAt
+            }))
+          }
+        };
       }
       default:
         return null;
@@ -79288,14 +79427,20 @@ async function initServices() {
       const agentDir = join4(config2.neuraHome, "agent");
       const sessionDir = defaultSessionDir(agentDir);
       const globalSkillsDir = join4(homedir5(), ".neura", "skills");
+      const bundleDir = dirname2(fileURLToPath(import.meta.url));
+      const bundledSkillsDir = join4(bundleDir, "..", "skills");
       skillRegistry = new SkillRegistry();
       skillWatcher = new SkillWatcher({
         registry: skillRegistry,
         cwd: process.cwd(),
-        globalSkillsDir
+        globalSkillsDir,
+        bundledSkillsDir
       });
       await skillWatcher.start();
-      log29.info("skill registry loaded", { count: skillRegistry.size });
+      log29.info("skill registry loaded", {
+        count: skillRegistry.size,
+        bundledSkillsDir
+      });
       voiceFanoutBridge = new VoiceFanoutBridge({
         interjector: { interject: () => Promise.resolve() }
       });
@@ -79347,7 +79492,12 @@ async function initServices() {
           },
           getTask: (idOrTitle) => store.getWorkItem(idOrTitle),
           listTaskComments: async (taskId, options) => {
-            return listComments(rawDb, { taskId, limit: options?.limit });
+            return listComments(rawDb, {
+              taskId,
+              limit: options?.limit,
+              order: options?.order,
+              excludeTypes: options?.excludeTypes
+            });
           },
           updateTask: async (idOrTitle, payload) => {
             const current = await store.getWorkItem(idOrTitle);
@@ -99061,7 +99211,12 @@ function attachWebSocket(httpServer2, services2) {
       listTaskComments: async (taskId, options) => {
         const db = store.getRawDb?.();
         if (!db) throw new Error("store does not expose a raw PGlite handle");
-        return listComments(db, { taskId, limit: options?.limit });
+        return listComments(db, {
+          taskId,
+          limit: options?.limit,
+          order: options?.order,
+          excludeTypes: options?.excludeTypes
+        });
       },
       updateTask: async (idOrTitle, payload) => {
         const current = await resolveTask(store, idOrTitle);