@lazyingart/agintiflow 0.1.0 → 0.3.0

package/src/docker-sandbox.js

@@ -93,9 +93,17 @@ export function getSandboxLogs(limit = 30) {
   return sandboxLogs.slice(-limit);
 }
 
+function sandboxPackageDir(config) {
+  return path.resolve(config.packageDir || config.baseDir || process.cwd());
+}
+
+function sandboxDockerfilePath(config) {
+  return path.join(sandboxPackageDir(config), "docker", "sandbox.Dockerfile");
+}
+
 export async function getDockerSandboxStatus(config) {
   const image = config.dockerSandboxImage;
-  const dockerfilePath = path.join(config.baseDir, "docker", "sandbox.Dockerfile");
+  const dockerfilePath = sandboxDockerfilePath(config);
   const workspace = config.commandCwd;
   const [dockerReady, dockerfileExists, workspaceExists, workspaceReadable, workspaceWritable] = await Promise.all([
     dockerAvailable(),
@@ -125,14 +133,15 @@ export async function getDockerSandboxStatus(config) {
 
 async function buildDockerSandboxImage(config, observers) {
   const image = config.dockerSandboxImage;
-  const dockerfilePath = path.join(config.baseDir, "docker", "sandbox.Dockerfile");
+  const packageDir = sandboxPackageDir(config);
+  const dockerfilePath = sandboxDockerfilePath(config);
   observers?.log?.("docker.building", {
     image,
     dockerfilePath,
   });
   recordSandboxLog("docker.building", { image, dockerfilePath });
 
-  await execDocker(["build", "-t", image, "-f", dockerfilePath, config.baseDir], {
+  await execDocker(["build", "-t", image, "-f", dockerfilePath, packageDir], {
     timeout: 10 * 60 * 1000,
     maxBuffer: 1024 * 1024,
   });
@@ -146,7 +155,7 @@ export async function ensureDockerSandboxReady(config, observers, options = {})
   const image = config.dockerSandboxImage;
   if (!config.useDockerSandbox || (READY_IMAGES.has(image) && !options.forceBuild)) return;
 
-  const dockerfilePath = path.join(config.baseDir, "docker", "sandbox.Dockerfile");
+  const dockerfilePath = sandboxDockerfilePath(config);
   await fs.access(dockerfilePath).catch(() => {
     throw new Error(`Docker sandbox file is missing: ${dockerfilePath}`);
   });
@@ -163,10 +172,11 @@ function dockerRunArgs(command, config, policy = evaluateCommandPolicy(command,
   const sandboxMode = normalizeSandboxMode(config.sandboxMode);
   const mountMode = sandboxMode === "docker-workspace" ? "rw" : "ro";
   const networkMode = policy.needsNetwork ? "bridge" : "none";
+  const toolchain = policy.category === "toolchain";
   const readOnlyArgs =
     mountMode === "ro"
       ? ["--read-only", "--tmpfs", "/tmp:rw,nosuid,nodev,size=128m"]
-      : ["--tmpfs", "/tmp:rw,nosuid,nodev,size=256m"];
+      : ["--tmpfs", `/tmp:rw,nosuid,nodev,size=${toolchain ? "512m" : "256m"}`];
 
   return [
     "run",
@@ -180,9 +190,9 @@ function dockerRunArgs(command, config, policy = evaluateCommandPolicy(command,
     "--pids-limit",
     "256",
     "--memory",
-    "768m",
+    toolchain ? "2g" : "768m",
     "--cpus",
-    "1.5",
+    toolchain ? "2" : "1.5",
     ...readOnlyArgs,
     ...userArgs,
     "-e",
@@ -204,7 +214,7 @@ function dockerRunArgs(command, config, policy = evaluateCommandPolicy(command,
 
 export async function runDockerSandboxCommand(command, config, policy = evaluateCommandPolicy(command, config)) {
   const result = await execDocker(dockerRunArgs(command, config, policy), {
-    timeout: policy.needsNetwork ? 120000 : 15000,
+    timeout: policy.needsNetwork ? 120000 : policy.category === "toolchain" ? 90000 : 15000,
     maxBuffer: 300 * 1024,
   });
 
@@ -238,6 +248,23 @@ export async function runDockerPreflight(config, options = {}) {
   const manifests = await detectWorkspaceManifests(config.commandCwd);
   let checks = [];
 
+  if (!config.useDockerSandbox || normalizeSandboxMode(config.sandboxMode) === "host") {
+    const result = {
+      ok: Boolean(statusBefore.workspaceExists && statusBefore.workspaceReadable),
+      status: statusBefore,
+      manifests,
+      checks,
+      logs: getSandboxLogs(),
+    };
+    recordSandboxLog("sandbox.preflight.completed", {
+      ok: result.ok,
+      mode: "host",
+      manifests,
+      checks: [],
+    });
+    return result;
+  }
+
   if (buildImage && statusBefore.dockerAvailable && statusBefore.dockerfileExists && !statusBefore.imageReady) {
     await ensureDockerSandboxReady(config, {
       log: (message, data) => recordSandboxLog(message, data),
@@ -253,6 +280,9 @@ export async function runDockerPreflight(config, options = {}) {
       "npm -v",
       "python3 --version",
       "python3 -m pip --version",
+      "python3 -c \"import matplotlib, numpy; print(matplotlib.__version__, numpy.__version__)\"",
+      "latexmk -version",
+      "pdflatex --version",
       "git --version",
       "rg --version",
     ]) {

package/src/guardrails.js

@@ -1,4 +1,6 @@
 import { evaluateCommandPolicy } from "./command-policy.js";
+import { checkWorkspaceToolUse, WORKSPACE_TOOL_NAMES } from "./workspace-tools.js";
+import { normalizeWrapperName } from "./tool-wrappers.js";
 
 const DESTRUCTIVE_KEYWORDS = [
   "delete",
@@ -15,6 +17,7 @@ const DESTRUCTIVE_KEYWORDS = [
 ];
 
 const KNOWN_WRAPPERS = new Set(["codex", "claude", "gemini", "copilot", "qwen"]);
+const MAX_CANVAS_CONTENT_BYTES = 120_000;
 const DESTRUCTIVE_PROMPT_HINTS = [
   "delete",
   "remove files",
@@ -44,6 +47,10 @@ export function isDomainAllowed(urlString, allowedDomains) {
 }
 
 export function checkToolUse({ toolName, args, snapshot, config }) {
+  if (WORKSPACE_TOOL_NAMES.includes(toolName)) {
+    return checkWorkspaceToolUse(toolName, args, config);
+  }
+
   if (toolName === "open_url") {
     if (!/^https?:\/\//.test(String(args.url || ""))) {
       return { allowed: false, reason: "Only http and https URLs are allowed." };
@@ -102,6 +109,11 @@ export function checkToolUse({ toolName, args, snapshot, config }) {
       return { allowed: false, reason: `Unknown agent wrapper: ${wrapper}` };
     }
 
+    const preferredWrapper = normalizeWrapperName(config.preferredWrapper);
+    if (wrapper !== preferredWrapper) {
+      return { allowed: false, reason: `Only the selected wrapper is enabled for this run: ${preferredWrapper}` };
+    }
+
     const prompt = String(args.prompt || "").trim();
     if (prompt.length < 8) {
       return { allowed: false, reason: "Agent wrapper prompt is too short." };
@@ -118,5 +130,24 @@ export function checkToolUse({ toolName, args, snapshot, config }) {
     return { allowed: true };
   }
 
+  if (toolName === "send_to_canvas") {
+    const title = String(args.title || "").trim();
+    if (!title) return { allowed: false, reason: "Canvas title is required." };
+    const content = typeof args.content === "string" ? args.content : "";
+    if (Buffer.byteLength(content, "utf8") > MAX_CANVAS_CONTENT_BYTES) {
+      return {
+        allowed: false,
+        reason: "Canvas content is too large. Write it to a workspace file and send the path instead.",
+      };
+    }
+
+    const canvasPath = String(args.path || "").trim();
+    if (canvasPath) {
+      return checkWorkspaceToolUse("read_file", { path: canvasPath }, config);
+    }
+
+    return { allowed: true };
+  }
+
   return { allowed: true };
 }

package/src/model-client.js

@@ -1,14 +1,124 @@
 import OpenAI from "openai";
-import { WRAPPER_NAMES, wrapperStatusText } from "./tool-wrappers.js";
+import { normalizeWrapperName, wrapperStatusText } from "./tool-wrappers.js";
 
 export function createClient(config) {
+  if (config.provider === "mock") {
+    return {
+      mock: true,
+      provider: "mock",
+    };
+  }
+
   return new OpenAI({
     apiKey: config.apiKey,
     baseURL: config.baseURL,
   });
 }
 
+function mockToolCall(name, args = {}) {
+  return {
+    id: `mock-${name}-${Date.now()}`,
+    type: "function",
+    function: {
+      name,
+      arguments: JSON.stringify(args),
+    },
+  };
+}
+
+function latestToolPayload(messages) {
+  const toolMessage = [...messages].reverse().find((message) => message.role === "tool" && message.content);
+  if (!toolMessage) return null;
+
+  try {
+    return JSON.parse(toolMessage.content);
+  } catch {
+    return null;
+  }
+}
+
+function prepareMessages(config, messages) {
+  if (config.provider === "deepseek") return messages;
+  return messages.map((message) => {
+    const prepared = { ...message };
+    delete prepared.reasoning_content;
+    delete prepared.reasoningContent;
+    return prepared;
+  });
+}
+
+function mockCommandForGoal(goal = "") {
+  const text = String(goal).toLowerCase();
+  if (/\blist\b|folder contents|directory contents|files?/.test(text)) return "ls -la";
+  return "pwd";
+}
+
+function mockPathForGoal(goal = "") {
+  const text = String(goal);
+  const explicit = text.match(/(?:file|path):\s*`?([A-Za-z0-9_./-]+)`?/i)?.[1];
+  if (explicit) return explicit;
+  if (/\.env/i.test(text)) return ".env";
+  if (/outside|escape/i.test(text)) return "../outside-workspace.txt";
+  if (/patch/i.test(text)) return "patch-target.txt";
+  return "mock-output.txt";
+}
+
+function mockWorkspaceToolForGoal(goal = "") {
+  const text = String(goal).toLowerCase();
+  const targetPath = mockPathForGoal(goal);
+  if (/patch|replace|edit/.test(text)) {
+    return mockToolCall("apply_patch", {
+      path: targetPath,
+      search: "old",
+      replace: "new",
+      expectedReplacements: 1,
+    });
+  }
+  if (/write|create|file|coding/.test(text)) {
+    return mockToolCall("write_file", {
+      path: targetPath,
+      mode: "create",
+      content: `Created by AgInTiFlow mock mode.\nGoal: ${String(goal).slice(0, 160)}\n`,
+    });
+  }
+  return null;
+}
+
+function mockCanvasToolForGoal(goal = "") {
+  const text = String(goal).toLowerCase();
+  if (!/canvas|artifact|image|figure|visual|preview|render/.test(text)) return null;
+  return mockToolCall("send_to_canvas", {
+    title: "Mock canvas note",
+    kind: "markdown",
+    content: `# Mock canvas artifact\n\nAgInTiFlow can send selected text, diffs, snapshots, and files into the frontend canvas.\n\nGoal: ${String(goal).slice(0, 160)}`,
+    note: "Mock mode exercised the backend-to-frontend artifact tunnel.",
+    selected: true,
+  });
+}
+
+function mockChatResponse(content, toolCalls = []) {
+  return {
+    choices: [
+      {
+        message: {
+          role: "assistant",
+          content,
+          tool_calls: toolCalls,
+        },
+      },
+    ],
+  };
+}
+
 export async function createPlan(client, config, state) {
+  if (client.mock) {
+    return [
+      "1. Inspect the request and prefer the local shell when available.",
+      "2. Use one safe allowlisted command if it answers the task.",
+      "3. Return a concise mock-mode result without using external model credentials.",
+    ].join("\n");
+  }
+
   const response = await client.chat.completions.create({
     model: config.model,
     temperature: 0,
@@ -25,9 +135,17 @@ export async function createPlan(client, config, state) {
           state.startUrl ? `Suggested start URL: ${state.startUrl}` : "",
           config.allowedDomains.length > 0 ? `Allowed domains: ${config.allowedDomains.join(", ")}` : "",
           config.allowShellTool
-            ? `Shell tool is enabled in ${config.commandCwd}. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}. For npm/pip/conda/venv setup, explain the need and wait for approval unless policy is allow.`
+            ? `Shell tool is enabled in ${config.commandCwd}. In Docker, this path is mounted as /workspace. Use relative paths or /workspace paths, not absolute host temp paths. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}. For npm/pip/conda/venv setup, explain the need and wait for approval unless policy is allow.`
+            : "",
+          config.allowFileTools
+            ? `Workspace file tools are enabled in ${config.commandCwd}: list_files, read_file, search_files, write_file, apply_patch. Keep all paths workspace-relative, for example plot_fx.svg or docs/report.tex, and avoid secrets.`
             : "",
-          config.allowWrapperTools ? `Agent wrappers are enabled: ${wrapperStatusText()}.` : "",
+          config.allowWrapperTools
+            ? `Agent wrappers are enabled. Use the selected wrapper only: ${normalizeWrapperName(config.preferredWrapper)}. Status: ${wrapperStatusText()}.`
+            : "",
+          "A canvas/artifacts tunnel is available through send_to_canvas. Use it when an output should be highlighted visually, such as screenshots, image files, important markdown, diffs, or generated artifact paths. It is optional for ordinary text answers.",
+          "When the user asks to draw, plot, graph, chart, diagram, create a figure, or visualize something, include a canvas artifact even if the user does not mention canvas. Prefer a small SVG file or concise markdown figure when file tools are available.",
+          "When the user asks for LaTeX, TeX, a paper, manuscript, report, or PDF, plan to create the needed source/assets, compile with the available allowlisted TeX toolchain, and publish the PDF through the canvas tunnel. For subfolder documents, keep outputs beside the source. For generated figures, use pdflatex-compatible formats such as PDF or PNG.",
           "Return a numbered plan only.",
         ]
           .filter(Boolean)
@@ -181,17 +299,114 @@ export async function requestNextStep(client, config, messages) {
     });
   }
 
+  if (config.allowFileTools) {
+    tools.splice(
+      -1,
+      0,
+      {
+        type: "function",
+        function: {
+          name: "list_files",
+          description:
+            "List workspace-local files under the configured working directory. Paths must stay inside the workspace; .git, node_modules, sessions, and sensitive files are skipped.",
+          parameters: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "Workspace-relative path to list. Defaults to ." },
+              maxDepth: { type: "integer", description: "Recursive depth, 1 to 8." },
+              limit: { type: "integer", description: "Maximum entries to return." },
+            },
+            additionalProperties: false,
+          },
+        },
+      },
+      {
+        type: "function",
+        function: {
+          name: "read_file",
+          description:
+            "Read a small UTF-8 workspace file. Secret paths, .git internals, files outside the workspace, binary files, and huge files are blocked.",
+          parameters: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "Workspace-relative file path." },
+            },
+            required: ["path"],
+            additionalProperties: false,
+          },
+        },
+      },
+      {
+        type: "function",
+        function: {
+          name: "search_files",
+          description:
+            "Search small UTF-8 workspace files for literal text. Secret paths, .git internals, node_modules, and huge files are skipped.",
+          parameters: {
+            type: "object",
+            properties: {
+              query: { type: "string" },
+              path: { type: "string", description: "Workspace-relative directory or file. Defaults to ." },
+              caseSensitive: { type: "boolean" },
+              maxResults: { type: "integer" },
+            },
+            required: ["query"],
+            additionalProperties: false,
+          },
+        },
+      },
+      {
+        type: "function",
+        function: {
+          name: "write_file",
+          description:
+            "Create or overwrite a small UTF-8 workspace file. Use mode=create for new files and mode=overwrite only after reading/understanding the existing file. Secret paths, .git, node_modules writes, and outside-workspace paths are blocked. The runtime records before/after hashes and a compact diff.",
+          parameters: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "Workspace-relative file path." },
+              content: { type: "string" },
+              mode: { type: "string", enum: ["create", "overwrite"] },
+            },
+            required: ["path", "content"],
+            additionalProperties: false,
+          },
+        },
+      },
+      {
+        type: "function",
+        function: {
+          name: "apply_patch",
+          description:
+            "Apply a deterministic workspace-local search/replace patch to one small UTF-8 file. Provide exact search and replacement text. The runtime records before/after hashes and a compact diff.",
+          parameters: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "Workspace-relative file path." },
+              search: { type: "string" },
+              replace: { type: "string" },
+              expectedReplacements: { type: "integer" },
+            },
+            required: ["path", "search", "replace"],
+            additionalProperties: false,
+          },
+        },
+      }
+    );
+  }
+
   if (config.allowWrapperTools) {
+    const selectedWrapper = normalizeWrapperName(config.preferredWrapper);
     tools.splice(-1, 0, {
       type: "function",
       function: {
         name: "delegate_agent",
         description:
-          "Ask an installed external coding agent wrapper for advisory help. Use for codebase analysis, implementation strategy, or second-opinion review. The wrapper is instructed to avoid modifying files.",
+          `Ask the selected external coding agent wrapper (${selectedWrapper}) for advisory help. Use for codebase analysis, implementation strategy, or second-opinion review. The wrapper is instructed to avoid modifying files.`,
         parameters: {
           type: "object",
           properties: {
-            wrapper: { type: "string", enum: WRAPPER_NAMES },
+            wrapper: { type: "string", enum: [selectedWrapper] },
             prompt: { type: "string" },
           },
           required: ["wrapper", "prompt"],
@@ -201,12 +416,91 @@ export async function requestNextStep(client, config, messages) {
     });
   }
 
+  tools.splice(-1, 0, {
+    type: "function",
+    function: {
+      name: "send_to_canvas",
+      description:
+        "Send an optional artifact notification to the frontend canvas/artifacts tunnel. Use for important markdown/text, generated images, screenshots, figures, diffs, or workspace file paths the user should preview. Proactively use this for draw/plot/graph/chart/diagram/figure requests even when the user did not mention canvas. This does not replace finish.",
+      parameters: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "Short display title for the canvas item." },
+          kind: {
+            type: "string",
+            enum: ["text", "markdown", "image", "json", "diff", "file", "pdf"],
+            description: "Renderer hint. Use image/file with path, markdown/text/json/diff with content.",
+          },
+          content: { type: "string", description: "Inline text or markdown content to render." },
+          path: { type: "string", description: "Optional workspace-relative file path to preview." },
+          note: { type: "string", description: "Short notification message for the artifact explorer." },
+          selected: { type: "boolean", description: "Whether the frontend should select this item immediately." },
+        },
+        required: ["title", "kind"],
+        additionalProperties: false,
+      },
+    },
+  });
+
+  if (client.mock) {
+    const toolPayload = latestToolPayload(messages);
+    if (toolPayload) {
+      const output = [
+        toolPayload.stdout,
+        toolPayload.stderr,
+        toolPayload.error,
+        toolPayload.reason,
+        toolPayload.path ? `Path: ${toolPayload.path}` : "",
+        toolPayload.change?.diff ? `Diff:\n${toolPayload.change.diff}` : "",
+      ]
+        .filter(Boolean)
+        .join("\n");
+      return mockChatResponse("Mock mode finished after receiving the latest tool result.", [
+        mockToolCall("finish", {
+          result: [
+            "Mock run complete.",
+            toolPayload.toolName ? `Tool: ${toolPayload.toolName}` : "",
+            toolPayload.args?.command ? `Command: ${toolPayload.args.command}` : "",
+            toolPayload.blocked ? "Blocked by guardrail." : "",
+            output ? `Output:\n${output}` : "No command output was returned.",
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        }),
+      ]);
+    }
+
+    const canvasTool = mockCanvasToolForGoal(config.goal);
+    if (canvasTool) {
+      return mockChatResponse("Mock mode will publish a canvas artifact for the UI tunnel.", [canvasTool]);
+    }
+
+    if (config.allowFileTools) {
+      const workspaceTool = mockWorkspaceToolForGoal(config.goal);
+      if (workspaceTool) {
+        return mockChatResponse("Mock mode will exercise a guarded workspace file tool.", [workspaceTool]);
+      }
+    }
+
+    if (config.allowShellTool) {
+      return mockChatResponse("Mock mode will use the guarded shell tool for a non-dangerous local inspection.", [
+        mockToolCall("run_command", { command: mockCommandForGoal(config.goal) }),
+      ]);
+    }
+
+    return mockChatResponse("Mock mode can complete without external model credentials.", [
+      mockToolCall("finish", {
+        result: `Mock run complete for: ${config.goal}`,
+      }),
+    ]);
+  }
+
   return client.chat.completions.create({
     model: config.model,
     temperature: 0,
     tool_choice: "auto",
     parallel_tool_calls: false,
-    messages,
+    messages: prepareMessages(config, messages),
     tools,
   });
 }

package/src/model-routing.js

@@ -17,9 +17,28 @@ const COMPLEXITY_KEYWORDS = [
   "github",
 ];
 
+const COMPLEX_ROUTE_HINTS = [
+  /\blatex\b/i,
+  /\btexlive\b/i,
+  /\bpdflatex\b/i,
+  /\blatexmk\b/i,
+  /\b(manuscript|research paper|white paper|technical report)\b/i,
+  /\bcompile\b.*\bpdf\b/i,
+  /\bwrite\b.*\bpdf\b/i,
+];
+
 export const ROUTING_MODES = ["smart", "fast", "complex", "manual"];
 
 export function getProviderDefaults(provider = "deepseek") {
+  if (provider === "mock") {
+    return {
+      provider: "mock",
+      apiKey: "mock-local",
+      baseURL: "",
+      model: process.env.MOCK_MODEL || "mock-agent",
+    };
+  }
+
   if (provider === "openai") {
     return {
       provider: "openai",
@@ -53,6 +72,13 @@ export function getModelPresets() {
       model: process.env.DEEPSEEK_PRO_MODEL || "deepseek-v4-pro",
       description: "Higher-capacity DeepSeek route for multi-step coding and design tasks.",
     },
+    mock: {
+      id: "mock",
+      label: "Local mock",
+      provider: "mock",
+      model: process.env.MOCK_MODEL || "mock-agent",
+      description: "Credential-free local route for UI, API, and tool-routing smoke tests.",
+    },
     codexPrimary: {
       id: "codexPrimary",
       label: "Codex primary wrapper",
@@ -78,6 +104,9 @@ export function scoreTaskComplexity(goal = "") {
   for (const keyword of COMPLEXITY_KEYWORDS) {
     if (text.includes(keyword)) score += 1;
   }
+  for (const hint of COMPLEX_ROUTE_HINTS) {
+    if (hint.test(goal)) score += 3;
+  }
   return score;
 }
 
@@ -89,6 +118,17 @@ export function selectModelRoute({ routingMode = "smart", provider = "deepseek",
   const mode = normalizeRoutingMode(routingMode);
   const presets = getModelPresets();
 
+  if (provider === "mock") {
+    const defaults = getProviderDefaults("mock");
+    return {
+      routingMode: "manual",
+      provider: defaults.provider,
+      model: model || defaults.model,
+      reason: "Local mock route selected for smoke tests and offline UI/API checks.",
+      complexityScore: scoreTaskComplexity(goal),
+    };
+  }
+
   if (mode === "manual") {
     const defaults = getProviderDefaults(provider);
     return {

package/src/session-store.js

@@ -70,4 +70,8 @@ export class SessionStore {
   screenshotPath(step) {
     return path.join(this.artifactsDir, `step-${String(step).padStart(3, "0")}.png`);
   }
+
+  async remove() {
+    await fs.rm(this.sessionDir, { recursive: true, force: true });
+  }
 }

package/src/tool-wrappers.js

@@ -6,6 +6,7 @@ import { redactSensitiveText } from "./redaction.js";
 const execFile = promisify(execFileCallback);
 
 export const WRAPPER_NAMES = ["codex", "claude", "gemini", "copilot", "qwen"];
+export const DEFAULT_WRAPPER_NAME = "codex";
 
 const BASE_ADVISORY_PROMPT = [
   "You are being called as an advisory wrapper tool inside AgInTiFlow.",
@@ -92,6 +93,11 @@ export function isKnownWrapper(wrapper) {
   return WRAPPER_NAMES.includes(wrapper);
 }
 
+export function normalizeWrapperName(wrapper, fallback = DEFAULT_WRAPPER_NAME) {
+  const candidate = String(wrapper || "").trim().toLowerCase();
+  return isKnownWrapper(candidate) ? candidate : fallback;
+}
+
 export function listAgentWrappers() {
   const presets = getModelPresets();
   return [