mixdog 0.9.1 → 0.9.2

package/scripts/toolcall-args-test.mjs

@@ -21,10 +21,12 @@ import {
     isInvalidToolArgsMarker,
     formatInvalidToolArgsResult,
 } from '../src/runtime/agent/orchestrator/providers/openai-compat-stream.mjs';
+import { parseSSEStream } from '../src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs';
 import { classifyError } from '../src/runtime/agent/orchestrator/providers/retry-classifier.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const STREAM_SRC = resolve(__dirname, '../src/runtime/agent/orchestrator/providers/openai-compat-stream.mjs');
+const UTF8 = new TextEncoder();
 
 // Captures the synchronous throw of `fn` and returns the Error, failing if none.
 function captureThrow(fn) {
@@ -148,3 +150,82 @@ test('retry-classifier: truncated stream (no finish) → transient (preserved be
         parseCompletedToolCallArgumentsJson('{', 'test'));
     assert.equal(classifyError(transient), 'transient');
 });
+
+function responseFromSseText(text) {
+    return {
+        body: new ReadableStream({
+            start(controller) {
+                controller.enqueue(UTF8.encode(text));
+                controller.close();
+            },
+        }),
+    };
+}
+
+function livePingOnlyResponse(intervalMs = 5) {
+    let timer = null;
+    return {
+        body: new ReadableStream({
+            start(controller) {
+                timer = setInterval(() => {
+                    try { controller.enqueue(UTF8.encode(':ping\n\n')); }
+                    catch { if (timer) clearInterval(timer); }
+                }, intervalMs);
+            },
+            cancel() {
+                if (timer) clearInterval(timer);
+            },
+        }),
+    };
+}
+
+test('anthropic SSE: comments do not count as stream progress', async () => {
+    const state = { firstMessageTimeoutMs: 100 };
+    let deltas = 0;
+    const result = await parseSSEStream(
+        responseFromSseText([
+            ':ping',
+            '',
+            'event: message_start',
+            'data: {"type":"message_start","message":{"model":"claude-test","usage":{"input_tokens":1}}}',
+            '',
+            'event: content_block_delta',
+            'data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"hi"}}',
+            '',
+            'event: message_stop',
+            'data: {"type":"message_stop"}',
+            '',
+        ].join('\n')),
+        null,
+        null,
+        () => { deltas += 1; },
+        null,
+        state,
+        null,
+    );
+    assert.equal(result.content, 'hi');
+    assert.equal(deltas, 1, 'only the text delta should count as semantic progress');
+});
+
+test('anthropic SSE: ping-only stream times out before empty-stream guard can hang', async () => {
+    const controller = new AbortController();
+    let deltas = 0;
+    await assert.rejects(
+        () => parseSSEStream(
+            livePingOnlyResponse(),
+            controller.signal,
+            (reason) => controller.abort(reason),
+            () => { deltas += 1; },
+            null,
+            { firstMessageTimeoutMs: 30 },
+            null,
+        ),
+        (err) => {
+            assert.equal(err.code, 'EEMPTYSTREAM');
+            assert.equal(err.isEmptyStream, true);
+            assert.equal(err.firstByteTimeout, true);
+            return true;
+        },
+    );
+    assert.equal(deltas, 0, 'SSE comments must not refresh semantic stream progress');
+});

package/src/agents/debugger/AGENT.md

@@ -4,8 +4,8 @@ permission: read
 
 # Debugger
 
-Bug tracking and analysis agent.
+Root-cause analysis agent.
 
-Return the most likely cause, supporting evidence, and the smallest useful next
-check or fix path. Avoid broad speculation; distinguish confirmed facts from
-inferences.
+Smallest confirmed cause chain before fixes. Return likely cause, evidence
+(`file:line`), smallest next check/fix. Fragments only, no narration. Mark
+confirmed facts vs inferences; avoid broad speculation.

package/src/agents/heavy-worker/AGENT.md

@@ -3,7 +3,9 @@ permission: read-write
 ---
 
 # Heavy Worker
-Complex implementation agent.
+Broad implementation agent.
 
