@agentproto/runtime 2.1.0 → 2.3.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';
@@ -309,11 +310,16 @@ function createTranscriptWriter(opts) {
     }, DEBOUNCE_MS);
   };
   return {
-    recordPrompt(sessionId, message) {
+    recordPrompt(sessionId, message, opts2) {
       const state = getState(sessionId);
       flushBuffers(sessionId, state);
       const text9 = typeof message === "string" ? message : JSON.stringify(message);
-      writeRecord(sessionId, state, { kind: "user-prompt", sessionId, text: text9 });
+      writeRecord(sessionId, state, {
+        kind: "user-prompt",
+        sessionId,
+        text: text9,
+        ...opts2?.source ? { source: opts2.source } : {}
+      });
     },
     recordEvent(sessionId, evt) {
       const state = getState(sessionId);
@@ -403,6 +409,22 @@ function createTranscriptWriter(opts) {
             options: evt.options
           });
           break;
+        // Durable counterpart to "agent-prompt" — recorded when
+        // `respondPermission` (or a dying session's cancel-in-flight sweep)
+        // resolves the ask, keyed by the same `toolCallId` so a reader can
+        // tell an answered request from a still-pending one without relying
+        // on the in-memory pending-permissions map (see sessions.ts's
+        // `resolvePendingPermission` / `cancelPendingPermissionsForSession`).
+        case "permission-resolved":
+          flushBuffers(sessionId, state);
+          writeRecord(sessionId, state, {
+            kind: "permission-resolved",
+            sessionId,
+            toolCallId: evt.toolCallId,
+            decision: evt.decision,
+            ...evt.optionId ? { optionId: evt.optionId } : {}
+          });
+          break;
         case "turn-end":
           flushBuffers(sessionId, state);
           writeRecord(sessionId, state, { kind: "turn-end", sessionId, reason: evt.reason });
@@ -5115,6 +5137,14 @@ async function spawnAgentSession(deps2, input) {
       };
     });
   }
