docs: document auto reply command gates

steipete · steipete · commit 119bb5762714 · 2026-06-04T02:39:12.000-04:00
diff --git a/src/auto-reply/reply/acp-projector.test.ts b/src/auto-reply/reply/acp-projector.test.ts
@@ -1,3 +1,4 @@
+// Tests ACP event projection into session updates and reply payloads.
 import { describe, expect, it, vi } from "vitest";
 import { prefixSystemMessage } from "../../infra/system-message.js";
 import { createAcpReplyProjector } from "./acp-projector.js";
diff --git a/src/auto-reply/reply/command-gates.ts b/src/auto-reply/reply/command-gates.ts
@@ -1,3 +1,4 @@
+// Applies command feature gates before command handlers execute.
 import { isCommandFlagEnabled, type CommandFlagKey } from "../../config/commands.flags.js";
 import { logVerbose } from "../../globals.js";
 import { redactIdentifier } from "../../logging/redact-identifier.js";
diff --git a/src/auto-reply/reply/commands-filesystem.test-support.ts b/src/auto-reply/reply/commands-filesystem.test-support.ts
@@ -1,3 +1,4 @@
+// Shared filesystem fixtures for command tests that write session artifacts.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/auto-reply/reply/commands-handlers.runtime.ts b/src/auto-reply/reply/commands-handlers.runtime.ts
@@ -1,3 +1,4 @@
+// Loads command handlers behind a runtime boundary for the command dispatcher.
 import { handleAcpCommand } from "./commands-acp.js";
 import { handleAllowlistCommand } from "./commands-allowlist.js";
 import { handleApproveCommand } from "./commands-approve.js";
diff --git a/src/auto-reply/reply/commands-info.tools.test.ts b/src/auto-reply/reply/commands-info.tools.test.ts
@@ -1,3 +1,4 @@
+// Tests tool listing in info command responses.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { EffectiveToolInventoryResult } from "../../agents/tools-effective-inventory.types.js";
 import type { OpenClawConfig } from "../../config/config.js";
diff --git a/src/auto-reply/reply/commands-session-abort.ts b/src/auto-reply/reply/commands-session-abort.ts
@@ -1,3 +1,4 @@
+// Implements session abort commands and active-run stop targeting.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { SessionEntry } from "../../config/sessions.js";
 import { logVerbose } from "../../globals.js";
