@yeaft/webchat-agent 0.1.466 → 0.1.468

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.466",
+  "version": "0.1.468",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/personas.js

@@ -0,0 +1,134 @@
+/**
+ * personas.js — Preset persona loader for sub-agents.
+ *
+ * A persona defines a sub-agent's role: which tools it can use, which
+ * model tier it runs on, and what system prompt it carries.
+ *
+ * Presets live as markdown files with YAML frontmatter in
+ * `agent/unify/templates/personas/*.md`.
+ */
+
+import { readFileSync, readdirSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PERSONAS_DIR = join(__dirname, 'templates', 'personas');
+
+/**
+ * @typedef {Object} Persona
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ * @property {'fast'|'primary'} modelTier
+ * @property {string[]} tools
+ * @property {string} systemPrompt
+ */
+
+/** @type {Map<string, Persona>|null} */
+let cached = null;
+
+/**
+ * Parse YAML frontmatter + body from a markdown file.
+ * Minimal parser for the fields we use (no external dep).
+ *
+ * @param {string} source
+ * @returns {{ meta: object, body: string }}
+ */
+export function parseFrontmatter(source) {
+  const match = source.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { meta: {}, body: source };
+
+  const [, yaml, body] = match;
+  const meta = {};
+  const lines = yaml.split('\n');
+  let currentKey = null;
+  let currentList = null;
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const listMatch = line.match(/^\s+-\s+(.+?)\s*$/);
+    if (listMatch && currentList) {
+      currentList.push(listMatch[1]);
+      continue;
+    }
+    const kvMatch = line.match(/^([\w-]+):\s*(.*)$/);
+    if (kvMatch) {
+      const [, key, value] = kvMatch;
+      if (!value.trim()) {
+        currentList = [];
+        meta[key] = currentList;
+        currentKey = key;
+      } else {
+        meta[key] = value.trim();
+        currentKey = key;
+        currentList = null;
+      }
+    }
+  }
+
+  return { meta, body: body.trim() };
+}
+
+/**
+ * Load all built-in personas from templates/personas/*.md.
+ *
+ * @param {{ dir?: string, fresh?: boolean }} [options]
+ * @returns {Map<string, Persona>}
+ */
+export function loadPersonas(options = {}) {
+  const { dir = PERSONAS_DIR, fresh = false } = options;
+  if (!fresh && cached) return cached;
+
+  const map = new Map();
+  let files;
+  try {
+    files = readdirSync(dir).filter(f => f.endsWith('.md'));
+  } catch {
+    if (!fresh) cached = map;
+    return map;
+  }
+
+  for (const file of files) {
+    try {
+      const source = readFileSync(join(dir, file), 'utf-8');
+      const { meta, body } = parseFrontmatter(source);
+      if (!meta.id) continue;
+      const persona = {
+        id: String(meta.id),
+        name: String(meta.name || meta.id),
+        description: String(meta.description || ''),
+        modelTier: meta.modelTier === 'primary' ? 'primary' : 'fast',
+        tools: Array.isArray(meta.tools) ? meta.tools.map(String) : [],
+        systemPrompt: body,
+      };
+      map.set(persona.id, persona);
+    } catch {
+      // skip bad files
+    }
+  }
+
+  if (!fresh) cached = map;
+  return map;
+}
+
+/**
+ * Get a persona by id. Returns undefined if not found.
+ * @param {string} id
+ * @returns {Persona|undefined}
+ */
+export function getPersona(id) {
+  if (!id) return undefined;
+  return loadPersonas().get(id);
+}
+
+/** @returns {string[]} */
+export function listPersonaIds() {
+  return Array.from(loadPersonas().keys());
+}
+
+/** Clear cache (for tests). */
+export function _resetPersonaCache() {
+  cached = null;
+}

package/unify/tools/agent.js

@@ -3,10 +3,26 @@
  *
  * Sub-agents run in isolated contexts and can be assigned
  * independent tasks. They communicate via send-message/wait-agent.
+ *
+ * SubagentSpec contract (v1):
+ *   {
+ *     name: string,
+ *     task: string,                   // legacy summary; becomes mission when not given
+ *     mission?: string,               // concrete objective statement
+ *     expected_output?: object,       // JSON schema describing the required output
+ *     persona?: string,               // preset id: explorer|implementer|reviewer|researcher
+ *     budget?: {
+ *       max_tokens?: number,
+ *       max_turns?: number,
+ *       wall_time_ms?: number
+ *     },
+ *     cwd?: string
+ *   }
  */
 
 import { defineTool } from './types.js';
 import { randomUUID } from 'crypto';
+import { getPersona, listPersonaIds } from '../personas.js';
 
 /** In-memory sub-agent registry. */
 const agents = new Map();
