@agentproto/runtime 2.1.0 → 2.2.0

package/dist/index.mjs

@@ -29,12 +29,13 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
-import { runWorkflow, compileWorkflow } from '@agentproto/workflow-runtime';
+import { loadAppHandle } from '@agentproto/app-kit';
+import { normalizeToolId } from '@agentproto/driver';
+import { runWorkflow, buildAgentStep, compileWorkflow } from '@agentproto/workflow-runtime';
 import { loadWorkflowHandle } from '@agentproto/workflow-loader';
 import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { Cron } from 'croner';
 import { parseRoutineManifest } from '@agentproto/routine';
-import { normalizeToolId } from '@agentproto/driver';
 import { createServer as createServer$1 } from 'net';
 import { promisify } from 'util';
 import { createRequire } from 'module';
@@ -21944,6 +21945,18 @@ async function startHttpServer(opts) {
           const handled = await handleRoutineDefs(req, res, path, opts.routineRegistrar);
           if (handled) return;
         }
+        if (opts.appRegistry && opts.performAppInstall && opts.listRegisteredToolIds && (path.startsWith("/apps/") || path.startsWith("/scopes/"))) {
+          const handled = await handleApps(
+            req,
+            res,
+            path,
+            opts.appRegistry,
+            opts.performAppInstall,
+            opts.listRegisteredToolIds,
+            opts.resolveAgentAdapter
+          );
+          if (handled) return;
+        }
         res.writeHead(404, { "content-type": "application/json" });
         res.end(JSON.stringify({ error: "not_found", path }));
       } catch (err) {
@@ -24152,6 +24165,116 @@ async function handleProviderInbound(req, res, slug, deps2) {
   res.writeHead(200, { "content-type": "application/json" });
   res.end(JSON.stringify(result));
 }
+async function handleApps(req, res, path, appRegistry, performInstall2, listRegisteredToolIds, resolveAgentAdapter) {
+  const method = req.method ?? "GET";
+  const applyMatch = path.match(/^\/apps\/([^/]+)\/apply$/);
+  if (applyMatch && method === "POST") {
+    const appId = decodeURIComponent(applyMatch[1]);
+    const body = await readJsonBody(req);
+    const scopeId = body?.scopeId ?? "root";
+    let installed = appRegistry.getApp(appId);
+    if (!installed && body?.dir) {
+      const installResult = await performInstall2(body.dir, appRegistry, listRegisteredToolIds, resolveAgentAdapter);
+      if (!installResult.ok) {
+        res.writeHead(400, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: installResult.error }));
+        return true;
+      }
+      installed = installResult.record;
+    }
+    if (!installed) {
+      res.writeHead(400, { "content-type": "application/json" });
+      res.end(
+        JSON.stringify({
+          error: `app "${appId}" is not installed. Either call app_install first or provide a 'dir' parameter.`
+        })
+      );
+      return true;
+    }
+    if (installed.requires && installed.requires.length > 0) {
+      const applied = appRegistry.listApplied(scopeId);
+      const appliedIds = new Set(applied.map((m) => m.appId));
+      const missing = installed.requires.filter((reqId) => !appliedIds.has(reqId));
+      if (missing.length > 0) {
+        res.writeHead(400, { "content-type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error: `app "${appId}" requires the following apps to be applied to scope "${scopeId}" first: ${missing.join(", ")}`
+          })
+        );
+        return true;
+      }
+    }
+    const mount = appRegistry.applyApp({ scopeId, appId });
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(
+      JSON.stringify({
+        scopeId: mount.scopeId,
+        appId: mount.appId,
+        appliedAt: mount.appliedAt,
+        agents: installed.agents,
+        workflows: installed.workflows,
+        unvalidatedAgentTools: installed.unvalidatedAgentTools
+      })
+    );
+    return true;
+  }
+  if (applyMatch && method === "DELETE") {
+    const appId = decodeURIComponent(applyMatch[1]);
+    const body = await readJsonBody(req);
+    const url = new URL(req.url ?? "", `http://${req.headers.host}`);
+    const scopeId = body?.scopeId ?? url.searchParams.get("scopeId") ?? "root";
+    const applied = appRegistry.listApplied(scopeId);
+    const dependents = [];
+    for (const mount of applied) {
+      if (mount.appId === appId) continue;
+      const app = appRegistry.getApp(mount.appId);
+      if (app?.requires?.includes(appId)) {
+        dependents.push(mount.appId);
+      }
+    }
+    if (dependents.length > 0) {
+      res.writeHead(400, { "content-type": "application/json" });
+      res.end(
+        JSON.stringify({
+          error: `cannot unapply app "${appId}" from scope "${scopeId}" \u2014 the following apps in this scope require it: ${dependents.join(", ")}`
+        })
+      );
+      return true;
+    }
+    const removed = appRegistry.unapplyApp({ scopeId, appId });
+    if (!removed) {
+      res.writeHead(404, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: `app "${appId}" is not applied to scope "${scopeId}".` }));
+      return true;
+    }
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify({ scopeId: removed.scopeId, appId: removed.appId, appliedAt: removed.appliedAt }));
+    return true;
+  }
+  const scopesMatch = path.match(/^\/scopes\/([^/]+)\/apps$/);
+  if (scopesMatch && method === "GET") {
+    const scopeId = decodeURIComponent(scopesMatch[1]);
+    const mounts = appRegistry.listApplied(scopeId);
+    const result = mounts.map((mount) => {
+      const app = appRegistry.getApp(mount.appId);
+      return {
+        scopeId: mount.scopeId,
+        appId: mount.appId,
+        appliedAt: mount.appliedAt,
+        ...app ? {
+          agents: app.agents,
+          workflows: app.workflows,
+          unvalidatedAgentTools: app.unvalidatedAgentTools
+        } : {}
+      };
+    });
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify(result));
+    return true;
+  }
+  return false;
+}
 async function readJsonBody(req) {
   const chunks = [];
   for await (const chunk of req) {
@@ -25260,6 +25383,525 @@ stderr: ${stderrText.slice(-600)}` : msg);
     `import "${entry.alias}" has unsupported transport type "${snap.type}"`
   );
 }
+function collectToolIds(steps, out) {
+  for (const step of steps) {
+    switch (step.kind) {
+      case "tool": {
+        const ref = typeof step.tool === "string" ? step.tool : step.tool.entry;
+        out.add(normalizeToolId(ref));
+        break;
+      }
+      case "map":
+      case "loop":
+        collectToolIds(step.steps, out);
+        break;
+      case "parallel":
+        for (const branch of step.branches) collectToolIds(branch.steps, out);
+        break;
+    }
+  }
+}
+function passthroughToolHandle(id) {
+  return {
+    id,
+    name: id,
+    description: `Daemon tool '${id}', dispatched via the routine/cron dispatchTool bridge.`,
+    mutates: [],
+    requires: { network: [], secrets: [], tools: [] },
+    approval: "auto",
+    riskLevel: 0,
+    costClass: "trivial",
+    timeoutMs: 3e4,
+    tags: [],
+    metadata: {},
+    idempotent: false,
+    driverConstraints: { forbid: [], requireKind: [] }
+  };
+}
+function unwrapDispatchResult(result) {
+  if (!result || typeof result !== "object" || !("content" in result)) return result;
+  const r = result;
+  const text9 = (r.content ?? []).map((c) => c.text ?? "").join("\n").trim();
+  if (r.isError) throw new Error(text9 || "tool call failed");
+  if (!text9) return void 0;
+  try {
+    return JSON.parse(text9);
+  } catch {
+    return text9;
+  }
+}
+function createDaemonToolRegistry(handle, dispatchTool) {
+  const toolIds = /* @__PURE__ */ new Set();
+  collectToolIds(handle.steps, toolIds);
+  const tools = {};
+  const execute = {};
+  for (const id of toolIds) {
+    tools[id] = passthroughToolHandle(id);
+    execute[id] = async ({ input }) => unwrapDispatchResult(await dispatchTool(id, input ?? {}));
+  }
+  if (toolIds.size === 0) return { tools, candidates: [] };
+  const daemonDriver = {
+    id: "daemon-tool-dispatch",
+    name: "Daemon tool dispatch",
+    description: "Catch-all AIP-30 provider routing every referenced WORKFLOW.md tool step through the daemon's dispatchTool.",
+    kind: "builtin",
+    implements: [...toolIds].map((id) => ({ tool: id, version: "*" })),
+    execute,
+    install: [],
+    network: { egress: [], ingress: [] },
+    region: ["global"],
+    policyTags: [],
+    tags: [],
+    metadata: {}
+  };
+  return { tools, candidates: [daemonDriver] };
+}
+var DEFAULT_PERSIST_PATH2 = () => join(homedir(), ".agentproto", "apps.json");
+function loadState(persistPath) {
+  const empty = { apps: [], runs: [], applied: [] };
+  if (!existsSync(persistPath)) return empty;
+  let raw;
+  try {
+    raw = readFileSync(persistPath, "utf8");
+  } catch {
+    return empty;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      apps: Array.isArray(parsed.apps) ? parsed.apps : [],
+      runs: Array.isArray(parsed.runs) ? parsed.runs : [],
+      applied: Array.isArray(parsed.applied) ? parsed.applied : []
+    };
+  } catch {
+    return empty;
+  }
+}
+function saveState(state, persistPath) {
+  try {
+    mkdirSync(dirname(persistPath), { recursive: true });
+    const tmp = `${persistPath}.tmp.${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", "utf8");
+    renameSync(tmp, persistPath);
+  } catch {
+  }
+}
+function createAppRegistry(opts) {
+  const persistPath = opts?.persistPath ?? DEFAULT_PERSIST_PATH2();
+  const shouldPersist = opts?.persist ?? opts?.persistPath !== void 0;
+  const state = shouldPersist ? loadState(persistPath) : { apps: [], runs: [], applied: [] };
+  const persist = () => {
+    if (shouldPersist) saveState(state, persistPath);
+  };
+  return {
+    upsertApp(input) {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const idx = state.apps.findIndex((a) => a.appId === input.appId);
+      const record2 = {
+        ...input,
+        installedAt: idx === -1 ? now : state.apps[idx].installedAt,
+        updatedAt: now
+      };
+      if (idx === -1) state.apps.push(record2);
+      else state.apps[idx] = record2;
+      persist();
+      return record2;
+    },
+    getApp(appId) {
+      return state.apps.find((a) => a.appId === appId);
+    },
+    listApps() {
+      return [...state.apps];
+    },
+    createRun(input) {
+      const run = {
+        appRunId: `apprun_${randomUUID()}`,
+        appId: input.appId,
+        sessions: input.sessions,
+        startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        status: "running"
+      };
+      state.runs.push(run);
+      persist();
+      return run;
+    },
+    getRun(appRunId) {
+      return state.runs.find((r) => r.appRunId === appRunId);
+    },
+    listRuns() {
+      return [...state.runs];
+    },
+    endRun(appRunId) {
+      const run = state.runs.find((r) => r.appRunId === appRunId);
+      if (!run) return void 0;
+      run.status = "stopped";
+      run.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+      persist();
+      return run;
+    },
+    applyApp(input) {
+      const idx = state.applied.findIndex(
+        (m) => m.scopeId === input.scopeId && m.appId === input.appId
+      );
+      const mount = {
+        scopeId: input.scopeId,
+        appId: input.appId,
+        appliedAt: idx === -1 ? (/* @__PURE__ */ new Date()).toISOString() : state.applied[idx].appliedAt
+      };
+      if (idx === -1) state.applied.push(mount);
+      else state.applied[idx] = mount;
+      persist();
+      return mount;
+    },
+    unapplyApp(input) {
+      const idx = state.applied.findIndex(
+        (m) => m.scopeId === input.scopeId && m.appId === input.appId
+      );
+      if (idx === -1) return void 0;
+      const removed = state.applied[idx];
+      state.applied.splice(idx, 1);
+      persist();
+      return removed;
+    },
+    listApplied(scopeId) {
+      if (scopeId === void 0) return [...state.applied];
+      return state.applied.filter((m) => m.scopeId === scopeId);
+    }
+  };
+}
+
+// src/app-tools.ts
+var DEFAULT_AGENT_ADAPTER = "mastra-agent";
+function resolveAgentRefsForWorkflow(appRegistry, workflowId) {
+  const app = appRegistry.listApps().find((a) => a.workflows.some((w) => w.id === workflowId));
+  if (!app) return void 0;
+  const refs = {};
+  for (const agent of app.agents) {
+    refs[agent.id] = { adapter: DEFAULT_AGENT_ADAPTER, options: { agent: agent.path } };
+  }
+  return refs;
+}
+function textResult(body) {
+  return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+}
+function errorResult(text9) {
+  return { content: [{ type: "text", text: JSON.stringify({ error: text9 }) }], isError: true };
+}
+function refIdOf(ref) {
+  if (typeof ref === "string") return ref;
+  return ref.ref ?? ref.file ?? "inline";
+}
+function resolveRef(dir, path) {
+  return isAbsolute(path) ? path : join(dir, path);
+}
+async function readAppRefs(dir) {
+  const appPath = join(dir, ".agentproto", "APP.md");
+  const source = await readFile(appPath, "utf8");
+  const { data } = matter(source);
+  const toRefs = (v) => Array.isArray(v) ? v.filter(
+    (e) => typeof e === "object" && e !== null && typeof e.id === "string" && typeof e.path === "string"
+  ).map((e) => ({ id: e.id, path: resolveRef(dir, e.path) })) : [];
+  return { agents: toRefs(data.agents), workflows: toRefs(data.workflows) };
+}
+async function performInstall(dir, appRegistry, listRegisteredToolIds, resolveAgentAdapter) {
+  let handle;
+  try {
+    handle = await loadAppHandle(dir);
+  } catch (err) {
+    return { ok: false, error: `${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (!handle.id) {
+    return { ok: false, error: "the app has no `id` \u2014 set one in defineApp()/APP.md frontmatter to install it." };
+  }
+  const missingByWorkflow = {};
+  const registeredIds = new Set(await listRegisteredToolIds());
+  for (const workflow of handle.workflows) {
+    const { tools } = createDaemonToolRegistry(workflow, async () => void 0);
+    const missing = Object.keys(tools).filter((id) => !registeredIds.has(id));
+    if (missing.length > 0) missingByWorkflow[workflow.id] = missing;
+  }
+  if (Object.keys(missingByWorkflow).length > 0) {
+    return {
+      ok: false,
+      error: `unknown daemon tool id(s) referenced by workflow step(s) \u2014 would otherwise fail at STEP-DISPATCH time: ${JSON.stringify(missingByWorkflow)}`
+    };
+  }
+  if (handle.agents.length > 0) {
+    const resolved = resolveAgentAdapter ? await resolveAgentAdapter(DEFAULT_AGENT_ADAPTER) : null;
+    if (!resolved) {
+      return {
+        ok: false,
+        error: `agent adapter "${DEFAULT_AGENT_ADAPTER}" could not be resolved \u2014 run \`agentproto install ${DEFAULT_AGENT_ADAPTER}\` first.`
+      };
+    }
+  }
+  const refs = await readAppRefs(dir);
+  const unvalidatedAgentTools = [
+    ...new Set(handle.agents.flatMap((e) => (e.agent.tools ?? []).map(refIdOf)))
+  ];
+  const record2 = appRegistry.upsertApp({
+    appId: handle.id,
+    dir,
+    ...handle.version ? { version: handle.version } : {},
+    ...handle.name ? { name: handle.name } : {},
+    agents: refs.agents,
+    workflows: refs.workflows,
+    unvalidatedAgentTools,
+    ...handle.requires ? { requires: handle.requires } : {}
+  });
+  return { ok: true, record: record2 };
+}
+function registerAppTools(server, opts) {
+  const { registry, resolveAgentAdapter, listRegisteredToolIds, workflowRunner } = opts;
+  const appRegistry = opts.appRegistry ?? createAppRegistry({
+    ...opts.persistPath !== void 0 ? { persistPath: opts.persistPath } : {},
+    ...opts.persist !== void 0 ? { persist: opts.persist } : {}
+  });
+  const notEnabled = (tool) => errorResult(
+    `${tool} is not enabled \u2014 the daemon was started without an adapter resolver. Re-run the daemon with the \`@agentproto/cli\` shim wired (see playground/scripts/gateway.ts).`
+  );
+  server.tool(
+    "app_install",
+    "Install an @agentproto/app-kit app from its emitted directory (`<dir>/.agentproto/APP.md` \u2014 see `defineApp().emit(dir)`). Validates every WORKFLOW.md `tool` step's id against the daemon's dispatchable tools (missing ids are reported ALL at once, instead of failing one at a time at STEP-DISPATCH time) and checks the `mastra-agent` adapter resolves. Agent-declared tool refs (workspace tools like `read_file`) are the adapter's own business and are never validated here \u2014 see `unvalidatedAgentTools` on the result. Re-installing the same appId upserts.",
+    { dir: z.string().describe("Absolute path to the app's directory.") },
+    async (input) => {
+      const result = await performInstall(input.dir, appRegistry, listRegisteredToolIds, resolveAgentAdapter);
+      if (!result.ok) return errorResult(`app_install: ${result.error}`);
+      return textResult(result.record);
+    }
+  );
+  server.tool(
+    "app_list",
+    "List installed apps, each with a summary of its app_run history.",
+    {},
+    async () => {
+      const runs = appRegistry.listRuns();
+      const apps = appRegistry.listApps().map((app) => ({
+        ...app,
+        runs: runs.filter((r) => r.appId === app.appId).map((r) => ({
+          appRunId: r.appRunId,
+          status: r.status,
+          startedAt: r.startedAt,
+          ...r.endedAt ? { endedAt: r.endedAt } : {},
+          sessions: r.sessions.length
+        }))
+      }));
+      return textResult(apps);
+    }
+  );
+  server.tool(
+    "app_run",
+    "Run an installed app's agents as live sessions \u2014 one `agent_start`-equivalent spawn per selected agent (adapter `mastra-agent`, pointed at that agent's emitted AGENT.md via the adapter's `agent` option), grouped under a fresh appRunId. Re-reads the app's directory first, so a stale install record (paths moved, a workflow renamed) is refreshed before spawning \u2014 the same refreshed paths are what make `workflow_run_file` work against this app's WORKFLOW.md files. Poll with `app_status`, kill with `app_stop`.",
+    {
+      appId: z.string(),
+      agents: z.array(z.string()).optional().describe("Agent ids to run. Omit to run every agent the app bundles."),
+      prompt: z.string().optional().describe("Prompt to send to each spawned agent session."),
+      cwd: z.string().optional().describe("Working directory for spawned sessions. Defaults to the app's installed `dir`."),
+      scopeId: z.string().optional().describe("When passed, refuse to run if the app is not applied to this scope.")
+      // follow-up: no sandbox support in this WP — the e2b image doesn't carry
+      // the mastra-agent adapter yet (see output/phase-a-findings.md A3). Thread
+      // a `sandbox` field through to `spawnAgentSession` here once an image
+      // provisions it (or `app_install`/boot does `agentproto install
+      // mastra-agent` inside the box).
+    },
+    async (input) => {
+      if (!resolveAgentAdapter) return notEnabled("app_run");
+      const installed = appRegistry.getApp(input.appId);
+      if (!installed) {
+        return errorResult(`app_run: no installed app "${input.appId}" \u2014 call app_install first.`);
+      }
+      if (input.scopeId) {
+        const applied = appRegistry.listApplied(input.scopeId);
+        if (!applied.some((m) => m.appId === input.appId)) {
+          return errorResult(
+            `app_run: app "${input.appId}" is not applied to scope "${input.scopeId}". Call app_apply first.`
+          );
+        }
+      }
+      let refs;
+      try {
+        refs = await readAppRefs(installed.dir);
+      } catch (err) {
+        return errorResult(
+          `app_run: could not re-read "${installed.dir}": ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+      const app = appRegistry.upsertApp({ ...installed, agents: refs.agents, workflows: refs.workflows });
+      const selected = input.agents ?? app.agents.map((a) => a.id);
+      const unknown = selected.filter((id) => !app.agents.some((a) => a.id === id));
+      if (unknown.length > 0) {
+        return errorResult(
+          `app_run: unknown agent id(s) for app "${input.appId}": ${unknown.join(", ")}`
+        );
+      }
+      const sessions = [];
+      const errors = [];
+      for (const agentId of selected) {
+        const agentPath = app.agents.find((a) => a.id === agentId).path;
+        const result = await spawnAgentSession(
+          { registry, resolveAgentAdapter },
+          {
+            adapter: DEFAULT_AGENT_ADAPTER,
+            cwd: input.cwd ?? app.dir,
+            ...input.prompt ? { prompt: input.prompt } : {},
+            options: { agent: agentPath },
+            label: `app:${app.appId}:${agentId}`
+          }
+        );
+        if (result.ok) sessions.push({ agentId, sessionId: result.descriptor.id });
+        else errors.push({ agentId, error: result.message });
+      }
+      const run = appRegistry.createRun({ appId: app.appId, sessions });
+      return textResult({
+        appRunId: run.appRunId,
+        sessions,
+        ...errors.length > 0 ? { errors } : {}
+      });
+    }
+  );
+  server.tool(
+    "app_status",
+    "Status of an app_run: its sessions' live descriptors, plus any workflow runs belonging to the app (any run of one of its bundled WORKFLOW.md files, however it was started).",
+    { appRunId: z.string() },
+    async (input) => {
+      const run = appRegistry.getRun(input.appRunId);
+      if (!run) return errorResult(`app_status: no app run "${input.appRunId}".`);
+      const app = appRegistry.getApp(run.appId);
+      const sessions = run.sessions.map((s) => ({
+        agentId: s.agentId,
+        sessionId: s.sessionId,
+        descriptor: registry.get(s.sessionId)
+      }));
+      const workflowRuns = workflowRunner && app ? workflowRunner.list().filter((r) => app.workflows.some((w) => w.id === r.workflowId)) : [];
+      return textResult({
+        appRunId: run.appRunId,
+        appId: run.appId,
+        status: run.status,
+        startedAt: run.startedAt,
+        ...run.endedAt ? { endedAt: run.endedAt } : {},
+        sessions,
+        workflowRuns
+      });
+    }
+  );
+  server.tool(
+    "app_stop",
+    "Kill every session in an app_run (existing kill path) and mark the run ended.",
+    { appRunId: z.string() },
+    async (input) => {
+      const run = appRegistry.getRun(input.appRunId);
+      if (!run) return errorResult(`app_stop: no app run "${input.appRunId}".`);
+      const killed = [];
+      const notFound = [];
+      for (const s of run.sessions) {
+        if (registry.kill(s.sessionId)) killed.push(s.sessionId);
+        else notFound.push(s.sessionId);
+      }
+      const ended = appRegistry.endRun(input.appRunId);
+      return textResult({
+        appRunId: input.appRunId,
+        killed,
+        ...notFound.length > 0 ? { notFound } : {},
+        status: ended?.status ?? run.status
+      });
+    }
+  );
+  server.tool(
+    "app_apply",
+    "Apply an app to a scope, making its capabilities available in that scope. If the app is not installed and `dir` is provided, installs it first. Validates that all `requires` dependencies are already applied to the same scope. Idempotent \u2014 re-applying the same app to the same scope updates the timestamp.",
+    {
+      appId: z.string(),
+      scopeId: z.string().optional().describe("Scope to apply to. Defaults to 'root'."),
+      dir: z.string().optional().describe("Absolute path to install from if not already installed.")
+    },
+    async (input) => {
+      const scopeId = input.scopeId ?? "root";
+      let installed = appRegistry.getApp(input.appId);
+      if (!installed && input.dir) {
+        const installResult = await performInstall(input.dir, appRegistry, listRegisteredToolIds, resolveAgentAdapter);
+        if (!installResult.ok) return errorResult(`app_apply: ${installResult.error}`);
+        installed = installResult.record;
+      } else if (!installed) {
+        return errorResult(
+          `app_apply: app "${input.appId}" is not installed. Either call app_install first or provide a 'dir' parameter.`
+        );
+      }
+      if (installed.requires && installed.requires.length > 0) {
+        const applied = appRegistry.listApplied(scopeId);
+        const appliedIds = new Set(applied.map((m) => m.appId));
+        const missing = installed.requires.filter((reqId) => !appliedIds.has(reqId));
+        if (missing.length > 0) {
+          return errorResult(
+            `app_apply: app "${input.appId}" requires the following apps to be applied to scope "${scopeId}" first: ${missing.join(", ")}`
+          );
+        }
+      }
+      const mount = appRegistry.applyApp({ scopeId, appId: input.appId });
+      return textResult({
+        scopeId: mount.scopeId,
+        appId: mount.appId,
+        appliedAt: mount.appliedAt,
+        agents: installed.agents,
+        workflows: installed.workflows,
+        unvalidatedAgentTools: installed.unvalidatedAgentTools
+      });
+    }
+  );
+  server.tool(
+    "app_unapply",
+    "Remove an app from a scope. Refuses if another applied app in the same scope requires this one.",
+    {
+      appId: z.string(),
+      scopeId: z.string().optional().describe("Scope to unapply from. Defaults to 'root'.")
+    },
+    async (input) => {
+      const scopeId = input.scopeId ?? "root";
+      const applied = appRegistry.listApplied(scopeId);
+      const dependents = [];
+      for (const mount of applied) {
+        if (mount.appId === input.appId) continue;
+        const app = appRegistry.getApp(mount.appId);
+        if (app?.requires?.includes(input.appId)) {
+          dependents.push(mount.appId);
+        }
+      }
+      if (dependents.length > 0) {
+        return errorResult(
+          `app_unapply: cannot unapply app "${input.appId}" from scope "${scopeId}" \u2014 the following apps in this scope require it: ${dependents.join(", ")}`
+        );
+      }
+      const removed = appRegistry.unapplyApp({ scopeId, appId: input.appId });
+      if (!removed) {
+        return errorResult(`app_unapply: app "${input.appId}" is not applied to scope "${scopeId}".`);
+      }
+      return textResult({ scopeId: removed.scopeId, appId: removed.appId, appliedAt: removed.appliedAt });
+    }
+  );
+  server.tool(
+    "app_list_applied",
+    "List applied mounts, optionally filtered by scope. Each mount is joined with its installed app summary.",
+    {
+      scopeId: z.string().optional().describe("Filter by scope. Omit to list all scopes.")
+    },
+    async (input) => {
+      const mounts = appRegistry.listApplied(input.scopeId);
+      const result = mounts.map((mount) => {
+        const app = appRegistry.getApp(mount.appId);
+        return {
+          scopeId: mount.scopeId,
+          appId: mount.appId,
+          appliedAt: mount.appliedAt,
+          ...app ? {
+            agents: app.agents,
+            workflows: app.workflows,
+            unvalidatedAgentTools: app.unvalidatedAgentTools
+          } : {}
+        };
+      });
+      return textResult(result);
+    }
+  );
+}
 function createSessionEventBus() {
   const ee = new EventEmitter();
   ee.setMaxListeners(100);
@@ -25433,7 +26075,8 @@ var SessionsRegistryAgentHost = class {
           cwd,
           workspaceSlug,
           sandbox,
-          label: `agent-step:${adapter}`
+          label: `agent-step:${adapter}`,
+          ...opts.options !== void 0 ? { options: opts.options } : {}
         }
       );
       if (!result.ok) {
@@ -25452,7 +26095,8 @@ var SessionsRegistryAgentHost = class {
       env: {
         [SESSION_ID_ENV]: stepSessionId,
         [WORKSPACE_SLUG_ENV]: workspaceSlug
-      }
+      },
+      ...opts.options !== void 0 ? { options: opts.options } : {}
     });
     const desc = this.registry.spawnAgent({
       id: stepSessionId,
@@ -25648,16 +26292,32 @@ function translateStages(stages, workflowId) {
     const branches = stage.steps.map((step) => ({
       id: step.label,
       steps: [
-        {
-          kind: "agent",
-          id: step.label,
+        buildAgentStep(step.label, {
+          prompt: (b) => {
+            const base = step.prompt ?? "";
+            const prevTexts = [];
+            if (b.steps && typeof b.steps === "object") {
+              for (const [id, val] of Object.entries(b.steps)) {
+                if (val && typeof val === "object" && "text" in val) {
+                  const text9 = val.text;
+                  if (text9) prevTexts.push(`[Output from step "${id}"]
+${text9}`);
+                }
+              }
+            }
+            if (prevTexts.length > 0) return `${prevTexts.join("\n\n")}
+
+---
+
+${base}`;
+            return base;
+          },
           ...step.adapter !== void 0 ? { adapter: step.adapter } : {},
           ...step.sessionRef !== void 0 ? { sessionRef: step.sessionRef } : {},
           ...step.sandbox !== void 0 ? { sandbox: step.sandbox } : {},
           ...step.cacheable ? { cacheable: true } : {},
-          prompt: () => step.prompt ?? "",
-          policy: step.policy ?? { awaiting: "fail" }
-        }
+          policy: step.policy
+        })
       ]
     }));
     return {
@@ -25710,7 +26370,7 @@ function runtimeWorkflowToStages(workflow) {
     }
   ];
 }
-var DEFAULT_PERSIST_PATH2 = () => join(homedir(), ".agentproto", "workflow-runs.json");
+var DEFAULT_PERSIST_PATH3 = () => join(homedir(), ".agentproto", "workflow-runs.json");
 function loadRuns(persistPath) {
   const result = /* @__PURE__ */ new Map();
   if (!existsSync(persistPath)) return result;
@@ -25825,7 +26485,7 @@ function fillStepStates(stages, defs, agents) {
   }
   return sessionIds;
 }
-async function executeRunWorkflow(state, runtimeWf, agents, signal, cache, cacheKey, input) {
+async function executeRunWorkflow(state, runtimeWf, agents, signal, cache, cacheKey, input, persist) {
   try {
     await runWorkflow({
       workflow: runtimeWf,
@@ -25834,13 +26494,49 @@ async function executeRunWorkflow(state, runtimeWf, agents, signal, cache, cache
       cwd: state.cwd,
       workspaceSlug: state.workspaceSlug,
       input,
-      ...cache ? { cache, cacheKey } : {}
+      ...cache ? { cache, cacheKey } : {},
+      onStepStart: (stepId) => {
+        for (const stage of state.run.stages) {
+          const step = stage.steps.find((s) => s.label === stepId);
+          if (step) {
+            if (step.status === "pending") {
+              step.status = "running";
+              step.startedAt = (/* @__PURE__ */ new Date()).toISOString();
+            }
+            if (stage.status === "pending") {
+              stage.status = "running";
+            }
+            persist?.();
+            break;
+          }
+        }
+      },
+      onStepComplete: (stepId, output) => {
+        for (const stage of state.run.stages) {
+          const step = stage.steps.find((s) => s.label === stepId);
+          if (step) {
+            step.status = "done";
+            step.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+            if (output && typeof output === "object" && "sessionId" in output) {
+              step.sessionId = output.sessionId;
+            }
+            const allDone = stage.steps.every((s) => s.status === "done");
+            if (allDone) {
+              stage.status = "done";
+            }
+            persist?.();
+            break;
+          }
+        }
+      }
     });
     for (const stage of state.run.stages) {
-      stage.status = "done";
+      if (stage.status !== "done") stage.status = "done";
       for (const step of stage.steps) {
-        step.status = "done";
-        step.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+        if (step.status !== "done") {
+          step.status = "done";
+          step.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+        }
       }
     }
     state.run.status = "done";
@@ -25875,7 +26571,7 @@ async function executeRunWorkflow(state, runtimeWf, agents, signal, cache, cache
 }
 function createWorkflowRunner(opts) {
   const { registry, sessionEvents, resolveAgentAdapter, compileWorkflow: compileWorkflow2 } = opts;
-  const persistPath = opts.persistPath ?? DEFAULT_PERSIST_PATH2();
+  const persistPath = opts.persistPath ?? DEFAULT_PERSIST_PATH3();
   const shouldPersist = opts.persist ?? opts.persistPath !== void 0;
   const runs = shouldPersist ? loadRuns(persistPath) : /* @__PURE__ */ new Map();
   const persist = () => {
@@ -25926,7 +26622,7 @@ function createWorkflowRunner(opts) {
         }
       );
       const cache = input.cacheKey ? createFileStepCache(input.cacheKey) : void 0;
-      void executeRunWorkflow(state, workflow, agents, abort.signal, cache, input.cacheKey).then(() => {
+      void executeRunWorkflow(state, workflow, agents, abort.signal, cache, input.cacheKey, void 0, persist).then(() => {
         persist();
       });
       return run;
@@ -25987,7 +26683,8 @@ function createWorkflowRunner(opts) {
         abort.signal,
         cache,
         args.cacheKey,
-        args.input
+        args.input,
+        persist
       ).then(() => {
         persist();
       });
@@ -26620,7 +27317,7 @@ function toDescriptor2(state) {
     spawned: state.spawned
   };
 }
-var DEFAULT_PERSIST_PATH3 = () => join(homedir(), ".agentproto", "cron-jobs.json");
+var DEFAULT_PERSIST_PATH4 = () => join(homedir(), ".agentproto", "cron-jobs.json");
 var TICK_INTERVAL_MS = 2e4;
 function loadJobs(persistPath) {
   const result = /* @__PURE__ */ new Map();
@@ -26678,7 +27375,7 @@ function nextFireDate(cronInstance) {
 }
 function createCronScheduler(opts) {
   const { sessionEvents, registry, resolveAgentAdapter, dispatchTool, workspace } = opts;
-  const persistPath = opts.persistPath ?? DEFAULT_PERSIST_PATH3();
+  const persistPath = opts.persistPath ?? DEFAULT_PERSIST_PATH4();
   const shouldPersist = opts.persist ?? opts.persistPath !== void 0;
   const jobs = shouldPersist ? loadJobs(persistPath) : /* @__PURE__ */ new Map();
   for (const state of jobs.values()) {
@@ -27123,79 +27820,6 @@ function createRoutineRegistrar(opts) {
     }
   };
 }
-function collectToolIds(steps, out) {
-  for (const step of steps) {
-    switch (step.kind) {
-      case "tool": {
-        const ref = typeof step.tool === "string" ? step.tool : step.tool.entry;
-        out.add(normalizeToolId(ref));
-        break;
-      }
-      case "map":
-      case "loop":
-        collectToolIds(step.steps, out);
-        break;
-      case "parallel":
-        for (const branch of step.branches) collectToolIds(branch.steps, out);
-        break;
-    }
-  }
-}
-function passthroughToolHandle(id) {
-  return {
-    id,
-    name: id,
-    description: `Daemon tool '${id}', dispatched via the routine/cron dispatchTool bridge.`,
-    mutates: [],
-    requires: { network: [], secrets: [], tools: [] },
-    approval: "auto",
-    riskLevel: 0,
-    costClass: "trivial",
-    timeoutMs: 3e4,
-    tags: [],
-    metadata: {},
-    idempotent: false,
-    driverConstraints: { forbid: [], requireKind: [] }
-  };
-}
-function unwrapDispatchResult(result) {
-  if (!result || typeof result !== "object" || !("content" in result)) return result;
-  const r = result;
-  const text9 = (r.content ?? []).map((c) => c.text ?? "").join("\n").trim();
-  if (r.isError) throw new Error(text9 || "tool call failed");
-  if (!text9) return void 0;
-  try {
-    return JSON.parse(text9);
-  } catch {
-    return text9;
-  }
-}
-function createDaemonToolRegistry(handle, dispatchTool) {
-  const toolIds = /* @__PURE__ */ new Set();
-  collectToolIds(handle.steps, toolIds);
-  const tools = {};
-  const execute = {};
-  for (const id of toolIds) {
-    tools[id] = passthroughToolHandle(id);
-    execute[id] = async ({ input }) => unwrapDispatchResult(await dispatchTool(id, input ?? {}));
-  }
-  if (toolIds.size === 0) return { tools, candidates: [] };
-  const daemonDriver = {
-    id: "daemon-tool-dispatch",
-    name: "Daemon tool dispatch",
-    description: "Catch-all AIP-30 provider routing every referenced WORKFLOW.md tool step through the daemon's dispatchTool.",
-    kind: "builtin",
-    implements: [...toolIds].map((id) => ({ tool: id, version: "*" })),
-    execute,
-    install: [],
-    network: { egress: [], ingress: [] },
-    region: ["global"],
-    policyTags: [],
-    tags: [],
-    metadata: {}
-  };
-  return { tools, candidates: [daemonDriver] };
-}
 var DEFAULT_ORCHESTRATOR_TOOLS = [
   "agent_start",
   "agent_prompt",
@@ -30776,6 +31400,13 @@ async function createGateway(opts) {
     }
     return dispatchToolBox.fn(name, inputs);
   };
+  const listToolIdsBox = {};
+  const listRegisteredToolIds = async () => {
+    if (!listToolIdsBox.fn) {
+      throw new Error("app_install: tool registry not ready yet (daemon still booting)");
+    }
+    return listToolIdsBox.fn();
+  };
   const cronScheduler = createCronScheduler({
     sessionEvents,
     registry: sessions,
@@ -30789,6 +31420,7 @@ async function createGateway(opts) {
     cronScheduler,
     dispatchTool
   });
+  const appRegistry = createAppRegistry();
   const workflowRunner = opts.resolveAgentAdapter ? createWorkflowRunner({
     registry: sessions,
     sessionEvents,
@@ -30805,7 +31437,13 @@ async function createGateway(opts) {
     // the same `dispatchTool` the routine registrar / cron scheduler use
     // (see `workflow-tool-registry.ts`). Agent-step workflows are
     // unaffected: an empty tool registry compiles them exactly as before.
-    compileWorkflow: (handle) => compileWorkflow(handle, createDaemonToolRegistry(handle, dispatchTool))
+    // `agentRefs` resolves a declarative agent-step's `agent.ref` against
+    // whichever installed app bundles this workflow id (undefined when
+    // none does — a plain `workflow_run_file` outside any app).
+    compileWorkflow: (handle) => compileWorkflow(handle, {
+      ...createDaemonToolRegistry(handle, dispatchTool),
+      agentRefs: resolveAgentRefsForWorkflow(appRegistry, handle.id)
+    })
   }) : void 0;
   const operatorWorkspaceSlug = await loadWorkspacesConfig().then((cfg) => getActiveWorkspace(cfg)?.slug).catch(() => void 0);
   const taskLedger = createTaskLedger({
@@ -30981,6 +31619,13 @@ async function createGateway(opts) {
       endpointStore: inboundEndpointStore,
       telegramCreds: telegramBotCreds
     });
+    registerAppTools(server, {
+      registry: sessions,
+      listRegisteredToolIds,
+      appRegistry,
+      ...opts.resolveAgentAdapter ? { resolveAgentAdapter: opts.resolveAgentAdapter } : {},
+      ...workflowRunner ? { workflowRunner } : {}
+    });
     registerTelegramBotTools(server, { telegramCreds: telegramBotCreds });
     const listSessionsFiltered = (filter) => {
       let rows = sessions.list().filter((s) => s.kind !== "command");
@@ -31078,6 +31723,12 @@ async function createGateway(opts) {
     }
     return tool.handler(inputs, {});
   };
+  listToolIdsBox.fn = async () => {
+    if (!internalToolServerPromise) internalToolServerPromise = mcpServerFactory();
+    const internalServer = await internalToolServerPromise;
+    const internal = internalServer;
+    return Object.keys(internal._registeredTools ?? {});
+  };
   try {
     routineRegistrar.reconcile();
   } catch (err) {
@@ -31136,6 +31787,9 @@ async function createGateway(opts) {
     activityProjector,
     taskLedger,
     ...workflowRunner ? { workflowRunner } : {},
+    appRegistry,
+    performAppInstall: performInstall,
+    listRegisteredToolIds,
     // POST /inbound push ingress — same shared transmitterBindings store
     // and liveness/restart adapters the inbound watcher's "route"/
     // "route-or-spawn" modes use above. No `spawnForContact`: an