madarx 2.19.0 → 2.22.0

package/app/components/dashboard/use-bg-agents.js

@@ -10,6 +10,39 @@ export function useBgAgents({ refresh, runs }) {
   useEffect(() => {
     if (typeof window === 'undefined' || !window.EventSource) return;
     const src = new EventSource('/api/events/stream');
+    let cancelled = false;
+
+    // Seed running agents from the persistent snapshot on mount and on every
+    // (re)connect, so a run in flight before this EventSource connected (or whose
+    // agent_run_start was missed on a reconnect) still shows. Never clobber a
+    // richer live entry already tracking tool steps.
+    async function seedActive() {
+      try {
+        const r = await fetch('/api/agents/active-runs');
+        if (!r.ok) return;
+        const { agents } = await r.json();
+        if (cancelled || !Array.isArray(agents)) return;
+        setBgAgents(prev => {
+          let changed = false;
+          const next = { ...prev };
+          for (const a of agents) {
+            if (!a.agent_id || next[a.agent_id]) continue;
+            next[a.agent_id] = {
+              agent_id: a.agent_id,
+              agent_name: a.agent_name || a.agent_id,
+              triggered_by: a.triggered_by || null,
+              status: 'running',
+              started_at: a.started_at || Date.now(),
+              steps: [],
+            };
+            changed = true;
+          }
+          return changed ? next : prev;
+        });
+      } catch { /* offline / not ready — live events will catch up */ }
+    }
+    seedActive();
+    src.addEventListener('ready', () => { seedActive(); });
 
     function applyToolStart(evt) {
       const id = evt.agent_id;
@@ -137,6 +170,7 @@ export function useBgAgents({ refresh, runs }) {
     src.onerror = () => { /* let browser auto-reconnect */ };
 
     return () => {
+      cancelled = true;
       src.close();
     };
   }, []);

package/app/components/dashboard/use-stream-command.js

@@ -40,6 +40,10 @@ export function useStreamCommand({
   // Drained into pending_approvals on the next outgoing request so the server
   // can inject approval_id into the retried tool call.
   const pendingApprovalsRef = useRef([]);
+  // Inline approval cards for delegated sub-agents (run_agent paused on an owner
+  // gate). Rendered in the chat thread with Approve/Deny so the owner never
+  // leaves the conversation. Approving re-dispatches the sub-agent.
+  const [agentApprovals, setAgentApprovals] = useState([]);
   const abortRef = useRef(null);
   const stoppedRef = useRef(false);
   const feedRef = useRef(null);
@@ -130,7 +134,7 @@ export function useStreamCommand({
         setChat, setLiveText, setAgentPhase, setLiveTool, setLiveSteps,
         setUsage, setSessionId, setSessionArtifactId,
         setLiveThinking, setLiveStatus,
-        pendingApprovalsRef,
+        pendingApprovalsRef, setAgentApprovals,
         bringToFront, refresh,
         onSession: (id) => { saveLastSessionId(id); sessionIdRef.current = id; },
       };
@@ -262,7 +266,7 @@ export function useStreamCommand({
 
     const EVENTS = ['session', 'text', 'cli_stream', 'cli_thinking', 'cli_status',
       'tool_start', 'tool_result', 'artifacts', 'agent_created', 'session_artifact',
-      'artifact_updated', 'usage', 'pending_approvals', 'error', 'done'];
+      'artifact_updated', 'usage', 'pending_approvals', 'agent_approval', 'error', 'done'];
     for (const name of EVENTS) {
       es.addEventListener(name, (ev) => {
         let payload;
@@ -307,6 +311,57 @@ export function useStreamCommand({
     }
   }
 
+  // Decide an inline sub-agent approval card. Approve → re-dispatch the sub-agent
+  // (server consumes the approval + generates), pinning the result to the canvas,
+  // all without leaving the chat. Deny → mark the request denied.
+  async function resumeAgentApprovalImpl(approvalId, decision) {
+    if (!approvalId) return;
+    if (decision === 'denied') {
+      setAgentApprovals(a => a.map(x => x.approval_id === approvalId ? { ...x, status: 'denied' } : x));
+      try {
+        await fetch(`/api/approvals/${approvalId}`, {
+          method: 'PATCH', headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ decision: 'denied' }),
+        });
+      } catch { /* best-effort */ }
+      return;
+    }
+    setAgentApprovals(a => a.map(x => x.approval_id === approvalId ? { ...x, status: 'resuming' } : x));
+    try {
+      const res = await fetch('/api/agents/resume-approval', {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ approval_id: approvalId }),
+      });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok || !data.ok) {
+        setAgentApprovals(a => a.map(x => x.approval_id === approvalId ? { ...x, status: 'error', error: data.error || res.status } : x));
+        setChat(c => [...c, { role: 'agent', text: `Could not continue: ${data.error || res.status}` }]);
+        return;
+      }
+      // A second gate surfaced — mark this one approved and add the next card.
+      if (data.status === 'awaiting_approval' && data.pending_approval?.approval_id) {
+        setAgentApprovals(a => [
+          ...a.map(x => x.approval_id === approvalId ? { ...x, status: 'approved' } : x),
+          {
+            approval_id: data.pending_approval.approval_id,
+            tool_name: data.pending_approval.tool_name,
+            agent_id: data.pending_approval.agent_id || null,
+            agent_name: data.pending_approval.agent_name || data.agent_name || 'Agent',
+            summary: data.pending_approval.summary || '',
+            status: 'pending',
+          },
+        ]);
+        return;
+      }
+      setAgentApprovals(a => a.map(x => x.approval_id === approvalId ? { ...x, status: 'done', artifact_id: data.artifact_id || null } : x));
+      if (data.artifact_id) { setSessionArtifactId(data.artifact_id); bringToFront(data.artifact_id); }
+      await refresh();
+      setChat(c => [...c, { role: 'agent', text: `${data.agent_name || 'Agent'} finished${data.title ? ` — "${data.title}"` : ''}.` }]);
+    } catch (err) {
+      setAgentApprovals(a => a.map(x => x.approval_id === approvalId ? { ...x, status: 'error', error: err.message } : x));
+    }
+  }
+
   function stopImpl() {
     if (!busy) return;
     stoppedRef.current = true;
@@ -317,6 +372,8 @@ export function useStreamCommand({
   stopRef.current = stopImpl;
   const decideApprovalRef = useRef(null);
   decideApprovalRef.current = decideApprovalImpl;
+  const resumeAgentApprovalRef = useRef(null);
+  resumeAgentApprovalRef.current = resumeAgentApprovalImpl;
   const attachRef = useRef(null);
   attachRef.current = attachImpl;
   const command = useCallback((text, attachments) => commandRef.current(text, attachments), []);
@@ -325,6 +382,10 @@ export function useStreamCommand({
     (id, decision, toolName) => decideApprovalRef.current(id, decision, toolName),
     [],
   );
+  const resumeAgentApproval = useCallback(
+    (id, decision) => resumeAgentApprovalRef.current(id, decision),
+    [],
+  );
   const attach = useCallback((id) => attachRef.current(id), []);
 
   // Close any live re-attach when this hook unmounts (page navigation).
@@ -349,5 +410,7 @@ export function useStreamCommand({
     command,
     stop,
     decideApproval,
+    agentApprovals,
+    resumeAgentApproval,
   };
 }

package/app/projects/[slug]/page.js

@@ -6,6 +6,7 @@ import ProjectAlbum from './album-view.jsx';
 import ProjectDropZone from './project-drop-zone.jsx';
 import ProjectHeaderActions from './header-actions.jsx';
 import { ProjectAlbumProvider } from './project-album-context.jsx';
+import ProjectScopeSync from './project-scope-sync.jsx';
 import { isProjectsLiveDeltasEnabled } from '../../../lib/feature-flags.js';
 
 export const dynamic = 'force-dynamic';
@@ -43,6 +44,7 @@ export default async function ProjectPage({ params, searchParams }) {
       currentFolderId={currentFolderId}
       liveDeltasEnabled={isProjectsLiveDeltasEnabled()}
     >
+      <ProjectScopeSync projectId={project.id} />
       <AdminShell
         kicker="Project"
         title={project.name}

package/app/projects/[slug]/project-scope-sync.jsx

@@ -0,0 +1,26 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * Scope the chat to this project. The main dashboard chat reads its active
+ * project from localStorage (`madarx:selected-project`) on mount and sends it
+ * as `project_id` to /api/orchestrator/stream — which scopes the disk_* tools
+ * (disk_list_files / disk_read_file) and artifact destination. Viewing a
+ * project here marks it active so the next chat turn reads THIS project's Disk,
+ * not 'personal' or whatever was last selected.
+ *
+ * Render-null effect component; persistence only. Manual project switches in
+ * the dashboard overwrite this later, which is the intended last-touch-wins.
+ */
+export default function ProjectScopeSync({ projectId }) {
+  useEffect(() => {
+    if (!projectId) return;
+    try {
+      if (localStorage.getItem('madarx:selected-project') !== projectId) {
+        localStorage.setItem('madarx:selected-project', projectId);
+      }
+    } catch { /* storage disabled — chat falls back to last/default scope */ }
+  }, [projectId]);
+  return null;
+}

package/lib/active-runs.js

@@ -31,3 +31,8 @@ export function clearRunActive(agentId) {
 export function isRunActive(agentId) {
   return (counts.get(String(agentId || '')) || 0) > 0;
 }
+
+/** All agent ids with a live in-process manual run (count > 0). */
+export function listActiveRunIds() {
+  return Array.from(counts.keys()).filter((id) => (counts.get(id) || 0) > 0);
+}

package/lib/agent-config.js

@@ -14,12 +14,16 @@ You are madarX — Chief of Staff to the principal. Local-first orchestrator. Yo
 // dashboard config modal, structured builder, or PUT /api/config — can erase
 // them. To intentionally change a contract, edit this constant in source.
 export const CORE_CONTRACTS = `ORCHESTRATOR_MODE (NON-NEGOTIABLE)
-For ANY task longer than a one-line factual reply, your default move is DELEGATE. Decision order on every request:
-  1. Is there an existing agent in workspace/agents/ whose role matches the task type or topic? Call run_agent to dispatch it now.
-  2. Is this a recurring or scheduled task (daily monitoring, weekly reports, ongoing watch)? Call create_agent with a schedule.
-  3. Is this a one-off specialist task (research, scraping, design, code, data, news)? Spawn a one-shot agent OR use the specialist toolset directly when no matching agent exists.
-  4. Is this a one-line factual ask answerable from your own context without any tool? Reply in chat.
-You have access to every tool the principal has enabled. Use them when delegation is not possible — but treat direct execution as the FALLBACK, not the default. You always own: presentation choice, artifact verification, escalation to principal, and approval gating for irreversible actions.
+You DELEGATE specialist work; you do not perform it yourself. Specialist domain tools (flights, hotels, email, GitHub writes, calendar, database, deploys, browser automation, voice) are intentionally absent from your toolset — they live with the specialist agents that own them. Do not try to work around this.
+
+For ANY request longer than a one-line factual reply, set the goal in one sentence, then call route_goal(goal) FIRST. It returns the live registry — every active agent with its role/mission/skills/granted tools, the tool catalog, and whether Tool Smith can build what's missing. Reason over it and pick exactly one ladder step:
+  1. delegate — a live specialist fits the goal: dispatch it with run_agent (pass instruction + expected_output so it knows what "done" means).
+  2. create_then_delegate — no fit specialist exists yet: create_agent for the role the goal needs, then run_agent it. BEFORE creating, CHECK THE ROSTER (route_goal's recommended_specialists, or list_agents) — if an existing agent already owns the tool the goal needs, delegate to it; never spawn a duplicate. When you do create one, grant it the tools the goal needs or it cannot finish.
+  3. build_capability — a specialist exists but lacks a required tool: call request_capability so Tool Smith builds and grants it, tell the principal it's being built, then delegate.
+  4. direct_fallback — ONLY a trivial one-line factual ask, or no capability can be built: answer in chat (or, if you must act and a tool was re-granted for this one turn, do so — audited).
+This works for ANY goal, not a fixed list of domains — route_goal grounds the decision in real capabilities. fast_path_hint is a shortcut for obvious cases, never the whole answer. You always own: presentation choice, artifact verification, escalation to principal, and approval gating for irreversible actions.
+
+TASK TRACKING (automatic): every run_agent delegation is filed as a tracked task on the /tasks board (assignee = the specialist), runs to completion, and its status is updated for you (in_progress → in_review → done, or blocked on failure). A background sweep re-drives any task that stalls. You do not need to create the task yourself — but you DO own making sure the goal is actually met: verify the returned artifact satisfies the expected_output before telling the principal it is done; if a task came back blocked or partial, re-dispatch or escalate. Use list_agents to see your workforce and their open task load before assigning more work.
 
 TOOL_USE_DISCIPLINE
 - Never end a turn with a promise of future action. If you say you will do X, call the tool for X in the same response.
@@ -29,15 +33,18 @@ TOOL_USE_DISCIPLINE
 - If required context is missing, do NOT guess. Fetch it with a tool, OR ask the principal one specific targeted question. Never hallucinate.
 - Act-don't-ask: when there is an obvious default interpretation, act on it. Ask only when the ambiguity changes which tool you would call.
 
-LIVE_DATA_RESEARCH_RULE (non-negotiable — CEO-report standard)
-You are reporting to the chairman. Your job is to bring back the actual answer, not a list of places to look.
-Workflow for any live-data query (flights, hotels, weather, news, prices, web research):
-  1. web_search to identify the 2-4 most authoritative sources (operator or booking sites, official pages, named publications). Ignore generic aggregators when a primary source is available. For flights, call flight_search directly — it always handles provider routing internally (Amadeus when configured, Google Flights free fallback otherwise).
-  2. web_fetch (or flight_search, hotel_search, hotel_rates) each chosen source to pull concrete values: prices, dates, times, addresses, names, distances, capacities, ratings. Never stop at snippets.
-  3. Present the result as a comparison table or structured list with real values in cells — no "see link" placeholders. Include a short "Sources" footnote with 2-4 cited links.
-  4. If a fetch fails or a value is genuinely unavailable, write "Not listed" in that cell — do not substitute search-engine titles for missing data.
-NEVER deliver a response that consists of "Results for X" sections of search titles and snippets. That is a failure mode. If you cannot extract concrete values, say so explicitly and propose the next step (retry, narrower query, or pivot to a different source).
-For JS-heavy sites (Skyscanner, Google Flights, booking platforms, social media), prefer browser_navigate over web_fetch when available.
+LIVE_DATA_RESEARCH_RULE (CEO-report standard — applies to whoever does the work)
+The deliverable is the actual answer with concrete values, never a list of places to look. Domain lookups (flights, hotels, prices, schedules) are SPECIALIST work — route_goal and delegate to the agent that owns the tool (e.g. the Travel Concierge owns flight_search / hotel_search). Do not run those tools yourself; you do not have them.
+You DO keep a quick-fact allowance: web_search and web_fetch remain on your toolset for a fast factual lookup that does not warrant a specialist (a single date, a definition, one current number). When you use them:
+  1. web_search to find the 2-4 most authoritative sources, then web_fetch to pull the concrete value — never stop at snippets.
+  2. Present real values in a table or structured list with a short "Sources" footnote; write "Not listed" for a genuinely missing value.
+When you (or a specialist you delegate to) return results, NEVER deliver "Results for X" sections of search titles and snippets — that is a failure mode. If the goal needs real booking/operator data behind a JS-heavy site, that is the specialist's job via its browser/domain tools, not a web_fetch from you.
+
+GOAL_COMPLETION_RULE (non-negotiable)
+The principal's goal must be met FULLY, not half-way. Before finishing:
+  - When you delegated, you MUST have passed an expected_output / acceptance contract, and you MUST check the specialist's returned artifact actually satisfies it (every part of the ask, real values, right format).
+  - If the result is partial, wrong, or the specialist returned blocked/escalated (missing capability), do NOT present it as the answer. Re-dispatch once with a sharper instruction, follow the build_capability ladder step, or tell the principal exactly what is blocked and what happens next.
+  - Only present a result you have verified meets the goal. A confirmed-partial delivered as if complete is the worst failure.
 
 FORMAT_DECISION_RULE (NON-NEGOTIABLE)
 Before choosing a tool, decide the output medium:

package/lib/agent-engines.js

@@ -670,7 +670,7 @@ function isDir(p) {
   try { return Boolean(p) && fs.statSync(p).isDirectory(); } catch { return false; }
 }
 
-function agentSubprocessCwd() {
+export function agentSubprocessCwd() {
   for (const dir of [WORKSPACE, DATA_DIR, PROJECT_ROOT, process.cwd()]) {
     if (isDir(dir)) return dir;
   }

package/lib/agent-routing.js

@@ -0,0 +1,195 @@
+/**
+ * Grounding provider for delegation-first, LLM-reasoned routing.
+ *
+ * The main agent does NOT route by a keyword table. It reasons over the live
+ * capability registry this module assembles: every active agent (role, title,
+ * mission, skills, granted tools, status), the enabled-tool catalog, and the
+ * fact that Tool Smith can build anything missing. buildRoutingContext() is the
+ * data the agent thinks with; the small keyword/category hints are only a
+ * shortcut for unambiguous cases.
+ *
+ * Works for ANY goal — including domains absent from role-capability-map.js —
+ * because it describes capabilities, not a fixed domain enum, and the fallback
+ * ladder (delegate → create_then_delegate → build_capability → direct_fallback)
+ * always resolves to a path.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { AGENTS_DIR } from './paths.js';
+import { listAgents, listAgentToolPermissions } from './runtime.js';
+import { listMarketplaceTools } from './tools/registry.js';
+import {
+  CATEGORY_TO_ROLE,
+  KEYWORD_CATEGORY_HINTS,
+  isSpecialistTool,
+  neededToolCategoriesForGoal,
+  roleForCategory,
+} from './role-capability-map.js';
+
+const TOOL_SMITH_AGENT_ID = 'tool-smith-agent';
+
+/** Exhaustive fallback ladder — every goal resolves to exactly one of these. */
+export const RECOMMENDATION_LADDER = [
+  { step: 'delegate', when: 'A live specialist exists whose role/tools cover the goal. Dispatch it with run_agent.' },
+  { step: 'create_then_delegate', when: 'No fit specialist exists yet. Spawn one (create_agent from the closest template/mission), then delegate.' },
+  { step: 'build_capability', when: 'A specialist exists but lacks a required tool. Call request_capability so Tool Smith builds + grants it, then delegate.' },
+  { step: 'direct_fallback', when: 'Trivial one-line factual ask, or no capability can be built — answer directly / re-grant the tool for this one turn (audited).' },
+];
+
+function readSkills(agentId) {
+  try {
+    return fs.readFileSync(path.join(AGENTS_DIR, agentId, 'skills.md'), 'utf8').trim().slice(0, 1200);
+  } catch {
+    return '';
+  }
+}
+
+function grantedToolsFor(agentId) {
+  // Authoritative grant = agent_tool_permissions (mode != disabled). Fall back
+  // to the declared `tools` column for legacy agents with no permission rows.
+  try {
+    const perms = listAgentToolPermissions(agentId).filter((p) => p.mode !== 'disabled');
+    if (perms.length) return perms.map((p) => p.tool_name);
+  } catch { /* fall through */ }
+  return [];
+}
+
+function isActiveStatus(status) {
+  return status !== 'terminated' && status !== 'paused';
+}
+
+/**
+ * Obvious-domain shortcut. Returns { category, role } when a goal clearly maps
+ * to a specialist category, else null. A hint only — the LLM still decides.
+ */
+export function fastPathHint(goal) {
+  const text = String(goal || '');
+  if (!text.trim()) return null;
+  for (const [re, category] of KEYWORD_CATEGORY_HINTS) {
+    if (re.test(text)) {
+      return { category, role: roleForCategory(category) || null };
+    }
+  }
+  return null;
+}
+
+/**
+ * Does `agentId` cover `neededTools`? Pure data answer for the missing-tool
+ * branch of the ladder.
+ * @returns {{ covered: boolean, granted: string[], missing_tools: string[] }}
+ */
+export function assessCoverage(agentId, neededTools = []) {
+  const granted = grantedToolsFor(agentId);
+  const grantedSet = new Set(granted);
+  const need = Array.from(new Set((neededTools || []).filter(Boolean)));
+  const missing = need.filter((t) => !grantedSet.has(t));
+  return { covered: missing.length === 0, granted, missing_tools: missing };
+}
+
+/** Catalog tools whose category is in `categories`. Pure. */
+export function toolsForCategories(catalog = [], categories = []) {
+  const cats = new Set(categories);
+  if (!cats.size) return [];
+  return (catalog || []).filter((t) => cats.has(t.category));
+}
+
+/**
+ * Rank existing agents that ALREADY own tools in the needed categories — the
+ * delegate-first answer. An image-gen goal surfaces the agent granted
+ * higgsfield_generate_image, so the main agent reuses it instead of spawning a
+ * tool-less new specialist that completes nothing. Pure (no DB).
+ *
+ * @returns {Array<{id,name,role,owns_tools:string[]}>} sorted by overlap desc
+ */
+export function recommendSpecialists({ agents = [], categories = [], catalog = [] } = {}) {
+  const cats = new Set(categories);
+  if (!cats.size) return [];
+  const toolCat = new Map((catalog || []).map((t) => [t.name, t.category]));
+  const ranked = [];
+  for (const a of agents) {
+    const owns = (a.tools || []).filter((name) => cats.has(toolCat.get(name)));
+    if (owns.length) ranked.push({ id: a.id, name: a.name, role: a.role || null, owns_tools: owns });
+  }
+  ranked.sort((x, y) => y.owns_tools.length - x.owns_tools.length);
+  return ranked;
+}
+
+/**
+ * Assemble the grounded registry the main agent reasons over to route a goal.
+ * Read-only; no side effects.
+ *
+ * @param {{ goal?: string, project_id?: string|null }} input
+ */
+export function buildRoutingContext({ goal = '', project_id = null } = {}) {
+  const allAgents = listAgents();
+  // Scope to the project when given, but always keep global/shared specialists
+  // (no project_id) so cross-project routing still finds them.
+  const scoped = project_id
+    ? allAgents.filter((a) => !a.project_id || a.project_id === project_id)
+    : allAgents;
+
+  const agents = scoped
+    .filter((a) => a.id !== TOOL_SMITH_AGENT_ID && isActiveStatus(a.status))
+    .map((a) => ({
+      id: a.id,
+      name: a.name,
+      role: a.role || a.type || null,
+      title: a.title || null,
+      mission: a.mission || null,
+      status: a.status || null,
+      tools: grantedToolsFor(a.id),
+      skills: readSkills(a.id),
+    }));
+
+  const catalog = listMarketplaceTools().map((t) => ({
+    name: t.name,
+    category: t.category || null,
+    title: t.title || null,
+    enabled: Boolean(t.enabled),
+    available: Boolean(t.available),
+    specialist: isSpecialistTool(t),
+  }));
+
+  const toolSmith = allAgents.find((a) => a.id === TOOL_SMITH_AGENT_ID && isActiveStatus(a.status));
+  const hint = fastPathHint(goal);
+
+  // Capability match: which tool categories this goal needs, which catalog tools
+  // sit in them, and which existing agents already own those tools. This is the
+  // delegate-first answer made explicit so the agent reuses an equipped
+  // specialist instead of spawning a tool-less new one.
+  const neededCategories = neededToolCategoriesForGoal(goal);
+  const recommendedSpecialists = recommendSpecialists({ agents, categories: neededCategories, catalog });
+  const toolsForGoal = toolsForCategories(catalog, neededCategories).map((t) => ({
+    name: t.name,
+    category: t.category,
+    enabled: t.enabled,
+    available: t.available,
+    owners: agents.filter((a) => (a.tools || []).includes(t.name)).map((a) => a.id),
+  }));
+
+  const matchNote = recommendedSpecialists.length
+    ? `CAPABILITY MATCH — recommended_specialists already own the tool(s) this goal needs (see tools_for_goal). PREFER ladder step 1 (delegate) to "${recommendedSpecialists[0].name}" (owns ${recommendedSpecialists[0].owns_tools.join(', ')}); do NOT create a new agent when one already owns the tool. `
+    : toolsForGoal.length
+      ? `CAPABILITY MATCH — no existing agent owns the tool(s) this goal needs (tools_for_goal lists them). create_then_delegate, and when you create_agent you MUST grant it those tools — an agent with no matching tool cannot finish the goal. `
+      : '';
+
+  return {
+    goal: String(goal || ''),
+    agents,
+    agent_count: agents.length,
+    tools_catalog: catalog,
+    tool_smith_available: Boolean(toolSmith),
+    fast_path_hint: hint,
+    needed_categories: neededCategories,
+    recommended_specialists: recommendedSpecialists,
+    tools_for_goal: toolsForGoal,
+    recommendation_ladder: RECOMMENDATION_LADDER,
+    routing_note:
+      matchNote
+      + 'Reason over agents[] (role/mission/skills/tools) vs. what this goal needs. '
+      + 'Pick a ladder step: delegate an existing fit specialist, create_then_delegate when none fits, '
+      + 'build_capability via Tool Smith when a specialist lacks a tool, or direct_fallback for trivial asks. '
+      + 'fast_path_hint is only a shortcut for obvious domains — do not treat it as the answer when the goal is broader.',
+  };
+}