madarx 2.19.0 → 2.22.0

package/lib/orchestrator-tools.js

@@ -19,6 +19,7 @@ import {
   deleteArtifact,
   moveArtifact,
   listAgents,
+  listAgentToolPermissions,
   setAgentWhatsAppNotify,
   findArtifacts,
   getArtifact,
@@ -40,10 +41,13 @@ import {
 import { resolveSafePath } from './tools/safety.js';
 import { executeRegistryTool, getEnabledToolSchemas, listMarketplaceTools, setToolEnabled } from './tools/registry.js';
 import { listMarketplaceItems } from './marketplace.js';
-import { createTask, listTasks } from './delegation.js';
+import { buildRoutingContext } from './agent-routing.js';
+import { isSpecialistTool } from './role-capability-map.js';
+import { createTask, listTasks, getTask, updateTask } from './delegation.js';
 import { runSingleReport } from './mines/diligence.js';
 import { getBridgeHealth, sendWhatsAppDocument, sendWhatsAppMessage } from './whatsapp.js';
 import { listProjects } from './projects.js';
+import { diskListFolders, diskListFiles, diskReadFile } from './tools/adapters/disk.js';
 import {
   createSpace,
   deleteSpace,
@@ -660,6 +664,72 @@ export const CORE_TOOLS = [
       properties: {},
     },
   },
+  {
+    name: 'list_agents',
+    description:
+      'List the existing sub-agents (your workforce) and WHAT EACH CAN DO — id, name, role, status, the tools each is granted, and how many open tasks it already has. Call this BEFORE creating a new agent: if an existing agent already owns the tool the goal needs, delegate to it with run_agent instead of spawning a duplicate. This is the cheap roster read; route_goal is the fuller capability match for a specific goal.',
+    input_schema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'list_projects',
+    description:
+      'List the owner\'s projects (the workspaces shown at /projects/<slug>). Returns each project\'s id, slug, name, and status. Use this to resolve which project the owner means before reading its Disk with disk_list_files / disk_list_folders.',
+    input_schema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'disk_list_folders',
+    description:
+      'List the FOLDERS inside a project\'s Disk — the owner\'s "project folder" / "my files" shown at /projects/<slug>. This is the owner\'s content, NOT the madarX source code. Use this (never file_read/directory_list/Bash on the source tree) when the owner asks to check their project, folder, or files.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        project_id: {
+          type: 'string',
+          description: 'Project id or slug (e.g. "ai-agents"). Omit to use the active project. If unsure, call list_projects first.',
+        },
+      },
+    },
+  },
+  {
+    name: 'disk_list_files',
+    description:
+      'List the FILES in a project\'s Disk (the owner\'s "project folder" at /projects/<slug>). Returns file id, name, kind, size, and local_only flag. This is the owner\'s uploaded/produced content — NOT madarX source code. Read a file\'s contents with disk_read_file using the returned id.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        project_id: {
+          type: 'string',
+          description: 'Project id or slug (e.g. "ai-agents"). Omit to use the active project. If unsure, call list_projects first.',
+        },
+        folder_id: {
+          type: 'string',
+          description: 'Optional folder id (from disk_list_folders) to list only that folder. Omit to list all files in the project.',
+        },
+      },
+    },
+  },
+  {
+    name: 'disk_read_file',
+    description:
+      'Read the contents of a single Disk file by id (get ids from disk_list_files). Returns the file body. local_only files are redacted for cloud engines by design.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        file_id: { type: 'string', description: 'The Disk file id, from disk_list_files.' },
+        project_id: {
+          type: 'string',
+          description: 'Optional project id or slug to scope the read to (cross-project reads are refused). Omit to use the active project.',
+        },
+      },
+      required: ['file_id'],
+    },
+  },
   {
     name: 'create_artifact',
     description:
@@ -1066,6 +1136,21 @@ export const CORE_TOOLS = [
       required: ['tool_name'],
     },
   },
