madarx 2.19.0 → 2.21.0

package/lib/agent-config.js

@@ -14,12 +14,14 @@ 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.
+  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.
 
 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 +31,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-routing.js

@@ -0,0 +1,142 @@
+/**
+ * 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,
+  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 };
+}
+
+/**
+ * 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);
+
+  return {
+    goal: String(goal || ''),
+    agents,
+    agent_count: agents.length,
+    tools_catalog: catalog,
+    tool_smith_available: Boolean(toolSmith),
+    fast_path_hint: hint,
+    recommendation_ladder: RECOMMENDATION_LADDER,
+    routing_note:
+      '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.',
+  };
+}

package/lib/agent-runner.js

@@ -4,6 +4,7 @@ import { chatWithClaude } from './claude.js';
 import { defaultModelForEngine, normalizeAgentEngine, runAgentEngine } from './agent-engines.js';
 import { currentDateInstruction } from './agent-config.js';
 import { renderDocumentHtml, stripEmoji } from './artifact-format.js';
+import { buildHiggsfieldGalleryHtml } from './higgsfield-media-card.js';
 import { getDb, nowIso } from './db.js';
 import { AGENTS_DIR, REPORTS_DIR, ensureDirs, relToRoot } from './paths.js';
 import { executeRegistryTool, getEnabledToolSchemasForAgent } from './tools/registry.js';
@@ -14,6 +15,7 @@ import { markRunActive, clearRunActive } from './active-runs.js';
 import {
   addTaskComment,
   appendAgentRunEvent,
+  createTask,
   createTaskRun,
   getAgentRun,
   getTask,
@@ -24,6 +26,29 @@ import {
   upsertAgentRuntimeState,
 } from './delegation.js';
 
+const TOOL_SMITH_AGENT_ID = 'tool-smith-agent';
+
+// A specialist sub-agent that cannot finish because a tool/capability is
+// missing emits this fenced block as its FINAL output instead of guessing or
+// fabricating. runAgentTick parses it, files a Tool Smith build task on the
+// agent's behalf (request_capability is orchestrator-only — sub-agents get no
+// new privilege), and ends the run blocked. Keeps the route→build→delegate
+// loop closed from the specialist side.
+const ESCALATE_RE = /```madarx-escalate\s*([\s\S]*?)```/i;
+
+function parseEscalation(output) {
+  const m = ESCALATE_RE.exec(String(output || ''));
+  if (!m) return null;
+  try {
+    const parsed = JSON.parse(m[1].trim());
+    const capability = String(parsed.capability || parsed.capability_description || '').trim();
+    if (!capability) return null;
+    return { capability, reason: String(parsed.reason || '').trim() };
+  } catch {
+    return null;
+  }
+}
+
 function parseJson(value, fallback) {
   if (!value) return fallback;
   try { return JSON.parse(value); } catch { return fallback; }
@@ -226,14 +251,28 @@ function readSkills(agentId) {
   try { return fs.readFileSync(file, 'utf8').trim(); } catch { return ''; }
 }
 
-async function generateTickOutput({ agent, systemPrompt, userMessage, onToolStart, onToolResult, onToolError, acting_on_behalf_of_user_id, heartbeat_task_id }) {
+async function generateTickOutput({ agent, systemPrompt, userMessage, onToolStart, onToolResult, onToolError, acting_on_behalf_of_user_id, heartbeat_task_id, pending_approvals = [] }) {
   if (process.env.MADARX_MOCK_CLAUDE_TICK) {
-    return { output: process.env.MADARX_MOCK_CLAUDE_TICK, toolEvents: [] };
+    return { output: process.env.MADARX_MOCK_CLAUDE_TICK, toolEvents: [], created_approvals: [] };
   }
   const maxTokens = Math.max(256, Math.min(8192, Number(process.env.MAX_TOKENS_PER_TICK || 1024) || 1024));
   const tools = getEnabledToolSchemasForAgent(agent.id);
   const messages = [{ role: 'user', content: userMessage }];
   const toolEvents = [];
+  // Approvals the owner already granted (inline in chat), to inject into the
+  // matching tool call so the gate consumes them instead of re-prompting. One-shot
+  // per (tool_name) — mirrors the main agent's injectPendingApproval.
+  const grants = (Array.isArray(pending_approvals) ? pending_approvals : [])
+    .filter((p) => p && typeof p.approval_id === 'string' && typeof p.tool_name === 'string')
+    .map((p) => ({ approval_id: p.approval_id, tool_name: p.tool_name, used: false }));
+  function injectGrant(toolName, input) {
+    const g = grants.find((x) => !x.used && x.tool_name === toolName);
+    if (!g) return input;
+    g.used = true;
+    return { ...(input || {}), approval_id: g.approval_id };
+  }
+  // Approvals this tick newly created (tool paused awaiting owner authorization).
+  const created_approvals = [];
   let finalText = '';
 
   for (let turn = 0; turn < 4; turn += 1) {
@@ -257,7 +296,7 @@ async function generateTickOutput({ agent, systemPrompt, userMessage, onToolStar
       });
       await onToolStart?.({ toolUse, inputSummary });
       try {
-        const result = await executeRegistryTool(toolUse.name, toolUse.input || {}, {
+        const result = await executeRegistryTool(toolUse.name, injectGrant(toolUse.name, toolUse.input || {}), {
           agent_id: agent.id,
           // Gate 0: thread service-principal identity for RD-1 membership check.
           acting_on_behalf_of_user_id: acting_on_behalf_of_user_id || null,
@@ -265,6 +304,13 @@ async function generateTickOutput({ agent, systemPrompt, userMessage, onToolStar
         });
         event.status = result?.status || 'complete';
         event.result = result;
+        if (result?.status === 'approval_required' && result?.approval_request_id) {
+          created_approvals.push({
+            approval_request_id: result.approval_request_id,
+            tool_name: toolUse.name,
+            summary: result.reason || `Approval required for ${toolUse.name}`,
+          });
+        }
         toolResults.push({
           type: 'tool_result',
           tool_use_id: toolUse.id,
@@ -304,6 +350,7 @@ async function generateTickOutput({ agent, systemPrompt, userMessage, onToolStar
   return {
     output: finalText,
     toolEvents,
+    created_approvals,
     engine: 'anthropic',
     model: agent.model || defaultModelForEngine('anthropic'),
   };
@@ -345,6 +392,10 @@ export async function runAgentTick(agentOrId, {
   // expected_output for THIS run only — never persisted onto the agent row.
   instruction = null,
   expected_output = null,
+  // Owner-granted approvals to inject into matching tool calls this tick, so an
+  // inline-approved sub-agent tool resumes instead of re-prompting. Shape:
+  // [{ approval_id, tool_name }].
+  pending_approvals = [],
   // Service-principal propagation (Task #7 / Gate 0):
   // Identity of the user on whose behalf this tick is running.
   // Passed from heartbeat-worker.js → executeRegistryTool context so Gate 0
@@ -397,7 +448,13 @@ export async function runAgentTick(agentOrId, {
   const systemPrompt = `${baseSystemPrompt.includes('CURRENT_DATE') ? baseSystemPrompt : `${currentDateInstruction()}\n\n${baseSystemPrompt}`}
 
 ${skills ? `<skills>\n${skills}\n</skills>\n` : ''}
-You are running as a scheduled cron tick. Your FINAL message is saved verbatim as the deliverable the owner sees — make it the complete result in clean markdown, not a status summary, progress recap, or "what I did" note. Reproduce the full content in your final message even if a prior version already exists on disk.`;
+You are running as a scheduled cron tick. Your FINAL message is saved verbatim as the deliverable the owner sees — make it the complete result in clean markdown, not a status summary, progress recap, or "what I did" note. Reproduce the full content in your final message even if a prior version already exists on disk.
+
+ESCALATION_PROTOCOL (non-negotiable): if you CANNOT fully achieve the goal because you are missing a tool or capability (a tool you need is not in your toolset, or returns "not permitted"), do NOT guess, fabricate, or deliver a half-answer. Instead make your FINAL message exactly one fenced block:
+\`\`\`madarx-escalate
+{"capability":"<plain-language capability you need, e.g. create pages in Notion>","reason":"<what you were blocked on>"}
+\`\`\`
+madarX will route this to Tool Smith to build the capability and grant it to you, then re-run you. Use this only for a genuine missing capability — not for a transient error you can retry.`;
 
   // Work-unit contract resolved by precedence (see resolveRunContract):
   //   per-call override  →  delegated task  →  agent standing contract  →  default.
@@ -426,7 +483,7 @@ Tools: ${parseJson(agent.tools, []).join(', ') || 'none listed'}
 ${lastMemory.length ? lastMemory.map((entry, index) => `${index + 1}. ${entry}`).join('\n') : 'No prior memory.'}
 </recent_memory>`;
 
-  const { output, toolEvents, engine, model } = (process.env.MADARX_MOCK_AGENT_TICK || process.env.MADARX_MOCK_CLAUDE_TICK)
+  const { output, toolEvents, engine, model, created_approvals = [] } = (process.env.MADARX_MOCK_AGENT_TICK || process.env.MADARX_MOCK_CLAUDE_TICK)
     ? {
         output: process.env.MADARX_MOCK_AGENT_TICK || process.env.MADARX_MOCK_CLAUDE_TICK,
         toolEvents: [],
@@ -440,6 +497,7 @@ ${lastMemory.length ? lastMemory.map((entry, index) => `${index + 1}. ${entry}`)
           userMessage,
           acting_on_behalf_of_user_id,
           heartbeat_task_id,
+          pending_approvals,
           onToolStart: ({ toolUse, inputSummary }) => {
             if (!taskRun) return;
             appendAgentRunEvent(taskRun.id, {
@@ -503,6 +561,79 @@ ${lastMemory.length ? lastMemory.map((entry, index) => `${index + 1}. ${entry}`)
     e.code = 'fabricated_tool_output';
     throw e;
   }
+
+  // Capability escalation: the specialist signalled it is missing a tool. File a
+  // Tool Smith build task on its behalf and end this run blocked — never persist
+  // a half-answer. request_capability stays orchestrator-only; this is the
+  // sub-agent's sanctioned, no-new-privilege path into the same loop.
+  const escalation = parseEscalation(output);
+  if (escalation) {
+    let toolSmithTaskId = null;
+    try {
+      const task = createTask({
+        title: `Build capability: ${escalation.capability.slice(0, 80)}`,
+        description: [
+          `Specialist "${agent.name}" (${agent.id}) is blocked — it needs a capability that does not exist yet:`,
+          `  "${escalation.capability}"`,
+          escalation.reason ? `\nBlocked on: ${escalation.reason}` : '',
+          '',
+          'Author the right path (composite tool / REST connector / skill / propose_tool) and grant it to the requester.',
+          `Grant the result to agent: ${agent.id}.`,
+        ].join('\n'),
+        acceptance_criteria: 'Capability authored and granted to the requesting specialist so its goal can be completed on re-run.',
+        assignee_agent_id: TOOL_SMITH_AGENT_ID,
+        created_by_agent_id: agent.id,
+        priority: 'high',
+        project_id: agent.project_id || null,
+      });
+      toolSmithTaskId = task.id;
+    } catch (err) {
+      if (process.env.MADARX_DEBUG) console.error('[agent-runner] escalation task creation failed:', err?.message || err);
+    }
+    const blockedMsg = `Blocked: missing capability "${escalation.capability}". Routed to Tool Smith${toolSmithTaskId ? ` (task ${toolSmithTaskId})` : ''} to build and grant it; this agent will re-run once available.`;
+    const { recordRun, appendAudit } = await import('./runtime.js');
+    recordRun({
+      kind: 'agent-tick',
+      title: `${agent.name} escalated a missing capability`,
+      agent: agent.name,
+      agent_id: agent.id,
+      status: 'blocked',
+      preview: blockedMsg,
+      output: blockedMsg,
+      triggered_by,
+    });
+    appendAudit({
+      type: 'agent.capability.escalated',
+      summary: `${agent.name} escalated missing capability: ${escalation.capability}`,
+      status: 'blocked',
+      meta: { agent_id: agent.id, tool_smith_task_id: toolSmithTaskId, capability: escalation.capability, triggered_by },
+    });
+    if (taskRun) {
+      try {
+        addTaskComment(task_id, { body: blockedMsg, author_agent_id: agent.id, created_by_run_id: taskRun.id });
+        updateTask(task_id, { status: 'blocked', blocked_reason: blockedMsg, actor_type: 'agent', actor_id: agent.id });
+        markAgentRunFinished(taskRun.id, { status: 'failed', error: blockedMsg });
+      } catch { /* best-effort */ }
+    }
+    publishLiveEvent({
+      type: 'agent_run_complete',
+      agent_id: agent.id,
+      agent_name: agent.name,
+      status: 'blocked',
+      triggered_by,
+      run_id: taskRun?.id || null,
+      task_id,
+    });
+    return {
+      id: taskRun?.id || null,
+      status: 'blocked',
+      escalated: true,
+      tool_smith_task_id: toolSmithTaskId,
+      capability: escalation.capability,
+      preview: blockedMsg,
+    };
+  }
+
   const reportOutput = toolEvents.length
     ? `${output}\n\n## Tool events\n${toolEvents.map(event => `- ${event.name}: ${event.status}`).join('\n')}`
     : output;
