mixdog 0.8.1 → 0.9.0

package/src/runtime/shared/tool-execution-contract.mjs

@@ -1,11 +1,11 @@
 export const TOOL_SYNC_EXECUTION_CONTRACT =
-  'Runs synchronously and returns the bounded result in this tool call.';
+  'Runs synchronously in this tool call.';
 
 export const TOOL_ASYNC_EXECUTION_CONTRACT =
-  'Async execution returns immediately; completion is delivered as an owner-session notification. Status/read/wait tools are for manual recovery or explicit blocking control only.';
+  'Async returns task_id; completion notification follows. status/read/wait are manual recovery or blocking only.';
 
 export const TOOL_MANUAL_CONTROL_CONTRACT =
-  'Use manual wait/peek/read/status only when you need explicit blocking, recovery, inspection, or cancellation.';
+  'Manual wait/read/status/cancel only for explicit blocking or recovery.';
 
 function clean(value) {
   return String(value ?? '').trim();
@@ -16,13 +16,111 @@ function positivePid(value) {
   return Number.isFinite(n) && n > 0 ? n : null;
 }
 
+const NON_PERSISTENT_TOOL_STATUSES = new Set(['running', 'pending', 'queued']);
+const TERMINAL_TOOL_STATUSES = new Set([
+  'completed',
+  'failed',
+  'cancelled',
+  'canceled',
+  'error',
+  'timeout',
+  'done',
+  'success',
+]);
+
+function notificationResultBody(text) {
+  const match = /\n\s*\n([\s\S]*)$/.exec(String(text || ''));
+  return match ? String(match[1] || '').trim() : '';
+}
+
+function backgroundTaskHeaderStatus(text) {
+  const match = /^status:\s*(\S+)/mi.exec(String(text || ''));
+  return clean(match?.[1]).toLowerCase();
+}
+
+function notificationHead(text) {
+  const value = String(text || '').trim();
+  const match = /\n\s*\n/.exec(value);
+  if (!match) return value;
+  return value.slice(0, match.index).trim();
+}
+
+function isInternalTaskNotificationEnvelope(text) {
+  const value = String(text || '').trim();
+  if (!value) return false;
+  if (/^background task\b/i.test(value)) return false;
+  if (/^<task-notification\b/i.test(value)) return true;
+  const head = notificationHead(value);
+  return /^<task-notification\b/i.test(head);
+}
+
+export function shouldPersistModelVisibleToolCompletion(text, meta = {}) {
+  const message = String(text || '').trim();
+  if (!message) return false;
+  if (isInternalTaskNotificationEnvelope(message)) return false;
+
+  const metaStatus = clean(meta?.status).toLowerCase();
+  if (NON_PERSISTENT_TOOL_STATUSES.has(metaStatus)) return false;
+
+  if (/^background task\b/i.test(message)) {
+    const headerStatus = backgroundTaskHeaderStatus(message) || metaStatus;
+    if (NON_PERSISTENT_TOOL_STATUSES.has(headerStatus)) return false;
+    if (!TERMINAL_TOOL_STATUSES.has(headerStatus) && !TERMINAL_TOOL_STATUSES.has(metaStatus)) return false;
+    return Boolean(notificationResultBody(message));
+  }
+
+  if (meta?.execution_id || meta?.execution_surface) {
+    if (NON_PERSISTENT_TOOL_STATUSES.has(metaStatus)) return false;
+    if (!TERMINAL_TOOL_STATUSES.has(metaStatus)) return false;
+    return Boolean(notificationResultBody(message));
+  }
+
+  if (/^(?:agent task:|task_id:)/mi.test(message)) {
+    if (NON_PERSISTENT_TOOL_STATUSES.has(metaStatus)) return false;
+    if (!TERMINAL_TOOL_STATUSES.has(metaStatus)) return false;
+    return Boolean(notificationResultBody(message));
+  }
+
+  return false;
+}
+
+const BRACKETED_SHELL_STATUS_RE = /^\[status:\s*(?:running|pending|queued|completed|failed|cancelled|canceled|error|timeout|done|success)\]/im;
+
+function isBracketedShellNotificationEnvelope(text) {
+  const value = String(text ?? '').trim();
+  if (!value) return false;
+  if (!/^\[task_id:\s*\S+\]/im.test(value)) return false;
+  return BRACKETED_SHELL_STATUS_RE.test(value);
+}
+
+export function isInternalRuntimeNotificationText(text) {
+  const value = String(text ?? '').trim();
+  if (!value) return false;
+  if (isInternalTaskNotificationEnvelope(value)) return true;
+  if (isBracketedShellNotificationEnvelope(value)) return true;
+  if (/^background task\b/i.test(value)
+    && /^task_id:\s*\S+/mi.test(value)
+    && /^status:\s*(?:running|pending|queued|completed|failed|cancelled|canceled)\b/mi.test(value)) {
+    return true;
+  }
+  if (/^task_id:\s*\S+/mi.test(value)
+    && /^status:\s*(?:running|pending|queued|completed|failed|cancelled|canceled)\b/mi.test(value)
+    && /^(?:surface|operation|type|target|role|agent|preset|model|effort|fast|notification):\s*/mi.test(value)) {
+    return true;
+  }
+  return false;
+}
+
 export function normalizeToolNotifyContext(context = {}) {
-  const callerSessionId = clean(context.callerSessionId || context.routingSessionId || context.sessionId);
+  const explicitCallerSessionId = clean(context.callerSessionId || context.sessionId);
+  const explicitRoutingSessionId = clean(context.routingSessionId);
+  const callerSessionId = explicitCallerSessionId || explicitRoutingSessionId;
+  const routingSessionId = explicitRoutingSessionId || callerSessionId;
   const clientHostPid = positivePid(context.clientHostPid);
   return {
     notifyFn: typeof context.notifyFn === 'function' ? context.notifyFn : null,
     callerSessionId: callerSessionId || null,
-    routingSessionId: callerSessionId || null,
+    routingSessionId: routingSessionId || null,
     clientHostPid,
   };
 }
@@ -30,8 +128,8 @@ export function normalizeToolNotifyContext(context = {}) {
 export function toolCompletionInstruction({ surface = 'tool', id, status, detail } = {}) {
   const label = surface === 'shell'
     ? 'shell task'
-    : surface === 'bridge'
-      ? 'bridge agent'
+    : surface === 'agent'
+      ? 'agent task'
       : `${surface} execution`;
   const statusText = status ? ` (${status}${detail ? `, ${detail}` : ''})` : '';
   return `The async ${label} ${id || ''} has finished${statusText} - review this result in your next step.`;
@@ -53,10 +151,73 @@ export function toolCompletionMeta({
     status: status || null,
     instruction: instruction || toolCompletionInstruction({ surface, id, status }),
     ...(ctx.callerSessionId ? { caller_session_id: ctx.callerSessionId } : {}),
+    ...(ctx.routingSessionId && ctx.routingSessionId !== ctx.callerSessionId ? { routing_session_id: ctx.routingSessionId } : {}),
     ...(ctx.clientHostPid ? { client_host_pid: String(ctx.clientHostPid) } : {}),
   };
 }
 
+const MODEL_VISIBLE_COMPLETION_INSTRUCTION_RE = /\b(async (?:agent task|shell task|\w+ execution)|Async \S+)/i;
+const MODEL_VISIBLE_COMPLETION_REVIEW_RE = /has finished\b[\s\S]*review this result in your next step/i;
+const MODEL_VISIBLE_COMPLETION_ASYNC_HEADER_RE = /^Async .+ finished\./i;
+
+export function isModelVisibleToolCompletionWrapper(text) {
+  const value = String(text ?? '').trim();
+  if (!value) return false;
+  const resultSplit = /\n\nResult:\n/.exec(value);
+  if (!resultSplit) return false;
+  const preamble = value.slice(0, resultSplit.index).trim();
+  if (!preamble) return false;
+  const instructionLike = MODEL_VISIBLE_COMPLETION_INSTRUCTION_RE.test(preamble)
+    || MODEL_VISIBLE_COMPLETION_REVIEW_RE.test(preamble)
+    || MODEL_VISIBLE_COMPLETION_ASYNC_HEADER_RE.test(preamble);
+  if (!instructionLike) return false;
+  const quotedSection = value.slice(resultSplit.index + resultSplit[0].length);
+  const quotedLines = quotedSection.split(/\r?\n/).filter((line) => line.length > 0);
+  if (quotedLines.length === 0) return false;
+  if (!quotedLines.every((line) => /^> /.test(line))) return false;
+  const unquoted = quotedLines.map((line) => line.slice(2)).join('\n');
+  return isInternalRuntimeNotificationText(unquoted);
+}
+
+export function modelVisibleToolCompletionMessage(text, meta = {}) {
+  const message = String(text || '').trim();
+  if (!message) return '';
+  if (!shouldPersistModelVisibleToolCompletion(message, meta)) return '';
+  const instruction = clean(meta?.instruction);
+  const type = clean(meta?.type || meta?.execution_surface || 'tool_completion');
+  const id = clean(meta?.execution_id);
+  const status = clean(meta?.status);
+  const header = `Async ${type}${id ? ` ${id}` : ''}${status ? ` ${status}` : ''} finished.`;
+  const MODEL_VISIBLE_RESULT_BODY_MAX = 12_000;
+  const bounded = message.length > MODEL_VISIBLE_RESULT_BODY_MAX
+    ? `${message.slice(0, MODEL_VISIBLE_RESULT_BODY_MAX)}\n\n[result truncated for model context]`
+    : message;
+  const quoted = bounded.split(/\r?\n/).map((line) => `> ${line}`).join('\n');
+  return [
+    instruction || header,
+    '',
+    'Result:',
+    quoted,
+  ].join('\n');
+}
+
+// Shared enqueue-fallback helper used by both the synchronous fallback path and
+// the asynchronous notifyFn reject/false-resolve rescue path. Only enqueues when
+// a caller session and fallback fn are present. Returns true only on a non-false,
+// non-zero fallback result; logs and returns false on throw.
+function tryEnqueueFallback(ctx, message, meta, enqueueFallback, logPrefix, id) {
+  if (!ctx.callerSessionId || typeof enqueueFallback !== 'function') return false;
+  try {
+    const enq = enqueueFallback(ctx.callerSessionId, message, meta);
+    return enq !== false && enq !== 0;
+  } catch (err) {
+    try {
+      process.stderr.write(`[${logPrefix}] async completion fallback enqueue failed: id=${id || 'unknown'} err=${err?.message || err}\n`);
+    } catch {}
+  }
+  return false;
+}
+
 export function notifyToolCompletion({
   surface = 'tool',
   id,
@@ -80,25 +241,43 @@ export function notifyToolCompletion({
     context: ctx,
   });
 
+  // Try the upstream owner notifyFn first. A `false` return means the owner
+  // *declined* delivery and a throw means it failed outright — in both cases we
+  // do NOT return early but fall through to the enqueueFallback path so the
+  // completion can still reach the caller session. Only a successful (non-false)
+  // notifyFn short-circuits as delivered.
   if (typeof ctx.notifyFn === 'function') {
-    Promise.resolve(ctx.notifyFn(message, meta)).catch((err) => {
-      try {
-        process.stderr.write(`[${logPrefix}] async completion notify failed: id=${id || 'unknown'} err=${err?.message || err}\n`);
-      } catch {}
-    });
-    return true;
-  }
-
-  if (ctx.callerSessionId && typeof enqueueFallback === 'function') {
     try {
-      enqueueFallback(ctx.callerSessionId, message, meta);
-      return true;
+      const notifyResult = ctx.notifyFn(message, meta);
+      if (notifyResult !== false) {
+        // Optimistically report delivered (keeps this fn synchronous). But a
+        // notifyFn that returns a Promise can still reject — or resolve to an
+        // explicit false/0 (declined/failed) — *after* we returned. In that
+        // case rescue the completion via enqueueFallback so the owner isn't
+        // left without a notification. The normal success path (truthy
+        // resolve) never enqueues, preserving exact-once delivery.
+        Promise.resolve(notifyResult).then((settled) => {
+          if (settled === false || settled === 0) {
+            tryEnqueueFallback(ctx, message, meta, enqueueFallback, logPrefix, id);
+          }
+        }).catch((err) => {
+          try {
+            process.stderr.write(`[${logPrefix}] async completion notify failed: id=${id || 'unknown'} err=${err?.message || err}\n`);
+          } catch {}
+          tryEnqueueFallback(ctx, message, meta, enqueueFallback, logPrefix, id);
+        });
+        return true;
+      }
     } catch (err) {
       try {
-        process.stderr.write(`[${logPrefix}] async completion fallback enqueue failed: id=${id || 'unknown'} err=${err?.message || err}\n`);
+        process.stderr.write(`[${logPrefix}] async completion notify failed: id=${id || 'unknown'} err=${err?.message || err}\n`);
       } catch {}
     }
   }
 
-  return false;
+  // Fallback enqueue (used when notifyFn is absent, declined, or threw). Respect
+  // the fallback's own success signal: an explicit false/0 return means the
+  // enqueue failed, so report failure and leave room for a retry rather than
+  // marking the task notified.
+  return tryEnqueueFallback(ctx, message, meta, enqueueFallback, logPrefix, id);
 }

package/src/runtime/shared/tool-execution-contract.test.mjs

@@ -0,0 +1,183 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  isInternalRuntimeNotificationText,
+  isModelVisibleToolCompletionWrapper,
+  modelVisibleToolCompletionMessage,
+  shouldPersistModelVisibleToolCompletion,
+  toolCompletionMeta,
+  toolCompletionInstruction,
+} from './tool-execution-contract.mjs';
+import { _isInternalRuntimeNotificationText } from '../agent/orchestrator/session/manager.mjs';
+
+const completedBackgroundTask = [
+  'background task',
+  'task_id: task_agent_abc123',
+  'surface: agent',
+  'operation: run',
+  'status: completed',
+  'started: 2026-03-28T00:00:00.000Z',
+  'finished: 2026-03-28T00:00:05.000Z',
+  '',
+  'worker finished successfully',
+].join('\n');
+
+const runningBackgroundTask = [
+  'background task',
+  'task_id: task_agent_abc123',
+  'surface: agent',
+  'operation: run',
+  'status: running',
+  'started: 2026-03-28T00:00:00.000Z',
+  'notification: completion will be delivered to the owner session; use status/read only for manual recovery.',
+].join('\n');
+
+test('terminal background task with body should persist as model-visible wrapper', () => {
+  const meta = toolCompletionMeta({
+    surface: 'agent',
+    id: 'task_agent_abc123',
+    status: 'completed',
+    context: { callerSessionId: 'sess_owner' },
+  });
+  assert.equal(shouldPersistModelVisibleToolCompletion(completedBackgroundTask, meta), true);
+  const visible = modelVisibleToolCompletionMessage(completedBackgroundTask, meta);
+  assert.ok(visible);
+  assert.equal(isInternalRuntimeNotificationText(visible), false);
+  assert.equal(_isInternalRuntimeNotificationText(visible), false);
+  assert.equal(isModelVisibleToolCompletionWrapper(visible), true);
+  assert.match(visible, /worker finished successfully/);
+});
+
+test('model-visible completion wrapper is not a human transcript item', () => {
+  const meta = toolCompletionMeta({
+    surface: 'agent',
+    id: 'task_agent_abc123',
+    status: 'completed',
+    instruction: toolCompletionInstruction({
+      surface: 'agent',
+      id: 'task_agent_abc123',
+      status: 'completed',
+    }),
+    context: { callerSessionId: 'sess_owner' },
+  });
+  const visible = modelVisibleToolCompletionMessage(completedBackgroundTask, meta);
+  assert.ok(visible);
+  assert.match(visible, /^The async agent task/);
+  assert.match(visible, /\n\nResult:\n/);
+  assert.equal(isModelVisibleToolCompletionWrapper(visible), true);
+  assert.equal(isModelVisibleToolCompletionWrapper('please fix the leak in engine.mjs'), false);
+  assert.equal(isModelVisibleToolCompletionWrapper(completedBackgroundTask), false);
+});
+
+test('running background task stays hidden from model-visible pending drain', () => {
+  const meta = toolCompletionMeta({
+    surface: 'agent',
+    id: 'task_agent_abc123',
+    status: 'running',
+    context: { callerSessionId: 'sess_owner' },
+  });
+  assert.equal(shouldPersistModelVisibleToolCompletion(runningBackgroundTask, meta), false);
+  assert.equal(modelVisibleToolCompletionMessage(runningBackgroundTask, meta), '');
+});
+
+test('terminal background task persists when result body mentions task-notification', () => {
+  const taskWithTagInBody = [
+    ...completedBackgroundTask.split('\n').slice(0, -1),
+    'log line: saw <task-notification status="completed"> in worker output',
+  ].join('\n');
+  const meta = toolCompletionMeta({
+    surface: 'agent',
+    id: 'task_agent_abc123',
+    status: 'completed',
+    context: { callerSessionId: 'sess_owner' },
+  });
+  assert.equal(shouldPersistModelVisibleToolCompletion(taskWithTagInBody, meta), true);
+  const visible = modelVisibleToolCompletionMessage(taskWithTagInBody, meta);
+  assert.ok(visible);
+  assert.match(visible, /<task-notification/);
+  assert.equal(isInternalRuntimeNotificationText(visible), false);
+  assert.equal(_isInternalRuntimeNotificationText(visible), false);
+});
+
+test('internal task-notification envelope does not persist', () => {
+  const internalEnvelope = [
+    '<task-notification>',
+    '<status>completed</status>',
+    '<summary>Agent completed</summary>',
+    '<task-id>task_agent_internal</task-id>',
+    '</task-notification>',
+  ].join('\n');
+  const meta = toolCompletionMeta({
+    surface: 'agent',
+    id: 'task_agent_internal',
+    status: 'completed',
+    context: { callerSessionId: 'sess_owner' },
+  });
+  assert.equal(shouldPersistModelVisibleToolCompletion(internalEnvelope, meta), false);
+  assert.equal(modelVisibleToolCompletionMessage(internalEnvelope, meta), '');
+  assert.equal(isInternalRuntimeNotificationText(internalEnvelope), true);
+  assert.equal(_isInternalRuntimeNotificationText(internalEnvelope), true);
+});
+
+test('raw running background task remains internal for manager pending drain', () => {
+  assert.equal(isInternalRuntimeNotificationText(runningBackgroundTask), true);
+  assert.equal(_isInternalRuntimeNotificationText(runningBackgroundTask), true);
+});
+
+
+
+const bracketedShellCompleted = [
+  "[task_id: shell_job_1]",
+  "[status: completed]",
+  "[exit: 0]",
+  "",
+  "done output",
+].join("\n");
+
+const bracketedShellRunning = [
+  "[task_id: shell_job_1]",
+  "[status: running]",
+  "[command: npm test]",
+].join("\n");
+
+test("bracketed shell completed raw envelope is internal", () => {
+  assert.equal(isInternalRuntimeNotificationText(bracketedShellCompleted), true);
+  assert.equal(_isInternalRuntimeNotificationText(bracketedShellCompleted), true);
+});
+
+test("bracketed shell running raw envelope is internal", () => {
+  assert.equal(isInternalRuntimeNotificationText(bracketedShellRunning), true);
+  assert.equal(_isInternalRuntimeNotificationText(bracketedShellRunning), true);
+});
+
+test("wrapped shell completion stays model-visible and not internal", () => {
+  const meta = toolCompletionMeta({
+    surface: "shell",
+    id: "shell_job_1",
+    status: "completed",
+    context: { callerSessionId: "sess_owner" },
+  });
+  const visible = modelVisibleToolCompletionMessage(bracketedShellCompleted, meta);
+  assert.ok(visible);
+  assert.match(visible, /done output/);
+  assert.equal(isInternalRuntimeNotificationText(visible), false);
+  assert.equal(_isInternalRuntimeNotificationText(visible), false);
+});
+
+test("model-visible wrapper bounds large completion bodies", () => {
+  const hugeBody = "x".repeat(20_000);
+  const hugeTask = [
+    ...completedBackgroundTask.split("\n").slice(0, -1),
+    hugeBody,
+  ].join("\n");
+  const meta = toolCompletionMeta({
+    surface: "agent",
+    id: "task_agent_abc123",
+    status: "completed",
+    context: { callerSessionId: "sess_owner" },
+  });
+  const visible = modelVisibleToolCompletionMessage(hugeTask, meta);
+  assert.ok(visible);
+  assert.match(visible, /\[result truncated for model context\]/);
+  assert.ok(visible.length < hugeBody.length);
+});