From 8b71d2347f2b31d829582471efa850a2353937ef Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Tue, 28 Apr 2026 23:55:26 -0700 Subject: [PATCH] docs(types): mark remaining deprecated aliases --- extensions/diffs/src/config.ts | 27 +++++++++++++++++++++------ extensions/diffs/src/tool.ts | 21 +++++++++++++++++---- extensions/ollama/src/stream.ts | 3 +-- extensions/qwen/models.ts | 10 +++++++++- src/agents/agent-scope.ts | 2 +- src/agents/bootstrap-budget.ts | 2 +- src/config/types.tts.ts | 2 +- src/cron/types.ts | 2 +- src/infra/exec-command-resolution.ts | 2 +- src/memory-host-sdk/dreaming.ts | 2 +- src/shared/net/ipv4.ts | 2 +- 11 files changed, 55 insertions(+), 20 deletions(-) diff --git a/extensions/diffs/src/config.ts b/extensions/diffs/src/config.ts index a238b8d0f2d..6f1b59b2a05 100644 --- a/extensions/diffs/src/config.ts +++ b/extensions/diffs/src/config.ts @@ -37,11 +37,15 @@ type DiffsPluginConfig = { fileQuality?: DiffImageQualityPreset; fileScale?: number; fileMaxWidth?: number; + /** @deprecated Use fileFormat. */ format?: DiffOutputFormat; - // Backward-compatible aliases retained for existing configs. + /** @deprecated Use fileFormat. */ imageFormat?: DiffOutputFormat; + /** @deprecated Use fileQuality. */ imageQuality?: DiffImageQualityPreset; + /** @deprecated Use fileScale. */ imageScale?: number; + /** @deprecated Use fileMaxWidth. */ imageMaxWidth?: number; mode?: DiffMode; }; @@ -142,17 +146,28 @@ const DiffsPluginJsonSchemaSource = z.strictObject({ .enum(DIFF_OUTPUT_FORMATS) .default(DEFAULT_DIFFS_TOOL_DEFAULTS.fileFormat) .optional(), - format: z.enum(DIFF_OUTPUT_FORMATS).optional(), + format: z.enum(DIFF_OUTPUT_FORMATS).optional().describe("Deprecated alias for fileFormat."), fileQuality: z .enum(DIFF_IMAGE_QUALITY_PRESETS) .default(DEFAULT_DIFFS_TOOL_DEFAULTS.fileQuality) .optional(), fileScale: z.number().min(1).max(4).optional(), fileMaxWidth: z.number().min(640).max(2400).optional(), - imageFormat: z.enum(DIFF_OUTPUT_FORMATS).optional(), - imageQuality: z.enum(DIFF_IMAGE_QUALITY_PRESETS).optional(), - imageScale: z.number().min(1).max(4).optional(), - imageMaxWidth: z.number().min(640).max(2400).optional(), + imageFormat: z + .enum(DIFF_OUTPUT_FORMATS) + .optional() + .describe("Deprecated alias for fileFormat."), + imageQuality: z + .enum(DIFF_IMAGE_QUALITY_PRESETS) + .optional() + .describe("Deprecated alias for fileQuality."), + imageScale: z.number().min(1).max(4).optional().describe("Deprecated alias for fileScale."), + imageMaxWidth: z + .number() + .min(640) + .max(2400) + .optional() + .describe("Deprecated alias for fileMaxWidth."), mode: z.enum(DIFF_MODES).default(DEFAULT_DIFFS_TOOL_DEFAULTS.mode).optional(), }) .optional(), diff --git a/extensions/diffs/src/tool.ts b/extensions/diffs/src/tool.ts index 8c1e40b528c..2edefeec1f9 100644 --- a/extensions/diffs/src/tool.ts +++ b/extensions/diffs/src/tool.ts @@ -34,11 +34,16 @@ const MAX_TITLE_BYTES = 1_024; const MAX_PATH_BYTES = 2_048; const MAX_LANG_BYTES = 128; -function stringEnum(values: T, description: string) { +function stringEnum( + values: T, + description: string, + options: { deprecated?: boolean } = {}, +) { return Type.Unsafe({ type: "string", enum: [...values], description, + ...options, }); } @@ -98,14 +103,21 @@ const DiffsToolSchema = Type.Object( ), /** @deprecated Use fileQuality. */ imageQuality: Type.Optional( - stringEnum(DIFF_IMAGE_QUALITY_PRESETS, "Deprecated alias for fileQuality."), + stringEnum(DIFF_IMAGE_QUALITY_PRESETS, "Deprecated alias for fileQuality.", { + deprecated: true, + }), ), /** @deprecated Use fileFormat. */ - imageFormat: Type.Optional(stringEnum(DIFF_OUTPUT_FORMATS, "Deprecated alias for fileFormat.")), + imageFormat: Type.Optional( + stringEnum(DIFF_OUTPUT_FORMATS, "Deprecated alias for fileFormat.", { + deprecated: true, + }), + ), /** @deprecated Use fileScale. */ imageScale: Type.Optional( Type.Number({ description: "Deprecated alias for fileScale.", + deprecated: true, minimum: 1, maximum: 4, }), @@ -114,6 +126,7 @@ const DiffsToolSchema = Type.Object( imageMaxWidth: Type.Optional( Type.Number({ description: "Deprecated alias for fileMaxWidth.", + deprecated: true, minimum: 640, maximum: 2400, }), @@ -140,7 +153,7 @@ const DiffsToolSchema = Type.Object( type DiffsToolParams = Static; type DiffsToolRawParams = DiffsToolParams & { - // Keep backward compatibility for direct calls that still pass `format`. + /** @deprecated Use fileFormat. */ format?: DiffOutputFormat; }; diff --git a/extensions/ollama/src/stream.ts b/extensions/ollama/src/stream.ts index bb101018ed2..b5fcd916f7e 100644 --- a/extensions/ollama/src/stream.ts +++ b/extensions/ollama/src/stream.ts @@ -387,8 +387,7 @@ export function createConfiguredOllamaCompatStreamWrapper( return streamFn; } -// Backward-compatible alias for existing imports/tests while the broader -// Ollama compat wrapper now owns more than num_ctx injection. +/** @deprecated Use createConfiguredOllamaCompatStreamWrapper. */ export const createConfiguredOllamaCompatNumCtxWrapper = createConfiguredOllamaCompatStreamWrapper; export function buildOllamaChatRequest(params: { diff --git a/extensions/qwen/models.ts b/extensions/qwen/models.ts index 3847db02c77..8f3d5ee1748 100644 --- a/extensions/qwen/models.ts +++ b/extensions/qwen/models.ts @@ -178,15 +178,23 @@ export function buildQwenDefaultModelDefinition(): ModelDefinitionConfig { return buildQwenModelDefinition({ id: QWEN_DEFAULT_MODEL_ID }); } -// Backward-compatible aliases while `modelstudio` references are still in the wild. +/** @deprecated Use QWEN_BASE_URL. */ export const MODELSTUDIO_BASE_URL = QWEN_BASE_URL; +/** @deprecated Use QWEN_GLOBAL_BASE_URL. */ export const MODELSTUDIO_GLOBAL_BASE_URL = QWEN_GLOBAL_BASE_URL; +/** @deprecated Use QWEN_CN_BASE_URL. */ export const MODELSTUDIO_CN_BASE_URL = QWEN_CN_BASE_URL; +/** @deprecated Use QWEN_STANDARD_CN_BASE_URL. */ export const MODELSTUDIO_STANDARD_CN_BASE_URL = QWEN_STANDARD_CN_BASE_URL; +/** @deprecated Use QWEN_STANDARD_GLOBAL_BASE_URL. */ export const MODELSTUDIO_STANDARD_GLOBAL_BASE_URL = QWEN_STANDARD_GLOBAL_BASE_URL; +/** @deprecated Use QWEN_DEFAULT_MODEL_ID. */ export const MODELSTUDIO_DEFAULT_MODEL_ID = QWEN_DEFAULT_MODEL_ID; +/** @deprecated Use QWEN_DEFAULT_COST. */ export const MODELSTUDIO_DEFAULT_COST = QWEN_DEFAULT_COST; +/** @deprecated Use qwen/${QWEN_DEFAULT_MODEL_ID}. */ export const MODELSTUDIO_DEFAULT_MODEL_REF = `modelstudio/${QWEN_DEFAULT_MODEL_ID}`; +/** @deprecated Use QWEN_MODEL_CATALOG. */ export const MODELSTUDIO_MODEL_CATALOG = QWEN_MODEL_CATALOG; export const isNativeModelStudioBaseUrl = isNativeQwenBaseUrl; export const applyModelStudioNativeStreamingUsageCompat = applyQwenNativeStreamingUsageCompat; diff --git a/src/agents/agent-scope.ts b/src/agents/agent-scope.ts index 9c53e36601e..57c7ddebfbf 100644 --- a/src/agents/agent-scope.ts +++ b/src/agents/agent-scope.ts @@ -146,7 +146,7 @@ export function setAgentEffectiveModelPrimary( return "defaults"; } -// Backward-compatible alias. Prefer explicit/effective helpers at new call sites. +/** @deprecated Prefer explicit/effective helpers at new call sites. */ export function resolveAgentModelPrimary(cfg: OpenClawConfig, agentId: string): string | undefined { return resolveAgentExplicitModelPrimary(cfg, agentId); } diff --git a/src/agents/bootstrap-budget.ts b/src/agents/bootstrap-budget.ts index 997dc29ab97..c50a12750ef 100644 --- a/src/agents/bootstrap-budget.ts +++ b/src/agents/bootstrap-budget.ts @@ -354,7 +354,7 @@ export function appendBootstrapPromptWarning( return prompt ? `${prompt}\n\n${warningBlock}` : warningBlock; } -// Backward-compatible alias while older callers still import the prepend name. +/** @deprecated Use appendBootstrapPromptWarning. */ export const prependBootstrapPromptWarning = appendBootstrapPromptWarning; export function buildBootstrapTruncationReportMeta(params: { diff --git a/src/config/types.tts.ts b/src/config/types.tts.ts index df6bfd70538..7df2de47340 100644 --- a/src/config/types.tts.ts +++ b/src/config/types.tts.ts @@ -55,7 +55,7 @@ export type ResolvedTtsPersona = TtsPersonaConfig & { export type TtsConfig = { /** Auto-TTS mode (preferred). */ auto?: TtsAutoMode; - /** Legacy: enable auto-TTS when `auto` is not set. */ + /** @deprecated Use auto. */ enabled?: boolean; /** Apply TTS to final replies only or to all replies (tool/block/final). */ mode?: TtsMode; diff --git a/src/cron/types.ts b/src/cron/types.ts index d75e68a43db..57e26d1397d 100644 --- a/src/cron/types.ts +++ b/src/cron/types.ts @@ -147,7 +147,7 @@ export type CronJobState = { lastRunAtMs?: number; /** Preferred execution outcome field. */ lastRunStatus?: CronRunStatus; - /** Back-compat alias for lastRunStatus. */ + /** @deprecated Use lastRunStatus. */ lastStatus?: "ok" | "error" | "skipped"; lastError?: string; /** Classified reason for the last error (when available). */ diff --git a/src/infra/exec-command-resolution.ts b/src/infra/exec-command-resolution.ts index fce7d7bc893..2e526fbf4d1 100644 --- a/src/infra/exec-command-resolution.ts +++ b/src/infra/exec-command-resolution.ts @@ -229,7 +229,7 @@ export function resolveApprovalAuditCandidatePath( return resolvePolicyTargetCandidatePath(resolution, cwd); } -// Legacy alias kept while callers migrate to explicit target naming. +/** @deprecated Use resolveExecutionTargetCandidatePath. */ export function resolveAllowlistCandidatePath( resolution: CommandResolution | ExecutableResolution | null, cwd?: string, diff --git a/src/memory-host-sdk/dreaming.ts b/src/memory-host-sdk/dreaming.ts index aade0337066..7c852b9e03c 100644 --- a/src/memory-host-sdk/dreaming.ts +++ b/src/memory-host-sdk/dreaming.ts @@ -351,7 +351,7 @@ export function resolveMemoryDreamingPluginConfig( return asNullableRecord(memoryPlugin?.config) ?? undefined; } -// Keep the legacy helper name exported until downstream memory plugins migrate. +/** @deprecated Use resolveMemoryDreamingPluginConfig. */ export const resolveMemoryCorePluginConfig = resolveMemoryDreamingPluginConfig; export function resolveMemoryDreamingConfig(params: { diff --git a/src/shared/net/ipv4.ts b/src/shared/net/ipv4.ts index afef27a204a..22638783dbc 100644 --- a/src/shared/net/ipv4.ts +++ b/src/shared/net/ipv4.ts @@ -10,7 +10,7 @@ export function validateDottedDecimalIPv4Input(value: string | undefined): strin return "Invalid IPv4 address (e.g., 192.168.1.100)"; } -// Backward-compatible alias for callers using the old helper name. +/** @deprecated Use validateDottedDecimalIPv4Input. */ export function validateIPv4AddressInput(value: string | undefined): string | undefined { return validateDottedDecimalIPv4Input(value); }