veryfront 0.1.48 → 0.1.49

package/src/src/server/runtime-handler/index.ts

@@ -324,10 +324,24 @@ export function createVeryfrontHandler(
         // proceeding would cause cryptic 500s deep in the rendering pipeline.
         if (isProxyMode && !isLightweightPath(url.pathname) && !isWebSocketPath(url.pathname)) {
           const token = req.headers.get("x-token");
-          if (!headers.projectSlug) {
-            logger.error("Missing required x-project-slug header in proxy mode", {
+
+          const missingHeader = !headers.projectSlug
+            ? {
+              error: "Missing project context",
+              detail: "x-project-slug header is required in proxy mode",
+            }
+            : !token
+            ? {
+              error: "Missing authentication context",
+              detail: "x-token header is required in proxy mode",
+            }
+            : null;
+
+          if (missingHeader) {
+            logger.error(missingHeader.detail, {
               pathname: url.pathname,
               domain,
+              projectSlug: headers.projectSlug,
               host: req.headers.get("host"),
               forwardedHost: req.headers.get("x-forwarded-host"),
             });
@@ -340,32 +354,7 @@ export function createVeryfrontHandler(
             completeIsolatedRequest(headers.projectSlug, lifecycle.shouldCheckIsolation, false);
             endRequestTracing(spanInfo.span, 502);
             return new dntShim.Response(
-              JSON.stringify({
-                error: "Missing project context",
-                detail: "x-project-slug header is required in proxy mode",
-              }),
-              { status: 502, headers: { "Content-Type": "application/json" } },
-            );
-          }
-          if (!token) {
-            logger.error("Missing required x-token header in proxy mode", {
-              pathname: url.pathname,
-              domain,
-              projectSlug: headers.projectSlug,
-            });
-            endContentMetrics({
-              requestId: lifecycle.requestId,
-              pathname: url.pathname,
-              mode: "proxy",
-            });
-            completeRequestTracking(lifecycle.requestId, 502, false);
-            completeIsolatedRequest(headers.projectSlug, lifecycle.shouldCheckIsolation, false);
-            endRequestTracing(spanInfo.span, 502);
-            return new dntShim.Response(
-              JSON.stringify({
-                error: "Missing authentication context",
-                detail: "x-token header is required in proxy mode",
-              }),
+              JSON.stringify(missingHeader),
               { status: 502, headers: { "Content-Type": "application/json" } },
             );
           }

package/src/src/server/shared/renderer/memory/pressure.ts

@@ -21,7 +21,7 @@ import { getEnvNumber, getEnvString } from "../../../../platform/compat/process.
 const memoryPressureLog = rendererLogger.component("memory-pressure");
 const rendererLog = rendererLogger.component("renderer");
 
-export type MemoryPressureLevel = "normal" | "warning" | "high" | "critical";
+type MemoryPressureLevel = "normal" | "warning" | "high" | "critical";
 
 function parseEnvThreshold(name: string, fallback: number): number {
   const value = getEnvString(name);
@@ -42,7 +42,7 @@ const THRESHOLDS = {
   CRITICAL: parseEnvThreshold("MEMORY_CRITICAL_THRESHOLD", 80),
 };
 
-export function getMemoryPressure(): { level: MemoryPressureLevel; heapUsedPercent: number } {
+function getMemoryPressure(): { level: MemoryPressureLevel; heapUsedPercent: number } {
   const { heapUsedPercent } = getHeapStats();
 
   if (heapUsedPercent >= THRESHOLDS.CRITICAL) return { level: "critical", heapUsedPercent };
@@ -59,16 +59,3 @@ export function shouldRejectDueToMemory(): boolean {
   rendererLog.warn("Rejecting request - memory critical", { heapUsedPercent });
   return true;
 }
-
-export function getCacheTTLMultiplier(): number {
-  const { level } = getMemoryPressure();
-
-  if (level === "warning") return 0.5;
-  if (level === "high" || level === "critical") return 0.25;
-  return 1.0;
-}
-
-export function shouldEvictAggressively(): boolean {
-  const { level } = getMemoryPressure();
-  return level === "high" || level === "critical";
-}

package/src/src/server/utils/domain-lookup.ts

@@ -227,10 +227,6 @@ export function clearDomainCache(): void {
   logger.debug("Cache cleared");
 }
 
-export function getDomainCacheStats(): { size: number; maxSize: number } {
-  return { size: domainCache.size, maxSize: DOMAIN_CACHE_MAX_ENTRIES };
-}
-
 /**
  * Inject a CacheRepository for testing or distributed caching.
  * Call with null to restore default Map-based caching.

package/src/src/skill/allowed-tools.ts

@@ -0,0 +1,107 @@
+/**
+ * Allowed-Tools Enforcement
+ *
+ * Dual-layer enforcement for skill tool access restrictions.
+ * Layer 1: Filter tool definitions before sending to model (planning-time)
+ * Layer 2: Check individual tool calls at execution time
+ *
+ * @module
+ */
+
+import { SKILL_ALLOWED_TOOL_PATTERN_REGEX, SKILL_TOOL_IDS } from "./types.js";
+import { createError, toError } from "../errors/veryfront-error.js";
+
+/**
+ * Check if a tool name matches a single allowed-tools pattern.
+ *
+ * Supports:
+ * - Exact match: "Read" matches "Read"
+ * - Prefix wildcard: "api:*" matches "api:list-users"
+ */
+export function matchesAllowedTool(toolName: string, pattern: string): boolean {
+  // Invalid patterns always fail (fail closed)
+  if (!SKILL_ALLOWED_TOOL_PATTERN_REGEX.test(pattern)) {
+    return false;
+  }
+
+  // Prefix wildcard
+  if (pattern.endsWith(":*")) {
+    const prefix = pattern.slice(0, -1); // keep the colon: "api:"
+    return toolName.startsWith(prefix);
+  }
+
+  // Exact match
+  return toolName === pattern;
+}
+
+/** Minimal tool definition shape for filtering */
+export interface FilterableToolDefinition {
+  name: string;
+  description: string;
+  parameters: unknown;
+}
+
+/**
+ * Layer 1: Filter tool definitions before sending to model.
+ *
+ * Removes tools not in the allowed list. Always-allowed tools
+ * (skill system tools) pass through regardless.
+ *
+ * @param tools - Full list of tool definitions
+ * @param allowedTools - Allowed tool patterns, or undefined for no restrictions
+ * @returns Filtered tool definitions
+ */
+export function filterToolsForSkill<T extends FilterableToolDefinition>(
+  tools: T[],
+  allowedTools: string[] | undefined,
+): T[] {
+  if (allowedTools === undefined) {
+    return tools;
+  }
+
+  return tools.filter((tool) => {
+    if (SKILL_TOOL_IDS.has(tool.name)) return true;
+    return allowedTools.some((pattern) => matchesAllowedTool(tool.name, pattern));
+  });
+}
+
+/**
+ * Layer 2: Check if a specific tool call is allowed at execution time.
+ *
+ * @param toolName - Name of the tool being called
+ * @param allowedTools - Allowed tool patterns, or undefined for no restrictions
+ * @returns true if the tool call is allowed
+ */
+export function isToolAllowedBySkill(
+  toolName: string,
+  allowedTools: string[] | undefined,
+): boolean {
+  if (allowedTools === undefined) return true;
+  if (SKILL_TOOL_IDS.has(toolName)) return true;
+  return allowedTools.some((pattern) => matchesAllowedTool(toolName, pattern));
+}
+
+/**
+ * Validate allowed-tool patterns at parse time.
+ *
+ * Ensures each pattern matches the expected format.
+ * Rejects unsupported patterns with a descriptive error (fail closed).
+ *
+ * @param patterns - Array of tool patterns to validate
+ * @returns Validated patterns (same array if all valid)
+ * @throws If any pattern is invalid
+ */
+export function validateAllowedToolPatterns(patterns: string[]): string[] {
+  for (const pattern of patterns) {
+    if (!SKILL_ALLOWED_TOOL_PATTERN_REGEX.test(pattern)) {
+      throw toError(
+        createError({
+          type: "agent",
+          message: `Invalid allowed-tools pattern "${pattern}". ` +
+            `Only exact tool IDs (e.g. "Read") and prefix wildcards (e.g. "api:*") are supported.`,
+        }),
+      );
+    }
+  }
+  return patterns;
+}

package/src/src/skill/executor.ts

@@ -0,0 +1,215 @@
+/**
+ * Skill Script Executor
+ *
+ * Executes skill scripts using cross-runtime subprocess execution.
+ *
+ * @module
+ */
+import * as dntShim from "../../_dnt.shims.js";
+
+
+import { getEnv, runCommand } from "../platform/compat/process.js";
+import { isDeno } from "../platform/compat/runtime.js";
+import { extname } from "../platform/compat/path/index.js";
+import { readTextFile } from "../platform/compat/fs.js";
+import { createError, toError } from "../errors/veryfront-error.js";
+import type { SkillScriptExecutor, SkillScriptExecutorInput, SkillScriptResult } from "./types.js";
+
+const DEFAULT_SCRIPT_TIMEOUT_MS = 60_000;
+const MAX_SCRIPT_TIMEOUT_MS = 300_000;
+const TIMEOUT_EXIT_CODE = 124;
+const ENV_KEY_REGEX = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const TIMEOUT_SENTINEL = Symbol("skill-script-timeout");
+
+function resolveTimeoutMs(timeoutMs?: number): number {
+  if (timeoutMs === undefined || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return DEFAULT_SCRIPT_TIMEOUT_MS;
+  }
+  return Math.min(Math.floor(timeoutMs), MAX_SCRIPT_TIMEOUT_MS);
+}
+
+async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+): Promise<T | typeof TIMEOUT_SENTINEL> {
+  let timeoutId: ReturnType<typeof dntShim.setTimeout> | undefined;
+  const timeoutPromise = new Promise<typeof TIMEOUT_SENTINEL>((resolve) => {
+    timeoutId = dntShim.setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs);
+  });
+
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+}
+
+function timeoutResult(timeoutMs: number): SkillScriptResult {
+  return {
+    stdout: "",
+    stderr: `Script execution timed out after ${timeoutMs}ms`,
+    exitCode: TIMEOUT_EXIT_CODE,
+  };
+}
+
+function shellEscapeArg(value: string): string {
+  return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+
+function buildShellCommand(parts: string[]): string {
+  return parts.map(shellEscapeArg).join(" ");
+}
+
+function formatEnvAssignments(env?: Record<string, string>): string[] {
+  if (!env) return [];
+  return Object.entries(env).map(([key, value]) => {
+    if (!ENV_KEY_REGEX.test(key)) {
+      throw toError(
+        createError({
+          type: "agent",
+          message: `Invalid environment variable name: "${key}"`,
+        }),
+      );
+    }
+    return `${key}=${value}`;
+  });
+}
+
+function createSandboxScriptPath(scriptPath: string): string {
+  const ext = extname(scriptPath) || ".sh";
+  const suffix = Math.random().toString(36).slice(2, 10);
+  return `/tmp/veryfront-skill-script-${Date.now()}-${suffix}${ext}`;
+}
+
+/**
+ * Detect the runtime command for a script based on file extension.
+ */
+export function detectRuntime(scriptPath: string): { command: string; args: string[] } {
+  const ext = extname(scriptPath).toLowerCase();
+
+  switch (ext) {
+    case ".py":
+      return { command: "python3", args: [scriptPath] };
+    case ".sh":
+      return { command: "bash", args: [scriptPath] };
+    case ".js":
+      return { command: "node", args: [scriptPath] };
+    case ".ts":
+      if (isDeno) {
+        return {
+          command: "deno",
+          args: ["run", "--allow-read", "--allow-env", "--allow-net", "--allow-write", scriptPath],
+        };
+      }
+      return { command: "npx", args: ["tsx", scriptPath] };
+    default:
+      return { command: scriptPath, args: [] };
+  }
+}
+
+/**
+ * Local script executor using runCommand() from the compat layer.
+ */
+export class LocalScriptExecutor implements SkillScriptExecutor {
+  async execute(input: SkillScriptExecutorInput): Promise<SkillScriptResult> {
+    const timeoutMs = resolveTimeoutMs(input.timeoutMs);
+    const { command, args: runtimeArgs } = detectRuntime(input.scriptPath);
+    const allArgs = [...runtimeArgs, ...(input.args ?? [])];
+
+    // Remove the script path from args if it's already the command
+    const finalArgs = command === input.scriptPath ? (input.args ?? []) : allArgs;
+
+    const result = await runCommand(command, {
+      args: finalArgs,
+      cwd: input.cwd,
+      env: input.env,
+      capture: true,
+      timeoutMs,
+    });
+
+    return {
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      exitCode: result.code,
+    };
+  }
+}
+
+/**
+ * Cloud script executor using sandbox.
+ * Requires SANDBOX_AUTH_TOKEN environment variable.
+ */
+export class CloudScriptExecutor implements SkillScriptExecutor {
+  async execute(input: SkillScriptExecutorInput): Promise<SkillScriptResult> {
+    const timeoutMs = resolveTimeoutMs(input.timeoutMs);
+    // NOTE: In SSR contexts, getEnv() reads through the project-env overlay
+    // (AsyncLocalStorage-backed). If the token is set at host level only,
+    // the overlay may not surface it. Ensure SANDBOX_AUTH_TOKEN is available
+    // in the request-scoped environment when running under SSR.
+    const authToken = getEnv("SANDBOX_AUTH_TOKEN");
+    if (!authToken) {
+      throw toError(
+        createError({
+          type: "agent",
+          message: "Cloud script execution requires SANDBOX_AUTH_TOKEN environment variable",
+        }),
+      );
+    }
+
+    // Lazy import to avoid bundling sandbox in non-cloud environments
+    const { Sandbox } = await import("../sandbox/index.js");
+    const sandbox = await Sandbox.create({ authToken });
+    try {
+      const sandboxScriptPath = createSandboxScriptPath(input.scriptPath);
+      const scriptContent = input.scriptContent ?? await readTextFile(input.scriptPath);
+
+      await sandbox.writeFiles([{ path: sandboxScriptPath, content: scriptContent }]);
+      await sandbox.executeCommand(buildShellCommand(["chmod", "+x", sandboxScriptPath]));
+
+      const { command, args: runtimeArgs } = detectRuntime(sandboxScriptPath);
+      const allArgs = [...runtimeArgs, ...(input.args ?? [])];
+      const finalArgs = command === sandboxScriptPath ? (input.args ?? []) : allArgs;
+
+      const envAssignments = formatEnvAssignments(input.env);
+      const commandParts = envAssignments.length > 0
+        ? ["env", ...envAssignments, command, ...finalArgs]
+        : [command, ...finalArgs];
+
+      const cmdString = buildShellCommand(commandParts);
+      const commandPromise = sandbox.executeCommand(cmdString);
+      const result = await withTimeout(commandPromise, timeoutMs);
+
+      if (result === TIMEOUT_SENTINEL) {
+        // Kill any running processes before returning — withTimeout only
+        // races the timer, it doesn't terminate the sandbox command.
+        try {
+          await sandbox.executeCommand("kill -9 -1 2>/dev/null || true");
+        } catch {
+          // Best-effort kill; sandbox.close() in finally will clean up.
+        }
+        return timeoutResult(timeoutMs);
+      }
+
+      return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+      };
+    } finally {
+      try {
+        await sandbox.close();
+      } catch {
+        // Best-effort cleanup.
+      }
+    }
+  }
+}
+
+/**
+ * Get the appropriate script executor.
+ * Checks SANDBOX_AUTH_TOKEN on every call so request-scoped env overlays
+ * (e.g. project-env AsyncLocalStorage) are respected.
+ */
+export function getSkillScriptExecutor(): SkillScriptExecutor {
+  return getEnv("SANDBOX_AUTH_TOKEN") ? new CloudScriptExecutor() : new LocalScriptExecutor();
+}

package/src/src/skill/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Agent Skills
+ *
+ * Public API for the agent skills system.
+ * Skills are project-level capabilities defined as SKILL.md files
+ * following the agentskills.io specification.
+ *
+ * @module
+ */
+
+// Types
+export type {
+  ActiveSkillContext,
+  Skill,
+  SkillContent,
+  SkillMetadata,
+  SkillScriptExecutor,
+  SkillScriptExecutorInput,
+  SkillScriptResult,
+} from "./types.js";
+
+export {
+  SKILL_ALLOWED_TOOL_PATTERN_REGEX,
+  SKILL_ASSETS_DIR,
+  SKILL_DESCRIPTION_MAX_LENGTH,
+  SKILL_MD_FILENAME,
+  SKILL_NAME_REGEX,
+  SKILL_REFERENCES_DIR,
+  SKILL_SCRIPTS_DIR,
+  SKILL_TOOL_IDS,
+} from "./types.js";
+
+// Registry
+export { getAllSkills, getSkill, registerSkill, skillRegistry } from "./registry.js";
+
+// Parser
+export { parseSkillFrontmatter, validateSkillMetadata } from "./parser.js";
+
+// Path Safety
+export { listSkillSubdir, validateSkillPath } from "./path-safety.js";
+
+// Tools
+export {
+  createExecuteSkillScriptTool,
+  createLoadSkillReferenceTool,
+  createLoadSkillTool,
+} from "./tools.js";
+
+// Executor
+export { getSkillScriptExecutor } from "./executor.js";
+
+// Prompt
+export { buildSkillManifestPrompt } from "./prompt-augmentation.js";
+
+// Allowed-Tools
+export {
+  filterToolsForSkill,
+  isToolAllowedBySkill,
+  validateAllowedToolPatterns,
+} from "./allowed-tools.js";

package/src/src/skill/parser.ts

@@ -0,0 +1,214 @@
+/**
+ * Skill frontmatter parser
+ *
+ * Parses SKILL.md files with YAML frontmatter.
+ * Primary parser: gray-matter shim (#std/front-matter/yaml.ts)
+ * Fallback: regex + line-by-line parser
+ *
+ * @module
+ */
+
+import { createError, toError } from "../errors/veryfront-error.js";
+import {
+  SKILL_ALLOWED_TOOL_PATTERN_REGEX,
+  SKILL_DESCRIPTION_MAX_LENGTH,
+  SKILL_NAME_REGEX,
+  type SkillMetadata,
+} from "./types.js";
+
+/** Result of parsing a SKILL.md file */
+export interface ParsedSkillContent {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+/**
+ * Parse SKILL.md content into frontmatter + body.
+ *
+ * Uses gray-matter shim as primary parser with a regex fallback
+ * for environments where gray-matter is not available.
+ */
+export async function parseSkillFrontmatter(content: string): Promise<ParsedSkillContent> {
+  // Try primary parser: gray-matter shim
+  try {
+    const { extract } = await import("../platform/compat/std/front-matter-yaml.js");
+    const result = extract<Record<string, unknown>>(content);
+    return { frontmatter: result.attrs, body: result.body };
+  } catch {
+    // Fall through to fallback
+  }
+
+  // Fallback: regex-based parser
+  return parseFrontmatterFallback(content);
+}
+
+/**
+ * Regex-based fallback parser for YAML frontmatter.
+ * Handles simple key: value pairs (no nested YAML).
+ */
+function parseFrontmatterFallback(content: string): ParsedSkillContent {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const rawFrontmatter = match[1]!;
+  const body = match[2]!;
+  const frontmatter: Record<string, unknown> = {};
+
+  for (const line of rawFrontmatter.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex === -1) continue;
+
+    const key = trimmed.slice(0, colonIndex).trim();
+    const value = trimmed.slice(colonIndex + 1).trim();
+    frontmatter[key] = value;
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * Validate and normalize parsed frontmatter into SkillMetadata.
+ *
+ * @param frontmatter - Parsed frontmatter object
+ * @param directoryName - Directory name used as fallback for skill name
+ */
+export function validateSkillMetadata(
+  frontmatter: Record<string, unknown>,
+  directoryName: string,
+): SkillMetadata {
+  // Name: from frontmatter or directory name
+  const rawName = typeof frontmatter.name === "string" ? frontmatter.name.trim() : directoryName;
+
+  if (!SKILL_NAME_REGEX.test(rawName)) {
+    throw toError(
+      createError({
+        type: "agent",
+        message:
+          `Invalid skill name "${rawName}": must be lowercase alphanumeric with hyphens, 1-64 characters`,
+      }),
+    );
+  }
+
+  // Description: required
+  const rawDescription = frontmatter.description;
+  if (!rawDescription || typeof rawDescription !== "string" || !rawDescription.trim()) {
+    throw toError(
+      createError({
+        type: "agent",
+        message: `Skill "${rawName}" is missing a required "description" field`,
+      }),
+    );
+  }
+
+  const description = rawDescription.trim().slice(0, SKILL_DESCRIPTION_MAX_LENGTH);
+
+  // Allowed-tools: parse from space-delimited string or array
+  const allowedTools = parseAllowedTools(frontmatter["allowed-tools"], rawName);
+
+  // License: optional string passthrough
+  const license = typeof frontmatter.license === "string" ? frontmatter.license.trim() : undefined;
+
+  // Compatibility: optional string passthrough
+  const compatibility = typeof frontmatter.compatibility === "string"
+    ? frontmatter.compatibility.trim()
+    : undefined;
+
+  // Metadata: convert nested object values to strings
+  const metadata = parseMetadata(frontmatter.metadata);
+
+  return {
+    name: rawName,
+    description,
+    ...(allowedTools && { allowedTools }),
+    ...(license && { license }),
+    ...(compatibility && { compatibility }),
+    ...(metadata && { metadata }),
+  };
+}
+
+/**
+ * Parse `allowed-tools` from frontmatter.
+ * Accepts a space-delimited string or an array of strings.
+ * Validates each pattern against SKILL_ALLOWED_TOOL_PATTERN_REGEX.
+ */
+function parseAllowedTools(
+  value: unknown,
+  skillName: string,
+): string[] | undefined {
+  if (value === undefined || value === null) return undefined;
+
+  let patterns: string[];
+
+  if (typeof value === "string") {
+    patterns = value.split(/\s+/).filter(Boolean);
+  } else if (Array.isArray(value)) {
+    patterns = [];
+    for (const rawPattern of value) {
+      if (typeof rawPattern !== "string") {
+        throw toError(
+          createError({
+            type: "agent",
+            message:
+              `Skill "${skillName}" has invalid allowed-tools value: expected all entries to be strings`,
+          }),
+        );
+      }
+      const pattern = rawPattern.trim();
+      if (!pattern) {
+        throw toError(
+          createError({
+            type: "agent",
+            message: `Skill "${skillName}" has invalid allowed-tools pattern: empty value`,
+          }),
+        );
+      }
+      patterns.push(pattern);
+    }
+  } else {
+    throw toError(
+      createError({
+        type: "agent",
+        message:
+          `Skill "${skillName}" has invalid allowed-tools value: expected a string or array of strings, got ${typeof value}`,
+      }),
+    );
+  }
+
+  if (patterns.length === 0) return undefined;
+
+  // Validate each pattern (fail closed)
+  for (const pattern of patterns) {
+    if (!SKILL_ALLOWED_TOOL_PATTERN_REGEX.test(pattern)) {
+      throw toError(
+        createError({
+          type: "agent",
+          message: `Skill "${skillName}" has invalid allowed-tools pattern "${pattern}". ` +
+            `Only exact tool IDs (e.g. "Read") and prefix wildcards (e.g. "api:*") are supported.`,
+        }),
+      );
+    }
+  }
+
+  return patterns;
+}
+
+/** Convert metadata object values to strings */
+function parseMetadata(
+  value: unknown,
+): Record<string, string> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+
+  const entries = Object.entries(value as Record<string, unknown>);
+  if (entries.length === 0) return undefined;
+
+  const result: Record<string, string> = {};
+  for (const [k, v] of entries) {
+    result[k] = String(v);
+  }
+  return result;
+}