docs: document subagent registry helpers

src/agents/subagent-registry-read.ts

@@ -1,3 +1,8 @@
+/**
+ * Read-only subagent registry accessors.
+ *
+ * Combines persisted snapshots with in-memory live runs for UI, announce, control, and recovery paths.
+ */
 import { getAgentRunContext } from "../infra/agent-events.js";
 import { subagentRuns } from "./subagent-registry-memory.js";
 import {
@@ -11,12 +16,6 @@ import {
 import { getSubagentRunsSnapshotForRead } from "./subagent-registry-state.js";
 import type { SubagentRunRecord } from "./subagent-registry.types.js";
 
-/**
- * Read-only accessors over subagent run state.
- *
- * Helpers combine persisted snapshots with in-memory live runs so UI, announce,
- * and control paths see recovered plus currently executing sessions consistently.
- */
 export {
   getSubagentSessionRuntimeMs,
   getSubagentSessionStartedAt,

src/agents/subagent-registry-run-manager.ts

@@ -1,3 +1,8 @@
+/**
+ * Subagent run manager.
+ *
+ * Waits for child runs, records terminal outcomes, creates task-runtime entries, and archives completed sessions.
+ */
 import { getRuntimeConfig } from "../config/config.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { callGateway } from "../gateway/call.js";

src/agents/subagent-registry-state.ts

@@ -1,3 +1,8 @@
+/**
+ * Subagent registry state persistence bridge.
+ *
+ * Merges process-local active runs with persisted SQLite state for cross-process readers.
+ */
 import {
   loadSubagentRegistryFromSqlite,
   saveSubagentRegistryToSqlite,

src/agents/subagent-registry-steer-runtime.ts

@@ -1,11 +1,10 @@
-import type { SubagentRunRecord } from "./subagent-registry.types.js";
-
 /**
  * Late-bound steer hooks for the subagent registry.
  *
- * Control/recovery code can depend on this small module while the full registry
- * installs the concrete mutation functions during startup.
+ * Lets steer/recovery code depend on a small module while the full registry installs concrete mutation hooks.
  */
+import type { SubagentRunRecord } from "./subagent-registry.types.js";
+
 type ReplaceSubagentRunAfterSteerParams = {
   previousRunId: string;
   nextRunId: string;

src/agents/subagent-registry.store.ts

@@ -1,3 +1,8 @@
+/**
+ * JSON-backed subagent registry store.
+ *
+ * Loads and saves persisted subagent run records with legacy migration and bounded read caching.
+ */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

src/agents/subagent-registry.ts

@@ -1,3 +1,8 @@
+/**
+ * Subagent registry coordinator.
+ *
+ * Owns registration, lifecycle, delivery retry, steering, orphan recovery, persistence, and cleanup for child runs.
+ */
 import type { cleanupBrowserSessionsForLifecycleEnd } from "../browser-lifecycle-cleanup.js";
 import { getRuntimeConfig } from "../config/config.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";

src/agents/subagent-registry.types.ts

@@ -1,3 +1,8 @@
+/**
+ * Subagent registry record types.
+ *
+ * Defines execution, completion, delivery, pending-delivery, and attachment state stored for child runs.
+ */
 import type { DeliveryContext } from "../utils/delivery-context.types.js";
 import type { SubagentRunOutcome } from "./subagent-announce-output.js";
 import type { SubagentLifecycleEndedReason } from "./subagent-lifecycle-events.js";

src/agents/subagent-requester-store-key.ts

@@ -1,11 +1,14 @@
+/**
+ * Subagent requester store-key normalization.
+ *
+ * Converts raw requester session keys into the canonical registry key shape.
+ */
 import {
   resolveAgentIdFromSessionKey,
   resolveMainSessionKey,
 } from "../config/sessions/main-session.js";
 import { normalizeMainKey } from "../routing/session-key.js";
 
-// Normalizes requester session keys to the store key shape used by subagent
-// registry records.
 type RequesterStoreKeyConfig = {
   session?: { mainKey?: string };
   agents?: { list?: Array<{ id?: string; default?: boolean }> };

src/agents/subagent-run-liveness.ts

@@ -1,9 +1,12 @@
+/**
+ * Subagent run liveness policy.
+ *
+ * Ages out stale unended runs while keeping recent/composed child links visible.
+ */
 import type { SubagentRunRecord } from "./subagent-registry.types.js";
 import { resolveSubagentRunDurationMs } from "./subagent-run-timeout.js";
 import { getSubagentSessionStartedAt } from "./subagent-session-metrics.js";
 
-// Liveness policy for subagent registry records. Unended runs age out after a
-// conservative cutoff, while recent/composed child links remain visible.
 export const STALE_UNENDED_SUBAGENT_RUN_MS = 2 * 60 * 60 * 1_000;
 export const RECENT_ENDED_SUBAGENT_CHILD_SESSION_MS = 30 * 60 * 1_000;
 const EXPLICIT_TIMEOUT_STALE_GRACE_MS = 60_000;

src/agents/subagent-run-timeout.ts

@@ -1,11 +1,14 @@
+/**
+ * Subagent run timeout math.
+ *
+ * Separates timer-safe delays from duration/deadline values because setTimeout has stricter bounds.
+ */
 import {
   asDateTimestampMs,
   finiteSecondsToTimerSafeMilliseconds,
 } from "../shared/number-coercion.js";
 import type { SubagentRunRecord } from "./subagent-registry.types.js";
 
-// Shared subagent timeout math. Timer delays and duration/deadline values are
-// resolved separately because setTimeout has stricter safe bounds.
 /** Convert subagent timeout seconds to a timer-safe delay. */
 export function resolveSubagentRunTimerDelayMs(timeoutSeconds: unknown): number | undefined {
   return finiteSecondsToTimerSafeMilliseconds(timeoutSeconds, { floorSeconds: true });

src/agents/subagent-session-metrics.ts

@@ -1,12 +1,11 @@
+/**
+ * Subagent session metric helpers.
+ *
+ * Derives display/runtime status from partial live, archived, or recovered registry records.
+ */
 import { SUBAGENT_ENDED_REASON_KILLED } from "./subagent-lifecycle-events.js";
 import type { SubagentRunRecord } from "./subagent-registry.types.js";
 
-/**
- * Derives display/runtime metrics from persisted subagent run records.
- *
- * These helpers tolerate partial records because registry views can include
- * archived, live, or recovered sessions with different timestamp coverage.
- */
 function resolveSubagentSessionStartedAtInternal(
   entry: Pick<SubagentRunRecord, "sessionStartedAt" | "startedAt" | "createdAt">,
 ): number | undefined {

src/agents/subagent-session-reconciliation.ts

@@ -1,3 +1,8 @@
+/**
+ * Subagent session-store reconciliation.
+ *
+ * Infers child completion from persisted session entries when registry updates arrive late.
+ */
 import { asFiniteNumber } from "@openclaw/normalization-core/number-coercion";
 import { getRuntimeConfig } from "../config/config.js";
 import {
@@ -15,8 +20,6 @@ import {
   type SubagentLifecycleEndedReason,
 } from "./subagent-lifecycle-events.js";
 
-// Reconcile subagent lifecycle events with persisted session store state. This
-// lets parent sessions announce completion even if registry updates arrive late.
 export type SubagentSessionStoreCache = Map<string, Record<string, SessionEntry>>;
 
 /** Completion inferred from the child session store. */

src/agents/subagent-spawn-accepted-note.ts

@@ -1,6 +1,10 @@
+/**
+ * Post-spawn guidance notes.
+ *
+ * Returns push-based completion guidance for run spawns and thread-binding guidance for session spawns.
+ */
 import { isCronSessionKey } from "../routing/session-key.js";
 
-// Prompt notes returned after sessions_spawn accepts work.
 export const SUBAGENT_SPAWN_ACCEPTED_NOTE =
   "Auto-announce is push-based. After spawning children, do NOT call sessions_list, sessions_history, exec sleep, or any polling tool. Track expected child session keys. Continue any independent work. If your final answer depends on child output, wait for runtime completion events to arrive as user messages and only answer after completion events for ALL required children arrive. If a child completion event arrives AFTER your final answer, reply ONLY with NO_REPLY.";
 export const SUBAGENT_SPAWN_SESSION_ACCEPTED_NOTE =

src/agents/subagent-spawn-ownership.ts

@@ -1,3 +1,8 @@
+/**
+ * Subagent spawn ownership resolver.
+ *
+ * Resolves which session controls spawn state, thread binding, and completion delivery.
+ */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
   resolveDisplaySessionKey,
@@ -5,10 +10,6 @@ import {
   resolveMainSessionAlias,
 } from "./tools/sessions-helpers.js";
 
-/**
- * Resolves which session owns subagent spawn control, thread binding, and
- * completion delivery.
- */
 export type SubagentSpawnOwnership = {
   controllerSessionKey: string;
   threadBindingRequesterSessionKey: string;

src/agents/subagent-spawn-plan.ts

@@ -1,14 +1,13 @@
+/**
+ * Subagent spawn planning helpers.
+ *
+ * Resolves model, thinking, and timeout choices before the sessions_spawn executor launches work.
+ */
 import { formatThinkingLevels } from "../auto-reply/thinking.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveSubagentSpawnModelSelection } from "./model-selection.js";
 import { resolveSubagentThinkingOverride } from "./subagent-spawn-thinking.js";
 
-/**
- * Builds the model, thinking, and timeout plan for sessions_spawn calls.
- *
- * This file keeps spawn argument normalization separate from the tool executor
- * so tests can cover policy/default resolution without launching sessions.
- */
 /** Splits a provider/model ref while preserving model-only refs. */
 export function splitModelRef(ref?: string) {
   if (!ref) {

src/agents/subagent-spawn.ts

@@ -1,3 +1,8 @@
+/**
+ * Subagent spawn executor.
+ *
+ * Validates spawn requests, prepares child sessions, stages attachments, binds delivery context, and registers runs.
+ */
 import crypto from "node:crypto";
 import { promises as fs } from "node:fs";
 import path from "node:path";

src/agents/subagent-system-prompt.ts

@@ -1,3 +1,8 @@
+/**
+ * Subagent system prompt builder.
+ *
+ * Produces role, completion, delegation, ACP, and native-command guidance for spawned child sessions.
+ */
 import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import { DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH } from "../config/agent-limits.js";
 import type { DeliveryContext } from "../utils/delivery-context.types.js";

src/agents/subagent-yield-output.ts

@@ -1,11 +1,10 @@
+/**
+ * sessions_yield transcript detectors.
+ *
+ * Accepts provider-specific tool-call and tool-result shapes used by transcript repair and announce capture.
+ */
 import { asOptionalRecord } from "@openclaw/normalization-core/record-coerce";
 
-/**
- * Detects sessions_yield calls and yielded tool results in provider transcript shapes.
- *
- * Providers encode tool calls/results differently, so this module accepts the
- * common OpenAI/Anthropic/function-call variants used by transcript repair.
- */
 function readToolName(value: unknown): string | undefined {
   const record = asOptionalRecord(value);
   if (!record) {

src/agents/system-prompt-cache-boundary.ts

@@ -1,3 +1,8 @@
+/**
+ * System prompt cache-boundary helpers.
+ *
+ * Keeps stable prompt prefixes separate from dynamic runtime additions for provider prompt caching.
+ */
 import { normalizeStructuredPromptSection } from "./prompt-cache-stability.js";
 
 export const SYSTEM_PROMPT_CACHE_BOUNDARY = "\n<!-- OPENCLAW_CACHE_BOUNDARY -->\n";

src/agents/system-prompt-params.ts

@@ -1,3 +1,8 @@
+/**
+ * System prompt runtime parameter resolver.
+ *
+ * Collects repository, time, timezone, channel, shell, and active-process facts for prompt rendering.
+ */
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";

src/agents/system-prompt.ts

@@ -1,3 +1,8 @@
+/**
+ * OpenClaw system prompt renderer.
+ *
+ * Assembles runtime, workspace, tooling, memory, delegation, channel, and cache-boundary prompt sections.
+ */
 import { createHmac, createHash } from "node:crypto";
 import {
   normalizeLowercaseStringOrEmpty,