@@ -514,9 +645,32 @@ ${lastMemory.length ? lastMemory.map((entry, index) => `${index + 1}. ${entry}`)
   fs.writeFileSync(file, deliverableMd, 'utf8');
   const filePath = relToRoot(file);
 
-  const artifactTitle = `${agent.name} scheduled report`;
+  // If the run generated visual media (Higgsfield image/video tools), make the
+  // artifact SHOW the media directly on the canvas — an embedded gallery with the
+  // markdown report tucked into a collapsible "Design spec" block — instead of a
+  // document that only links to the image URL.
+  const mediaItems = toolEvents
+    .filter((e) => typeof e.name === 'string' && e.name.startsWith('higgsfield_') && e.result?.ok && e.result?.url)
+    .map((e) => ({
+      url: e.result.url,
+      kind: e.name === 'higgsfield_generate_video' ? 'video' : 'image',
+      thumbnail: e.result.thumbnail || null,
+      prompt: e.input?.prompt || '',
+    }));
+
   const cleanMd = stripEmoji(deliverableMd);
-  const renderedHtml = renderDocumentHtml({ title: artifactTitle, markdown: cleanMd });
+  const artifactTitle = mediaItems.length
+    ? `${agent.name} — ${mediaItems[0].kind === 'video' ? 'video' : 'image'}`
+    : `${agent.name} scheduled report`;
+  // Media runs render an embedded gallery (image shown directly on canvas); the
+  // markdown spec is preserved as source_md for download. Both are kind:'document'
+  // so the canvas renders the HTML content in an iframe.
+  const renderedHtml = mediaItems.length
+    ? buildHiggsfieldGalleryHtml(mediaItems, {
+        title: artifactTitle,
+        caption: mediaItems[0].prompt || '',
+      })
+    : renderDocumentHtml({ title: artifactTitle, markdown: cleanMd });
 
   const { recordRun, recordArtifact, appendAudit } = await import('./runtime.js');
   const run = recordRun({
@@ -609,6 +763,37 @@ ${lastMemory.length ? lastMemory.map((entry, index) => `${index + 1}. ${entry}`)
     });
   }
 
+  // If this tick paused on an owner-approval gate, persist enough context on the
+  // approval row to re-dispatch this exact delegation when the owner approves it
+  // inline in chat — and surface the first pending approval to the caller so the
+  // orchestrator can render an inline Approve/Deny card.
+  if (Array.isArray(created_approvals) && created_approvals.length) {
+    const resume = {
+      agent_id: agent.id,
+      agent_name: agent.name,
+      instruction: instruction || null,
+      expected_output: expected_output || null,
+      triggered_by,
+    };
+    for (const ca of created_approvals) {
+      try {
+        const cur = db.prepare('SELECT payload FROM approval_requests WHERE id = ?').get(ca.approval_request_id);
+        const payload = cur?.payload ? parseJson(cur.payload, {}) : {};
+        payload.resume = resume;
+        db.prepare('UPDATE approval_requests SET payload = ? WHERE id = ?')
+          .run(JSON.stringify(payload), ca.approval_request_id);
+      } catch { /* best-effort — resume falls back to main-agent re-delegation */ }
+    }
+    const first = created_approvals[0];
+    run.pending_approval = {
+      approval_id: first.approval_request_id,
+      tool_name: first.tool_name,
+      summary: first.summary,
+      agent_id: agent.id,
+      agent_name: agent.name,
+    };
+  }
+
   return run;
   } catch (err) {
     const message = (err?.message || String(err)).slice(0, 1000);

package/lib/agent-templates.js

@@ -8,6 +8,7 @@ import { PROCESS_AGENT_TEMPLATES } from './process/seeds/agent-templates.js';
 export const AGENT_TEMPLATES = [
   ['project-watcher','Project Watcher','project_watcher','claude-code',['gh_repo_read','gh_issue_list','gh_pr_list','web_fetch','file_read'],['investigate','retro'],'Watches repos, issues, PRs, deploys, and produces weekly project pulses.'],
   ['personal-assistant','Personal Assistant','personal_assistant','anthropic',['gmail_messages_list','gmail_message_read','calendar_events_list','whatsapp_send'],[], 'Reads inbox and calendar context, drafts replies, and keeps the operator organized.'],
+  ['travel-concierge','Travel Concierge','travel_concierge','anthropic',['flight_search','flight_status','hotel_search','hotel_rates','web_search','web_fetch','create_artifact'],[], 'Plans trips end to end — flights, hotels, and itineraries — and returns a booking-ready comparison with real prices, times, and sources. Bookings and purchases stay approval-gated.'],
   ['engineering-lead','Engineering Lead','engineering_lead','claude-code',['gh_repo_read','gh_issue_list','gh_pr_list','terminal_run','file_read','file_write'],['investigate','review','ship','qa'],'Leads implementation, review, QA, and preview deploys with explicit approval gates.'],
   ['marketing-lead','Marketing Lead','marketing_lead','anthropic',['web_search','web_fetch','file_write','create_artifact'],['design-shotgun','impeccable'],'Creates market research, launch copy, positioning, and design briefs.'],
   ['meeting-notes','Meeting Notes Taker','meeting_notes','anthropic',['transcribe_audio','file_write','create_artifact'],[], 'Turns recordings into transcripts, decisions, action items, and follow-ups.'],

package/lib/connection-seeds.js

@@ -523,6 +523,50 @@ const CONNECTION_SEEDS = [
     risk: 'CRM writes (contact/deal upsert) require approval.',
     tags: ['sales', 'crm', 'hubspot', 'oauth'],
   }),
+  {
+    slug: 'higgsfield',
+    title: 'Higgsfield AI',
+    description: 'Generate images and videos via Higgsfield AI. Pair once with your API key/secret to unlock the generation tools.',
+    category: 'integration',
+    author: 'madarx',
+    source_kind: 'builtin',
+    source_url: 'https://cloud.higgsfield.ai/',
+    version: null,
+    risk_summary: 'Generation spends paid Higgsfield credits; both tools stay approval-gated by default.',
+    tags: ['integration', 'media', 'image-generation', 'video-generation', 'higgsfield'],
+    manifest: {
+      service_key: 'higgsfield',
+      setup_kind: 'api_key',
+      benefit: 'Unlock higgsfield_generate_image and higgsfield_generate_video.',
+      credentials: [
+        {
+          name: 'HIGGSFIELD_KEY_ID',
+          label: 'API key ID',
+          type: 'password',
+          placeholder: 'key id',
+          help_url: 'https://cloud.higgsfield.ai/',
+          help_text: 'From your Higgsfield dashboard → API section. Create a key, then copy its ID.',
+          required: true,
+        },
+        {
+          name: 'HIGGSFIELD_KEY_SECRET',
+          label: 'API key secret',
+          type: 'password',
+          placeholder: 'key secret',
+          help_url: 'https://cloud.higgsfield.ai/',
+          help_text: 'The matching secret for the key ID. Stored encrypted in the local vault — never echoed back.',
+          required: true,
+        },
+      ],
+      verify_endpoint: '/api/connections/higgsfield/verify',
+      verify_supported: true,
+      deep_link: null,
+      supports_scopes: ['global', 'project', 'agent'],
+      unlocks_tool_slugs: ['higgsfield_generate_image', 'higgsfield_product_photoshoot', 'higgsfield_generate_video'],
+      engines: [],
+      logo_glyph: 'higgsfield',
+    },
+  },
 ];
 
 function upsertConnection(db, seed) {