@agentproto/runtime 2.2.0 → 2.3.0

package/README.md

@@ -42,6 +42,7 @@ A per-boot bearer token is generated automatically and written into `<workspace>
 | MCP               | `POST /mcp` (Streamable HTTP)            | Stateless mode; per-request transport                  |
 | Conversations     | `GET /conversations` / `GET /conversations/<id>` | Markdown bodies                                |
 | Adapter discovery | `GET /adapters` / `POST /adapters/:slug/install` | When `listAgentAdapters` / `installAgentAdapter` is wired |
+| App scope mounts   | `POST /apps/:appId/apply` / `DELETE /apps/:appId/apply` / `GET /scopes/:scopeId/apps` | Mirrors MCP `app_apply` / `app_unapply` / `app_list_applied`; needs `appRegistry` |
 | Sessions list     | `GET /sessions` / `GET /sessions/:id` / `GET /sessions/summaries` | id-or-name in `:id`; summaries are lightweight + paginated |
 | Agent spawn       | `POST /sessions/agent`                   | Long-lived ACP agent (needs `resolveAgentAdapter`)    |
 | Interrupt turn    | `POST /sessions/:id/interrupt`           | Cancel the in-flight turn; session stays alive        |

package/dist/index.d.ts

@@ -3753,8 +3753,14 @@ interface AuthOptions {
  */
 
 interface SessionObserver {
-    /** Record the outgoing message that opens a new turn. */
-    recordPrompt(sessionId: string, message: unknown): void;
+    /** Record the outgoing message that opens a new turn. `opts.source`, when
+     *  set, is the prompt's provenance — `agent:<sessionId>` for a prompt
+     *  injected by another session (`agent_prompt` from a supervisor), absent
+     *  for a human operator — so a transcript view can attribute the turn to
+     *  its real author instead of "you". */
+    recordPrompt(sessionId: string, message: unknown, opts?: {
+        source?: string;
+    }): void;
     /** Record one structured stream event (text-delta, tool-call, usage_update, …). */
     recordEvent(sessionId: string, evt: AgentStreamEvent): void;
     /** Record the durable turn-boundary / exit usage snapshot. */
@@ -3995,6 +4001,16 @@ interface AgentStreamEvent {
      *  but no `cost`). */
     tokensIn?: number;
     tokensOut?: number;
+    /** "permission-resolved" outcome for the "agent-prompt" it answers (same
+     *  `toolCallId`) — mirrors `session:permission-resolved`'s `decision` so
+     *  the durable transcript can tell an answered ask from a still-pending
+     *  one. Not an ACP `StreamEvent` kind (synthesized by the registry, same
+     *  as "notice"/"turn-end" synthetics) — see registerPendingPermission's
+     *  docblock for the "agent-prompt" ask this resolves. */
+    decision?: "approve" | "deny" | "cancelled";
+    /** "permission-resolved" chosen option id, when the driver's offered
+     *  options included one (e.g. ACP's `allow_always`). */
+    optionId?: string;
 }
 /**
  * Env vars the registry injects into every process it spawns on a session's
@@ -4019,6 +4035,14 @@ interface AgentStreamEvent {
  * assign-last rule is what makes that true by construction rather than by
  * accident, and is what guarantees a child spawned from inside a session
  * gets its OWN id rather than inheriting its parent's.
+ *
+ * `PARENT_SESSION_ID_ENV` is the third var, injected by `session-spawn.ts`
+ * only (agent spawns, and only when the spawn resolved a parent): the
+ * recorded `parentSessionId` lineage, so a child agent can know WHO spawned
+ * it without a registry round-trip — the discovery half of the child→parent
+ * report-back channel (`message_parent` is the delivery half). Same
+ * assign-last/no-forgery rule as the other two: it mirrors the descriptor's
+ * own `parentSessionId` field, never anything caller- or env-inherited.
  */
 declare const SESSION_ID_ENV = "AGENTPROTO_SESSION_ID";
 declare const WORKSPACE_SLUG_ENV = "AGENTPROTO_WORKSPACE_SLUG";
@@ -4943,6 +4967,7 @@ interface SessionsRegistry {
      *  the previous mid-turn rejection byte-for-byte. */
     sendPrompt(id: string, message: unknown, opts?: {
         interrupt?: boolean;
+        source?: string;
     }): Promise<void>;
     /** Fire-and-forget variant of `sendPrompt` for the TURN ITSELF only.
      *  Admission (resume attempt + the missing/wrong-kind/dead/busy
@@ -4962,8 +4987,12 @@ interface SessionsRegistry {
      *  prompt is admitted + fired on the SAME live session. Ignored
      *  (identical to the default) when the session is idle. Omitted or
      *  `false` reproduces today's mid-turn rejection byte-for-byte. */
+    /** `opts.source` on either prompt verb is the turn's provenance
+     *  (`agent:<sessionId>` when another session injected it — see
+     *  `SessionObserver.recordPrompt`); recording-only, never behavioral. */
     enqueuePrompt(id: string, message: unknown, opts?: {
         interrupt?: boolean;
+        source?: string;
     }): Promise<void>;
     /** Eagerly resume ONE dead-but-resumable agent-cli session IN PLACE,
      *  WITHOUT a prompt — the boot-time counterpart to the lazy resume that

package/dist/index.mjs

@@ -310,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);
@@ -404,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 });
@@ -5116,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,
@@ -5277,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);
@@ -5536,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);
@@ -6721,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));
@@ -6740,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 {
       }
     },
@@ -7446,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;
@@ -7748,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;
   };
@@ -7803,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 } : {} };
@@ -8435,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");
     }
@@ -8471,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);
@@ -8882,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)}`,
@@ -9010,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)}`,
@@ -9268,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);
@@ -9280,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)}`,
@@ -10707,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(
@@ -11288,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: [
@@ -11316,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`.",
@@ -27825,6 +27950,11 @@ var DEFAULT_ORCHESTRATOR_TOOLS = [
   "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",