docs: document embedded agent barrels

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";
 

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();

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,