-Reviewer/Lead verification follows your delivery; avoid broad build/test loops and focus on minimal checks plus how to verify. Scope confirmation, obvious-error checks, and static review are fine.
+Bounded slices; smallest coherent change, not rewrite. Stop: unclear scope,
+growing blast radius, or Lead-only verification. Minimal checks + how-to-verify.
+Handoff fragments only, no report bloat: changed `file:line`, verification, risks.
 

package/src/agents/reviewer/AGENT.md

@@ -4,8 +4,8 @@ permission: read
 
 # Reviewer
 
-Cross-checking review agent.
+Regression/risk review agent.
 
-Return findings first, ordered by severity, with precise file references when
-available. If no actionable issues are found, say so clearly and note only
-material residual risk or missing verification.
+Find actionable correctness/regression/security/verification risks. Findings
+first, severity-ordered, one line with `file:line`; skip non-risky nits. No
+preamble/prose padding. If clean, one line + only material residual risk.

package/src/agents/worker/AGENT.md

@@ -3,7 +3,9 @@ permission: read-write
 ---
 
 # Worker
-Basic implementation agent.
+Scoped implementation agent.
 
-Reviewer/Lead verification follows your delivery; keep self-checks minimal (scope confirmation and obvious-error checks). Static review, change summaries, and manual verification notes are fine.
+Smallest scoped change; no drive-by cleanup. Stop when done/blocked.
+Self-check scope+obvious errors; Lead/Reviewer verify. Handoff fragments only,
+no report bloat: changed `file:line`, verification, risks.
 

package/src/app.mjs