@@ -16,19 +32,163 @@ export function getAgentRegistry() {
   return agents;
 }
 
+/** Reset registry (for tests). */
+export function _resetAgentRegistry() {
+  agents.clear();
+}
+
+/**
+ * Validate a SubagentSpec. Returns { ok: true, spec } or { ok: false, error }.
+ *
+ * @param {object} input
+ */
+export function validateSpec(input) {
+  if (!input || typeof input !== 'object') {
+    return { ok: false, error: 'spec must be an object' };
+  }
+  const { name, task, mission, expected_output, persona, budget } = input;
+  if (!name || typeof name !== 'string') {
+    return { ok: false, error: 'name is required' };
+  }
+  if (!task && !mission) {
+    return { ok: false, error: 'task or mission is required' };
+  }
+  if (persona && !getPersona(persona)) {
+    return {
+      ok: false,
+      error: `unknown persona "${persona}"; available: ${listPersonaIds().join(', ')}`,
+    };
+  }
+  if (expected_output !== undefined && (typeof expected_output !== 'object' || expected_output === null)) {
+    return { ok: false, error: 'expected_output must be a JSON schema object' };
+  }
+  if (budget !== undefined) {
+    if (typeof budget !== 'object' || budget === null) {
+      return { ok: false, error: 'budget must be an object' };
+    }
+    for (const k of ['max_tokens', 'max_turns', 'wall_time_ms']) {
+      if (budget[k] !== undefined && (typeof budget[k] !== 'number' || budget[k] <= 0)) {
+        return { ok: false, error: `budget.${k} must be a positive number` };
+      }
+    }
+  }
+  return {
+    ok: true,
+    spec: {
+      name,
+      mission: mission || task,
+      task: task || mission,
+      expected_output: expected_output || null,
+      persona: persona || null,
+      budget: budget || null,
+    },
+  };
+}
+
+/**
+ * Check a sub-agent's budget against current usage.
+ * Returns { exceeded: true, reason } when any bound is breached, else { exceeded: false }.
+ *
+ * @param {{ budget: object|null, usage: { tokens: number, turns: number, startedAt: number } }} agent
+ * @param {number} [now=Date.now()]
+ */
+export function checkBudget(agent, now = Date.now()) {
+  const b = agent.budget;
+  if (!b) return { exceeded: false };
+  const u = agent.usage || { tokens: 0, turns: 0, startedAt: now };
+  if (b.max_tokens !== undefined && u.tokens >= b.max_tokens) {
+    return { exceeded: true, reason: `max_tokens (${b.max_tokens}) reached`, limit: 'max_tokens' };
+  }
+  if (b.max_turns !== undefined && u.turns >= b.max_turns) {
+    return { exceeded: true, reason: `max_turns (${b.max_turns}) reached`, limit: 'max_turns' };
+  }
+  if (b.wall_time_ms !== undefined && (now - u.startedAt) >= b.wall_time_ms) {
+    return { exceeded: true, reason: `wall_time_ms (${b.wall_time_ms}) exceeded`, limit: 'wall_time_ms' };
+  }
+  return { exceeded: false };
+}
+
+/**
+ * Build a budget-exceeded result envelope.
+ * @param {object} agent
+ * @param {string} reason
+ */
+export function budgetExceededResult(agent, reason) {
+  return {
+    status: 'budget_exceeded',
+    partial_output: agent.partial_output || agent.result || '',
+    reason,
+    usage: { ...(agent.usage || {}) },
+  };
+}
+
+/**
+ * Apply an incremental delta to an agent's usage, then check budget.
+ * If exceeded: abort the agent's signal, set result to the budget envelope,
+ * flip status to 'completed', and return the envelope. Otherwise returns null.
+ *
+ * Call this at each turn boundary inside the sub-agent's execution loop.
+ *
+ * @param {string} agentId
+ * @param {{ tokens?: number, turns?: number, partial_output?: string }} [delta]
+ * @param {number} [now=Date.now()]
+ * @returns {object|null} — budget envelope if exceeded, else null
+ */
+export function tickAgent(agentId, delta = {}, now = Date.now()) {
+  const agent = agents.get(agentId);
+  if (!agent) return null;
+  if (agent.status === 'completed' || agent.status === 'closed') return null;
+
+  if (typeof delta.tokens === 'number' && delta.tokens > 0) {
+    agent.usage.tokens += delta.tokens;
+  }
+  if (typeof delta.turns === 'number' && delta.turns > 0) {
+    agent.usage.turns += delta.turns;
+  }
+  if (typeof delta.partial_output === 'string' && delta.partial_output) {
+    agent.partial_output = delta.partial_output;
+  }
+
+  const check = checkBudget(agent, now);
+  if (!check.exceeded) return null;
+
+  const envelope = budgetExceededResult(agent, check.reason);
+  agent.result = envelope;
+  agent.status = 'completed';
+  agent.diagnostics.push({
+    type: 'budget_exceeded',
+    limit: check.limit,
+    reason: check.reason,
+    at: now,
+  });
+  // Signal any in-flight sub-agent work to stop
+  if (agent.abortController && !agent.abortController.signal.aborted) {
+    try {
+      agent.abortController.abort(check.reason);
+    } catch {
+      // ignore double-abort
+    }
+  }
+  return envelope;
+}
+
 export default defineTool({
   name: 'Agent',
   description: `Create a sub-agent to work on an independent task in parallel.
 
-Sub-agents run in their own context and can be given specific tasks.
-Use for parallel execution of independent subtasks.
+Sub-agents run in their own context and can be given a concrete mission
+with an expected_output schema and a budget (max_tokens/max_turns/wall_time_ms).
+Pick a preset persona to pre-wire a tool subset and model tier:
+  - explorer   : fast, read-only scout (Read/Grep/Glob/ListDir)
+  - implementer: builder with full work tools (primary model)
+  - reviewer   : read-only critic (primary model)
+  - researcher : web-facing info gatherer (WebSearch/WebFetch/Read)
 
 Guidelines:
-- Give each agent a clear, focused task description
-- Use unique, descriptive names
-- Sub-agents share the same tools but have independent conversations
-- Use SendMessage to communicate with agents, WaitAgent to collect results
-- Close agents with CloseAgent when done`,
+- Give a clear, focused mission — what "done" looks like
+- Use expected_output to pin the structure you want back
+- Always set a budget for unbounded missions
+- Use SendMessage to communicate, WaitAgent to collect results, CloseAgent to finalize`,
   parameters: {
     type: 'object',
     properties: {
@@ -38,22 +198,45 @@ Guidelines:
       },
       task: {
         type: 'string',
-        description: 'The task description for the sub-agent',
+        description: 'Legacy one-line task description (used if `mission` is omitted)',
+      },
+      mission: {
+        type: 'string',
+        description: 'Concrete mission statement — what this agent must accomplish',
+      },
+      expected_output: {
+        type: 'object',
+        description: 'JSON schema describing the structure the agent should return',
+      },
+      persona: {
+        type: 'string',
+        enum: ['explorer', 'implementer', 'reviewer', 'researcher'],
+        description: 'Preset persona that pre-wires tool subset + model tier',
+      },
+      budget: {
+        type: 'object',
+        properties: {
+          max_tokens: { type: 'number' },
+          max_turns: { type: 'number' },
+          wall_time_ms: { type: 'number' },
+        },
+        description: 'Budget limits; exceeding any returns { status: "budget_exceeded", partial_output, reason }',
       },
       cwd: {
         type: 'string',
         description: 'Working directory for the sub-agent (optional, defaults to parent cwd)',
       },
     },
-    required: ['name', 'task'],
+    required: ['name'],
   },
   modes: ['work'],
   isConcurrencySafe: () => false,
   isReadOnly: () => false,
   async execute(input, ctx) {
-    const { name, task, cwd } = input;
-    if (!name) return JSON.stringify({ error: 'name is required' });
-    if (!task) return JSON.stringify({ error: 'task is required' });
+    const validation = validateSpec(input);
+    if (!validation.ok) return JSON.stringify({ error: validation.error });
+    const spec = validation.spec;
+    const { name, cwd } = input;
 
     // Check for name collision
     for (const [, agent] of agents) {
@@ -65,16 +248,28 @@ Guidelines:
       }
     }
 
+    const persona = spec.persona ? getPersona(spec.persona) : null;
+    const now = Date.now();
     const agentId = `agent-${randomUUID().slice(0, 8)}`;
     const agent = {
       id: agentId,
       name,
-      task,
+      task: spec.task,
+      mission: spec.mission,
+      expected_output: spec.expected_output,
+      persona: spec.persona,
+      personaData: persona || null,
+      budget: spec.budget,
       cwd: cwd || ctx?.cwd || process.cwd(),
       status: 'created',
       messages: [],
       result: null,
-      createdAt: Date.now(),
+      partial_output: '',
+      diagnostics: [],
+      usage: { tokens: 0, turns: 0, startedAt: now },
+      createdAt: now,
+      trace: [],
+      abortController: new AbortController(),
     };
 
     agents.set(agentId, agent);
@@ -83,6 +278,8 @@ Guidelines:
       success: true,
       agentId,
       name,
+      persona: spec.persona || null,
+      budget: spec.budget || null,
       message: `Sub-agent "${name}" created (${agentId}). Use SendMessage to give it work.`,
     });
   },