+  {
+    name: 'route_goal',
+    description:
+      'CALL THIS FIRST for any non-trivial request, BEFORE attempting a specialist task yourself. It grounds your delegation decision: given the user goal, it returns the live capability registry — every active agent with its role, mission, skills, and granted tools; the enabled-tool catalog; whether Tool Smith is available to build missing capabilities — plus the fallback ladder. Reason over it and pick the path: delegate to a fit specialist (run_agent), create_then_delegate when none fits (create_agent), build_capability when a specialist exists but lacks a required tool (request_capability), or direct_fallback for a trivial one-line factual answer. Read-only, no side effects.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        goal: {
+          type: 'string',
+          description: 'The user goal in one sentence, e.g. "find a return flight DXB to London for May 18-25" or "draft a reply to this email".',
+        },
+      },
+      required: ['goal'],
+    },
+  },
   {
     name: 'request_capability',
     description:
@@ -1093,10 +1178,28 @@ export const CORE_TOOLS = [
 
 const HERMES_TOOL_NAMES = new Set(['send_to_hermes', 'start_hermes_job']);
 
+/**
+ * Names of enabled marketplace tools in a SPECIALIST-owned category. These are
+ * stripped from the MAIN agent's directly-callable catalog so specialist work
+ * must be delegated to an agent that owns the tool (the load-bearing
+ * delegation-first gate). Sub-agents still receive their granted specialist
+ * tools via getEnabledToolSchemasForAgent — the narrowing applies to the
+ * orchestrator catalog only. Kill-switch: MADARX_DELEGATION_ENFORCEMENT=off.
+ */
+function mainAgentDirectDenylist() {
+  if (process.env.MADARX_DELEGATION_ENFORCEMENT === 'off') return new Set();
+  try {
+    return new Set(listMarketplaceTools().filter(isSpecialistTool).map(t => t.name));
+  } catch {
+    return new Set();
+  }
+}
+
 export function getTools() {
   const hermesOk = isHermesAvailable();
   const coreTools = hermesOk ? CORE_TOOLS : CORE_TOOLS.filter(t => !HERMES_TOOL_NAMES.has(t.name));
-  return getEnabledToolSchemas(coreTools);
+  const denylist = mainAgentDirectDenylist();
+  return getEnabledToolSchemas(coreTools).filter(t => !denylist.has(t.name));
 }
 
 export const TOOLS = CORE_TOOLS;
@@ -1280,6 +1383,19 @@ export function clampToolResult(value) {
  * @returns {unknown}
  */
 export async function executeTool(toolName, input = {}, context = {}) {
+  // Load-bearing delegation-first gate (main-agent path, both Anthropic + CLI
+  // engines): specialist domain tools are not the orchestrator's to call. Block
+  // here so even a CLI engine emitting a raw madarx-action cannot bypass the
+  // catalog narrowing that hides them from the Anthropic schema. Sub-agents go
+  // through executeRegistryTool and are unaffected. Kill-switch via
+  // MADARX_DELEGATION_ENFORCEMENT=off (honored inside mainAgentDirectDenylist).
+  if (mainAgentDirectDenylist().has(toolName)) {
+    return clampToolResult({
+      ok: false,
+      error: 'delegate_required',
+      message: `"${toolName}" is a specialist tool you do not own directly. Call route_goal(goal), then delegate to the agent that owns it with run_agent — or request_capability if no agent has it.`,
+    });
+  }
   const result = await dispatchTool(toolName, input, context);
   return clampToolResult(result);
 }
@@ -1310,9 +1426,51 @@ async function dispatchTool(toolName, input = {}, context = {}) {
       return summarizeStateForTool(full);
     }
 
+    case 'list_agents': {
+      // Roster + capabilities + current load, so the main agent reuses an
+      // equipped agent instead of creating a duplicate. Excludes the Tool Smith
+      // (it builds capabilities, it isn't a delegation target).
+      const roster = listAgents()
+        .filter((a) => a.id !== 'tool-smith-agent' && a.status !== 'terminated')
+        .map((a) => {
+          let tools = [];
+          try {
+            tools = listAgentToolPermissions(a.id)
+              .filter((p) => p.mode !== 'disabled')
+              .map((p) => p.tool_name);
+          } catch { /* legacy agent with no permission rows */ }
+          let openTasks = 0;
+          try {
+            openTasks = listTasks({ assignee_agent_id: a.id }).filter(
+              (t) => t.status !== 'done' && t.status !== 'cancelled',
+            ).length;
+          } catch { /* tasks table not ready */ }
+          return {
+            id: a.id,
+            name: a.name,
+            role: a.role || a.type || null,
+            status: a.status || null,
+            engine: a.engine || null,
+            mission: a.mission || null,
+            tools,
+            open_tasks: openTasks,
+          };
+        });
+      return { ok: true, agents: roster, agent_count: roster.length };
+    }
+
     case 'list_projects':
       return { ok: true, projects: listProjects({ status: 'all' }) };
 
+    case 'disk_list_folders':
+      return diskListFolders(input, context);
+
+    case 'disk_list_files':
+      return diskListFiles(input, context);
+
+    case 'disk_read_file':
+      return diskReadFile(input, context);
+
     case 'create_artifact': {
       const allowedKinds = new Set(['markdown', 'text']);
       const kind = allowedKinds.has(input.kind) ? input.kind : 'markdown';
@@ -1375,7 +1533,7 @@ async function dispatchTool(toolName, input = {}, context = {}) {
       return sendWhatsAppMessage(input.chat_id, input.text);
 
     case 'run_agent':
-      return runAgentOnDemand(input);
+      return runAgentOnDemand(input, context);
 
     case 'mines_run_report':
       // One-action mines report trigger from chat. The actual report tool call
@@ -1411,6 +1569,9 @@ async function dispatchTool(toolName, input = {}, context = {}) {
     case 'uninstall_tool':
       return uninstallToolHandler(input);
 
+    case 'route_goal':
+      return buildRoutingContext({ goal: input.goal, project_id: context.project_id || null });
+
     case 'request_capability':
       return requestCapabilityHandler(input, context);
 
@@ -1572,13 +1733,16 @@ function resolveAgentId({ agent_id, agent_name }) {
   return { ok: false, error: 'Pass either agent_id or agent_name.' };
 }
 
-async function runAgentOnDemand(input) {
+async function runAgentOnDemand(input, context = {}) {
   const resolved = resolveAgentId(input);
   if (!resolved.ok) return { ok: false, error: resolved.error };
   const agent = resolved.agent;
   const wake_reason = input.wake_reason || 'on-demand from main agent';
   const instruction = typeof input.instruction === 'string' && input.instruction.trim() ? input.instruction.trim() : null;
   const expected_output = typeof input.expected_output === 'string' && input.expected_output.trim() ? input.expected_output.trim() : null;
+  // Owner-granted inline approvals to inject into this sub-agent's matching tool
+  // calls (so an approved gate resumes instead of re-prompting).
+  const pending_approvals = Array.isArray(context.pending_approvals) ? context.pending_approvals : [];
   try {
     // Per-call overrides are auditable but NOT persisted onto the agent row —
     // they shape this single run's prompt only (see runAgentTick precedence).
@@ -1590,20 +1754,60 @@ async function runAgentOnDemand(input) {
         meta: { agent_id: agent.id, wake_reason, has_instruction: Boolean(instruction), has_expected_output: Boolean(expected_output) },
       });
     }
-    const run = await runAgentTick(agent.id, { triggered_by: 'main_agent', wake_reason, instruction, expected_output });
+    // Task-backed delegation: every chat-initiated delegation is a tracked task
+    // on the /tasks board, so the owner can follow it and the sweep cron can
+    // ensure it completes. We create the task with suppress_wake and run it
+    // SYNCHRONOUSLY here (passing task_id) — runAgentTick persists the agent_run
+    // (running→terminal), moves the task in_progress→in_review, and emits the
+    // live events the activity panels seed from. Best-effort: a tasks-table hiccup
+    // must never block the delegation itself.
+    let task = null;
+    try {
+      const title = (instruction || wake_reason || `Run ${agent.name}`).slice(0, 140);
+      task = createTask({
+        title,
+        description: instruction || null,
+        assignee_agent_id: agent.id,
+        status: 'todo',
+        priority: 'medium',
+        created_by_user_id: context.user_id || null,
+        project_id: context.project_id || null,
+        acceptance_criteria: expected_output || null,
+        suppress_wake: true,
+      });
+    } catch { task = null; }
+
+    const run = await runAgentTick(agent.id, { triggered_by: 'main_agent', task_id: task?.id || null, wake_reason, instruction, expected_output, pending_approvals });
     if (!run) return { ok: false, error: `runAgentTick returned null for ${agent.id}` };
+
+    // Auto-complete the happy path: runAgentTick advances a successful run's task
+    // to in_review. With the deliverable on canvas and no approval pending, mark
+    // it done. Blocked/failed tasks stay open for the sweep + main-agent verify.
+    if (task && !run.pending_approval) {
+      try {
+        const cur = getTask(task.id);
+        if (cur && cur.status === 'in_review') {
+          updateTask(task.id, { status: 'done', actor_type: 'agent', actor_id: agent.id });
+        }
+      } catch { /* leave for the task sweep / main-agent verification */ }
+    }
+
     return {
       ok: true,
       agent_id: agent.id,
       agent_name: agent.name,
       run_id: run.id,
-      status: run.status || 'complete',
+      task_id: task?.id || null,
+      status: run.pending_approval ? 'awaiting_approval' : (run.status || 'complete'),
       title: run.artifact_title || run.title,
       preview: (run.preview || '').slice(0, 600),
       // Addressable artifact row (for pinning to the canvas). `artifact` stays
       // the file-path string for backward compatibility.
       artifact_id: run.artifact_id || null,
       artifact: run.artifact || null,
+      // Inline-approval surface: when the sub-agent paused on an owner-approval
+      // gate, this carries the approval the chat should render as Approve/Deny.
+      pending_approval: run.pending_approval || null,
     };
   } catch (err) {
     return { ok: false, error: err.message, agent_id: agent.id };

package/lib/role-capability-map.js

@@ -0,0 +1,111 @@
+/**
+ * Role ↔ capability hints for delegation-first routing.
+ *
+ * IMPORTANT: this file is a FAST-PATH HINT + SEED LIST, not the routing
+ * authority. The authoritative routing decision is the main agent reasoning
+ * over the live registry returned by lib/agent-routing.js::buildRoutingContext.
+ * A goal whose domain is absent from these maps still routes correctly via the
+ * grounded context + the fallback ladder — these maps only let obvious cases
+ * skip the reasoning round-trip and tell the seeder which specialists to plant.
+ *
+ * Keyed off the `category` field every MARKETPLACE_TOOLS entry already carries
+ * (lib/tools/registry.js), so adding a tool category here is the only manual
+ * step — no per-tool wiring.
+ */
+
+/**
+ * Tool categories that are SPECIALIST-OWNED: their tools are removed from the
+ * main agent's directly-callable catalog (see getTools() narrowing) and are
+ * reachable only by delegating to an agent that owns them.
+ *
+ * Scope note: the hard gate covers clear specialist WORK domains with low
+ * main-agent overlap. Deliberately NOT specialist (kept on the main agent):
+ *  - web        → web_search / web_fetch are the orchestrator's quick-fact allowance.
+ *  - voice      → voice_speak is how the main/voice agent talks — a mechanism, not a domain.
+ *  - browser    → browser_* is a main-agent mechanism (BROWSER_CONTROL contract).
+ *  - github     → heavy main-agent overlap (read context); routing + prompt steer
+ *                 engineering work to engineering_lead without a structural block (follow-up).
+ *  - authoring  → skill/composite/connector authoring belongs to the Tool Smith flow.
+ *  - workflow   → process-definition tools are orchestration.
+ *  - core/system/cli_generator → orchestration + presentation primitives.
+ *  - local_machine → file_read etc. used by the orchestrator for grounding.
+ */
+export const SPECIALIST_TOOL_CATEGORIES = new Set([
+  'travel',
+  'email',
+  'calendar',
+  'supabase',
+  'vercel',
+  'mines',
+]);
+
+/**
+ * Obvious-domain shortcut: tool category → the specialist role that owns it.
+ * Only a hint for fastPathHint(); never the sole basis of a routing decision.
+ */
+export const CATEGORY_TO_ROLE = {
+  travel: 'travel_concierge',
+  email: 'personal_assistant',
+  github: 'engineering_lead',
+  calendar: 'ops_manager',
+  supabase: 'web_ecommerce',
+  vercel: 'web_ecommerce',
+  browser: 'web_ecommerce',
+  voice: 'content_social',
+};
+
+/**
+ * Lightweight keyword → category guesses for fastPathHint(). Intentionally
+ * small: clear wins only. Anything not matched here falls through to the LLM
+ * reasoning over buildRoutingContext — which is the point.
+ */
+export const KEYWORD_CATEGORY_HINTS = [
+  [/\b(flight|flights|fly|airfare|airline|hotel|hotels|itinerary|trip|travel|book a (room|stay))\b/i, 'travel'],
+  [/\b(email|inbox|reply to .*(mail|message)|draft a (reply|mail|email)|gmail)\b/i, 'email'],
+  [/\b(pull request|\bpr\b|open an? issue|github|merge|commit|repo|repository)\b/i, 'github'],
+  [/\b(calendar|schedule a (meeting|call)|book (a )?(meeting|slot|30 ?min)|invite .* to)\b/i, 'calendar'],
+  [/\b(deploy|vercel|production build|ship the site)\b/i, 'vercel'],
+  [/\b(supabase|database row|insert into|update the table|sql)\b/i, 'supabase'],
+  // Visual / image generation — routes to whoever owns the media tools
+  // (higgsfield_generate_image / _video / product_photoshoot). Without this, an
+  // "create an ad image" goal had no hint and the agent spawned a bare,
+  // tool-less specialist that could not generate anything.
+  [/\b(image|images|photo|photograph|photoshoot|picture|visual|visuals|render|rendering|artwork|illustration|graphic|poster|advert|advertisement|\bad\b|\bads\b|banner|logo|thumbnail|mockup|still[\s-]?life|moodboard|generate (an?|the) (image|picture|visual|ad)|text[\s-]?to[\s-]?image)\b/i, 'media'],
+];
+
+/**
+ * Specialists to AUTO-SEED on first launch so the most common delegation
+ * targets exist out of the box. Kept minimal: every other domain is covered by
+ * the `create_then_delegate` ladder step at runtime. Each entry is an
+ * agent-templates.js slug; the seeder installs it idempotently.
+ */
+export const SEED_SPECIALISTS = [
+  'travel-concierge',
+];
+
+/** True when a marketplace tool belongs to a specialist-owned category. */
+export function isSpecialistTool(tool) {
+  return Boolean(tool && SPECIALIST_TOOL_CATEGORIES.has(tool.category));
+}
+
+/** Obvious role for a tool category, or null when there is no clear owner. */
+export function roleForCategory(category) {
+  return CATEGORY_TO_ROLE[category] || null;
+}
+
+/**
+ * ALL tool categories a goal plausibly needs (deduped), not just the first hit.
+ * Used by buildRoutingContext to surface which existing specialists already own
+ * the matching tools, so the main agent delegates to an equipped agent instead
+ * of spawning a tool-less one. A goal with no keyword match returns [] and the
+ * routing falls back to pure LLM reasoning over the registry — unchanged.
+ */
+export function neededToolCategoriesForGoal(goal) {
+  const text = String(goal || '');
+  if (!text.trim()) return [];
+  const cats = [];
+  for (const [re, category] of KEYWORD_CATEGORY_HINTS) {
+    if (re.test(text) && !cats.includes(category)) cats.push(category);
+  }
+  return cats;
+}

package/lib/seeds.js

@@ -5,6 +5,7 @@ import { ROOT } from './paths.js';
 import { seedMarketplaceItems } from './marketplace-seeds.js';
 import { ensureDefaultProject } from './projects.js';
 import { seedAgentTemplates, installAgentTemplate } from './agent-templates.js';
+import { SEED_SPECIALISTS } from './role-capability-map.js';
 import { ensureOpsAgent, createArtifact, migrateDefaultAgentSkills } from './runtime.js';
 import { renderChangelogHtml } from './artifact-format.js';
 import { migrateArtifactsToProjects } from './artifact-migration.js';
@@ -88,6 +89,31 @@ function seedUpdateCheckTask(db) {
   `).run(id, 'update_check', payload, runAfter, now, now);
 }
 
+/**
+ * Ensure a queued recurring task_sweep heartbeat task exists (idempotent). The
+ * worker re-schedules the next sweep +2m after each run, so this seed only fires
+ * on a fresh install. The sweep drives assigned tasks toward completion:
+ * dispatches never-woken tasks, re-wakes stuck/overdue ones. See
+ * lib/delegation.js::sweepTasks.
+ */
+function seedTaskSweepTask(db) {
+  const existing = db.prepare(
+    "SELECT id FROM heartbeat_tasks WHERE type = 'task_sweep' AND status IN ('queued','leased','running') LIMIT 1"
+  ).get();
+  if (existing) return;
+
+  const id = `hbtask-sweep-${Date.now().toString(36)}`;
+  const payload = JSON.stringify({ type: 'task_sweep' });
+  const now = new Date().toISOString();
+  // First sweep: 2 min after install.
+  const runAfter = new Date(Date.now() + 2 * 60 * 1000).toISOString();
+  db.prepare(`
+    INSERT INTO heartbeat_tasks
+      (id, agent_id, schedule_id, type, status, priority, payload, attempts, max_attempts, run_after, created_at, updated_at)
+    VALUES (?, NULL, NULL, ?, 'queued', 0, ?, 0, 99, ?, ?, ?)
+  `).run(id, 'task_sweep', payload, runAfter, now, now);
+}
+
 /**
  * Seed a default email allowlist entry for the email_send tool.
  *
@@ -347,6 +373,28 @@ function seedToolSmithAgentIfMissing(db) {
   }
 }
 
+/**
+ * Auto-seed the minimal specialist set (lib/role-capability-map.js
+ * SEED_SPECIALISTS) on first launch so delegation-first routing always has the
+ * most common targets — e.g. a Travel Concierge — instead of forcing the main
+ * agent to create_then_delegate on the very first request.
+ *
+ * Idempotent per template via agent_template_installations; if the user deletes
+ * one it stays deleted. Every other domain is still covered at runtime by the
+ * create_then_delegate / build_capability ladder. Silent + non-fatal.
+ */
+function seedSpecialistAgentsIfMissing(db) {
+  for (const slug of SEED_SPECIALISTS) {
+    try {
+      const installed = db.prepare('SELECT agent_id FROM agent_template_installations WHERE template_slug = ? LIMIT 1').get(slug);
+      if (installed) continue;
+      installAgentTemplate(slug, 'personal', { seed: true });
+    } catch (err) {
+      console.warn(`[seeds] seedSpecialistAgentsIfMissing(${slug}) failed:`, err?.message || err);
+    }
+  }
+}
+
 /**
  * Fire-and-forget disk-encryption health check on each boot.
  *
@@ -425,6 +473,14 @@ export function seedDefaults(db) {
     // Ignore — heartbeat_tasks table may not be ready yet during schema bootstrap.
   }
 
+  // Infrastructure: ensure the recurring task-sweep is queued (idempotent). Keeps
+  // assigned tasks moving toward completion (dispatch/​re-wake stuck/overdue).
+  try {
+    seedTaskSweepTask(db);
+  } catch {
+    // Ignore — heartbeat_tasks table may not be ready yet during schema bootstrap.
+  }
+
   // Email allowlist: seed install user's domain from git config on first install.
   try {
     seedDefaultEmailAllowlist(db);
@@ -537,6 +593,7 @@ export function seedDefaults(db) {
 
   // Auto-seed the Tool Smith agent so request_capability delegation has a target.
   seedToolSmithAgentIfMissing(db);
+  seedSpecialistAgentsIfMissing(db);
 
   // Refresh the business-default skills in existing default-shaped skills.md
   // files (no-op for fresh installs and user-customized agents). Idempotent.

package/lib/tools/adapters/disk.js

@@ -0,0 +1,107 @@
+// Project Disk read tools for the orchestrator. Bridges the agent to the
+// user-facing "project folder" (data/disk/<slug>/, the disk_folders/disk_files
+// tables) so "check my project files" reads the Disk — NOT the madarX source
+// tree. Read-only, scoped to a single project, engine-aware local_only redaction.
+import { listFolders, listFiles, readFileForEngine } from '../../disk.js';
+import { getProject } from '../../projects.js';
+import { appendAudit } from '../../runtime.js';
+
+function audit(tool, status, meta = {}) {
+  try { appendAudit({ type: `disk.${tool}`, summary: `${tool} ${status}`, status, meta }); } catch { /* observation-only */ }
+}
+
+// Resolve a canonical project from input (id or slug) or the active context.
+// Throws a clear error the agent can act on (e.g. call list_projects).
+function resolveProject(input = {}, context = {}) {
+  const ref = input.project_id ?? context.project_id ?? null;
+  if (!ref) {
+    const err = new Error('No project specified. Pass project_id (id or slug), or call list_projects to find one.');
+    err.code = 'project_required';
+    throw err;
+  }
+  const project = getProject(String(ref));
+  if (!project) {
+    const err = new Error(`Project "${ref}" not found. Call list_projects to see available projects and their slugs.`);
+    err.code = 'project_not_found';
+    throw err;
+  }
+  return project;
+}
+
+export async function diskListFolders(input = {}, context = {}) {
+  const project = resolveProject(input, context);
+  const folders = listFolders(project.id).map(f => ({
+    id: f.id, name: f.name, path: f.path, parent_id: f.parent_id ?? null,
+  }));
+  audit('list_folders', 'complete', { project_id: project.id, count: folders.length });
+  return {
+    ok: true,
+    tool: 'disk_list_folders',
+    project: { id: project.id, slug: project.slug, name: project.name },
+    folders,
+    metadata: { count: folders.length },
+  };
+}
+
+export async function diskListFiles(input = {}, context = {}) {
+  const project = resolveProject(input, context);
+  const opts = { project_id: project.id };
+  if (input.folder_id) opts.folder_id = String(input.folder_id);
+  const files = listFiles(opts).map(f => ({
+    id: f.id,
+    name: f.name,
+    kind: f.kind,
+    folder_id: f.folder_id ?? null,
+    size_bytes: f.size_bytes,
+    local_only: f.local_only === true,
+    updated_at: f.updated_at,
+  }));
+  audit('list_files', 'complete', { project_id: project.id, folder_id: opts.folder_id ?? null, count: files.length });
+  return {
+    ok: true,
+    tool: 'disk_list_files',
+    project: { id: project.id, slug: project.slug, name: project.name },
+    files,
+    metadata: { count: files.length },
+  };
+}
+
+export async function diskReadFile(input = {}, context = {}) {
+  const fileId = input.file_id ? String(input.file_id) : '';
+  if (!fileId) {
+    const err = new Error('file_id is required. Call disk_list_files first to get a file id.');
+    err.code = 'file_id_required';
+    throw err;
+  }
+  // Engine drives local_only redaction (cloud engines get a redacted marker).
+  // Default to a cloud engine so omission is fail-safe (redacts), never leaks.
+  const engine = context.engine || 'anthropic';
+  const result = readFileForEngine(fileId, engine); // throws 'file not found' for bad id
+
+  // Cross-project guard: when a project scope is in play, the file must belong
+  // to it. Prevents reading another project's Disk by raw file id.
+  const scopeRef = input.project_id ?? context.project_id ?? null;
+  if (scopeRef) {
+    const project = getProject(String(scopeRef));
+    if (project && result.project_id && result.project_id !== project.id) {
+      const err = new Error('That file belongs to a different project.');
+      err.code = 'cross_project_denied';
+      throw err;
+    }
+  }
+
+  audit('read_file', 'complete', { file_id: fileId, project_id: result.project_id ?? null, redacted: Boolean(result.redacted), engine });
+  return {
+    ok: true,
+    tool: 'disk_read_file',
+    file: {
+      id: result.id,
+      name: result.name,
+      kind: result.kind,
+      project_id: result.project_id ?? null,
+      local_only: result.local_only === true,
+      redacted: Boolean(result.redacted),
+    },
+    content: result.content,
+  };
+}