mixdog 0.9.151 → 0.9.153

package/src/runtime/shared/child-spawn-remote.test.mjs

@@ -0,0 +1,124 @@
+// Machine-wide child-spawn budget: every runtime shard must stay on the
+// daemon-owned gate. Two ways that silently breaks (and multiplies the cap by
+// the shard count) are covered here: an inherited env flag activating the
+// process-local lane in a grandchild, and one failed lease latching a shard
+// off the remote budget for the rest of its life.
+import assert from 'node:assert/strict';
+import { fork } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+
+import { isSessionRuntimeWorkerProcess } from './child-spawn-remote.mjs';
+
+const REMOTE_URL = new URL('./child-spawn-remote.mjs', import.meta.url).href;
+const GATE_URL = new URL('./child-spawn-gate.mjs', import.meta.url).href;
+
+const CHILD_SOURCE = `
+const inherited = process.env.STUB_PID_MODE === 'inherited';
+process.env.MIXDOG_SESSION_RUNTIME_WORKER = '1';
+// A grandchild inherits BOTH variables; only its own pid differs.
+process.env.MIXDOG_SESSION_RUNTIME_WORKER_PID = inherited
+  ? String(process.pid + 1)
+  : String(process.pid);
+const remote = await import(process.env.REMOTE_URL);
+const gate = await import(process.env.GATE_URL);
+const report = { enabled: remote.remoteSpawnLeasesEnabled(), mode: gate.snapshot().mode };
+if (!inherited) {
+  try {
+    await remote.acquireRemoteSpawnLease({ lane: 'search', ownerKey: 'test', waitTimeoutMs: 30000 });
+    report.firstLease = 'granted';
+  } catch (error) {
+    report.firstLease = String(error?.code || error?.message || error);
+  }
+  report.enabledAfterFailure = remote.remoteSpawnLeasesEnabled();
+  report.modeAfterFailure = gate.snapshot().mode;
+  const release = await remote.acquireRemoteSpawnLease({ lane: 'search', ownerKey: 'test', waitTimeoutMs: 30000 });
+  report.secondLease = typeof release === 'function' ? 'granted' : 'unexpected';
+  release();
+}
+process.send({ type: 'report', report });
+setTimeout(() => process.exit(0), 50).unref?.();
+`;
+
+async function runChild(mode, { onLease = () => {} } = {}) {
+  const dir = await mkdtemp(join(tmpdir(), 'mixdog-spawn-remote-'));
+  const entry = join(dir, 'child.mjs');
+  await writeFile(entry, CHILD_SOURCE, 'utf8');
+  try {
+    return await new Promise((resolve, reject) => {
+      const child = fork(entry, [], {
+        stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+        env: {
+          ...process.env,
+          STUB_PID_MODE: mode,
+          REMOTE_URL,
+          GATE_URL,
+        },
+      });
+      const timer = setTimeout(() => {
+        try { child.kill(); } catch {}
+        reject(new Error('child spawn-lease probe timed out'));
+      }, 20_000);
+      let stderr = '';
+      child.stderr?.on('data', (chunk) => { stderr += String(chunk); });
+      child.on('message', (message) => {
+        if (message?.type === 'spawn-lease') {
+          onLease(child, message);
+          return;
+        }
+        if (message?.type !== 'report') return;
+        clearTimeout(timer);
+        try { child.kill(); } catch {}
+        resolve({ ...message.report, stderr });
+      });
+      child.on('error', reject);
+    });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+test('only the pid-scoped runtime worker uses the machine-wide spawn budget', () => {
+  assert.equal(isSessionRuntimeWorkerProcess({ MIXDOG_SESSION_RUNTIME_WORKER_PID: '4242' }, 4242), true);
+  assert.equal(isSessionRuntimeWorkerProcess({ MIXDOG_SESSION_RUNTIME_WORKER_PID: '4242' }, 99), false);
+  // The inheritable flag alone can never claim the runtime IPC channel.
+  assert.equal(isSessionRuntimeWorkerProcess({ MIXDOG_SESSION_RUNTIME_WORKER: '1' }, 99), false);
+  assert.equal(isSessionRuntimeWorkerProcess({}, 99), false);
+});
+
+test('a grandchild that inherited the worker flag stays on its own local lane', async () => {
+  const report = await runChild('inherited');
+  assert.equal(report.enabled, false);
+  assert.equal(report.mode, 'local');
+});
+
+test('a failed lease never latches a shard off the machine-wide budget', async () => {
+  let leases = 0;
+  const report = await runChild('shard', {
+    onLease: (child, message) => {
+      leases += 1;
+      // First lease fails the way a momentarily unreachable pool does.
+      child.send(leases === 1
+        ? {
+          type: 'spawn-lease-result',
+          leaseId: message.leaseId,
+          ok: false,
+          error: 'pool channel unavailable',
+          code: 'ELEASEFALLBACK',
+        }
+        : { type: 'spawn-lease-result', leaseId: message.leaseId, ok: true });
+    },
+  });
+  assert.equal(report.enabled, true);
+  assert.equal(report.mode, 'remote-lease');
+  assert.equal(report.firstLease, 'ELEASEFALLBACK');
+  // Recovery: the shard is still on the daemon budget and the next lease is
+  // granted remotely instead of silently using a per-process lane.
+  assert.equal(report.enabledAfterFailure, true);
+  assert.equal(report.modeAfterFailure, 'remote-lease');
+  assert.equal(report.secondLease, 'granted');
+  assert.equal(leases, 2);
+});

package/src/runtime/shared/pristine-execution-contract.json

@@ -67,7 +67,8 @@
     "gemini": "GEMINI_API_KEY",
     "deepseek": "DEEPSEEK_API_KEY",
     "xai": "XAI_API_KEY",
-    "opencode-go": "OPENCODE_API_KEY"
+    "opencode-go": "OPENCODE_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY"
   },
   "personalStateCounters": [
     "behavioralStateFilesCopied",

package/src/runtime/shared/provider-api-key.mjs

@@ -13,6 +13,7 @@ export const AGENT_PROVIDER_ENV = Object.freeze({
   deepseek: 'DEEPSEEK_API_KEY',
   xai: 'XAI_API_KEY',
   'opencode-go': 'OPENCODE_API_KEY',
+  openrouter: 'OPENROUTER_API_KEY',
 });
 
 export const AGENT_PROVIDER_ENV_ALIASES = Object.freeze({

package/src/runtime/shared/session-runtime-health.mjs

@@ -1,4 +1,5 @@
 import { normalize } from 'node:path';
+import { monitorEventLoopDelay } from 'node:perf_hooks';
 
 export const SESSION_RUNTIME_WORKER_UNHEALTHY_EVENT = 'mixdog:session-runtime-worker-unhealthy';
 
@@ -67,6 +68,96 @@ export function reportRuntimeDirectoryReadFailure(path, error, now = Date.now())
   });
 }
 
+// ── Per-shard event-loop lag ───────────────────────────────────────────────
+// Each runtime shard runs provider parsing, transcript projection and tool
+// results on its OWN event loop, so lag is the per-shard saturation signal the
+// daemon cannot see (it only measures itself). Lag is DIAGNOSTIC + ROUTING
+// input, never a kill signal: a saturated shard still owns accepted input and
+// in-flight turns, so the host quarantines it from NEW placement instead of
+// recycling it out from under that work.
+export const RUNTIME_LAG_DEFAULTS = Object.freeze({
+  intervalMs: 5_000,
+  warnP99Ms: 250,
+  degradedP99Ms: 2_000,
+  degradedSamples: 3,
+  recoverP99Ms: 750,
+});
+
+function lagMs(value) {
+  return Number.isFinite(value) ? Math.round(value / 1e6) : 0;
+}
+
+/**
+ * Sample this process's event-loop delay on a fixed interval.
+ * Returns a stop function; the timer is unref'd so it never holds the process.
+ */
+export function startRuntimeEventLoopLagMonitor({
+  intervalMs = RUNTIME_LAG_DEFAULTS.intervalMs,
+  resolution = 20,
+  onSample = () => {},
+} = {}) {
+  const histogram = monitorEventLoopDelay({ resolution });
+  histogram.enable();
+  const timer = setInterval(() => {
+    const sample = {
+      p50Ms: lagMs(histogram.percentile(50)),
+      p95Ms: lagMs(histogram.percentile(95)),
+      p99Ms: lagMs(histogram.percentile(99)),
+      maxMs: lagMs(histogram.max),
+      meanMs: lagMs(histogram.mean),
+      intervalMs,
+      at: Date.now(),
+    };
+    histogram.reset();
+    try { onSample(sample); } catch { /* telemetry must never throw upward */ }
+  }, intervalMs);
+  timer.unref?.();
+  return () => {
+    clearInterval(timer);
+    try { histogram.disable(); } catch {}
+  };
+}
+
+/**
+ * Hysteresis state machine over lag samples: a shard becomes `degraded` only
+ * after repeated sustained lag and recovers once it drops well below the
+ * trigger, so a single GC pause never quarantines a healthy shard.
+ */
+export function createRuntimeLagTracker(overrides = {}) {
+  const config = { ...RUNTIME_LAG_DEFAULTS, ...(overrides || {}) };
+  let consecutive = 0;
+  let degraded = false;
+  let sample = null;
+  return {
+    get config() { return config; },
+    get degraded() { return degraded; },
+    get sample() { return sample; },
+    record(next) {
+      sample = next && typeof next === 'object' ? next : null;
+      const p99 = Number(sample?.p99Ms) || 0;
+      if (p99 >= config.degradedP99Ms) {
+        consecutive += 1;
+        if (!degraded && consecutive >= config.degradedSamples) {
+          degraded = true;
+          return { degraded, changed: true, sample, consecutive };
+        }
+        return { degraded, changed: false, sample, consecutive };
+      }
+      consecutive = 0;
+      if (degraded && p99 <= config.recoverP99Ms) {
+        degraded = false;
+        return { degraded, changed: true, sample, consecutive };
+      }
+      return { degraded, changed: false, sample, consecutive };
+    },
+    reset() {
+      consecutive = 0;
+      degraded = false;
+      sample = null;
+    },
+  };
+}
+
 export function reportRuntimeAbortListenerPressure(warning, now = Date.now(), retainedListeners = 0) {
   if (!isCurrentSessionRuntimeWorker()) return false;
   if (!Number.isFinite(Number(retainedListeners)) || Number(retainedListeners) <= 50) {

package/src/runtime/shared/session-runtime-health.test.mjs

@@ -2,10 +2,63 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import {
+  createRuntimeLagTracker,
   recordRuntimeDirectoryReadSuccess,
   reportRuntimeAbortListenerPressure,
+  RUNTIME_LAG_DEFAULTS,
+  startRuntimeEventLoopLagMonitor,
 } from './session-runtime-health.mjs';
 
+test('sustained event-loop lag degrades a shard, a single spike does not', () => {
+  const tracker = createRuntimeLagTracker();
+  const spike = { p99Ms: RUNTIME_LAG_DEFAULTS.degradedP99Ms + 500 };
+  assert.equal(tracker.record(spike).degraded, false);
+  assert.equal(tracker.record(spike).degraded, false);
+  const degraded = tracker.record(spike);
+  assert.equal(degraded.degraded, true);
+  assert.equal(degraded.changed, true);
+  // Already degraded: no repeated transition.
+  assert.equal(tracker.record(spike).changed, false);
+  assert.equal(tracker.degraded, true);
+
+  // Hysteresis: still-elevated lag keeps the quarantine, a clean sample lifts it.
+  assert.equal(tracker.record({ p99Ms: RUNTIME_LAG_DEFAULTS.degradedP99Ms - 1 }).degraded, true);
+  const recovered = tracker.record({ p99Ms: 10 });
+  assert.equal(recovered.degraded, false);
+  assert.equal(recovered.changed, true);
+
+  // A fresh process starts from a clean slate.
+  tracker.record(spike);
+  tracker.reset();
+  assert.equal(tracker.degraded, false);
+  assert.equal(tracker.sample, null);
+});
+
+test('the event-loop lag monitor samples this process and stops cleanly', async () => {
+  const samples = [];
+  const stop = startRuntimeEventLoopLagMonitor({
+    intervalMs: 20,
+    onSample: (sample) => samples.push(sample),
+  });
+  try {
+    const deadline = Date.now() + 2_000;
+    while (samples.length === 0 && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+  } finally {
+    stop();
+  }
+  assert.ok(samples.length > 0, 'monitor produced at least one sample');
+  const [sample] = samples;
+  for (const key of ['p50Ms', 'p95Ms', 'p99Ms', 'maxMs']) {
+    assert.equal(Number.isFinite(sample[key]), true, `${key} is numeric`);
+    assert.ok(sample[key] >= 0);
+  }
+  const seen = samples.length;
+  await new Promise((resolve) => setTimeout(resolve, 80));
+  assert.equal(samples.length, seen, 'no samples after stop');
+});
+
 test('repeated AbortSignal listener pressure marks only the session runtime worker unhealthy', () => {
   const originalRuntimeWorkerPid = process.env.MIXDOG_SESSION_RUNTIME_WORKER_PID;
   let detail = null;

package/src/runtime/shared/skill-document.mjs

@@ -0,0 +1,86 @@
+import { parseDocument } from 'yaml';
+
+const SKILL_FRONTMATTER_RE =
+  /^(?:\uFEFF)?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+
+const scalarText = (value, field) => {
+  if (typeof value !== 'string') {
+    throw new Error(`Skill ${field} must be a string.`);
+  }
+  return value.trim();
+};
+
+export function validateSkillName(value) {
+  const name = String(value || '').trim();
+  if (!name) throw new Error('Skill name is required.');
+  if (name.length > 64) throw new Error('Skill name must be 64 characters or fewer.');
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    throw new Error('Skill name may contain only lowercase letters, numbers, and hyphens.');
+  }
+  if (name.startsWith('-') || name.endsWith('-') || name.includes('--')) {
+    throw new Error('Skill name cannot start or end with a hyphen or contain consecutive hyphens.');
+  }
+  return name;
+}
+
+export function validateSkillDescription(value) {
+  const description = String(value || '').trim();
+  if (!description) throw new Error('Skill trigger is required.');
+  if (description.length > 1024) {
+    throw new Error('Skill trigger must be 1024 characters or fewer.');
+  }
+  return description;
+}
+
+function parseFrontmatterDocument(markdown) {
+  const source = String(markdown || '');
+  const match = source.match(SKILL_FRONTMATTER_RE);
+  if (!match) throw new Error('SKILL.md must start with YAML frontmatter.');
+  const document = parseDocument(match[1], {
+    prettyErrors: false,
+    strict: true,
+    uniqueKeys: true,
+  });
+  if (document.errors.length) {
+    throw new Error(`Invalid SKILL.md frontmatter: ${document.errors[0].message}`);
+  }
+  const frontmatter = document.toJS({ maxAliasCount: 100 });
+  if (!frontmatter || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    throw new Error('SKILL.md frontmatter must be a YAML mapping.');
+  }
+  return { source, match, document, frontmatter };
+}
+
+export function parseSkillDocument(markdown) {
+  const parsed = parseFrontmatterDocument(markdown);
+  const name = validateSkillName(scalarText(parsed.frontmatter.name, 'name'));
+  const description = validateSkillDescription(
+    scalarText(parsed.frontmatter.description, 'description'),
+  );
+  return {
+    name,
+    description,
+    body: parsed.source.slice(parsed.match[0].length).replace(/^\r?\n/, ''),
+    frontmatter: parsed.frontmatter,
+  };
+}
+
+function renderSkillDocument(document, body) {
+  const instructions = String(body || '').replace(/\r\n/g, '\n').trim();
+  if (!instructions) throw new Error('Skill instructions are required.');
+  return `---\n${String(document).trimEnd()}\n---\n\n${instructions}\n`;
+}
+
+export function createSkillDocument({ name, description, body }) {
+  const document = parseDocument('');
+  document.set('name', validateSkillName(name));
+  document.set('description', validateSkillDescription(description));
+  return renderSkillDocument(document, body);
+}
+
+export function updateSkillDocument(markdown, { name, description, body }) {
+  const parsed = parseFrontmatterDocument(markdown);
+  parsed.document.set('name', validateSkillName(name));
+  parsed.document.set('description', validateSkillDescription(description));
+  return renderSkillDocument(parsed.document, body);
+}

package/src/runtime/shared/skill-document.test.mjs

@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  createSkillDocument,
+  parseSkillDocument,
+  updateSkillDocument,
+  validateSkillName,
+} from './skill-document.mjs';
+
+test('parses standard multiline YAML and the Markdown instructions body', () => {
+  const parsed = parseSkillDocument([
+    '---',
+    'name: imported-skill',
+    'description: >',
+    '  Use when an imported skill',
+    '  needs multiline matching.',
+    'metadata:',
+    '  author: example',
+    'allowed-tools:',
+    '  - shell',
+    '---',
+    '',
+    '# Instructions',
+    '',
+    'Read `references/guide.md`.',
+    '',
+  ].join('\n'));
+
+  assert.equal(parsed.name, 'imported-skill');
+  assert.equal(parsed.description,
+    'Use when an imported skill needs multiline matching.');
+  assert.deepEqual(parsed.frontmatter.metadata, { author: 'example' });
+  assert.deepEqual(parsed.frontmatter['allowed-tools'], ['shell']);
+  assert.match(parsed.body, /^# Instructions/);
+});
+
+test('updates the three editable fields without dropping optional frontmatter', () => {
+  const source = [
+    '---',
+    '# retained comment',
+    'name: old-name',
+    'description: Old trigger.',
+    'license: MIT',
+    'compatibility: Requires Python.',
+    'metadata:',
+    '  author: example',
+    'allowed-tools: shell',
+    '---',
+    '',
+    'Old instructions.',
+    '',
+  ].join('\n');
+
+  const updated = updateSkillDocument(source, {
+    name: 'new-name',
+    description: 'Use when the new trigger matches.',
+    body: '# New instructions',
+  });
+  const parsed = parseSkillDocument(updated);
+
+  assert.equal(parsed.name, 'new-name');
+  assert.equal(parsed.description, 'Use when the new trigger matches.');
+  assert.equal(parsed.body, '# New instructions\n');
+  assert.equal(parsed.frontmatter.license, 'MIT');
+  assert.equal(parsed.frontmatter.compatibility, 'Requires Python.');
+  assert.deepEqual(parsed.frontmatter.metadata, { author: 'example' });
+  assert.equal(parsed.frontmatter['allowed-tools'], 'shell');
+  assert.match(updated, /# retained comment/);
+});
+
+test('creates a standard document and rejects non-standard names', () => {
+  const source = createSkillDocument({
+    name: 'project-skill',
+    description: 'Use when this project needs the skill.',
+    body: '# Instructions',
+  });
+  assert.equal(parseSkillDocument(source).name, 'project-skill');
+  assert.throws(() => validateSkillName('Project_Skill'), /lowercase letters/);
+  assert.throws(() => validateSkillName('project--skill'), /consecutive hyphens/);
+});

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

@@ -185,6 +185,22 @@ const INTERNAL_TRANSCRIPT_CONTEXT_RE =
 const INTERNAL_TRANSCRIPT_SYNTHETIC_RE =
   /^(?:\[mixdog-runtime\]|A previous model worked on this task and produced the compacted handoff summary below\b|Re-attached after compaction\b|Reference files:\s)/i;
 const INTERNAL_TRANSCRIPT_ASYNC_HEAD_RE = /^Async .+ finished\./i;
+const TRANSCRIPT_HIDDEN_CONTROL_TOOL_NAMES = new Set([
+  'goal',
+  'create_goal',
+  'get_goal',
+  'set_goal_tasks',
+  'update_goal',
+  'load_tool',
+  'tool_search',
+  'skill',
+]);
+
+export function isTranscriptHiddenControlToolName(name) {
+  const normalized = clean(name).toLowerCase().replace(/^functions\./, '');
+  return TRANSCRIPT_HIDDEN_CONTROL_TOOL_NAMES.has(normalized);
+}
+
 // Persisted USER cancellation control rows ("[Request interrupted by user]"
 // and its tool-use variant) exist for the next model step, not for humans:
 // the human already saw the cancel they typed. The live engine path already

package/src/runtime/shared/tool-surface.mjs

@@ -153,6 +153,12 @@ export function displayToolName(name, args = {}) {
     case 'web_fetch':
     case 'fetch':
       return 'Fetch';
+    case 'browser':
+      return 'Browser';
+    case 'computer':
+      return 'Computer';
+    case 'office':
+      return 'Office';
     case 'list_mcp_resources':
     case 'list_mcp_resource_templates':
     case 'cwd':
@@ -275,6 +281,21 @@ export function summarizeToolArgs(name, args, { max = DEFAULT_SUMMARY_MAX } = {}
         return formatCountedUnit(collectionCount(a.url, a.uri), 'URL', 'URLs');
       }
       return truncateToolText(a.url || a.uri || '', max);
+    case 'browser':
+      return compactParts([
+        String(a.action || ''),
+        a.url ? truncateToolText(a.url, max) : a.ref ? String(a.ref) : '',
+      ]);
+    case 'computer':
+      return compactParts([
+        String(a.action || ''),
+        a.window ? truncateToolText(a.window, max) : a.ref ? String(a.ref) : a.app ? truncateToolText(a.app, max) : '',
+      ]);
+    case 'office':
+      return compactParts([
+        String(a.action || ''),
+        a.path ? truncateToolText(a.path, max) : a.session ? String(a.session) : '',
+      ]);
     case 'read_mcp_resource':
       return truncateToolText(a.uri || '', max);
     case 'list_mcp_resources':
@@ -559,6 +580,12 @@ export function toolWorkUnit(name, args = {}, category = '') {
       return unitDescriptor('Web Research', { count: queryCount(a, 'query', 'queries', 'keywords') || 1, noun: 'query', pluralNoun: 'queries' });
     case 'web_fetch':
       return unitDescriptor('Web Research', { count: queryCount(a, 'url', 'urls', 'uri', 'uris') || 1, active: 'Fetching', done: 'Fetched', noun: 'URL', pluralNoun: 'URLs' });
+    case 'browser':
+      return unitDescriptor('Browser', { count: 1, active: 'Browsing', done: 'Browsed', noun: 'action' });
+    case 'computer':
+      return unitDescriptor('Computer', { count: 1, active: 'Operating', done: 'Operated', noun: 'action' });
+    case 'office':
+      return unitDescriptor('Office', { count: 1, active: 'Editing', done: 'Edited', noun: 'document action' });
     case 'fetch': {
       const fetchLimit = Number(a.limit ?? a.messages);
       const fetchCount = Number.isFinite(fetchLimit) && fetchLimit > 0

package/src/runtime/shared/turn-snapshot-store.mjs

@@ -109,6 +109,7 @@ export async function saveTurnSnapshotRecord(sessionId, turn) {
       const turns = (existing?.turns || []).filter((entry) => entry?.generation !== generation);
       turns.push({
         generation,
+        checkpointId: clean(turn?.checkpointId),
         root,
         baselineTree,
         // Relative, forward-slashed paths this session's own tools mutated.