From 3894fe11caa072ccbc90da354cafe97dcb075e85 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 10:08:39 -0400 Subject: [PATCH] docs: document subagent registry helpers --- src/agents/subagent-registry-read.ts | 11 +++++------ src/agents/subagent-registry-run-manager.ts | 5 +++++ src/agents/subagent-registry-state.ts | 5 +++++ src/agents/subagent-registry-steer-runtime.ts | 7 +++---- src/agents/subagent-registry.store.ts | 5 +++++ src/agents/subagent-registry.ts | 5 +++++ src/agents/subagent-registry.types.ts | 5 +++++ src/agents/subagent-requester-store-key.ts | 7 +++++-- src/agents/subagent-run-liveness.ts | 7 +++++-- src/agents/subagent-run-timeout.ts | 7 +++++-- src/agents/subagent-session-metrics.ts | 11 +++++------ src/agents/subagent-session-reconciliation.ts | 7 +++++-- src/agents/subagent-spawn-accepted-note.ts | 6 +++++- src/agents/subagent-spawn-ownership.ts | 9 +++++---- src/agents/subagent-spawn-plan.ts | 11 +++++------ src/agents/subagent-spawn.ts | 5 +++++ src/agents/subagent-system-prompt.ts | 5 +++++ src/agents/subagent-yield-output.ts | 11 +++++------ src/agents/system-prompt-cache-boundary.ts | 5 +++++ src/agents/system-prompt-params.ts | 5 +++++ src/agents/system-prompt.ts | 5 +++++ 21 files changed, 103 insertions(+), 41 deletions(-) diff --git a/src/agents/subagent-registry-read.ts b/src/agents/subagent-registry-read.ts index d554d41c65d..b8c266886a0 100644 --- a/src/agents/subagent-registry-read.ts +++ b/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, diff --git a/src/agents/subagent-registry-run-manager.ts b/src/agents/subagent-registry-run-manager.ts index f22da824fdd..ced5ff4ede2 100644 --- a/src/agents/subagent-registry-run-manager.ts +++ b/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"; diff --git a/src/agents/subagent-registry-state.ts b/src/agents/subagent-registry-state.ts index f6da7dc238f..ab49f8943f7 100644 --- a/src/agents/subagent-registry-state.ts +++ b/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, diff --git a/src/agents/subagent-registry-steer-runtime.ts b/src/agents/subagent-registry-steer-runtime.ts index eff383a7694..705abf29f9d 100644 --- a/src/agents/subagent-registry-steer-runtime.ts +++ b/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; diff --git a/src/agents/subagent-registry.store.ts b/src/agents/subagent-registry.store.ts index fce9e7a31c8..ed99ca2f766 100644 --- a/src/agents/subagent-registry.store.ts +++ b/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"; diff --git a/src/agents/subagent-registry.ts b/src/agents/subagent-registry.ts index d9c5a9ff706..78a4a239622 100644 --- a/src/agents/subagent-registry.ts +++ b/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"; diff --git a/src/agents/subagent-registry.types.ts b/src/agents/subagent-registry.types.ts index 20a9f398c7b..317cc1832b9 100644 --- a/src/agents/subagent-registry.types.ts +++ b/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"; diff --git a/src/agents/subagent-requester-store-key.ts b/src/agents/subagent-requester-store-key.ts index a21933a8313..8795c9b2636 100644 --- a/src/agents/subagent-requester-store-key.ts +++ b/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 }> }; diff --git a/src/agents/subagent-run-liveness.ts b/src/agents/subagent-run-liveness.ts index d0eff2dc77b..42450439277 100644 --- a/src/agents/subagent-run-liveness.ts +++ b/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; diff --git a/src/agents/subagent-run-timeout.ts b/src/agents/subagent-run-timeout.ts index 93b8a749923..4ea982b8376 100644 --- a/src/agents/subagent-run-timeout.ts +++ b/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 }); diff --git a/src/agents/subagent-session-metrics.ts b/src/agents/subagent-session-metrics.ts index d4ff2584677..e7c1cf9b768 100644 --- a/src/agents/subagent-session-metrics.ts +++ b/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, ): number | undefined { diff --git a/src/agents/subagent-session-reconciliation.ts b/src/agents/subagent-session-reconciliation.ts index 98d796e39d0..a44ecb7ab39 100644 --- a/src/agents/subagent-session-reconciliation.ts +++ b/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>; /** Completion inferred from the child session store. */ diff --git a/src/agents/subagent-spawn-accepted-note.ts b/src/agents/subagent-spawn-accepted-note.ts index bf09a14d377..55fcdd61d83 100644 --- a/src/agents/subagent-spawn-accepted-note.ts +++ b/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 = diff --git a/src/agents/subagent-spawn-ownership.ts b/src/agents/subagent-spawn-ownership.ts index 748700c4c42..05db04bafdd 100644 --- a/src/agents/subagent-spawn-ownership.ts +++ b/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; diff --git a/src/agents/subagent-spawn-plan.ts b/src/agents/subagent-spawn-plan.ts index 0f57b2d2bb8..06e402c4c07 100644 --- a/src/agents/subagent-spawn-plan.ts +++ b/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) { diff --git a/src/agents/subagent-spawn.ts b/src/agents/subagent-spawn.ts index 72ee94184b6..ec521306a05 100644 --- a/src/agents/subagent-spawn.ts +++ b/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"; diff --git a/src/agents/subagent-system-prompt.ts b/src/agents/subagent-system-prompt.ts index 945dd2a4920..2ef341b1d15 100644 --- a/src/agents/subagent-system-prompt.ts +++ b/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"; diff --git a/src/agents/subagent-yield-output.ts b/src/agents/subagent-yield-output.ts index 446ff49af6d..99045eb7c51 100644 --- a/src/agents/subagent-yield-output.ts +++ b/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) { diff --git a/src/agents/system-prompt-cache-boundary.ts b/src/agents/system-prompt-cache-boundary.ts index 6026b864589..06c805f5816 100644 --- a/src/agents/system-prompt-cache-boundary.ts +++ b/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\n"; diff --git a/src/agents/system-prompt-params.ts b/src/agents/system-prompt-params.ts index 2ad5c98c971..9b5556610a0 100644 --- a/src/agents/system-prompt-params.ts +++ b/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"; diff --git a/src/agents/system-prompt.ts b/src/agents/system-prompt.ts index 36090b82853..706eb3d27b9 100644 --- a/src/agents/system-prompt.ts +++ b/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,