diff --git a/src/auto-reply/reply/commands-session-usage.test.ts b/src/auto-reply/reply/commands-session-usage.test.ts
@@ -1,3 +1,4 @@
+// Tests session usage command output and token accounting summaries.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
 import type {
diff --git a/src/auto-reply/reply/commands-status.thinking-default.test.ts b/src/auto-reply/reply/commands-status.thinking-default.test.ts
@@ -1,3 +1,4 @@
+// Tests status command defaults for thinking and reasoning display.
 import { beforeAll, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
 
diff --git a/src/auto-reply/reply/commands-subagents-status.test.ts b/src/auto-reply/reply/commands-subagents-status.test.ts
@@ -1,3 +1,4 @@
+// Tests subagent status command output and active run summaries.
 import { beforeEach, describe, expect, it } from "vitest";
 import { subagentRuns } from "../../agents/subagent-registry-memory.js";
 import {
diff --git a/src/auto-reply/reply/conversation-label-generator.ts b/src/auto-reply/reply/conversation-label-generator.ts
@@ -1,3 +1,4 @@
+// Generates short labels for sessions from conversation context.
 import { resolveModelAsync } from "../../agents/embedded-agent-runner/model.js";
 import { requireApiKey } from "../../agents/model-auth.js";
 import { resolveDefaultModelForAgent } from "../../agents/model-selection.js";
diff --git a/src/auto-reply/reply/debug-commands.ts b/src/auto-reply/reply/debug-commands.ts
@@ -1,3 +1,4 @@
+// Implements debug command toggles used by maintainers during reply runs.
 import { parseStandardSetUnsetSlashCommand } from "./commands-setunset-standard.js";
 
 export type DebugCommand =
diff --git a/src/auto-reply/reply/dispatch-acp.ts b/src/auto-reply/reply/dispatch-acp.ts
@@ -1,3 +1,4 @@
+// Dispatches reply turns through ACP runtimes and projects their events.
 import { formatAcpRuntimeErrorText } from "@openclaw/acp-core/runtime/error-text";
 import { resolveAcpThreadSessionDetailLines } from "@openclaw/acp-core/runtime/session-identifiers";
 import {
diff --git a/src/auto-reply/reply/dispatch-from-config.shared.test-harness.ts b/src/auto-reply/reply/dispatch-from-config.shared.test-harness.ts
@@ -1,3 +1,4 @@
+// Shared harness for dispatch-from-config tests and mocked runtimes.
 import { vi } from "vitest";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { SessionBindingRecord } from "../../infra/outbound/session-binding-service.js";
diff --git a/src/auto-reply/reply/get-reply.fast-path.runtime.test.ts b/src/auto-reply/reply/get-reply.fast-path.runtime.test.ts
@@ -1,3 +1,4 @@
+// Tests runtime-loaded fast-path command behavior for get-reply.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
 import {
diff --git a/src/auto-reply/reply/get-reply.types.ts b/src/auto-reply/reply/get-reply.types.ts
@@ -1,3 +1,4 @@
+// Shared get-reply type contracts for command, directive, and runtime layers.
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { GetReplyOptions } from "../get-reply-options.types.js";
 import type { ReplyPayload } from "../reply-payload.js";
diff --git a/src/auto-reply/reply/group-id-simple.ts b/src/auto-reply/reply/group-id-simple.ts
@@ -1,3 +1,4 @@
+// Derives stable group ids from simple channel and conversation facts.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 /** Extracts a simple group/channel id from stable group-like source ids. */
diff --git a/src/auto-reply/reply/mentions.test.ts b/src/auto-reply/reply/mentions.test.ts
@@ -1,3 +1,4 @@
+// Tests mention detection and command trigger matching.
 import { describe, expect, it } from "vitest";
 import { stripStructuralPrefixes } from "./mentions.js";
 
diff --git a/src/auto-reply/reply/plugins-commands.ts b/src/auto-reply/reply/plugins-commands.ts
@@ -1,3 +1,4 @@
+// Provides plugin command discovery and handler registration helpers.
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
diff --git a/src/auto-reply/reply/provider-dispatcher.types.ts b/src/auto-reply/reply/provider-dispatcher.types.ts
@@ -1,3 +1,4 @@
+// Shared provider dispatch type contracts for reply runtime execution.
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { GetReplyOptions } from "../get-reply-options.types.js";
 import type { FinalizedMsgContext, MsgContext } from "../templating.js";
diff --git a/src/auto-reply/reply/queue-policy.test.ts b/src/auto-reply/reply/queue-policy.test.ts
@@ -1,3 +1,4 @@
+// Tests queue policy parsing and admission decisions.
 import { describe, expect, it } from "vitest";
 import { resolveActiveRunQueueAction } from "./queue-policy.js";
 
diff --git a/src/auto-reply/reply/reply-media-paths.test.ts b/src/auto-reply/reply/reply-media-paths.test.ts
@@ -1,3 +1,4 @@
+// Tests media path normalization and attachment metadata generation.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/auto-reply/reply/reply-state.test.ts b/src/auto-reply/reply/reply-state.test.ts
@@ -1,3 +1,4 @@
+// Tests reply state persistence and recovery across process restarts.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/auto-reply/reply/session-hooks-context.test.ts b/src/auto-reply/reply/session-hooks-context.test.ts
@@ -1,3 +1,4 @@
+// Tests context passed to session lifecycle hooks.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/auto-reply/reply/typing-mode.ts b/src/auto-reply/reply/typing-mode.ts
@@ -1,3 +1,4 @@
+// Normalizes typing indicator modes from config and directives.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { TypingMode } from "../../config/types.js";
 import type { SourceReplyDeliveryMode } from "../get-reply-options.types.js";

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests ACP event projection into session updates and reply payloads.`
`1`	`2`	`import { describe, expect, it, vi } from "vitest";`
`2`	`3`	`import { prefixSystemMessage } from "../../infra/system-message.js";`
`3`	`4`	`import { createAcpReplyProjector } from "./acp-projector.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Applies command feature gates before command handlers execute.`
`1`	`2`	`import { isCommandFlagEnabled, type CommandFlagKey } from "../../config/commands.flags.js";`
`2`	`3`	`import { logVerbose } from "../../globals.js";`
`3`	`4`	`import { redactIdentifier } from "../../logging/redact-identifier.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Shared filesystem fixtures for command tests that write session artifacts.`
`1`	`2`	`import fs from "node:fs/promises";`
`2`	`3`	`import os from "node:os";`
`3`	`4`	`import path from "node:path";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Loads command handlers behind a runtime boundary for the command dispatcher.`
`1`	`2`	`import { handleAcpCommand } from "./commands-acp.js";`
`2`	`3`	`import { handleAllowlistCommand } from "./commands-allowlist.js";`
`3`	`4`	`import { handleApproveCommand } from "./commands-approve.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests tool listing in info command responses.`
`1`	`2`	`import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import type { EffectiveToolInventoryResult } from "../../agents/tools-effective-inventory.types.js";`
`3`	`4`	`import type { OpenClawConfig } from "../../config/config.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Implements session abort commands and active-run stop targeting.`
`1`	`2`	`import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";`
`2`	`3`	`import type { SessionEntry } from "../../config/sessions.js";`
`3`	`4`	`import { logVerbose } from "../../globals.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests session usage command output and token accounting summaries.`
`1`	`2`	`import { beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../../config/config.js";`
`3`	`4`	`import type {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests status command defaults for thinking and reasoning display.`
`1`	`2`	`import { beforeAll, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../../config/config.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests subagent status command output and active run summaries.`
`1`	`2`	`import { beforeEach, describe, expect, it } from "vitest";`
`2`	`3`	`import { subagentRuns } from "../../agents/subagent-registry-memory.js";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Generates short labels for sessions from conversation context.`
`1`	`2`	`import { resolveModelAsync } from "../../agents/embedded-agent-runner/model.js";`
`2`	`3`	`import { requireApiKey } from "../../agents/model-auth.js";`
`3`	`4`	`import { resolveDefaultModelForAgent } from "../../agents/model-selection.js";`