docs: document auto reply dispatch helpers

steipete · steipete · commit ea6d3a35ff01 · 2026-06-04T02:35:34.000-04:00
diff --git a/src/auto-reply/reply/agent-runner-cli-dispatch.ts b/src/auto-reply/reply/agent-runner-cli-dispatch.ts
@@ -1,3 +1,4 @@
+// Builds CLI runtime dispatch inputs for agent runner executions.
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import {
   normalizeLowercaseStringOrEmpty,
diff --git a/src/auto-reply/reply/agent-runner.runreplyagent.e2e.test.ts b/src/auto-reply/reply/agent-runner.runreplyagent.e2e.test.ts
@@ -1,3 +1,4 @@
+// E2E tests for run-reply-agent execution and generated session artifacts.
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
diff --git a/src/auto-reply/reply/block-reply-pipeline.ts b/src/auto-reply/reply/block-reply-pipeline.ts
@@ -1,3 +1,4 @@
+// Buffers streaming reply blocks before coalesced final delivery.
 import {
   hasOutboundReplyContent,
   resolveSendableOutboundReplyParts,
diff --git a/src/auto-reply/reply/commands-bash.ts b/src/auto-reply/reply/commands-bash.ts
@@ -1,3 +1,4 @@
+// Implements bash command execution, approval, and stop handling.
 import { resolveSessionAgentId } from "../../agents/agent-scope.js";
 import { handleBashChatCommand } from "./bash-command.js";
 import { rejectUnauthorizedCommand } from "./command-gates.js";
diff --git a/src/auto-reply/reply/commands-compact.ts b/src/auto-reply/reply/commands-compact.ts
@@ -1,3 +1,4 @@
+// Implements compaction commands for session context and model state.
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import {
   normalizeLowercaseStringOrEmpty,
diff --git a/src/auto-reply/reply/commands-context-command.ts b/src/auto-reply/reply/commands-context-command.ts
@@ -1,3 +1,4 @@
+// Implements context inspection commands for the active reply session.
 import { logVerbose } from "../../globals.js";
 import { buildContextReply } from "./commands-context-report.js";
 import type { CommandHandler } from "./commands-types.js";
diff --git a/src/auto-reply/reply/commands-export-session.ts b/src/auto-reply/reply/commands-export-session.ts
@@ -1,3 +1,4 @@
+// Builds export bundles for a session transcript and runtime context.
 import fsp from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/auto-reply/reply/commands-plugins.test.ts b/src/auto-reply/reply/commands-plugins.test.ts
@@ -1,3 +1,4 @@
+// Tests plugin command install, listing, and config behavior.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
 import { handlePluginsCommand } from "./commands-plugins.js";
diff --git a/src/auto-reply/reply/commands-session-abort.test-support.ts b/src/auto-reply/reply/commands-session-abort.test-support.ts
@@ -1,3 +1,4 @@
+// Shared mocks for session abort command tests.
 import { vi } from "vitest";
 
 vi.mock("./queue.js", async () => {
diff --git a/src/auto-reply/reply/commands-session.ts b/src/auto-reply/reply/commands-session.ts
@@ -1,3 +1,4 @@
+// Implements session commands for list, show, fork, reset, and routing state.
 import { timestampMsToIsoString } from "@openclaw/normalization-core/number-coercion";
 import {
   normalizeLowercaseStringOrEmpty,
diff --git a/src/auto-reply/reply/commands-subagents.ts b/src/auto-reply/reply/commands-subagents.ts
@@ -1,3 +1,4 @@
+// Implements subagent commands for spawn, focus, routing, and status.
 import { logVerbose } from "../../globals.js";
 import { createLazyImportLoader } from "../../shared/lazy-promise.js";
 import {
diff --git a/src/auto-reply/reply/config-commands.ts b/src/auto-reply/reply/config-commands.ts
@@ -1,3 +1,4 @@
+// Parses config command set/unset requests into typed config operations.
 import { parseStandardSetUnsetSlashCommand } from "./commands-setunset-standard.js";
 
 export type ConfigCommand =
diff --git a/src/auto-reply/reply/directive-handling.model.ts b/src/auto-reply/reply/directive-handling.model.ts
@@ -1,3 +1,4 @@
+// Handles model directives and persists provider/model selections.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
diff --git a/src/auto-reply/reply/dispatch-acp-command-bypass.test.ts b/src/auto-reply/reply/dispatch-acp-command-bypass.test.ts
@@ -1,3 +1,4 @@
+// Tests ACP command bypass detection before normal dispatch.
 import { beforeEach, describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
 import { setActivePluginRegistry } from "../../plugins/runtime.js";
diff --git a/src/auto-reply/reply/dispatch-from-config.reply-dispatch.test.ts b/src/auto-reply/reply/dispatch-from-config.reply-dispatch.test.ts
@@ -1,3 +1,4 @@
+// Tests dispatch-from-config reply dispatch integration and final payload routing.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { clearAgentHarnesses } from "../../agents/harness/registry.js";
 import type { PluginHookReplyDispatchResult } from "../../plugins/hooks.js";
diff --git a/src/auto-reply/reply/display-text-sanitize.ts b/src/auto-reply/reply/display-text-sanitize.ts
@@ -1,3 +1,4 @@
+// Removes internal runtime context from text shown back to users.
 import { stripInternalRuntimeContext } from "../../agents/internal-runtime-context.js";
 import { stripEnvelope, stripMessageIdHints } from "../../shared/chat-envelope.js";
 import { stripInboundMetadata } from "./strip-inbound-meta.js";
diff --git a/src/auto-reply/reply/followup-delivery.test.ts b/src/auto-reply/reply/followup-delivery.test.ts
@@ -1,3 +1,4 @@
+// Tests follow-up reply delivery and route preservation.
 import { describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
 import { resolveFollowupDeliveryPayloads } from "./followup-delivery.js";
diff --git a/src/auto-reply/reply/inbound-context.ts b/src/auto-reply/reply/inbound-context.ts
@@ -1,3 +1,4 @@
+// Builds prompt context facts from inbound channel and sender metadata.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeChatType } from "../../channels/chat-type.js";
 import { resolveConversationLabel } from "../../channels/conversation-label.js";
diff --git a/src/auto-reply/reply/inbound-meta.test.ts b/src/auto-reply/reply/inbound-meta.test.ts
@@ -1,3 +1,4 @@
+// Tests inbound metadata normalization before prompt injection.
 import { describe, expect, it, vi } from "vitest";
 import { resetPluginRuntimeStateForTest, setActivePluginRegistry } from "../../plugins/runtime.js";
 import { createTestRegistry } from "../../test-utils/channel-plugins.js";
diff --git a/src/auto-reply/reply/reply-payloads.test.ts b/src/auto-reply/reply/reply-payloads.test.ts
@@ -1,3 +1,4 @@
+// Tests reply payload helper behavior and delivery metadata.
 import { describe, expect, it, vi } from "vitest";
 import { resetPluginRuntimeStateForTest, setActivePluginRegistry } from "../../plugins/runtime.js";
 import { createOutboundTestPlugin, createTestRegistry } from "../../test-utils/channel-plugins.js";
diff --git a/src/auto-reply/reply/reply-turn-admission.ts b/src/auto-reply/reply/reply-turn-admission.ts
@@ -1,3 +1,4 @@
+// Decides whether an inbound turn may start, queue, or abort a reply run.
 import {
   createReplyOperation,
   REPLY_RUN_IDLE_SETTLE_TIMEOUT_MS,
diff --git a/src/auto-reply/reply/reply.test-helpers.ts b/src/auto-reply/reply/reply.test-helpers.ts
@@ -1,3 +1,4 @@
+// Shared reply test helpers for mocked typing and delivery callbacks.
 export function createMockTypingController() {
   return {
     onReplyStart: async () => undefined,
diff --git a/src/auto-reply/reply/session-system-events.ts b/src/auto-reply/reply/session-system-events.ts
@@ -1,3 +1,4 @@
+// Records system-level session events for restarts, forks, and resets.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
diff --git a/src/auto-reply/reply/typing-persistence.test.ts b/src/auto-reply/reply/typing-persistence.test.ts
@@ -1,3 +1,4 @@
+// Tests typing mode persistence across session updates and reply turns.
 import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from "vitest";
 import { MAX_TIMER_TIMEOUT_MS } from "../../shared/number-coercion.js";
 import { createTypingController } from "./typing.js";

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Builds CLI runtime dispatch inputs for agent runner executions.`
`1`	`2`	`import { isRecord } from "@openclaw/normalization-core/record-coerce";`
`2`	`3`	`import {`
`3`	`4`	`normalizeLowercaseStringOrEmpty,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// E2E tests for run-reply-agent execution and generated session artifacts.`
`1`	`2`	`import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";`
`2`	`3`	`import { tmpdir } from "node:os";`
`3`	`4`	`import { join } from "node:path";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Buffers streaming reply blocks before coalesced final delivery.`
`1`	`2`	`import {`
`2`	`3`	`hasOutboundReplyContent,`
`3`	`4`	`resolveSendableOutboundReplyParts,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Implements bash command execution, approval, and stop handling.`
`1`	`2`	`import { resolveSessionAgentId } from "../../agents/agent-scope.js";`
`2`	`3`	`import { handleBashChatCommand } from "./bash-command.js";`
`3`	`4`	`import { rejectUnauthorizedCommand } from "./command-gates.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Implements compaction commands for session context and model state.`
`1`	`2`	`import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";`
`2`	`3`	`import {`
`3`	`4`	`normalizeLowercaseStringOrEmpty,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Implements context inspection commands for the active reply session.`
`1`	`2`	`import { logVerbose } from "../../globals.js";`
`2`	`3`	`import { buildContextReply } from "./commands-context-report.js";`
`3`	`4`	`import type { CommandHandler } from "./commands-types.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Builds export bundles for a session transcript and runtime context.`
`1`	`2`	`import fsp from "node:fs/promises";`
`2`	`3`	`import path from "node:path";`
`3`	`4`	`import { fileURLToPath } from "node:url";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests plugin command install, listing, and config behavior.`
`1`	`2`	`import { beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../../config/config.js";`
`3`	`4`	`import { handlePluginsCommand } from "./commands-plugins.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Shared mocks for session abort command tests.`
`1`	`2`	`import { vi } from "vitest";`
`2`	`3`
`3`	`4`	`vi.mock("./queue.js", async () => {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Implements session commands for list, show, fork, reset, and routing state.`
`1`	`2`	`import { timestampMsToIsoString } from "@openclaw/normalization-core/number-coercion";`
`2`	`3`	`import {`
`3`	`4`	`normalizeLowercaseStringOrEmpty,`