feat(ui): profils locaux/LAN OpenAI-compatible dans le first-run et les terminaux (#14)

Câble la surface frontend des profils IA locaux/LAN OpenAI-compatible,
en parité avec l'adapter backend additif (aab4bca).

- domain: types de profil OpenAI-compatible
- first-run: édition/validation du profil dans le FirstRunWizard
- adapters/mock: mock de profil pour les tests
- terminals: rendu des round-trips et erreurs endpoint (role=alert)

Validé QA (frontend GO): typecheck exit 0, vitest 59 fichiers / 566 tests,
0 echec ; couverture timeouts round-trip + erreur endpoint role=alert
prouvees ; pas de regression sur les tests de bail headless.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

frontend/src/features/first-run/FirstRunWizard.test.tsx

@@ -173,6 +173,134 @@ describe("FirstRunWizard (with MockProfileGateway)", () => {
   });
 });
 
+describe("FirstRunWizard — OpenAI-compatible local/LAN profile (ticket #14)", () => {
+  const OLLAMA = "Ollama / OpenAI-compatible local model";
+
+  it("offers the local model as a selectable, pre-filled HTTP config row", async () => {
+    renderWizard();
+    await waitForLoaded();
+
+    expect(screen.getByText(OLLAMA)).toBeTruthy();
+    // The structured HTTP fields are rendered, pre-filled from the reference.
+    expect(
+      (screen.getByLabelText(`${OLLAMA} endpoint`) as HTMLInputElement).value,
+    ).toBe("http://localhost:11434/v1");
+    expect(
+      (screen.getByLabelText(`${OLLAMA} model`) as HTMLInputElement).value,
+    ).toBe("qwen2.5-coder");
+    // Claude/Codex rows must NOT grow HTTP fields (additive, no regression).
+    expect(screen.queryByLabelText("Claude Code endpoint")).toBeNull();
+  });
+
+  it("labels the API key field as an env var NAME and flags a raw key", async () => {
+    renderWizard();
+    await waitForLoaded();
+
+    const apiKey = screen.getByLabelText(`${OLLAMA} api key env`) as HTMLInputElement;
+    // The label/placeholder make the env-var-name intent explicit.
+    expect(apiKey.placeholder.toLowerCase()).toContain("variable name");
+
+    // A raw secret is not a valid env var identifier ⇒ inline error.
+    fireEvent.change(apiKey, { target: { value: "sk-secret-123" } });
+    expect(
+      screen.getByText(/valid env var name \(not the key itself\)/i),
+    ).toBeTruthy();
+
+    // A proper env var name clears the error.
+    fireEvent.change(apiKey, { target: { value: "OPENAI_API_KEY" } });
+    expect(
+      screen.queryByText(/valid env var name \(not the key itself\)/i),
+    ).toBeNull();
+  });
+
+  it("flags an invalid endpoint scheme inline", async () => {
+    renderWizard();
+    await waitForLoaded();
+
+    const endpoint = screen.getByLabelText(`${OLLAMA} endpoint`);
+    fireEvent.change(endpoint, { target: { value: "ftp://oops" } });
+    expect(screen.getByText(/must start with http:\/\/ or https:\/\//i)).toBeTruthy();
+  });
+
+  it("exposes the timeout / tool-guard fields pre-filled from the reference", async () => {
+    renderWizard();
+    await waitForLoaded();
+
+    expect(
+      (screen.getByLabelText(`${OLLAMA} request timeout`) as HTMLInputElement).value,
+    ).toBe("120000");
+    expect(
+      (screen.getByLabelText(`${OLLAMA} connect timeout`) as HTMLInputElement).value,
+    ).toBe("5000");
+    expect(
+      (screen.getByLabelText(`${OLLAMA} max tool iterations`) as HTMLInputElement)
+        .value,
+    ).toBe("16");
+  });
+
+  it("persists edited timeouts / tool-guard round-trip into chatHttp", async () => {
+    const { profile } = renderWizard();
+    await waitForLoaded();
+
+    fireEvent.click(screen.getByLabelText(`use ${OLLAMA}`));
+    fireEvent.change(screen.getByLabelText(`${OLLAMA} request timeout`), {
+      target: { value: "90000" },
+    });
+    fireEvent.change(screen.getByLabelText(`${OLLAMA} connect timeout`), {
+      target: { value: "3000" },
+    });
+    fireEvent.change(screen.getByLabelText(`${OLLAMA} max tool iterations`), {
+      target: { value: "8" },
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Save and continue" }));
+
+    await waitFor(async () => {
+      const saved = await profile.listProfiles();
+      const ollama = saved.find((p) => p.command === "openai-compatible");
+      expect(ollama?.chatHttp?.requestTimeoutMs).toBe(90000);
+      expect(ollama?.chatHttp?.connectTimeoutMs).toBe(3000);
+      expect(ollama?.chatHttp?.maxToolIterations).toBe(8);
+    });
+  });
+
+  it("flags a zero timeout inline (mirror of the backend guard)", async () => {
+    renderWizard();
+    await waitForLoaded();
+
+    fireEvent.change(screen.getByLabelText(`${OLLAMA} request timeout`), {
+      target: { value: "0" },
+    });
+    expect(screen.getByText(/positive integer \(ms\)/i)).toBeTruthy();
+  });
+
+  it("persists the edited HTTP config round-trip when selected and saved", async () => {
+    const { profile } = renderWizard();
+    await waitForLoaded();
+
+    // Select the local model and edit its model name.
+    fireEvent.click(screen.getByLabelText(`use ${OLLAMA}`));
+    fireEvent.change(screen.getByLabelText(`${OLLAMA} model`), {
+      target: { value: "qwen3" },
+    });
+    fireEvent.change(screen.getByLabelText(`${OLLAMA} api key env`), {
+      target: { value: "LAN_KEY" },
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Save and continue" }));
+
+    await waitFor(async () => {
+      const saved = await profile.listProfiles();
+      const ollama = saved.find((p) => p.command === "openai-compatible");
+      expect(ollama?.structuredAdapter).toBe("openAiCompatible");
+      expect(ollama?.chatHttp?.model).toBe("qwen3");
+      expect(ollama?.chatHttp?.apiKeyEnv).toBe("LAN_KEY");
+      // The endpoint round-trips untouched.
+      expect(ollama?.chatHttp?.endpoint).toBe("http://localhost:11434/v1");
+    });
+  });
+});
+
 describe("FirstRunWizard reopening after the first run (forceOpen)", () => {
   /** A gateway whose first run is already done (profiles configured). */
   async function configuredGateway() {

frontend/src/features/first-run/FirstRunWizard.tsx

@@ -15,10 +15,15 @@
  * `./profile`.
  */
 
-import type { AgentProfile } from "@/domain";
+import type { AgentProfile, HttpChatConfig } from "@/domain";
 import { Button, IconButton, Input, Panel, Toolbar, cn } from "@/shared";
 import { useFirstRun, type WizardEntry } from "./useFirstRun";
-import { parseArgs, validateProfile } from "./profile";
+import {
+  defaultHttpChatConfig,
+  parseArgs,
+  validateProfile,
+  type ProfileErrors,
+} from "./profile";
 
 /** A small caption above a control. */
 function Caption({ children }: { children: React.ReactNode }) {
@@ -174,6 +179,133 @@ function ProfileRow({
           onChange={(e) => onChange({ ...profile, args: parseArgs(e.target.value) })}
         />
       </label>
+
+      {profile.structuredAdapter === "openAiCompatible" && (
+        <HttpChatFields profile={profile} errors={errors} onChange={onChange} />
+      )}
     </li>
   );
 }
+
+/** Parses a number field: blank ⇒ `undefined` (backend applies its default). */
+function parseOptInt(raw: string): number | undefined {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return undefined;
+  const n = Number(trimmed);
+  return Number.isFinite(n) ? n : NaN;
+}
+
+/**
+ * The OpenAI-compatible (local/LAN) HTTP config section: endpoint, model, the
+ * *name* of the API-key env var (never the key), and optional timeouts / tool
+ * guard. Rendered only for a `openAiCompatible` profile; edits flow back through
+ * `onChange` as a patched `chatHttp`.
+ */
+function HttpChatFields({
+  profile,
+  errors,
+  onChange,
+}: {
+  profile: AgentProfile;
+  errors: ProfileErrors;
+  onChange: (p: AgentProfile) => void;
+}) {
+  const http = profile.chatHttp ?? defaultHttpChatConfig();
+  const patch = (next: Partial<HttpChatConfig>) =>
+    onChange({ ...profile, chatHttp: { ...http, ...next } });
+
+  return (
+    <fieldset className="mt-1 flex flex-col gap-2 rounded-md border border-border/70 p-2">
+      <legend className="px-1 text-xs font-medium text-muted">
+        Local / LAN model (OpenAI-compatible)
+      </legend>
+
+      <label className="flex flex-col gap-1">
+        <Caption>Endpoint</Caption>
+        <Input
+          aria-label={`${profile.name} endpoint`}
+          value={http.endpoint}
+          placeholder="http://localhost:11434/v1"
+          invalid={Boolean(errors.endpoint)}
+          onChange={(e) => patch({ endpoint: e.target.value })}
+        />
+        {errors.endpoint && (
+          <small className="text-xs text-danger">{errors.endpoint}</small>
+        )}
+      </label>
+
+      <label className="flex flex-col gap-1">
+        <Caption>Model</Caption>
+        <Input
+          aria-label={`${profile.name} model`}
+          value={http.model}
+          placeholder="qwen2.5-coder"
+          invalid={Boolean(errors.model)}
+          onChange={(e) => patch({ model: e.target.value })}
+        />
+        {errors.model && <small className="text-xs text-danger">{errors.model}</small>}
+      </label>
+
+      <label className="flex flex-col gap-1">
+        <Caption>API key — environment variable name (never the key itself)</Caption>
+        <Input
+          aria-label={`${profile.name} api key env`}
+          value={http.apiKeyEnv ?? ""}
+          placeholder="e.g. OPENAI_API_KEY (variable name, not the secret)"
+          invalid={Boolean(errors.apiKeyEnv)}
+          onChange={(e) => {
+            const v = e.target.value.trim();
+            patch({ apiKeyEnv: v.length === 0 ? undefined : v });
+          }}
+        />
+        {errors.apiKeyEnv && (
+          <small className="text-xs text-danger">{errors.apiKeyEnv}</small>
+        )}
+      </label>
+
+      <div className="flex flex-wrap gap-2">
+        <label className="flex min-w-[8rem] flex-1 flex-col gap-1">
+          <Caption>Request timeout (ms)</Caption>
+          <Input
+            aria-label={`${profile.name} request timeout`}
+            value={http.requestTimeoutMs?.toString() ?? ""}
+            inputMode="numeric"
+            invalid={Boolean(errors.requestTimeoutMs)}
+            onChange={(e) => patch({ requestTimeoutMs: parseOptInt(e.target.value) })}
+          />
+          {errors.requestTimeoutMs && (
+            <small className="text-xs text-danger">{errors.requestTimeoutMs}</small>
+          )}
+        </label>
+
+        <label className="flex min-w-[8rem] flex-1 flex-col gap-1">
+          <Caption>Connect timeout (ms)</Caption>
+          <Input
+            aria-label={`${profile.name} connect timeout`}
+            value={http.connectTimeoutMs?.toString() ?? ""}
+            inputMode="numeric"
+            invalid={Boolean(errors.connectTimeoutMs)}
+            onChange={(e) => patch({ connectTimeoutMs: parseOptInt(e.target.value) })}
+          />
+          {errors.connectTimeoutMs && (
+            <small className="text-xs text-danger">{errors.connectTimeoutMs}</small>
+          )}
+        </label>
+
+        <label className="flex min-w-[8rem] flex-1 flex-col gap-1">
+          <Caption>Max tool iterations</Caption>
+          <Input
+            aria-label={`${profile.name} max tool iterations`}
+            value={http.maxToolIterations?.toString() ?? ""}
+            inputMode="numeric"
+            invalid={Boolean(errors.maxToolIterations)}
+            onChange={(e) => patch({ maxToolIterations: parseOptInt(e.target.value) })}
+          />
+          {errors.maxToolIterations && (
+            <small className="text-xs text-danger">{errors.maxToolIterations}</small>
+          )}
+        </label>
+      </div>
+    </fieldset>
+  );
+}

frontend/src/features/first-run/profile.test.ts

@@ -7,12 +7,15 @@ import { describe, it, expect } from "vitest";
 
 import type { AgentProfile } from "@/domain";
 import {
+  defaultHttpChatConfig,
   defaultInjection,
   emptyCustomProfile,
   isProfileValid,
   isRelativeSafe,
   isValidEnvVar,
+  isValidHttpUrl,
   parseArgs,
+  validateHttpChatConfig,
   validateProfile,
 } from "./profile";
 
@@ -93,6 +96,99 @@ describe("validateProfile / isProfileValid", () => {
   });
 });
 
+describe("isValidHttpUrl", () => {
+  it("accepts http/https endpoints", () => {
+    expect(isValidHttpUrl("http://localhost:11434/v1")).toBe(true);
+    expect(isValidHttpUrl("https://lan.host:8080/v1")).toBe(true);
+  });
+  it("rejects empty, non-http and other schemes", () => {
+    expect(isValidHttpUrl("")).toBe(false);
+    expect(isValidHttpUrl("   ")).toBe(false);
+    expect(isValidHttpUrl("ftp://host")).toBe(false);
+    expect(isValidHttpUrl("localhost:11434")).toBe(false);
+    // Leading whitespace fails the raw prefix check, mirroring the backend.
+    expect(isValidHttpUrl("  http://host")).toBe(false);
+  });
+});
+
+describe("validateHttpChatConfig", () => {
+  it("a well-formed local model config is valid", () => {
+    expect(validateHttpChatConfig(defaultHttpChatConfig())).toEqual({});
+  });
+  it("reports a bad endpoint scheme and an empty model", () => {
+    const errors = validateHttpChatConfig({ endpoint: "ftp://x", model: "  " });
+    expect(errors.endpoint).toBeDefined();
+    expect(errors.model).toBeDefined();
+  });
+  it("apiKeyEnv must be an env var NAME, never a raw key", () => {
+    // A plausible raw key contains characters illegal in an env var identifier.
+    const withKey = validateHttpChatConfig({
+      endpoint: "http://host",
+      model: "m",
+      apiKeyEnv: "sk-abc123",
+    });
+    expect(withKey.apiKeyEnv).toBeDefined();
+    // A valid identifier passes; blank/undefined is allowed (optional).
+    expect(
+      validateHttpChatConfig({
+        endpoint: "http://host",
+        model: "m",
+        apiKeyEnv: "OPENAI_API_KEY",
+      }).apiKeyEnv,
+    ).toBeUndefined();
+    expect(
+      validateHttpChatConfig({ endpoint: "http://host", model: "m" }).apiKeyEnv,
+    ).toBeUndefined();
+  });
+  it("rejects zero / non-integer timeouts and tool-iteration guard", () => {
+    const errors = validateHttpChatConfig({
+      endpoint: "http://host",
+      model: "m",
+      requestTimeoutMs: 0,
+      connectTimeoutMs: -1,
+      maxToolIterations: 1.5,
+    });
+    expect(errors.requestTimeoutMs).toBeDefined();
+    expect(errors.connectTimeoutMs).toBeDefined();
+    expect(errors.maxToolIterations).toBeDefined();
+  });
+});
+
+describe("validateProfile for openAiCompatible profiles", () => {
+  function ollama(overrides: Partial<AgentProfile> = {}): AgentProfile {
+    return base({
+      name: "Ollama",
+      command: "openai-compatible",
+      structuredAdapter: "openAiCompatible",
+      chatHttp: defaultHttpChatConfig(),
+      ...overrides,
+    });
+  }
+  it("the reference local-model profile is valid", () => {
+    expect(validateProfile(ollama())).toEqual({});
+    expect(isProfileValid(ollama())).toBe(true);
+  });
+  it("surfaces chatHttp field errors through the profile validator", () => {
+    const errors = validateProfile(
+      ollama({ chatHttp: { endpoint: "nope", model: "" } }),
+    );
+    expect(errors.endpoint).toBeDefined();
+    expect(errors.model).toBeDefined();
+    expect(isProfileValid(ollama({ chatHttp: { endpoint: "nope", model: "m" } }))).toBe(
+      false,
+    );
+  });
+  it("a missing chatHttp on an openAiCompatible profile is invalid", () => {
+    const errors = validateProfile(ollama({ chatHttp: undefined }));
+    expect(errors.endpoint).toBeDefined();
+    expect(errors.model).toBeDefined();
+  });
+  it("does not touch validation of Claude/Codex (non-structured-http) profiles", () => {
+    // A plain profile with no structuredAdapter never triggers chatHttp checks.
+    expect(validateProfile(base())).toEqual({});
+  });
+});
+
 describe("defaultInjection", () => {
   it("produces a sensible default per strategy", () => {
     expect(defaultInjection("conventionFile")).toEqual({

frontend/src/features/first-run/profile.ts

@@ -7,12 +7,26 @@
 import type {
   AgentProfile,
   ContextInjection,
+  HttpChatConfig,
   InjectionStrategy,
 } from "@/domain";
 
 /** A field-keyed validation error map (empty ⇒ valid). */
 export type ProfileErrors = Partial<
-  Record<"name" | "command" | "target" | "flag" | "var", string>
+  Record<
+    | "name"
+    | "command"
+    | "target"
+    | "flag"
+    | "var"
+    | "endpoint"
+    | "model"
+    | "apiKeyEnv"
+    | "requestTimeoutMs"
+    | "connectTimeoutMs"
+    | "maxToolIterations",
+    string
+  >
 >;
 
 /** Whether a path is a relative, traversal-free file name (mirror of backend). */
@@ -29,6 +43,58 @@ export function isValidEnvVar(v: string): boolean {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(v);
 }
 
+/**
+ * Whether a string is a valid `http://`/`https://` endpoint (mirror of the
+ * backend `HttpChatConfig::new`: non-empty once trimmed, and the raw value
+ * starts with `http://` or `https://`).
+ */
+export function isValidHttpUrl(v: string): boolean {
+  if (v.trim().length === 0) return false;
+  return v.startsWith("http://") || v.startsWith("https://");
+}
+
+/**
+ * Whether a value is an acceptable positive-integer timeout/guard (mirror of the
+ * backend, which rejects `0` and only ever holds `u32`/`u16`). `undefined` means
+ * "left blank" and is valid (the backend applies its own default).
+ */
+function isValidPositiveInt(value: number | undefined, max: number): boolean {
+  if (value === undefined) return true;
+  return Number.isInteger(value) && value > 0 && value <= max;
+}
+
+const MAX_U32 = 0xffff_ffff;
+const MAX_U16 = 0xffff;
+
+/**
+ * Validates an {@link HttpChatConfig} draft the way the backend
+ * `HttpChatConfig::new` would, so the wizard can surface errors before any
+ * `invoke`. Returns an empty object when the draft is valid.
+ */
+export function validateHttpChatConfig(c: HttpChatConfig): ProfileErrors {
+  const errors: ProfileErrors = {};
+  if (!isValidHttpUrl(c.endpoint)) {
+    errors.endpoint = "Endpoint must start with http:// or https://.";
+  }
+  if (c.model.trim().length === 0) {
+    errors.model = "Model is required.";
+  }
+  // The API key field holds the NAME of an environment variable, never a key.
+  if (c.apiKeyEnv !== undefined && c.apiKeyEnv.length > 0 && !isValidEnvVar(c.apiKeyEnv)) {
+    errors.apiKeyEnv = "Must be a valid env var name (not the key itself).";
+  }
+  if (!isValidPositiveInt(c.requestTimeoutMs, MAX_U32)) {
+    errors.requestTimeoutMs = "Must be a positive integer (ms).";
+  }
+  if (!isValidPositiveInt(c.connectTimeoutMs, MAX_U32)) {
+    errors.connectTimeoutMs = "Must be a positive integer (ms).";
+  }
+  if (!isValidPositiveInt(c.maxToolIterations, MAX_U16)) {
+    errors.maxToolIterations = "Must be a positive integer.";
+  }
+  return errors;
+}
+
 /**
  * Validates a profile draft the way the backend would, so the wizard can surface
  * errors before any `invoke`. Returns an empty object when the draft is valid.
@@ -48,6 +114,17 @@ export function validateProfile(p: AgentProfile): ProfileErrors {
   } else if (ci.strategy === "env") {
     if (!isValidEnvVar(ci.var)) errors.var = "Must be a valid env var identifier.";
   }
+
+  // An OpenAI-compatible profile additionally carries an HTTP chat config; the
+  // backend refuses to persist it unless it is well-formed, so mirror that here.
+  if (p.structuredAdapter === "openAiCompatible") {
+    if (!p.chatHttp) {
+      errors.endpoint = "Endpoint must start with http:// or https://.";
+      errors.model = "Model is required.";
+    } else {
+      Object.assign(errors, validateHttpChatConfig(p.chatHttp));
+    }
+  }
   return errors;
 }
 
@@ -73,6 +150,21 @@ export function defaultInjection(strategy: InjectionStrategy): ContextInjection
   }
 }
 
+/**
+ * A sensible default {@link HttpChatConfig} for a fresh OpenAI-compatible
+ * profile draft — pre-fills a local Ollama endpoint so the form starts valid.
+ * Mirrors the backend reference profile (`http://localhost:11434/v1`).
+ */
+export function defaultHttpChatConfig(): HttpChatConfig {
+  return {
+    endpoint: "http://localhost:11434/v1",
+    model: "qwen2.5-coder",
+    requestTimeoutMs: 120_000,
+    connectTimeoutMs: 5_000,
+    maxToolIterations: 16,
+  };
+}
+
 /** A fresh, empty custom-profile draft (id minted client-side). */
 export function emptyCustomProfile(): AgentProfile {
   return {