diff --git a/src/agents/embedded-agent-subscribe.handlers.types.ts b/src/agents/embedded-agent-subscribe.handlers.types.ts
index 170b027d9011..2ff28556c313 100644
--- a/src/agents/embedded-agent-subscribe.handlers.types.ts
+++ b/src/agents/embedded-agent-subscribe.handlers.types.ts
@@ -1,3 +1,8 @@
+/**
+ * Shared state and context contracts for embedded-agent subscription handlers.
+ * Message, tool, compaction, and liveness handlers all mutate this single
+ * state shape while keeping their implementation files decoupled.
+ */
 import type { InlineCodeState } from "../../packages/markdown-core/src/code-spans.js";
 import type { FenceScanState } from "../../packages/markdown-core/src/fences.js";
 import type { HeartbeatToolResponse } from "../auto-reply/heartbeat-tool-response.js";
@@ -35,6 +40,7 @@ type EmbeddedSubscribeLogger = {
   warn: (message: string, meta?: Record<string, unknown>) => void;
 };
 
+/** Per-tool metadata tracked between tool start/update/end events. */
 export type ToolCallSummary = {
   meta?: string;
   mutatingAction: boolean;
@@ -42,6 +48,7 @@ export type ToolCallSummary = {
   fileTarget?: import("./tool-mutation.js").FileTarget;
 };
 
+/** User-visible assistant stream payload emitted to subscribers. */
 export type AssistantStreamData = {
   text: string;
   delta: string;
@@ -50,11 +57,13 @@ export type AssistantStreamData = {
   phase?: AssistantPhase;
 };
 
+/** Deferred assistant stream event plus whether it should emit partial replies. */
 export type AssistantStreamDelivery = {
   data: AssistantStreamData;
   emitPartialReply: boolean;
 };
 
+/** Mutable subscription state shared by embedded-agent event handlers. */
 export type EmbeddedAgentSubscribeState = {
   assistantTexts: string[];
   toolMetas: Array<{
@@ -168,6 +177,7 @@ export type EmbeddedAgentSubscribeState = {
   lastAssistant?: AgentMessage;
 };
 
+/** Handler context bundling params, mutable state, emitters, and helper hooks. */
 export type EmbeddedAgentSubscribeContext = {
   params: SubscribeEmbeddedAgentSessionParams;
   state: EmbeddedAgentSubscribeState;
diff --git a/src/agents/models-config.providers.policy.runtime.ts b/src/agents/models-config.providers.policy.runtime.ts
index b08e4f1dac58..e4783f8959aa 100644
--- a/src/agents/models-config.providers.policy.runtime.ts
+++ b/src/agents/models-config.providers.policy.runtime.ts
@@ -1,3 +1,7 @@
+/**
+ * Runtime-policy bridge for provider config normalization. These helpers call
+ * plugin hooks without triggering runtime plugin loading from config assembly.
+ */
 import {
   applyProviderNativeStreamingUsageCompatWithPlugin,
   normalizeProviderConfigWithPlugin,
@@ -6,8 +10,6 @@ import {
 import { resolveProviderPluginLookupKey } from "./models-config.providers.policy.lookup.js";
 import type { ProviderConfig } from "./models-config.providers.secrets.js";
 
-// Runtime-policy bridge for provider config normalization. These helpers call
-// plugin hooks without triggering runtime plugin loading from config assembly.
 /** Apply provider native-streaming usage compatibility policy. */
 export function applyProviderNativeStreamingUsagePolicy(
   providerKey: string,
diff --git a/src/agents/responses-image-payload-sanitizer.ts b/src/agents/responses-image-payload-sanitizer.ts
index e1db4d24b8d0..df77d26c4c7a 100644
--- a/src/agents/responses-image-payload-sanitizer.ts
+++ b/src/agents/responses-image-payload-sanitizer.ts
@@ -1,8 +1,11 @@
+/**
+ * Sanitizes OpenAI Responses payloads before transport. Invalid inline images
+ * are replaced with text placeholders so the request remains valid and
+ * auditable.
+ */
 import { sanitizeInlineImageDataUrl as sanitizeSharedInlineImageDataUrl } from "@openclaw/media-core/inline-image-data-url";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 
-// Sanitizes OpenAI Responses payloads before transport. Invalid inline images
-// are replaced with text placeholders so the request remains valid and auditable.
 const IMAGE_OMITTED_TEXT = "omitted image payload: invalid inline image data";
 
 type JsonRecord = Record<string, unknown>;
diff --git a/src/agents/sandbox-tool-policy.ts b/src/agents/sandbox-tool-policy.ts
index 92966ee471db..4928341ca418 100644
--- a/src/agents/sandbox-tool-policy.ts
+++ b/src/agents/sandbox-tool-policy.ts
@@ -1,8 +1,11 @@
+/**
+ * Converts user-facing sandbox tool policy config into the normalized runtime
+ * allow/deny policy object used by tool filtering.
+ */
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import type { SandboxToolPolicy } from "./sandbox/types.js";
 
-// Converts user-facing sandbox tool policy config into the normalized runtime
-// allow/deny policy object used by tool filtering.
+/** Provenance marker for wildcard allowlists created from `alsoAllow`. */
 export const IMPLICIT_ALLOW_ALL_FROM_ALSO_ALLOW = Symbol.for(
   "openclaw.toolPolicy.implicitAllowAllFromAlsoAllow",
 );
@@ -32,6 +35,7 @@ function hasExplicitAllowAll(list?: string[]): boolean {
   return Array.isArray(list) && list.some((entry) => entry.trim() === "*");
 }
 
+/** Picks the effective sandbox tool policy from allow/alsoAllow/deny config. */
 export function pickSandboxToolPolicy(
   config?: SandboxToolPolicyConfig,
 ): SandboxToolPolicy | undefined {
diff --git a/src/agents/tool-policy-match.ts b/src/agents/tool-policy-match.ts
index 892b9fed1913..1ec5c41f1f33 100644
--- a/src/agents/tool-policy-match.ts
+++ b/src/agents/tool-policy-match.ts
@@ -1,9 +1,11 @@
+/**
+ * Runtime matcher for sandbox tool policies. Deny patterns always win, then
+ * an empty allow list means "allow everything not denied".
+ */
 import { compileGlobPatterns, matchesAnyGlobPattern } from "./glob-pattern.js";
 import type { SandboxToolPolicy } from "./sandbox/types.js";
 import { expandToolGroups, normalizeToolName } from "./tool-policy.js";
 
-// Runtime matcher for sandbox tool policies. Deny patterns always win, then an
-// empty allow list means "allow everything not denied".
 function makeToolPolicyMatcher(policy: SandboxToolPolicy) {
   const deny = compileGlobPatterns({
     raw: expandToolGroups(policy.deny ?? []),
diff --git a/src/agents/workspace.ts b/src/agents/workspace.ts
index 7cb8eb749017..3517b4df8ec2 100644
--- a/src/agents/workspace.ts
+++ b/src/agents/workspace.ts
@@ -1,3 +1,8 @@
+/**
+ * Workspace bootstrap, template, state, and attestation helpers. This module
+ * creates and reads AGENTS/SOUL/TOOLS-style bootstrap files while guarding
+ * filesystem boundaries and recently-attested workspaces.
+ */
 import { createHash } from "node:crypto";
 import syncFs from "node:fs";
 import fs from "node:fs/promises";