diff --git a/src/agents/embedded-agent-runner.ts b/src/agents/embedded-agent-runner.ts
index f0ad045de2e..ecc62ba93bd 100644
--- a/src/agents/embedded-agent-runner.ts
+++ b/src/agents/embedded-agent-runner.ts
@@ -1,3 +1,5 @@
+// Embedded-agent runner barrel. Focused submodules own run orchestration,
+// compaction, queues, sandbox metadata, and SDK tool splitting.
 export { compactEmbeddedAgentSession } from "./embedded-agent-runner/compact.queued.js";
 export { applyExtraParamsToAgent } from "./embedded-agent-runner/extra-params.js";
 
diff --git a/src/agents/embedded-agent-subscribe.handlers.ts b/src/agents/embedded-agent-subscribe.handlers.ts
index 7b09a4ad530..d5b8e1b6e07 100644
--- a/src/agents/embedded-agent-subscribe.handlers.ts
+++ b/src/agents/embedded-agent-subscribe.handlers.ts
@@ -20,12 +20,15 @@ import type {
 } from "./embedded-agent-subscribe.handlers.types.js";
 import { isPromiseLike } from "./embedded-agent-subscribe.promise.js";
 
+/** Create the serialized event dispatcher for subscribed embedded-agent sessions. */
 export function createEmbeddedAgentSessionEventHandler(ctx: EmbeddedAgentSubscribeContext) {
   const scheduleEvent = (
     evt: EmbeddedAgentSubscribeEvent,
     handler: () => void | Promise<void>,
     options?: { detach?: boolean },
   ): void => {
+    // Most stream events must preserve order across async formatting and flush
+    // work. A detached event may run after the chain without blocking delivery.
     const run = () => {
       try {
         return handler();
diff --git a/src/agents/embedded-agent.ts b/src/agents/embedded-agent.ts
index bd877010799..65aa6972aa4 100644
--- a/src/agents/embedded-agent.ts
+++ b/src/agents/embedded-agent.ts
@@ -1,3 +1,5 @@
+// Public embedded-agent barrel. Re-export the runner API used by gateway,
+// command, and plugin surfaces without exposing internal runner file layout.
 export type {
   EmbeddedAgentCompactResult,
   EmbeddedAgentMeta,