docs: document tts helpers

steipete · steipete · commit f5b6a977d743 · 2026-06-04T20:19:15.000-04:00
diff --git a/src/tts/directive-number.test.ts b/src/tts/directive-number.test.ts
@@ -1,3 +1,4 @@
+// TTS directive number tests cover parsing numeric speech directives.
 import { describe, expect, it } from "vitest";
 import { parseSpeechDirectiveNumberOverride } from "./directive-number.js";
 
diff --git a/src/tts/directive-number.ts b/src/tts/directive-number.ts
@@ -1,3 +1,4 @@
+// TTS directive number helpers parse strict numeric directive values.
 import { parseStrictFiniteNumber } from "@openclaw/normalization-core/number-coercion";
 import type {
   SpeechDirectiveTokenParseContext,
diff --git a/src/tts/directives.test.ts b/src/tts/directives.test.ts
@@ -1,3 +1,4 @@
+// TTS directive tests cover parsing and applying speech directives.
 import { describe, expect, it } from "vitest";
 import type { SpeechProviderPlugin } from "../plugins/types.js";
 import { createTtsDirectiveTextStreamCleaner, parseTtsDirectives } from "./directives.js";
diff --git a/src/tts/directives.ts b/src/tts/directives.ts
@@ -1,3 +1,4 @@
+// TTS directive helpers parse inline speech directives from text.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.js";
 import type { SpeechProviderPlugin } from "../plugins/types.js";
diff --git a/src/tts/openai-compatible-speech-provider.test.ts b/src/tts/openai-compatible-speech-provider.test.ts
@@ -1,3 +1,4 @@
+// OpenAI-compatible speech provider tests cover speech request and file output.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createOpenAiCompatibleSpeechProvider } from "./openai-compatible-speech-provider.js";
 
diff --git a/src/tts/openai-compatible-speech-provider.ts b/src/tts/openai-compatible-speech-provider.ts
@@ -1,3 +1,4 @@
+// OpenAI-compatible speech provider sends speech synthesis requests to OpenAI-style APIs.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import {
   assertOkOrThrowHttpError,
diff --git a/src/tts/prepare-text.test.ts b/src/tts/prepare-text.test.ts
@@ -1,3 +1,4 @@
+// TTS prepare text tests cover text cleanup before speech synthesis.
 import { describe, expect, it } from "vitest";
 import { stripMarkdown } from "../shared/text/strip-markdown.js";
 
diff --git a/src/tts/provider-registry-core.ts b/src/tts/provider-registry-core.ts
@@ -1,3 +1,4 @@
+// TTS provider registry core stores provider factories and defaults.
 import type { OpenClawConfig } from "../config/types.js";
 import {
   buildCapabilityProviderMaps,
diff --git a/src/tts/provider-registry.test.ts b/src/tts/provider-registry.test.ts
@@ -1,3 +1,4 @@
+// TTS provider registry tests cover registration and provider resolution.
 import { beforeEach, describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/types.js";
 import type { SpeechProviderPlugin } from "../plugins/types.js";
diff --git a/src/tts/provider-registry.ts b/src/tts/provider-registry.ts
@@ -1,3 +1,4 @@
+// TTS provider registry resolves configured speech providers at runtime.
 import type { OpenClawConfig } from "../config/types.js";
 import { getActiveRuntimePluginRegistry } from "../plugins/active-runtime-registry.js";
 import {
diff --git a/src/tts/provider-types.ts b/src/tts/provider-types.ts
@@ -1,3 +1,4 @@
+// TTS provider types describe speech provider config and synthesize APIs.
 import type { TalkProviderConfig } from "../config/types.gateway.js";
 import type { OpenClawConfig } from "../config/types.js";
 import type { ResolvedTtsPersona } from "../config/types.tts.js";
diff --git a/src/tts/status-config.test.ts b/src/tts/status-config.test.ts
@@ -1,3 +1,4 @@
+// TTS status config tests cover status file path and config resolution.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/tts/status-config.ts b/src/tts/status-config.ts
@@ -1,3 +1,4 @@
+// TTS status config helpers resolve status output paths for speech generation.
 import path from "node:path";
 import { isRecord as isObjectRecord } from "@openclaw/normalization-core/record-coerce";
 import {
diff --git a/src/tts/tts-auto-mode.ts b/src/tts/tts-auto-mode.ts
@@ -1,3 +1,4 @@
+// TTS auto mode helpers decide when speech should be generated automatically.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { TtsAutoMode } from "../config/types.tts.js";
 
diff --git a/src/tts/tts-config.test.ts b/src/tts/tts-config.test.ts
@@ -1,3 +1,4 @@
+// TTS config tests cover text-to-speech config loading and overrides.
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
diff --git a/src/tts/tts-config.ts b/src/tts/tts-config.ts
@@ -1,3 +1,4 @@
+// TTS config helpers read and normalize text-to-speech provider settings.
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { isRecord as isPlainObject } from "@openclaw/normalization-core/record-coerce";
diff --git a/src/tts/tts-core.test.ts b/src/tts/tts-core.test.ts
@@ -1,10 +1,11 @@
+// TTS core tests cover provider selection, synthesis, and error handling.
 import { describe, expect, it, vi } from "vitest";
 import type { ResolvedProviderAuth } from "../agents/model-auth-runtime-shared.js";
 import { AuthStorage, ModelRegistry } from "../agents/sessions/index.js";
 import type { AssistantMessage, Model, Usage } from "../llm/types.js";
 import { MAX_TIMER_TIMEOUT_MS } from "../shared/number-coercion.js";
-import { summarizeText } from "./tts-core.js";
 import type { SpeechModelOverridePolicy } from "./provider-types.js";
+import { summarizeText } from "./tts-core.js";
 import type { ResolvedTtsConfig } from "./tts-types.js";
 
 const modelOverridePolicy: SpeechModelOverridePolicy = {
diff --git a/src/tts/tts-core.ts b/src/tts/tts-core.ts
@@ -1,3 +1,4 @@
+// TTS core coordinates text preparation, provider selection, and speech output.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { resolveModelAsync } from "../agents/embedded-agent-runner/model.js";
 import { getApiKeyForModel, requireApiKey } from "../agents/model-auth.js";
diff --git a/src/tts/tts-provider-helpers.ts b/src/tts/tts-provider-helpers.ts
@@ -1,3 +1,4 @@
+// TTS provider helpers manage provider temp files and output cleanup.
 import { rmSync } from "node:fs";
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 
diff --git a/src/tts/tts-types.ts b/src/tts/tts-types.ts
@@ -1,3 +1,4 @@
+// TTS shared types describe speech requests, responses, and runtime config.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type {
   ResolvedTtsPersona,
diff --git a/src/tts/tts.test.ts b/src/tts/tts.test.ts
@@ -1,3 +1,4 @@
+// TTS integration tests cover text-to-speech command behavior.
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// TTS directive number tests cover parsing numeric speech directives.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { parseSpeechDirectiveNumberOverride } from "./directive-number.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// TTS directive number helpers parse strict numeric directive values.`
`1`	`2`	`import { parseStrictFiniteNumber } from "@openclaw/normalization-core/number-coercion";`
`2`	`3`	`import type {`
`3`	`4`	`SpeechDirectiveTokenParseContext,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// TTS directive tests cover parsing and applying speech directives.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import type { SpeechProviderPlugin } from "../plugins/types.js";`
`3`	`4`	`import { createTtsDirectiveTextStreamCleaner, parseTtsDirectives } from "./directives.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// TTS directive helpers parse inline speech directives from text.`
`1`	`2`	`import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";`
`2`	`3`	`import type { OpenClawConfig } from "../config/types.js";`
`3`	`4`	`import type { SpeechProviderPlugin } from "../plugins/types.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// OpenAI-compatible speech provider tests cover speech request and file output.`
`1`	`2`	`import { afterEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import { createOpenAiCompatibleSpeechProvider } from "./openai-compatible-speech-provider.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// OpenAI-compatible speech provider sends speech synthesis requests to OpenAI-style APIs.`
`1`	`2`	`import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";`
`2`	`3`	`import {`
`3`	`4`	`assertOkOrThrowHttpError,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// TTS prepare text tests cover text cleanup before speech synthesis.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { stripMarkdown } from "../shared/text/strip-markdown.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// TTS provider registry core stores provider factories and defaults.`
`1`	`2`	`import type { OpenClawConfig } from "../config/types.js";`
`2`	`3`	`import {`
`3`	`4`	`buildCapabilityProviderMaps,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// TTS provider registry tests cover registration and provider resolution.`
`1`	`2`	`import { beforeEach, describe, expect, it } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../config/types.js";`
`3`	`4`	`import type { SpeechProviderPlugin } from "../plugins/types.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// TTS provider registry resolves configured speech providers at runtime.`
`1`	`2`	`import type { OpenClawConfig } from "../config/types.js";`
`2`	`3`	`import { getActiveRuntimePluginRegistry } from "../plugins/active-runtime-registry.js";`
`3`	`4`	`import {`