docs: document auto reply queue and acp helpers

steipete · steipete · commit b18a05ae3ef6 · 2026-06-04T02:43:05.000-04:00
diff --git a/src/auto-reply/reply/commands-acp/context.test.ts b/src/auto-reply/reply/commands-acp/context.test.ts
@@ -1,3 +1,4 @@
+// Tests ACP context command output and session metadata handling.
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../../config/config.js";
 import {
diff --git a/src/auto-reply/reply/commands-acp/context.ts b/src/auto-reply/reply/commands-acp/context.ts
@@ -1,3 +1,4 @@
+// Implements ACP context commands for session metadata and prompt state.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { normalizeConversationText } from "../../../acp/conversation-id.js";
 import { normalizeConversationTargetRef } from "../../../infra/outbound/session-binding-normalization.js";
diff --git a/src/auto-reply/reply/commands-acp/diagnostics.ts b/src/auto-reply/reply/commands-acp/diagnostics.ts
@@ -1,3 +1,4 @@
+// Formats ACP diagnostics and runtime error details for command replies.
 import { formatAcpRuntimeErrorText } from "@openclaw/acp-core/runtime/error-text";
 import {
   normalizeLowercaseStringOrEmpty,
diff --git a/src/auto-reply/reply/commands-acp/install-hints.test.ts b/src/auto-reply/reply/commands-acp/install-hints.test.ts
@@ -1,3 +1,4 @@
+// Tests ACP install hint detection and command guidance.
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../../config/config.js";
diff --git a/src/auto-reply/reply/commands-acp/install-hints.ts b/src/auto-reply/reply/commands-acp/install-hints.ts
@@ -1,3 +1,4 @@
+// Builds install hints for ACP runtimes missing local prerequisites.
 import { existsSync } from "node:fs";
 import path from "node:path";
 import {
diff --git a/src/auto-reply/reply/commands-acp/lifecycle.ts b/src/auto-reply/reply/commands-acp/lifecycle.ts
@@ -1,3 +1,4 @@
+// Implements ACP lifecycle commands for start, stop, reset, and resume.
 import { randomUUID } from "node:crypto";
 import {
   resolveAcpSessionCwd,
diff --git a/src/auto-reply/reply/commands-acp/runtime-options.ts b/src/auto-reply/reply/commands-acp/runtime-options.ts
@@ -1,3 +1,4 @@
+// Formats ACP runtime option details for command responses.
 import { resolveAcpSessionIdentifierLinesFromIdentity } from "@openclaw/acp-core/runtime/session-identifiers";
 import { timestampMsToIsoString } from "@openclaw/normalization-core/number-coercion";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
diff --git a/src/auto-reply/reply/commands-acp/shared.test.ts b/src/auto-reply/reply/commands-acp/shared.test.ts
@@ -1,3 +1,4 @@
+// Tests shared ACP command helpers for formatting and identifiers.
 import { describe, expect, it } from "vitest";
 import { parseSpawnInput, parseSteerInput } from "./shared.js";
 
diff --git a/src/auto-reply/reply/commands-acp/shared.ts b/src/auto-reply/reply/commands-acp/shared.ts
@@ -1,3 +1,4 @@
+// Shared ACP command helpers for session identity and reply formatting.
 import { randomUUID } from "node:crypto";
 import { toAcpRuntimeErrorText } from "@openclaw/acp-core/runtime/error-text";
 import type { AcpRuntimeSessionMode } from "@openclaw/acp-core/runtime/types";
diff --git a/src/auto-reply/reply/commands-acp/targets.ts b/src/auto-reply/reply/commands-acp/targets.ts
@@ -1,3 +1,4 @@
+// Resolves ACP command target sessions from user text and active state.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { callGateway } from "../../../gateway/call.js";
 import { resolveEffectiveResetTargetSessionKey } from "../acp-reset-target.js";
diff --git a/src/auto-reply/reply/commands-subagents/action-agents.test.ts b/src/auto-reply/reply/commands-subagents/action-agents.test.ts
@@ -1,3 +1,4 @@
+// Tests subagent agent-list command output and filtering.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const THREAD_CHANNEL = "thread-chat";
diff --git a/src/auto-reply/reply/commands-subagents/action-focus.ts b/src/auto-reply/reply/commands-subagents/action-focus.ts
@@ -1,3 +1,4 @@
+// Focuses an existing subagent run for follow-up routing.
 import {
   resolveAcpSessionCwd,
   resolveAcpThreadSessionDetailLines,
diff --git a/src/auto-reply/reply/commands-subagents/action-list.ts b/src/auto-reply/reply/commands-subagents/action-list.ts
@@ -1,3 +1,4 @@
+// Lists subagent runs with focus and status information.
 import { buildSubagentList } from "../../../agents/subagent-list.js";
 import type { CommandHandlerResult } from "../commands-types.js";
 import { type SubagentsCommandContext, RECENT_WINDOW_MINUTES, stopWithText } from "./shared.js";
diff --git a/src/auto-reply/reply/commands-subagents/action-unfocus.ts b/src/auto-reply/reply/commands-subagents/action-unfocus.ts
@@ -1,3 +1,4 @@
+// Clears active subagent focus for a session or scoped target.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeConversationRef } from "../../../infra/outbound/session-binding-normalization.js";
 import { getSessionBindingService } from "../../../infra/outbound/session-binding-service.js";
diff --git a/src/auto-reply/reply/commands-subagents/shared.ts b/src/auto-reply/reply/commands-subagents/shared.ts
@@ -1,3 +1,4 @@
+// Shared helpers for subagent command actions and target resolution.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
diff --git a/src/auto-reply/reply/exec/directive.ts b/src/auto-reply/reply/exec/directive.ts
@@ -1,3 +1,4 @@
+// Parses execution directives for approval, sandbox, and target settings.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import {
   type ExecAsk,
diff --git a/src/auto-reply/reply/export-html/template.security.test.ts b/src/auto-reply/reply/export-html/template.security.test.ts
@@ -1,3 +1,4 @@
+// Tests exported HTML transcript escaping and template safety.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/auto-reply/reply/queue/cleanup.test.ts b/src/auto-reply/reply/queue/cleanup.test.ts
@@ -1,3 +1,4 @@
+// Tests queue cleanup behavior for expired state and dedupe records.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { testing, clearSessionQueues } from "./cleanup.js";
 
diff --git a/src/auto-reply/reply/queue/cleanup.ts b/src/auto-reply/reply/queue/cleanup.ts
@@ -1,3 +1,4 @@
+// Cleans stale queue state and recent dedupe entries.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { resolveEmbeddedSessionLane } from "../../../agents/embedded-agent-runner/lanes.js";
 import { clearCommandLane } from "../../../process/command-queue.js";
diff --git a/src/auto-reply/reply/queue/directive.ts b/src/auto-reply/reply/queue/directive.ts
@@ -1,3 +1,4 @@
+// Converts queue directives into normalized queue settings.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import { parseDurationMs } from "../../../cli/parse-duration.js";
 import { parseStrictPositiveInteger } from "../../../infra/parse-finite-number.js";
diff --git a/src/auto-reply/reply/queue/drain.ts b/src/auto-reply/reply/queue/drain.ts
@@ -1,3 +1,4 @@
+// Drains queued follow-up runs while preserving route and session identity.
 import { channelRouteCompactKey } from "../../../plugin-sdk/channel-route.js";
 import { defaultRuntime } from "../../../runtime.js";
 import { resolveGlobalMap } from "../../../shared/global-singleton.js";
diff --git a/src/auto-reply/reply/queue/enqueue.ts b/src/auto-reply/reply/queue/enqueue.ts
@@ -1,3 +1,4 @@
+// Enqueues follow-up reply runs and schedules queue drains.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { resolveGlobalDedupeCache } from "../../../infra/dedupe.js";
 import { channelRouteDedupeKey } from "../../../plugin-sdk/channel-route.js";
diff --git a/src/auto-reply/reply/queue/normalize.ts b/src/auto-reply/reply/queue/normalize.ts
@@ -1,3 +1,4 @@
+// Normalizes queue config values from user and persisted settings.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { QueueDropPolicy, QueueMode } from "./types.js";
 
diff --git a/src/auto-reply/reply/queue/settings-runtime.test.ts b/src/auto-reply/reply/queue/settings-runtime.test.ts
@@ -1,3 +1,4 @@
+// Tests runtime queue settings with mocked provider fallback state.
 import { describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 
diff --git a/src/auto-reply/reply/queue/settings-runtime.ts b/src/auto-reply/reply/queue/settings-runtime.ts
@@ -1,3 +1,4 @@
+// Resolves runtime queue settings after considering provider fallback health.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import { getLoadedChannelPlugin } from "../../../channels/plugins/index.js";
 import { resolveQueueSettings as resolveQueueSettingsCore } from "./settings.js";
diff --git a/src/auto-reply/reply/queue/settings.test.ts b/src/auto-reply/reply/queue/settings.test.ts
@@ -1,3 +1,4 @@
+// Tests queue setting normalization and directive parsing.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 import { resolveQueueSettings } from "./settings.js";
diff --git a/src/auto-reply/reply/queue/settings.ts b/src/auto-reply/reply/queue/settings.ts
@@ -1,3 +1,4 @@
+// Resolves queue settings from config, directives, and fallback policy.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { InboundDebounceByProvider } from "../../../config/types.messages.js";
 import {
diff --git a/src/auto-reply/reply/queue/state.test.ts b/src/auto-reply/reply/queue/state.test.ts
@@ -1,3 +1,4 @@
+// Tests queue state storage, dedupe, and cleanup primitives.
 import { afterEach, describe, expect, it } from "vitest";
 import { clearFollowupQueue, getFollowupQueue, refreshQueuedFollowupSession } from "./state.js";
 import type { FollowupRun } from "./types.js";
diff --git a/src/auto-reply/reply/queue/state.ts b/src/auto-reply/reply/queue/state.ts
@@ -1,3 +1,4 @@
+// Tracks queue state for active, pending, and recently deduped reply runs.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { resolveGlobalMap } from "../../../shared/global-singleton.js";
 import { applyQueueRuntimeSettings } from "../../../utils/queue-helpers.js";
diff --git a/src/auto-reply/reply/queue/types.ts b/src/auto-reply/reply/queue/types.ts
@@ -1,3 +1,4 @@
+// Shared queue type contracts for admission, drain, and fallback handling.
 import type { AutoFallbackPrimaryProbe } from "../../../agents/agent-scope.js";
 import type { ExecToolDefaults } from "../../../agents/bash-tools.js";
 import type { CurrentInboundPromptContext } from "../../../agents/embedded-agent-runner/run/params.js";
diff --git a/src/auto-reply/reply/test-fixtures/acp-runtime.ts b/src/auto-reply/reply/test-fixtures/acp-runtime.ts
@@ -1,3 +1,4 @@
+// Test fixture helpers for constructing ACP runtime session metadata.
 import type { SessionAcpMeta } from "../../../config/sessions/types.js";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests ACP context command output and session metadata handling.`
`1`	`2`	`import { afterEach, beforeEach, describe, expect, it } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../../../config/config.js";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Implements ACP context commands for session metadata and prompt state.`
`1`	`2`	`import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";`
`2`	`3`	`import { normalizeConversationText } from "../../../acp/conversation-id.js";`
`3`	`4`	`import { normalizeConversationTargetRef } from "../../../infra/outbound/session-binding-normalization.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Formats ACP diagnostics and runtime error details for command replies.`
`1`	`2`	`import { formatAcpRuntimeErrorText } from "@openclaw/acp-core/runtime/error-text";`
`2`	`3`	`import {`
`3`	`4`	`normalizeLowercaseStringOrEmpty,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests ACP install hint detection and command guidance.`
`1`	`2`	`import path from "node:path";`
`2`	`3`	`import { afterEach, describe, expect, it, vi } from "vitest";`
`3`	`4`	`import type { OpenClawConfig } from "../../../config/config.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Builds install hints for ACP runtimes missing local prerequisites.`
`1`	`2`	`import { existsSync } from "node:fs";`
`2`	`3`	`import path from "node:path";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Implements ACP lifecycle commands for start, stop, reset, and resume.`
`1`	`2`	`import { randomUUID } from "node:crypto";`
`2`	`3`	`import {`
`3`	`4`	`resolveAcpSessionCwd,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Formats ACP runtime option details for command responses.`
`1`	`2`	`import { resolveAcpSessionIdentifierLinesFromIdentity } from "@openclaw/acp-core/runtime/session-identifiers";`
`2`	`3`	`import { timestampMsToIsoString } from "@openclaw/normalization-core/number-coercion";`
`3`	`4`	`import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests shared ACP command helpers for formatting and identifiers.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { parseSpawnInput, parseSteerInput } from "./shared.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Shared ACP command helpers for session identity and reply formatting.`
`1`	`2`	`import { randomUUID } from "node:crypto";`
`2`	`3`	`import { toAcpRuntimeErrorText } from "@openclaw/acp-core/runtime/error-text";`
`3`	`4`	`import type { AcpRuntimeSessionMode } from "@openclaw/acp-core/runtime/types";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Resolves ACP command target sessions from user text and active state.`
`1`	`2`	`import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";`
`2`	`3`	`import { callGateway } from "../../../gateway/call.js";`
`3`	`4`	`import { resolveEffectiveResetTargetSessionKey } from "../acp-reset-target.js";`