+  if (mcpServers === void 0 && parentSessionId && buildOrchestratorMcp && input.orchestrator !== false && input.sandbox === void 0) {
+    const injection = buildOrchestratorMcp({
+      tools: ["message_parent"],
+      role: role.name
+    });
+    mcpServers = [injection.entry];
+    bindOrchestratorLifecycle = injection.bindLifecycle;
+  }
   const spawnDefaults = resolveSpawnDefaults(configDefaults, input.adapter, {
     skills: input.skills,
     options: input.options,
@@ -5276,9 +5306,8 @@ async function spawnAgentSession(deps2, input) {
       details: { adapter: input.adapter, gateway }
     };
   }
-  let effectivePrompt = input.prompt ? `${composeRoleContext(role, input.promptAppend, roleRegistry)}
-
-${input.prompt}` : input.prompt;
+  const parentContextLine = parentSessionId ? `You were spawned by session ${parentSessionId} (also available in the ${PARENT_SESSION_ID_ENV} env var). When you finish \u2014 or hit a blocker you cannot resolve \u2014 report back to it via the message_parent tool if one is available (no session id needed; the daemon resolves your parent).` : void 0;
+  let effectivePrompt = input.prompt ? [composeRoleContext(role, input.promptAppend, roleRegistry), parentContextLine, input.prompt].filter((p) => !!p).join("\n\n") : input.prompt;
   const explicitTitle = input.title?.trim() ? input.title.trim() : void 0;
   const spawnLabel = input.label?.trim() ? input.label.trim() : void 0;
   const initialTitle = explicitTitle ?? spawnLabel ?? (input.prompt ? deriveSessionTitle(input.prompt) : void 0);
@@ -5535,7 +5564,12 @@ ${asyncPrompt}`;
         // collide with, so this is the entire env for this spawn.
         env: {
           [SESSION_ID_ENV]: mintedSessionId,
-          [WORKSPACE_SLUG_ENV]: resolvedSlug
+          [WORKSPACE_SLUG_ENV]: resolvedSlug,
+          // Lineage (PARENT_SESSION_ID_ENV's doc, sessions.ts) — mirrors
+          // the descriptor's `parentSessionId` so the child can discover
+          // who spawned it without a registry round-trip. Absent on a
+          // parentless root spawn.
+          ...parentSessionId ? { [PARENT_SESSION_ID_ENV]: parentSessionId } : {}
         },
         onActivity: () => {
           if (liveSessionId) registry.pulseActivity(liveSessionId);
@@ -6720,8 +6754,8 @@ function composeSessionObservers(observers) {
     );
   };
   return {
-    recordPrompt(sessionId, message) {
-      forEachSafe((o) => o.recordPrompt(sessionId, message));
+    recordPrompt(sessionId, message, opts) {
+      forEachSafe((o) => o.recordPrompt(sessionId, message, opts));
     },
     recordEvent(sessionId, evt) {
       forEachSafe((o) => o.recordEvent(sessionId, evt));
@@ -6739,10 +6773,10 @@ function composeSessionObservers(observers) {
 }
 function filterSessionObserver(inner, shouldObserve) {
   return {
-    recordPrompt(sessionId, message) {
+    recordPrompt(sessionId, message, opts) {
       if (!shouldObserve(sessionId)) return;
       try {
-        inner.recordPrompt(sessionId, message);
+        inner.recordPrompt(sessionId, message, opts);
       } catch {
       }
     },
@@ -7445,6 +7479,7 @@ function mintSessionId() {
 }
 var SESSION_ID_ENV = "AGENTPROTO_SESSION_ID";
 var WORKSPACE_SLUG_ENV = "AGENTPROTO_WORKSPACE_SLUG";
+var PARENT_SESSION_ID_ENV = "AGENTPROTO_PARENT_SESSION_ID";
 var SessionNotAliveError = class extends Error {
   sessionId;
   status;
@@ -7747,6 +7782,11 @@ function createSessionsRegistry(opts) {
           ts: (/* @__PURE__ */ new Date()).toISOString()
         });
       }
+      transcriptWriter.recordEvent(rt.desc.id, {
+        kind: "permission-resolved",
+        toolCallId: id,
+        decision: "cancelled"
+      });
     }
     delete rt.desc.awaitingPermission;
   };
@@ -7802,6 +7842,12 @@ function createSessionsRegistry(opts) {
         ts: (/* @__PURE__ */ new Date()).toISOString()
       });
     }
+    transcriptWriter.recordEvent(pending.sessionId, {
+      kind: "permission-resolved",
+      toolCallId: id,
+      decision: input.decision,
+      ...chosenOptionId ? { optionId: chosenOptionId } : {}
+    });
     schedulePersist();
     if (!okResolved) {
       return { ok: true, permission: pending, decision: input.decision, ...chosenOptionId ? { optionId: chosenOptionId } : {} };
@@ -8434,7 +8480,7 @@ function createSessionsRegistry(opts) {
         return;
     }
   }
-  const runAgentTurn = async (rt, message) => {
+  const runAgentTurn = async (rt, message, turnOpts) => {
     if (!rt.agentSession) {
       throw new Error("runAgentTurn: session has no agentSession");
     }
@@ -8470,7 +8516,11 @@ ${message}`;
         `\x1B[2m\u2500\u2500 \u25B6 ${typeof message === "string" ? message : JSON.stringify(message)} \u2500\u2500\x1B[0m`,
         "stdout"
       );
