metame-cli 1.4.15 → 1.4.18

package/scripts/task-board.js

@@ -0,0 +1,398 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DEFAULT_DB_PATH = path.join(os.homedir(), '.metame', 'task_board.db');
+
+function parseJsonSafe(raw, fallback) {
+  try { return JSON.parse(raw); } catch { return fallback; }
+}
+
+function toJson(value, fallback) {
+  try { return JSON.stringify(value); } catch { return JSON.stringify(fallback); }
+}
+
+function sanitizeText(input, maxLen = 1000) {
+  return String(input || '').replace(/[\x00-\x1F\x7F]/g, ' ').trim().slice(0, maxLen);
+}
+
+function sanitizeStringArray(values, maxItems = 40, maxItemLen = 500) {
+  if (!Array.isArray(values)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const item of values) {
+    const v = sanitizeText(item, maxItemLen);
+    if (!v || seen.has(v)) continue;
+    seen.add(v);
+    out.push(v);
+    if (out.length >= maxItems) break;
+  }
+  return out;
+}
+
+function createTaskBoard(opts = {}) {
+  const dbPath = opts.dbPath || DEFAULT_DB_PATH;
+  const logger = typeof opts.logger === 'function' ? opts.logger : null;
+  let db = null;
+
+  function logWarn(msg) {
+    if (logger) logger(msg);
+  }
+
+  function getDb() {
+    if (db) return db;
+    const dir = path.dirname(dbPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    const { DatabaseSync } = require('node:sqlite');
+    db = new DatabaseSync(dbPath);
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA busy_timeout = 3000');
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS tasks (
+        task_id             TEXT PRIMARY KEY,
+        scope_id            TEXT NOT NULL DEFAULT '',
+        parent_task_id      TEXT,
+        from_agent          TEXT NOT NULL,
+        to_agent            TEXT NOT NULL,
+        goal                TEXT NOT NULL,
+        task_kind           TEXT NOT NULL DEFAULT 'team',
+        participants        TEXT NOT NULL DEFAULT '[]',
+        definition_of_done  TEXT NOT NULL DEFAULT '[]',
+        inputs              TEXT NOT NULL DEFAULT '{}',
+        artifacts           TEXT NOT NULL DEFAULT '[]',
+        owned_paths         TEXT NOT NULL DEFAULT '[]',
+        status              TEXT NOT NULL DEFAULT 'queued',
+        priority            TEXT NOT NULL DEFAULT 'normal',
+        summary             TEXT NOT NULL DEFAULT '',
+        last_error          TEXT NOT NULL DEFAULT '',
+        created_at          TEXT NOT NULL,
+        updated_at          TEXT NOT NULL
+      )
+    `);
+    try { db.exec("ALTER TABLE tasks ADD COLUMN scope_id TEXT NOT NULL DEFAULT ''"); } catch {}
+    try { db.exec("ALTER TABLE tasks ADD COLUMN task_kind TEXT NOT NULL DEFAULT 'team'"); } catch {}
+    try { db.exec("ALTER TABLE tasks ADD COLUMN participants TEXT NOT NULL DEFAULT '[]'"); } catch {}
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS handoffs (
+        handoff_id          TEXT PRIMARY KEY,
+        task_id             TEXT NOT NULL,
+        from_agent          TEXT NOT NULL,
+        to_agent            TEXT NOT NULL,
+        payload             TEXT NOT NULL DEFAULT '{}',
+        status              TEXT NOT NULL DEFAULT 'sent',
+        created_at          TEXT NOT NULL,
+        updated_at          TEXT NOT NULL
+      )
+    `);
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS task_events (
+        id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+        task_id             TEXT NOT NULL,
+        event_type          TEXT NOT NULL,
+        actor               TEXT NOT NULL,
+        body                TEXT NOT NULL DEFAULT '{}',
+        created_at          TEXT NOT NULL
+      )
+    `);
+
+    try { db.exec('CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status)'); } catch {}
+    try { db.exec('CREATE INDEX IF NOT EXISTS idx_tasks_scope_id ON tasks(scope_id)'); } catch {}
+    try { db.exec('CREATE INDEX IF NOT EXISTS idx_tasks_updated_at ON tasks(updated_at)'); } catch {}
+    try { db.exec('CREATE INDEX IF NOT EXISTS idx_events_task_id ON task_events(task_id)'); } catch {}
+    try { db.exec('CREATE INDEX IF NOT EXISTS idx_handoffs_task_id ON handoffs(task_id)'); } catch {}
+    return db;
+  }
+
+  function upsertTask(task) {
+    if (!task || !task.task_id) return { ok: false, error: 'task_id_required' };
+    const nowIso = new Date().toISOString();
+    const safe = {
+      task_id: sanitizeText(task.task_id, 80),
+      scope_id: sanitizeText(task.scope_id, 120) || sanitizeText(task.task_id, 80),
+      parent_task_id: sanitizeText(task.parent_task_id, 80) || null,
+      from_agent: sanitizeText(task.from_agent, 80) || 'unknown',
+      to_agent: sanitizeText(task.to_agent, 80),
+      goal: sanitizeText(task.goal, 500),
+      task_kind: sanitizeText(task.task_kind, 20) || 'team',
+      participants: sanitizeStringArray(task.participants, 40, 80),
+      definition_of_done: sanitizeStringArray(task.definition_of_done, 20, 300),
+      inputs: task.inputs && typeof task.inputs === 'object' ? task.inputs : {},
+      artifacts: sanitizeStringArray(task.artifacts, 40, 500),
+      owned_paths: sanitizeStringArray(task.owned_paths, 40, 500),
+      status: sanitizeText(task.status, 20) || 'queued',
+      priority: sanitizeText(task.priority, 20) || 'normal',
+      summary: sanitizeText(task.summary, 2000),
+      last_error: sanitizeText(task.last_error, 2000),
+      created_at: sanitizeText(task.created_at, 64) || nowIso,
+      updated_at: sanitizeText(task.updated_at, 64) || nowIso,
+    };
+    if (!safe.task_id || !safe.to_agent || !safe.goal) {
+      return { ok: false, error: 'task_fields_missing' };
+    }
+
+    const sql = `
+      INSERT INTO tasks (
+        task_id, scope_id, parent_task_id, from_agent, to_agent, goal, task_kind, participants,
+        definition_of_done, inputs, artifacts, owned_paths, status, priority, summary, last_error,
+        created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(task_id) DO UPDATE SET
+        scope_id = excluded.scope_id,
+        parent_task_id = excluded.parent_task_id,
+        from_agent = excluded.from_agent,
+        to_agent = excluded.to_agent,
+        goal = excluded.goal,
+        task_kind = excluded.task_kind,
+        participants = excluded.participants,
+        definition_of_done = excluded.definition_of_done,
+        inputs = excluded.inputs,
+        artifacts = excluded.artifacts,
+        owned_paths = excluded.owned_paths,
+        status = excluded.status,
+        priority = excluded.priority,
+        summary = excluded.summary,
+        last_error = excluded.last_error,
+        updated_at = excluded.updated_at
+    `;
+    try {
+      getDb().prepare(sql).run(
+        safe.task_id,
+        safe.scope_id,
+        safe.parent_task_id,
+        safe.from_agent,
+        safe.to_agent,
+        safe.goal,
+        safe.task_kind,
+        toJson(safe.participants, []),
+        toJson(safe.definition_of_done, []),
+        toJson(safe.inputs, {}),
+        toJson(safe.artifacts, []),
+        toJson(safe.owned_paths, []),
+        safe.status,
+        safe.priority,
+        safe.summary,
+        safe.last_error,
+        safe.created_at,
+        safe.updated_at
+      );
+      return { ok: true, task_id: safe.task_id };
+    } catch (e) {
+      logWarn(`TaskBoard upsertTask failed: ${e.message}`);
+      return { ok: false, error: e.message };
+    }
+  }
+
+  function appendTaskEvent(taskId, eventType, actor, body = {}) {
+    const safeTaskId = sanitizeText(taskId, 80);
+    if (!safeTaskId) return { ok: false, error: 'task_id_required' };
+    const safeEvent = sanitizeText(eventType, 60) || 'event';
+    const safeActor = sanitizeText(actor, 80) || 'system';
+    const nowIso = new Date().toISOString();
+    try {
+      getDb().prepare(`
+        INSERT INTO task_events (task_id, event_type, actor, body, created_at)
+        VALUES (?, ?, ?, ?, ?)
+      `).run(safeTaskId, safeEvent, safeActor, toJson(body, {}), nowIso);
+      return { ok: true };
+    } catch (e) {
+      logWarn(`TaskBoard appendTaskEvent failed: ${e.message}`);
+      return { ok: false, error: e.message };
+    }
+  }
+
+  function recordHandoff(handoff) {
+    const nowIso = new Date().toISOString();
+    const safe = {
+      handoff_id: sanitizeText(handoff && handoff.handoff_id, 90),
+      task_id: sanitizeText(handoff && handoff.task_id, 80),
+      from_agent: sanitizeText(handoff && handoff.from_agent, 80) || 'unknown',
+      to_agent: sanitizeText(handoff && handoff.to_agent, 80),
+      payload: handoff && typeof handoff.payload === 'object' ? handoff.payload : {},
+      status: sanitizeText(handoff && handoff.status, 30) || 'sent',
+      created_at: sanitizeText(handoff && handoff.created_at, 64) || nowIso,
+      updated_at: sanitizeText(handoff && handoff.updated_at, 64) || nowIso,
+    };
+    if (!safe.handoff_id || !safe.task_id || !safe.to_agent) return { ok: false, error: 'handoff_fields_missing' };
+    try {
+      getDb().prepare(`
+        INSERT INTO handoffs (handoff_id, task_id, from_agent, to_agent, payload, status, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(handoff_id) DO UPDATE SET
+          payload = excluded.payload,
+          status = excluded.status,
+          updated_at = excluded.updated_at
+      `).run(
+        safe.handoff_id,
+        safe.task_id,
+        safe.from_agent,
+        safe.to_agent,
+        toJson(safe.payload, {}),
+        safe.status,
+        safe.created_at,
+        safe.updated_at
+      );
+      return { ok: true };
+    } catch (e) {
+      logWarn(`TaskBoard recordHandoff failed: ${e.message}`);
+      return { ok: false, error: e.message };
+    }
+  }
+
+  function getTask(taskId) {
+    const safeTaskId = sanitizeText(taskId, 80);
+    if (!safeTaskId) return null;
+    try {
+      const row = getDb().prepare('SELECT * FROM tasks WHERE task_id = ?').get(safeTaskId);
+      if (!row) return null;
+      return {
+        ...row,
+        participants: parseJsonSafe(row.participants, []),
+        definition_of_done: parseJsonSafe(row.definition_of_done, []),
+        inputs: parseJsonSafe(row.inputs, {}),
+        artifacts: parseJsonSafe(row.artifacts, []),
+        owned_paths: parseJsonSafe(row.owned_paths, []),
+      };
+    } catch (e) {
+      logWarn(`TaskBoard getTask failed: ${e.message}`);
+      return null;
+    }
+  }
+
+  function listRecentTasks(limit = 10, status = null, taskKind = null) {
+    const lim = Math.max(1, Math.min(100, Number(limit) || 10));
+    const statusVal = sanitizeText(status, 30);
+    const kindVal = sanitizeText(taskKind, 20);
+    try {
+      let sql = 'SELECT * FROM tasks';
+      const params = [];
+      const where = [];
+      if (statusVal) { where.push('status = ?'); params.push(statusVal); }
+      if (kindVal) { where.push('task_kind = ?'); params.push(kindVal); }
+      if (where.length > 0) sql += ' WHERE ' + where.join(' AND ');
+      sql += ' ORDER BY updated_at DESC LIMIT ?';
+      params.push(lim);
+      const rows = getDb().prepare(sql).all(...params);
+      return rows.map(r => ({
+        ...r,
+        participants: parseJsonSafe(r.participants, []),
+        definition_of_done: parseJsonSafe(r.definition_of_done, []),
+        inputs: parseJsonSafe(r.inputs, {}),
+        artifacts: parseJsonSafe(r.artifacts, []),
+        owned_paths: parseJsonSafe(r.owned_paths, []),
+      }));
+    } catch (e) {
+      logWarn(`TaskBoard listRecentTasks failed: ${e.message}`);
+      return [];
+    }
+  }
+
+  function listTaskEvents(taskId, limit = 20) {
+    const safeTaskId = sanitizeText(taskId, 80);
+    if (!safeTaskId) return [];
+    const lim = Math.max(1, Math.min(200, Number(limit) || 20));
+    try {
+      const rows = getDb()
+        .prepare('SELECT * FROM task_events WHERE task_id = ? ORDER BY id DESC LIMIT ?')
+        .all(safeTaskId, lim);
+      return rows.map(r => ({ ...r, body: parseJsonSafe(r.body, {}) }));
+    } catch (e) {
+      logWarn(`TaskBoard listTaskEvents failed: ${e.message}`);
+      return [];
+    }
+  }
+
+  function listScopeTasks(scopeId, limit = 30) {
+    const safeScopeId = sanitizeText(scopeId, 120);
+    if (!safeScopeId) return [];
+    const lim = Math.max(1, Math.min(200, Number(limit) || 30));
+    try {
+      const rows = getDb()
+        .prepare('SELECT * FROM tasks WHERE scope_id = ? ORDER BY updated_at DESC LIMIT ?')
+        .all(safeScopeId, lim);
+      return rows.map(r => ({
+        ...r,
+        participants: parseJsonSafe(r.participants, []),
+        definition_of_done: parseJsonSafe(r.definition_of_done, []),
+        inputs: parseJsonSafe(r.inputs, {}),
+        artifacts: parseJsonSafe(r.artifacts, []),
+        owned_paths: parseJsonSafe(r.owned_paths, []),
+      }));
+    } catch (e) {
+      logWarn(`TaskBoard listScopeTasks failed: ${e.message}`);
+      return [];
+    }
+  }
+
+  function listScopeParticipants(scopeId) {
+    const tasks = listScopeTasks(scopeId, 200);
+    const set = new Set();
+    for (const t of tasks) {
+      const arr = Array.isArray(t.participants) ? t.participants : [];
+      for (const p of arr) {
+        const v = sanitizeText(p, 80);
+        if (v) set.add(v);
+      }
+      const from = sanitizeText(t.from_agent, 80);
+      const to = sanitizeText(t.to_agent, 80);
+      if (from) set.add(from);
+      if (to) set.add(to);
+    }
+    return [...set];
+  }
+
+  function markTaskStatus(taskId, status, opts = {}) {
+    const task = getTask(taskId);
+    if (!task) return { ok: false, error: 'task_not_found' };
+    const mergedArtifacts = sanitizeStringArray([...(task.artifacts || []), ...sanitizeStringArray(opts.artifacts || [])], 80, 500);
+    const mergedOwned = sanitizeStringArray([...(task.owned_paths || []), ...sanitizeStringArray(opts.owned_paths || [])], 80, 500);
+    const next = {
+      ...task,
+      status: sanitizeText(status, 20) || task.status,
+      summary: sanitizeText(opts.summary, 2000) || task.summary || '',
+      last_error: sanitizeText(opts.last_error, 2000) || '',
+      artifacts: mergedArtifacts,
+      owned_paths: mergedOwned,
+      updated_at: new Date().toISOString(),
+    };
+    return upsertTask(next);
+  }
+
+  function addArtifacts(taskId, artifacts) {
+    const task = getTask(taskId);
+    if (!task) return { ok: false, error: 'task_not_found' };
+    const merged = sanitizeStringArray([...(task.artifacts || []), ...sanitizeStringArray(artifacts || [])], 80, 500);
+    return upsertTask({ ...task, artifacts: merged, updated_at: new Date().toISOString() });
+  }
+
+  function close() {
+    if (!db) return;
+    try { db.close(); } catch {}
+    db = null;
+  }
+
+  return {
+    dbPath,
+    upsertTask,
+    appendTaskEvent,
+    recordHandoff,
+    getTask,
+    listRecentTasks,
+    listScopeTasks,
+    listScopeParticipants,
+    listTaskEvents,
+    markTaskStatus,
+    addArtifacts,
+    close,
+  };
+}
+
+module.exports = {
+  createTaskBoard,
+  DEFAULT_DB_PATH,
+};

package/scripts/task-board.test.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { createTaskBoard } = require('./task-board');
+
+function newTmpDbPath() {
+  const rand = Math.random().toString(36).slice(2, 8);
+  return path.join(os.tmpdir(), `metame-task-board-${Date.now()}-${rand}.db`);
+}
+
+test('task board upsert/get/list/status flow', () => {
+  const dbPath = newTmpDbPath();
+  const board = createTaskBoard({ dbPath });
+  const taskId = 't_test_001';
+
+  const up = board.upsertTask({
+    task_id: taskId,
+    scope_id: 'scope_alpha',
+    from_agent: 'assistant',
+    to_agent: 'coder',
+    goal: 'run tests',
+    task_kind: 'team',
+    participants: ['assistant', 'coder'],
+    definition_of_done: ['all tests pass'],
+    inputs: { cwd: '/tmp/project' },
+    priority: 'high',
+    status: 'queued',
+    created_at: '2026-02-25T00:00:00.000Z',
+    updated_at: '2026-02-25T00:00:00.000Z',
+  });
+  assert.equal(up.ok, true);
+
+  const got = board.getTask(taskId);
+  assert.ok(got);
+  assert.equal(got.task_kind, 'team');
+  assert.equal(got.scope_id, 'scope_alpha');
+  assert.equal(got.goal, 'run tests');
+  assert.deepEqual(got.definition_of_done, ['all tests pass']);
+  assert.deepEqual(got.participants, ['assistant', 'coder']);
+
+  const ev = board.appendTaskEvent(taskId, 'dispatch_enqueued', 'assistant', { x: 1 });
+  assert.equal(ev.ok, true);
+  const events = board.listTaskEvents(taskId, 5);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].event_type, 'dispatch_enqueued');
+
+  const st = board.markTaskStatus(taskId, 'done', { summary: 'ok', artifacts: ['/tmp/log.txt'] });
+  assert.equal(st.ok, true);
+  const done = board.getTask(taskId);
+  assert.equal(done.status, 'done');
+  assert.equal(done.summary, 'ok');
+  assert.deepEqual(done.artifacts, ['/tmp/log.txt']);
+
+  const recent = board.listRecentTasks(5, null, 'team');
+  assert.ok(recent.some(t => t.task_id === taskId));
+
+  const up2 = board.upsertTask({
+    task_id: 't_test_002',
+    scope_id: 'scope_alpha',
+    from_agent: 'coder',
+    to_agent: 'reviewer',
+    goal: 'review test results',
+    task_kind: 'team',
+    participants: ['coder', 'reviewer'],
+    status: 'queued',
+    priority: 'normal',
+    created_at: '2026-02-25T00:01:00.000Z',
+    updated_at: '2026-02-25T00:01:00.000Z',
+  });
+  assert.equal(up2.ok, true);
+  const scoped = board.listScopeTasks('scope_alpha', 10);
+  assert.equal(scoped.length >= 2, true);
+  const participants = board.listScopeParticipants('scope_alpha');
+  assert.deepEqual(participants.sort(), ['assistant', 'coder', 'reviewer'].sort());
+
+  board.close();
+  try { fs.unlinkSync(dbPath); } catch {}
+});

package/scripts/usage-classifier.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const path = require('path');
+
+const DEFAULT_USAGE_CATEGORY = 'unknown';
+const USAGE_RETENTION_DAYS_DEFAULT = 30;
+
+const USAGE_CATEGORY_ORDER = Object.freeze([
+  'memory',
+  'cognition',
+  'skill_evolution',
+  'heartbeat',
+  'team_task',
+  'chat',
+  'chat_project',
+  'manual_task',
+  'unknown',
+]);
+
+const CORE_USAGE_CATEGORIES = Object.freeze([
+  'memory',
+  'cognition',
+  'skill_evolution',
+  'heartbeat',
+  'team_task',
+]);
+
+const USAGE_CATEGORY_LABEL = Object.freeze({
+  memory: '记忆',
+  cognition: '认知',
+  skill_evolution: '技能演化',
+  heartbeat: '心跳任务',
+  team_task: '团队任务',
+  chat: '对话',
+  chat_project: '项目对话',
+  manual_task: '手动任务',
+  unknown: '未分类',
+});
+
+const USAGE_CATEGORY_ALIASES = Object.freeze({
+  memory: 'memory',
+  recall: 'memory',
+  facts: 'memory',
+  cognition: 'cognition',
+  distill: 'cognition',
+  reflection: 'cognition',
+  skill_evolution: 'skill_evolution',
+  skillevolution: 'skill_evolution',
+  'skill-evolution': 'skill_evolution',
+  skill: 'skill_evolution',
+  heartbeat: 'heartbeat',
+  scheduled_task: 'heartbeat',
+  team_task: 'team_task',
+  teamtask: 'team_task',
+  team: 'team_task',
+  chat: 'chat',
+  conversation: 'chat',
+  chat_project: 'chat_project',
+  project_chat: 'chat_project',
+  scoped_chat: 'chat_project',
+  manual_task: 'manual_task',
+  manual: 'manual_task',
+  unknown: 'unknown',
+});
+
+const warnedUnknownCategories = new Set();
+
+function normalizeUsageCategory(rawCategory, opts = {}) {
+  const key = String(rawCategory || '').trim().toLowerCase();
+  if (!key) return DEFAULT_USAGE_CATEGORY;
+  const normalized = USAGE_CATEGORY_ALIASES[key];
+  if (normalized) return normalized;
+
+  if (typeof opts.logger === 'function' && !warnedUnknownCategories.has(key)) {
+    warnedUnknownCategories.add(key);
+    opts.logger(`Unknown usage category "${key}", fallback to "${DEFAULT_USAGE_CATEGORY}"`);
+  }
+  return DEFAULT_USAGE_CATEGORY;
+}
+
+function classifyTaskUsage(task, context = {}, opts = {}) {
+  const fallbackCategory = normalizeUsageCategory(opts.fallbackCategory || 'heartbeat');
+  const kind = String(task && task.task_kind ? task.task_kind : '').toLowerCase();
+  if (kind === 'team') return 'team_task';
+
+  const joined = [
+    task && task.name,
+    task && task.type,
+    task && task.prompt,
+    task && task._project && task._project.key,
+    context && context.skill,
+    context && context.prompt,
+  ].filter(Boolean).join(' ').toLowerCase();
+
+  if (!joined) return fallbackCategory;
+  if (/\bteam[-_\s]?task\b|团队|协作|handoff|dispatch/.test(joined)) return 'team_task';
+  if (/\bskill[-_\s]?(?:evo|evolution|manager|scout)\b|技能演化/.test(joined)) return 'skill_evolution';
+  if (/\bmemory(?:-extract)?\b|记忆|facts?|recall|retriev|rag/.test(joined)) return 'memory';
+  if (/\bdistill\b|\bcognition\b|认知|反思|洞察/.test(joined)) return 'cognition';
+  if (/\bheartbeat\b|提醒|定时|cron|every\s+\d/.test(joined)) return 'heartbeat';
+  return fallbackCategory;
+}
+
+function projectKeyFromCwd(cwd, homeDir = '') {
+  const raw = String(cwd || '').trim();
+  if (!raw) return '';
+  try {
+    const abs = path.resolve(raw);
+    const homeAbs = String(homeDir || '').trim() ? path.resolve(homeDir) : '';
+    if (homeAbs && abs === homeAbs) return '';
+    const base = path.basename(abs);
+    return base && base !== '.' && base !== path.sep ? base : '';
+  } catch {
+    return '';
+  }
+}
+
+function classifyChatUsage(chatId, opts = {}) {
+  const cid = String(chatId || '');
+  if (cid.startsWith('_scope_') || cid.startsWith('_agent_')) return 'team_task';
+
+  const projectScope = String(opts.projectScope || '').trim();
+  const projectKey = String(opts.projectKey || '').trim();
+  const derivedKey = projectKeyFromCwd(opts.cwd, opts.homeDir);
+  if (projectScope || projectKey || derivedKey) return 'chat_project';
+  return 'chat';
+}
+
+module.exports = {
+  DEFAULT_USAGE_CATEGORY,
+  USAGE_RETENTION_DAYS_DEFAULT,
+  USAGE_CATEGORY_ORDER,
+  CORE_USAGE_CATEGORIES,
+  USAGE_CATEGORY_LABEL,
+  normalizeUsageCategory,
+  classifyTaskUsage,
+  classifyChatUsage,
+};
+