@@ -5,7 +5,7 @@ import { performance } from 'node:perf_hooks';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VALUE_OPTIONS = new Set(['--provider', '--model']);
-const FLAG_OPTIONS = new Set(['--readonly', '--help', '-h', '--plain', '--react']);
+const FLAG_OPTIONS = new Set(['--readonly', '--help', '-h', '--plain', '--react', '--remote', '--onboarding']);
 const HEADLESS_ROLE_ALIASES = new Map([
   ['explorer', 'explore'],
   ['explore', 'explore'],
@@ -72,7 +72,7 @@ function positionalArgs(argv) {
   return out;
 }
 
-function normalizeHeadlessRole(value) {
+function normalizeHeadlessAgent(value) {
   const key = String(value || '').trim().toLowerCase().replace(/[\s_]+/g, '-');
   return HEADLESS_ROLE_ALIASES.get(key) || null;
 }
@@ -85,11 +85,11 @@ export function parseHeadlessRoleCommand(argv = []) {
     return { error: 'usage: mixdog <role> <message...>' };
   }
 
-  const role = normalizeHeadlessRole(args[0]);
-  if (!role) return null;
+  const agent = normalizeHeadlessAgent(args[0]);
+  if (!agent) return null;
   const message = args.slice(1).join(' ').trim();
   if (!message) return { error: `usage: mixdog ${args[0]} <message...>` };
-  return { role, message };
+  return { agent, message };
 }
 
 /**
@@ -110,10 +110,14 @@ export async function run(argv = []) {
   const provIdx = argv.indexOf('--provider');
   const modelIdx = argv.indexOf('--model');
   const toolMode = argv.includes('--readonly') ? 'readonly' : 'full';
+  const remote = argv.includes('--remote');
+  const forceOnboarding = argv.includes('--onboarding');
   const opts = {
     provider: provIdx >= 0 ? argv[provIdx + 1] : undefined,
     model: modelIdx >= 0 ? argv[modelIdx + 1] : undefined,
     toolMode,
+    remote,
+    forceOnboarding,
   };
 
   // `--help` / `-h`: keep this path tiny; do not import the REPL/runtime stack.
@@ -142,7 +146,7 @@ export async function run(argv = []) {
   if (headless) {
     const { runHeadlessRole } = await import('./headless-role.mjs');
     return await runHeadlessRole({
-      role: headless.role,
+      agent: headless.agent,
       message: headless.message,
       provider: opts.provider,
       model: opts.model,

package/src/defaults/{hidden-roles.json → agents.json}

@@ -1,7 +1,7 @@
 {
-  "roles": [
+  "agents": [
     {
-      "name": "explorer",
+      "agent": "explorer",
       "slot": "explore",
       "systemFile": "rules/agent/30-explorer.md",
       "description": "Filesystem navigation agent invoked by the `explore` MCP tool",
@@ -12,7 +12,7 @@
       "stallCap": { "idleSeconds": 240, "toolRunningSeconds": 180 }
     },
     {
-      "name": "cycle1-agent",
+      "agent": "cycle1-agent",
       "slot": "cycle1",
       "systemFile": "rules/agent/40-cycle1-agent.md",
       "description": "Chunker/classifier invoked by memory-cycle runCycle1",
@@ -24,7 +24,7 @@
       "stallCap": { "idleSeconds": 300, "toolRunningSeconds": 300 }
     },
     {
-      "name": "cycle2-agent",
+      "agent": "cycle2-agent",
       "slot": "cycle2",
       "systemFile": "rules/agent/41-cycle2-agent.md",
       "description": "Root re-scorer invoked by memory-cycle runCycle2",
@@ -36,7 +36,7 @@
       "stallCap": { "idleSeconds": 300, "toolRunningSeconds": 300 }
     },
     {
-      "name": "cycle3-agent",
+      "agent": "cycle3-agent",
       "slot": "cycle3",
       "systemFile": "rules/agent/42-cycle3-agent.md",
       "description": "Core memory reviewer invoked by memory-cycle runCycle3",
@@ -48,7 +48,7 @@
       "stallCap": { "idleSeconds": 300, "toolRunningSeconds": 300 }
     },
     {
-      "name": "scheduler-task",
+      "agent": "scheduler-task",
       "slot": "scheduler",
       "systemFile": "agents/scheduler-task/AGENT.md",
       "description": "Scheduled-task executor invoked by scheduler tick",
@@ -61,7 +61,7 @@
       "stallCap": { "idleSeconds": 600, "toolRunningSeconds": 600 }
     },
     {
-      "name": "webhook-handler",
+      "agent": "webhook-handler",
       "slot": "webhook",
       "systemFile": "agents/webhook-handler/AGENT.md",
       "description": "Webhook payload handler invoked by inbound webhook events",

package/src/examples/schedules/SCHEDULE.example.md

@@ -0,0 +1,32 @@
+---
+time: 0 9 * * *
+timezone: Asia/Seoul
+days: weekday
+channel: main
+model: gpt-5
+enabled: true
+---
+
+# Schedule instructions (prompt body)
+
+This whole markdown body is the prompt the scheduler runs when the cron fires.
+Everything above the second `---` is frontmatter metadata; everything below is
+the instructions.
+
+Frontmatter keys:
+
+- `time` — required. 5- or 6-field cron expression (e.g. `0 9 * * *`).
+- `timezone` — optional IANA tz (e.g. `Asia/Seoul`); host-local when omitted.
+- `days` — optional; omit for `daily`. Allowed values: `weekday`, `weekend`, or
+  a comma list of day abbreviations (`mon,tue,wed,thu,fri,sat,sun`). Written
+  only when not `daily`.
+- `channel` — optional channel label. WITH a channel the run dispatches to that
+  channel (non-interactive) and REQUIRES `model`; WITHOUT it the run injects
+  into the current session (interactive).
+- `model` — required when `channel` is set; the preset id used for dispatch.
+- `enabled` — optional; written `false` to disable. Missing/anything-else means
+  enabled. The reader casts this string to a boolean.
+
+Storage layout: `<data>/schedules/<name>/SCHEDULE.md` — one file per schedule.
+This `.example.md` is documentation only; the readers match `SCHEDULE.md`
+exactly, so this file is never loaded as a real schedule.

package/src/examples/webhooks/WEBHOOK.example.md

@@ -0,0 +1,40 @@
+---
+parser: github
+channel: main
+model: gpt-5
+role: webhook-handler
+enabled: true
+---
+
+# Webhook instructions (prompt body)
+
+This markdown body is the handler prompt. On each verified delivery the webhook
+payload is fenced as untrusted data and appended after these instructions.
+Everything above the second `---` is frontmatter metadata; everything below is
+the instructions.
+
+Frontmatter keys:
+
+- `parser` — required. One of `github`, `generic`, `stripe`, `sentry`. Selects
+  the signature header + verification scheme.
+- `channel` — optional channel label. WITH a channel the delivery is dispatched
+  as a delegate (REQUIRES `model` + `role`) and reported to that channel;
+  WITHOUT it the payload is enqueued into the current session (interactive).
+- `model` — required when `channel` is set; the preset id used for delegate
+  dispatch.
+- `role` — user-workflow role for delegate mode; defaults to `webhook-handler`.
+- `enabled` — optional; written `false` to disable (delivery rejected with 404).
+  Missing/anything-else means enabled. The reader casts this string to a boolean.
+
+Secret storage: the HMAC secret is NOT a frontmatter key. It lives in a side
+file `<data>/webhooks/<name>/secret` (plaintext, one line), autogenerated
+(24 random bytes hex) when omitted at save time. Keeping it out of the lossy
+`key: value` frontmatter lets an arbitrary user secret (quotes/colons/newlines)
+round-trip losslessly and prevents enable/disable rewrites from corrupting it.
+The admin list API never exposes the value — only `secretSet: true/false`.
+
+Storage layout: `<data>/webhooks/<name>/WEBHOOK.md` — one file per endpoint.
+`secret` and `deliveries.jsonl` live alongside it and are managed separately.
+This
+`.example.md` is documentation only; the readers match `WEBHOOK.md` exactly, so
+this file is never loaded as a real endpoint.

package/src/headless-role.mjs

@@ -19,16 +19,16 @@ function taskIdFromOutput(text) {
   return clean(text).match(/agent task:\s*(\S+)/i)?.[1] || null;
 }
 
-function makeTag(role) {
-  return `headless-${role}-${process.pid}-${Date.now()}`
+function makeTag(agent) {
+  return `headless-${agent}-${process.pid}-${Date.now()}`
     .replace(/[^A-Za-z0-9_.-]+/g, '-')
     .replace(/^-+|-+$/g, '');
 }
 
-function buildHeadlessSpawnArgs({ role, tag, cwd, message, provider, model } = {}) {
+export function buildHeadlessSpawnArgs({ agent, tag, cwd, message, provider, model } = {}) {
   const spawnArgs = {
     type: 'spawn',
-    role: clean(role),
+    agent: clean(agent),
     tag,
     cwd,
     prompt: clean(message),
@@ -52,7 +52,7 @@ function buildAgentRunner(cwd) {
 }
 
 export async function runHeadlessRole({
-  role,
+  agent,
   message,
   provider,
   model,
@@ -60,10 +60,10 @@ export async function runHeadlessRole({
   write = (text) => stdout.write(text),
   writeErr = (text) => stderr.write(text),
 } = {}) {
-  const cleanRole = clean(role);
+  const cleanAgent = clean(agent);
   const cleanMessage = clean(message);
-  if (!cleanRole) {
-    writeErr('mixdog: role is required\n');
+  if (!cleanAgent) {
+    writeErr('mixdog: agent is required\n');
     return 1;
   }
   if (!cleanMessage) {
@@ -71,8 +71,8 @@ export async function runHeadlessRole({
     return 1;
   }
 
-  const agent = buildAgentRunner(cwd);
-  const tag = makeTag(cleanRole);
+  const agentRunner = buildAgentRunner(cwd);
+  const tag = makeTag(cleanAgent);
   const context = {
     invocationSource: 'headless',
     cwd,
@@ -80,7 +80,7 @@ export async function runHeadlessRole({
     clientHostPid: process.pid,
   };
   const spawnArgs = buildHeadlessSpawnArgs({
-    role: cleanRole,
+    agent: cleanAgent,
     tag,
     cwd,
     message: cleanMessage,
@@ -91,7 +91,7 @@ export async function runHeadlessRole({
   let taskId = null;
   let lastOutput = '';
   try {
-    const started = await agent.execute(spawnArgs, context);
+    const started = await agentRunner.execute(spawnArgs, context);
     lastOutput = clean(started);
     taskId = taskIdFromOutput(started);
     if (!taskId) {
@@ -100,7 +100,7 @@ export async function runHeadlessRole({
     }
 
     for (;;) {
-      lastOutput = clean(await agent.execute({ type: 'read', task_id: taskId }, context));
+      lastOutput = clean(await agentRunner.execute({ type: 'read', task_id: taskId }, context));
       if (TERMINAL_STATUS_RE.test(lastOutput)) break;
       await sleep(500);
     }
@@ -109,7 +109,7 @@ export async function runHeadlessRole({
     return FAILURE_STATUS_RE.test(lastOutput) ? 1 : 0;
   } finally {
     try {
-      await agent.execute({ type: 'close', tag }, context);
+      await agentRunner.execute({ type: 'close', tag }, context);
     } catch {
       // Best-effort cleanup only; the command result above is the useful signal.
     }

package/src/help.mjs

@@ -6,6 +6,7 @@ export const HELP_LINES = [
   '',
   'Usage:',
   '  mixdog [--provider <name>] [--model <name>] [--readonly]',
+  '  mixdog [--onboarding]      re-run the first-run setup wizard',
   '  mixdog <role> <message...>',
   '  mixdog --help',
   '',

package/src/lib/rules-builder.cjs

@@ -21,10 +21,10 @@
  * Source files (rules/):
  *   - shared/01-tool.md              — universal tool policy (Lead + agent BP1, identical full set)
  *   - lead/lead-tool.md             — Lead-specific control-tower / delegation / ToolSearch guidance
- *   - lead/01-04                     — Lead workflow / channels / team / general
+ *   - lead/01-02                     — Lead general / channels
  *   - output-styles/<name>.md        — Lead output style, selected by config outputStyle
  *   - agent/00-common.md             — agent common behavior + universal worker contract (BP2)
- *   - agent/10..50-*.md              — per-hidden-role bodies (consumed by loadScopedRoleInstructions)
+ *   - agent/10..50-*.md              — per-hidden-agent bodies (consumed by loadScopedRoleInstructions)
  *
  * Core memory snapshot is injected separately from the memory worker (pgdata)
  * (Lead only).
@@ -184,29 +184,29 @@ function loadOutputStyle({ PLUGIN_ROOT, DATA_DIR }) {
 
 /**
  * Resolve the DATA_DIR subdir whose *.md instruction tree is sent as
- * BP4-adjacent user/task data, from the role's `instructionDir` metadata in
- * defaults/hidden-roles.json. Returns null when the role declares none.
+ * BP4-adjacent user/task data, from the agent's `instructionDir` metadata in
+ * defaults/agents.json. Returns null when the agent declares none.
  *
- * Mirrors internal-roles.mjs getRoleInstructionDir — rules-builder is CommonJS
+ * Mirrors internal-agents.mjs getAgentInstructionDir — rules-builder is CommonJS
  * and cannot import the ESM module, so it reads the same source of truth
  * directly. Keeps the webhook-handler→webhooks / scheduler-task→schedules
- * mapping declarative instead of a hard-coded role-name ternary.
+ * mapping declarative instead of a hard-coded agent-name ternary.
  *
  * @param {string} mixdogRoot
- * @param {string} role
+ * @param {string} agent
  * @returns {string|null}
  */
-function resolveRoleInstructionDir(mixdogRoot, role) {
-  if (!mixdogRoot || !role) return null;
-  const metaPath = path.join(mixdogRoot, 'defaults', 'hidden-roles.json');
+function resolveAgentInstructionDir(mixdogRoot, agent) {
+  if (!mixdogRoot || !agent) return null;
+  const metaPath = path.join(mixdogRoot, 'defaults', 'agents.json');
   let raw;
   try {
     raw = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
   } catch (e) {
-    throw new Error(`[rules-builder] failed to read/parse hidden-roles.json at ${metaPath}: ${e.message}`);
+    throw new Error(`[rules-builder] failed to read/parse agents.json at ${metaPath}: ${e.message}`);
   }
-  for (const entry of (raw.roles || [])) {
-    if (entry && entry.name === role) {
+  for (const entry of (raw.agents || [])) {
+    if (entry && entry.agent === agent) {
       const dir = typeof entry.instructionDir === 'string' ? entry.instructionDir.trim() : '';
       return dir || null;
     }
@@ -247,34 +247,15 @@ function composeUserAddressBullet(memoryConfig) {
 }
 
 function splitLeadGeneral(general, addressBullet = '') {
-  const lines = String(general || '').split(/\r?\n/);
-  const roleLines = [];
-  const metaLines = [];
-  let inMeta = false;
-  for (const line of lines) {
-    if (/language used by the user/i.test(line)) {
-      if (!inMeta) {
-        metaLines.push('# General');
-        metaLines.push('');
-        inMeta = true;
-      }
-      metaLines.push(line);
-    } else {
-      roleLines.push(line);
-    }
-  }
-  if (addressBullet) {
-    if (!inMeta) {
-      metaLines.push('# General');
-      metaLines.push('');
-      inMeta = true;
-    }
-    metaLines.push(addressBullet);
-  }
-  return {
-    role: roleLines.join('\n').trim(),
-    meta: metaLines.join('\n').trim(),
-  };
+  // Language is owned solely by the `# Language` section (buildLanguageSection);
+  // general.md never carries a language line, so there is no language content to
+  // promote into the meta layer here. The only meta-tier content this split
+  // emits is the optional user address-form bullet.
+  const role = String(general || '').trim();
+  const meta = addressBullet
+    ? ['# General', '', addressBullet].join('\n').trim()
+    : '';
+  return { role, meta };
 }
 
 function buildSharedToolContent({ PLUGIN_ROOT }) {
@@ -299,9 +280,6 @@ function buildLeadRoleContent({ PLUGIN_ROOT, DATA_DIR }) {
   const channels = readOptional(path.join(LEAD_DIR, '02-channels.md'));
   if (channels) parts.push(channels);
 
-  const workflow = readOptional(path.join(LEAD_DIR, '04-workflow.md'));
-  if (workflow) parts.push(workflow);
-
   return parts.join('\n\n');
 }
 
@@ -420,26 +398,26 @@ function buildAgentRetrievalInjectionContent() {
  * @param {object} opts
  * @param {string} opts.PLUGIN_ROOT
  * @param {string} opts.DATA_DIR
- * @param {string|null} opts.currentRole
+ * @param {string|null} opts.currentAgent
  * @returns {string}
  */
-function buildAgentRoleSpecificContent({ PLUGIN_ROOT, DATA_DIR, currentRole }) {
-  if (!currentRole) return '';
+function buildAgentRoleSpecificContent({ PLUGIN_ROOT, DATA_DIR, currentAgent }) {
+  if (!currentAgent) return '';
   const parts = [];
 
-  // The role's instruction subdir (webhook-handler → webhooks, scheduler-task
-  // → schedules) is declared via `instructionDir` in defaults/hidden-roles.json
-  // rather than hard-coded here, so adding a new inbound-event role needs only
+  // The agent's instruction subdir (webhook-handler → webhooks, scheduler-task
+  // → schedules) is declared via `instructionDir` in defaults/agents.json
+  // rather than hard-coded here, so adding a new inbound-event agent needs only
   // a metadata entry.
-  const subdirForRole = resolveRoleInstructionDir(PLUGIN_ROOT, currentRole);
-  if (subdirForRole) {
-    const dir = path.join(DATA_DIR, subdirForRole);
+  const subdirForAgent = resolveAgentInstructionDir(PLUGIN_ROOT, currentAgent);
+  if (subdirForAgent) {
+    const dir = path.join(DATA_DIR, subdirForAgent);
     const collected = collectMarkdownFilesRecursive(dir);
     if (collected.length > 0) {
       collected.sort();
       const blocks = collected.map(f => stripFrontmatter(readOptional(f))).filter(Boolean);
       if (blocks.length > 0) {
-        parts.push([`# Agent ${subdirForRole}`, '', blocks.join('\n\n')].join('\n'));
+        parts.push([`# Agent ${subdirForAgent}`, '', blocks.join('\n\n')].join('\n'));
       }
     }
   }