-      transcriptWriter.recordPrompt(rt.desc.id, message);
+      transcriptWriter.recordPrompt(
+        rt.desc.id,
+        message,
+        turnOpts?.promptSource ? { source: turnOpts.promptSource } : void 0
+      );
       const wrapped = typeof message === "string" ? { type: "text", text: message } : message;
       for await (const evt of rt.agentSession.send(wrapped)) {
         transcriptWriter.recordEvent(rt.desc.id, evt);
@@ -8881,7 +8931,11 @@ ${message}`;
       schedulePersist();
       recordConversationLink(rt);
       if (input.initialPrompt) {
-        void runAgentTurn(rt, input.initialPrompt).catch((err) => {
+        void runAgentTurn(
+          rt,
+          input.initialPrompt,
+          desc.parentSessionId ? { promptSource: `agent:${desc.parentSessionId}` } : void 0
+        ).catch((err) => {
           appendLine(
             rt,
             `[turn error] ${err instanceof Error ? err.message : String(err)}`,
@@ -9009,7 +9063,11 @@ ${message}`;
       schedulePersist();
       recordConversationLink(rt);
       if (outcome.initialPrompt) {
-        void runAgentTurn(rt, outcome.initialPrompt).catch((err) => {
+        void runAgentTurn(
+          rt,
+          outcome.initialPrompt,
+          rt.desc.parentSessionId ? { promptSource: `agent:${rt.desc.parentSessionId}` } : void 0
+        ).catch((err) => {
           appendLine(
             rt,
             `[turn error] ${err instanceof Error ? err.message : String(err)}`,
@@ -9267,7 +9325,7 @@ ${message}`;
       }
       if (rtPre) await maybeResumeAgent(rtPre);
       const rt = validateAgentTurn(id, "sendPrompt");
-      await runAgentTurn(rt, message);
+      await runAgentTurn(rt, message, opts2?.source ? { promptSource: opts2.source } : void 0);
     },
     async enqueuePrompt(id, message, opts2) {
       const rtPre = sessions.get(id);
@@ -9279,7 +9337,7 @@ ${message}`;
       }
       await maybeResumeAgent(rtPre);
       const rt = validateAgentTurn(id, "enqueuePrompt");
-      void runAgentTurn(rt, message).catch((err) => {
+      void runAgentTurn(rt, message, opts2?.source ? { promptSource: opts2.source } : void 0).catch((err) => {
         appendLine(
           rtPre,
           `[error] ${err instanceof Error ? err.message : String(err)}`,
@@ -10706,12 +10764,17 @@ function registerFsTools(server, opts) {
   const anchor = makeAnchor(opts.workspace);
   server.tool(
     "file_read",
-    "Read a UTF-8 file from the workspace.",
-    { path: z.string().describe("Workspace-relative path to the file.") },
-    async ({ path }) => {
+    `Read a file from the workspace. Defaults to UTF-8 text; pass encoding: "base64" for binary files (images, audio, video, \u2026) \u2014 UTF-8 decoding a non-text file replaces invalid byte sequences (e.g. a PNG's 0x89 header byte) with U+FFFD, corrupting the content.`,
+    {
+      path: z.string().describe("Workspace-relative path to the file."),
+      encoding: z.enum(["utf8", "base64"]).optional().describe(
+        '"utf8" (default) for text files, "base64" for binary files.'
+      )
+    },
+    async ({ path, encoding }) => {
       const abs = anchor(path);
       const buf = await readFile(abs);
-      return text(buf.toString("utf8"));
+      return text(buf.toString(encoding === "base64" ? "base64" : "utf8"));
     }
   );
   server.tool(
@@ -11287,8 +11350,10 @@ function registerAgentTools(server, opts) {
       const sessionId = resolveSessionIdArg(input);
       if (!sessionId) return missingSessionIdError("agent_prompt");
       try {
+        const promptSource = callerScope?.ownerSessionId ?? callerSessionId;
         await registry.enqueuePrompt(sessionId, input.prompt, {
-          interrupt: input.interrupt
+          interrupt: input.interrupt,
+          ...promptSource ? { source: `agent:${promptSource}` } : {}
         });
         return {
           content: [
@@ -11315,6 +11380,67 @@ function registerAgentTools(server, opts) {
       }
     }
   );
+  server.tool(
+    "message_parent",
+    "Report a message UP to the session that spawned you (your parent/supervisor) \u2014 a result, a progress update, or a blocker. No session id needed: the daemon resolves your recorded parent from your own session identity (also visible as the AGENTPROTO_PARENT_SESSION_ID env var). Delivered as a prompt when the parent is idle, or queued onto its next turn when it's mid-turn (never interrupts). Errors if this session has no recorded parent or the parent is gone.",
+    {
+      message: z.string().min(1).describe("The message to deliver to your parent session (plain text).")
+    },
+    async (input) => {
+      const fail = (text9) => ({
+        content: [{ type: "text", text: text9 }],
+        isError: true
+      });
+      const selfId = callerScope?.ownerSessionId ?? callerSessionId;
+      if (!selfId) {
+        return fail(
+          "message_parent: cannot identify the calling session \u2014 this tool needs gateway access attributed to a session (a scoped orchestrator gateway, or a daemon `/mcp` URL carrying `?callerSessionId=`). A human/root caller has no parent to message."
+        );
+      }
+      const self = registry.get(selfId);
+      if (!self) {
+        return fail(`message_parent: calling session "${selfId}" is not in the registry.`);
+      }
+      const parentId = self.parentSessionId;
+      if (!parentId || parentId === selfId) {
+        return fail(
+          "message_parent: this session has no recorded parent \u2014 it was spawned at the root, so there is no one to report up to."
+        );
+      }
+      const parent = registry.get(parentId);
+      if (!parent) {
+        return fail(`message_parent: parent session "${parentId}" no longer exists.`);
+      }
+      if (parent.status !== "running" && parent.status !== "starting") {
+        return fail(
+          `message_parent: parent session "${parentId}" is not running (status: ${parent.status}) \u2014 the message cannot be delivered.`
+        );
+      }
+      const who = self.label ?? selfId;
+      const notice = `[child-message] ${who} (${selfId}): ${input.message}`;
+      const done = (delivery) => ({
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ ok: true, parentSessionId: parentId, delivery }, null, 2)
+          }
+        ]
+      });
+      if (!parent.busy) {
+        try {
+          await registry.enqueuePrompt(parentId, notice, {});
+          return done("enqueued");
+        } catch {
+        }
+      }
+      if (!registry.stampPendingChildCrashNotice(parentId, notice)) {
+        return fail(
+          `message_parent: parent session "${parentId}" vanished mid-delivery.`
+        );
+      }
+      return done("queued-next-turn");
+    }
+  );
   server.tool(
     "agent_output",
     "Tail the recent output of a session. Returns the last N lines of the ring buffer (stdout + stderr inter-leaved, newest last). Use this to read an agent's reply after `agent_prompt`.",
@@ -21944,6 +22070,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 +24290,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 +25508,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 +26200,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 +26220,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 +26417,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 +26495,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 +26610,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 +26619,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 +26696,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 +26747,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 +26808,8 @@ function createWorkflowRunner(opts) {
         abort.signal,
         cache,
         args.cacheKey,
-        args.input
+        args.input,
+        persist
       ).then(() => {
         persist();
       });
@@ -26620,7 +27442,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 +27500,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,84 +27945,16 @@ 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",
   "agent_output",
   "agent_kill",
+  // Child→parent report-back. NOT a delegation tool (takes no session id;
+  // the daemon resolves the caller's own recorded parent, and it can reach
+  // nothing else) — it's also the sole tool of the minimal report-only
+  // scope `session-spawn.ts` mints for a gateway-less child with a parent.
+  "message_parent",
   "session_monitor",
   "session_events_poll",
   "session_list",
@@ -30776,6 +31530,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 +31550,7 @@ async function createGateway(opts) {
     cronScheduler,
     dispatchTool
   });
+  const appRegistry = createAppRegistry();
   const workflowRunner = opts.resolveAgentAdapter ? createWorkflowRunner({
     registry: sessions,
     sessionEvents,
@@ -30805,7 +31567,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 +31749,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 +31853,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 +31917,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