jev-agent-tools 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -9,10 +9,25 @@ modules are not a stable library API.
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-10-02
+
+### Added
+
+- Interactive configuration for pi and omp: first-launch offer, `/jev-setup`, masked
+  key entry, `--jev-skip-setup`, `--jev-url` and `--jev-model`. Configuration applies
+  immediately; optional saving uses a private file outside the repository and stores the
+  key in plaintext. No dialog appears in print, JSON, RPC or sub-agent sessions.
+
+### Changed
+
+- Release publication uses trusted publishing (OIDC) without a temporary npm token.
+- Document the npm release's verified pi 1.0.0 integration, simulated-service smoke
+  scope and non-blocking `@sinclair/typebox` packaging warning.
+
 ## [0.1.3] - 2026-10-02
 
-Initial npm release candidate, under the name `jev-agent-tools`. Versions 0.1.0,
-0.1.1 and 0.1.2 were tagged but never published; their outcomes are recorded below.
+First npm release, published as `jev-agent-tools`. Versions 0.1.0, 0.1.1 and 0.1.2
+were tagged but never published; their outcomes are recorded below.
 
 ### Added
 
@@ -59,7 +74,8 @@ Tagged but never published to npm: the unscoped package name was rejected.
 
 Tagged but never published to npm: the publish workflow failed before upload.
 
-[Unreleased]: https://github.com/NomenAK/jev-tools/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/NomenAK/jev-tools/compare/v0.1.4...HEAD
+[0.1.4]: https://github.com/NomenAK/jev-tools/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/NomenAK/jev-tools/compare/v0.1.0...v0.1.3
 [0.1.2]: https://github.com/NomenAK/jev-tools/tree/v0.1.2
 [0.1.1]: https://github.com/NomenAK/jev-tools/tree/v0.1.1

package/README.md

@@ -9,23 +9,45 @@ Install through your host's package manager. The npm package is `jev-agent-tools
 ### pi
 
 ```sh
-pi install npm:jev-agent-tools@0.1.3
+pi install npm:jev-agent-tools@0.1.4
 # Project-local installation:
-pi install -l npm:jev-agent-tools@0.1.3
+pi install -l npm:jev-agent-tools@0.1.4
 ```
 
 ### omp
 
 ```sh
-omp plugin install jev-agent-tools@0.1.3
+omp plugin install jev-agent-tools@0.1.4
 ```
 
 ### Requirements and compatibility
 
 Requires Node.js 24 or later. Supported host baselines are pi 0.87.1 and omp 18.4.10. These are support baselines, not claims that every later version has been individually validated. omp uses its Bun runtime; Node.js is also required for Node-based project checks. Git and, for optional command evidence, Bash must be available. Optional native parsers and file-search acceleration may be unavailable on some platforms; affected tools report their limitations.
 
+The published `jev-agent-tools@0.1.3` package was also checked with **pi 1.0.0** on Linux under Node.js 24.15.0: npm installation, TypeScript checking against the host types, all six tools in the actual CLI, and reading-guide injection passed. The CLI smoke used a simulated conversation provider and Jev endpoint; it verifies host integration, not live model accuracy or every tool scenario.
+
+**pi 1.0.0 packaging warning:** the package declares `@sinclair/typebox` in `dependencies`, while pi expects host-provided extension modules in `peerDependencies` with a `"*"` range. pi warns that separately installed copies can create duplicate runtime modules. The warning did not prevent the smoke from completing; it remains a packaging issue, not a claim of warning-free compatibility.
+
 ## Configure
 
+### Interactive setup
+
+In the main interactive terminal of pi or omp, a first launch without configuration offers **Configure now / Later**. Run `/jev-setup` at any time to change the endpoint, model or key. The key is typed in a masked field and is never passed as a command-line argument. Choose **This session only** (nothing is written) or **Save for future sessions**. Cancelling at any step changes nothing.
+
+| Flag | Effect |
+|---|---|
+| `--jev-skip-setup` | Suppress the first-launch offer for this run; `/jev-setup` still works. |
+| `--jev-url <url>` | Endpoint for this run. |
+| `--jev-model <name>` | Jev model for this run, not the conversation model. |
+
+No dialog appears in print, JSON or RPC modes, or in sub-agents; configure those with the environment variables below. Changes apply immediately, without restarting the host.
+
+**Precedence per field:** environment variable, then launch flag, then this session's setup, then saved configuration, then the default model `openjev`. A field set by the environment or a flag is shown as controlled and is never saved.
+
+**Saved configuration** lives outside the repository at `$XDG_CONFIG_HOME/jev-agent-tools/config.json` (default `~/.config/jev-agent-tools/config.json`), in a private directory (`0700`) with a private file (`0600`). **The key is stored in plaintext, not encrypted.** Storage that is a symlink, group/world-accessible, not owned by you or malformed is refused rather than overwritten.
+
+### Environment variables
+
 Set these before starting the host, using your own endpoint and credentials:
 
 ```sh
@@ -35,7 +57,7 @@ export JEV_TOOLS_API_KEY="${YOUR_JEV_API_KEY}"
 export JEV_TOOLS_MODEL="openjev"
 ```
 
-`YOUR_*` placeholders are inputs you supply, not additional product settings. Configuration is read when the extension loads; restart the host after changing it.
+`YOUR_*` placeholders are inputs you supply, not additional product settings. Environment variables are read when the extension loads and take precedence over everything else.
 
 | Variable | Meaning |
 |---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-agent-tools",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "license": "MIT",
   "description": "Six evidence-oriented tools for pi and omp coding agents, compatible with the Jev API format.",

package/src/configuration.ts

@@ -0,0 +1,267 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { createJevClient } from "./jev/client.ts";
+import type { JevClient } from "./jev/types.ts";
+
+export interface ConfigurationValues {
+  url: string;
+  apiKey: string;
+  model: string;
+}
+
+type SavedConfiguration = Partial<ConfigurationValues>;
+const fields = ["url", "apiKey", "model"] as const;
+const defaults: ConfigurationValues = { url: "", apiKey: "", model: "openjev" };
+const storageError = () =>
+  new Error(
+    "Cannot read or save Jev configuration. Check that the configuration directory and config.json are owned by you, private, regular storage without symlinks, and contain valid configuration JSON.",
+  );
+
+function nonempty(value: string | undefined): value is string {
+  return value !== undefined && value.trim().length > 0;
+}
+
+function validate(values: ConfigurationValues): void {
+  let validUrl = false;
+  try {
+    const url = new URL(values.url);
+    validUrl =
+      /^https?:\/\//i.test(values.url) &&
+      (url.protocol === "http:" || url.protocol === "https:") &&
+      url.hostname !== "" &&
+      url.username === "" &&
+      url.password === "";
+  } catch {
+    // Keep user-controlled URL and credentials out of error messages.
+  }
+  if (
+    !validUrl ||
+    !nonempty(values.apiKey) ||
+    /[^\x20-\x7e\x80-\xff]/.test(values.apiKey) ||
+    !nonempty(values.model)
+  ) {
+    throw new Error(
+      "Jev configuration requires a full HTTP(S) URL without embedded credentials, a nonempty HTTP-header-compatible API key, and a nonempty model.",
+    );
+  }
+}
+
+/** Effective configuration and its client move together, only after a save succeeds. */
+export class ConfigController {
+  private readonly environment: SavedConfiguration = {};
+  private flags: SavedConfiguration = {};
+  private saved: SavedConfiguration = {};
+  private session: SavedConfiguration = {};
+  private readonly directory: string;
+  private initialization: Promise<void> | undefined;
+  private currentClient: JevClient | undefined;
+
+  constructor(options: { env?: NodeJS.ProcessEnv; directory?: string } = {}) {
+    const env = options.env ?? process.env;
+    for (const [field, name] of [
+      ["url", "JEV_TOOLS_URL"],
+      ["apiKey", "JEV_TOOLS_API_KEY"],
+      ["model", "JEV_TOOLS_MODEL"],
+    ] as const) {
+      if (nonempty(env[name])) this.environment[field] = env[name];
+    }
+    const base =
+      nonempty(env.XDG_CONFIG_HOME) && isAbsolute(env.XDG_CONFIG_HOME)
+        ? env.XDG_CONFIG_HOME
+        : join(homedir(), ".config");
+    this.directory = resolve(
+      options.directory ?? join(base, "jev-agent-tools"),
+    );
+    if (nonempty(this.environment.url) && nonempty(this.environment.apiKey)) {
+      const effective = this.values();
+      validate(effective);
+      this.currentClient = createJevClient(effective);
+    }
+  }
+
+  get client(): JevClient | undefined {
+    return this.currentClient;
+  }
+
+  initialize(flags: { url?: string; model?: string }): Promise<void> {
+    if (this.initialization) return this.initialization;
+    this.initialization = this.load(flags).catch((error: unknown) => {
+      this.initialization = undefined;
+      throw error;
+    });
+    return this.initialization;
+  }
+
+  values(): ConfigurationValues {
+    return {
+      ...defaults,
+      ...this.saved,
+      ...this.session,
+      ...this.flags,
+      ...this.environment,
+    };
+  }
+
+  locked(field: keyof ConfigurationValues): boolean {
+    return (
+      this.environment[field] !== undefined || this.flags[field] !== undefined
+    );
+  }
+
+  async apply(values: ConfigurationValues, persist: boolean): Promise<void> {
+    if (!this.initialization) {
+      throw new Error("Initialize Jev configuration before applying changes.");
+    }
+    await this.initialization;
+    const session = { ...this.session };
+    for (const field of fields) {
+      if (!this.locked(field)) session[field] = values[field];
+    }
+    const effective = {
+      ...defaults,
+      ...this.saved,
+      ...session,
+      ...this.flags,
+      ...this.environment,
+    };
+    validate(effective);
+    const saved = { ...this.saved, ...session };
+    if (persist) await this.save(saved);
+    const previous = this.values();
+    this.session = session;
+    if (persist) this.saved = saved;
+    if (fields.some((field) => previous[field] !== effective[field])) {
+      this.currentClient?.clearCache();
+      this.currentClient = createJevClient(effective);
+    } else {
+      this.currentClient ??= createJevClient(effective);
+    }
+  }
+
+  private async load(flags: { url?: string; model?: string }): Promise<void> {
+    const saved = await this.readSaved();
+    const supplied: SavedConfiguration = {};
+    if (nonempty(flags.url)) supplied.url = flags.url;
+    if (nonempty(flags.model)) supplied.model = flags.model;
+    const effective = {
+      ...defaults,
+      ...saved,
+      ...supplied,
+      ...this.environment,
+    };
+    if (nonempty(effective.url) && nonempty(effective.apiKey)) {
+      validate(effective);
+      this.currentClient?.clearCache();
+      this.currentClient = createJevClient(effective);
+    }
+    this.saved = saved;
+    this.flags = supplied;
+  }
+
+  private async checkDirectory(): Promise<boolean> {
+    // Check ancestors too: recursive mkdir and path-based reads must not follow symlinks.
+    let path = this.directory;
+    let exists = true;
+    while (true) {
+      try {
+        const stat = await lstat(path);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) throw storageError();
+        if (
+          path === this.directory &&
+          ((stat.mode & 0o077) !== 0 ||
+            (process.getuid && stat.uid !== process.getuid()))
+        ) {
+          throw storageError();
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException)?.code !== "ENOENT")
+          throw storageError();
+        if (path === this.directory) exists = false;
+      }
+      const parent = dirname(path);
+      if (parent === path) break;
+      path = parent;
+    }
+    return exists;
+  }
+
+  private async readSaved(): Promise<SavedConfiguration> {
+    try {
+      if (!(await this.checkDirectory())) return {};
+      const path = join(this.directory, "config.json");
+      try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink()) throw storageError();
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return {};
+        throw error;
+      }
+      const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+      try {
+        const stat = await file.stat();
+        if (
+          !stat.isFile() ||
+          stat.nlink !== 1 ||
+          (stat.mode & 0o077) !== 0 ||
+          (process.getuid && stat.uid !== process.getuid())
+        ) {
+          throw storageError();
+        }
+        const value: unknown = JSON.parse(await file.readFile("utf8"));
+        if (
+          value === null ||
+          typeof value !== "object" ||
+          Array.isArray(value) ||
+          Object.entries(value).some(
+            ([key, entry]) =>
+              !fields.some((field) => field === key) ||
+              typeof entry !== "string",
+          )
+        ) {
+          throw storageError();
+        }
+        return value as SavedConfiguration;
+      } finally {
+        await file.close();
+      }
+    } catch {
+      throw storageError();
+    }
+  }
+
+  private async save(values: SavedConfiguration): Promise<void> {
+    let temporary: string | undefined;
+    try {
+      if (!(await this.checkDirectory())) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+      }
+      // Refuse to replace malformed, insecure or newly introduced storage.
+      await this.readSaved();
+      temporary = join(this.directory, `.config-${randomUUID()}.tmp`);
+      const file = await open(
+        temporary,
+        constants.O_WRONLY |
+          constants.O_CREAT |
+          constants.O_EXCL |
+          constants.O_NOFOLLOW,
+        0o600,
+      );
+      try {
+        await file.writeFile(`${JSON.stringify(values, null, 2)}\n`, "utf8");
+        await file.sync();
+      } finally {
+        await file.close();
+      }
+      await this.readSaved();
+      await rename(temporary, join(this.directory, "config.json"));
+      temporary = undefined;
+    } catch {
+      throw storageError();
+    } finally {
+      if (temporary) await unlink(temporary).catch(() => {});
+    }
+  }
+}

package/src/host-tui.d.ts

@@ -0,0 +1,14 @@
+// Runtime implementations are supplied by the pi/omp extension loader.
+declare module "@earendil-works/pi-tui" {
+  export function matchesKey(
+    data: string,
+    key: "enter" | "escape" | "backspace" | "ctrl+c" | "ctrl+u",
+  ): boolean;
+  export const decodePrintableKey:
+    | ((data: string) => string | undefined)
+    | undefined;
+  export const decodeKittyPrintable:
+    | ((data: string) => string | undefined)
+    | undefined;
+  export function isKeyRelease(data: string): boolean;
+}

package/src/index.ts

@@ -1,9 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ConfigController } from "./configuration.ts";
 import { Guide } from "./guide.ts";
 import { detectHost } from "./host.ts";
-import { createJevClient, readConfig } from "./jev/client.ts";
 import { RunEnd, type RunEndHost } from "./run-end.ts";
 import { readSessionLimits, Session } from "./session.ts";
+import { Setup } from "./setup.ts";
 import { createAskTool } from "./tools/ask.ts";
 import { createAskFilesTool } from "./tools/ask-files.ts";
 import { createCheckDiffTool } from "./tools/check-diff.ts";
@@ -12,8 +13,7 @@ import { createLocateTool } from "./tools/locate.ts";
 import { createSelectTestsTool } from "./tools/select-tests.ts";
 export default function extension(api: ExtensionAPI & { pi?: unknown }): void {
   const host = detectHost(api);
-  const config = readConfig(process.env);
-  const client = config ? createJevClient(config) : undefined;
+  const config = new ConfigController();
   const runtime = {
     session: new Session(readSessionLimits(process.env)),
     guide: new Guide(host),
@@ -22,14 +22,22 @@ export default function extension(api: ExtensionAPI & { pi?: unknown }): void {
   api.on("session_start", async () => {
     runtime.session.reset();
     runtime.guide.reset();
-    client?.clearCache();
+    config.client?.clearCache();
     if (host.isOmp) {
       const active = api.getActiveTools();
       if (!active.includes("find"))
         await api.setActiveTools([...active, "jev_find_files"]);
     }
   });
-  const dependencies = { client, host, runtime, exec: api.exec.bind(api) };
+  new Setup(config).attach(api);
+  const dependencies = {
+    get client() {
+      return config.client;
+    },
+    host,
+    runtime,
+    exec: api.exec.bind(api),
+  };
   new RunEnd(dependencies).attach(api as unknown as RunEndHost);
   api.registerTool(createAskTool(dependencies));
   api.registerTool(createSelectTestsTool(dependencies));

package/src/secret-input.ts

@@ -0,0 +1,222 @@
+type SecretKey = "enter" | "escape" | "ctrl+c" | "backspace";
+
+export interface SecretKeyHelpers {
+  matchesKey(data: string, key: SecretKey): boolean;
+  decodePrintableKey(data: string): string | undefined;
+  isKeyRelease(data: string): boolean;
+}
+
+export interface SecretUIContext {
+  ui: {
+    custom<T>(
+      factory: (
+        tui: { requestRender(): void },
+        theme: unknown,
+        keybindings: unknown,
+        done: (result: T) => void,
+      ) => MaskedSecretInput,
+    ): Promise<T>;
+  };
+}
+
+const pasteStart = "\x1b[200~";
+const pasteEnd = "\x1b[201~";
+
+/** A dedicated input: no editor, clipboard, history, undo stack or kill ring. */
+export class MaskedSecretInput {
+  #characters: number[] = [];
+  #pasting = false;
+  #pasteLength = 0;
+  #invalidPaste = false;
+  #pasteRejected = false;
+  #pasteMarker = "";
+  #closed = false;
+  #required = false;
+  #title: string;
+  #existing: boolean;
+  #keys: SecretKeyHelpers;
+  #done: (result: string | undefined) => void;
+  #requestRender: () => void;
+
+  constructor(
+    title: string,
+    existing: boolean,
+    keys: SecretKeyHelpers,
+    done: (result: string | undefined) => void,
+    requestRender: () => void,
+  ) {
+    this.#title = title.replace(/[^\x20-\x7e]/g, "?");
+    this.#existing = existing;
+    this.#keys = keys;
+    this.#done = done;
+    this.#requestRender = requestRender;
+  }
+
+  render(width: number): string[] {
+    const columns = Number.isFinite(width) ? Math.max(0, Math.floor(width)) : 0;
+    return [
+      this.#title,
+      `Key: ${"*".repeat(Math.min(this.#characters.length, columns))}`,
+      this.#existing ? "Enter: save (empty keeps current key)" : "Enter: save",
+      "Esc / Ctrl+C: cancel",
+      this.#pasteRejected
+        ? "Paste rejected: use a single line without controls."
+        : "",
+      this.#required ? "A key is required." : "",
+    ].map((line) => line.slice(0, columns));
+  }
+
+  handleInput(data: string): void {
+    if (this.#closed) return;
+    if (this.#pasting) {
+      // Keep only a possible delimiter prefix, never a second secret buffer.
+      let offset = 0;
+      for (const character of data) {
+        offset += character.length;
+        while (
+          this.#pasteMarker &&
+          character !== pasteEnd[this.#pasteMarker.length]
+        ) {
+          this.#append(this.#pasteMarker);
+          this.#pasteMarker = "";
+        }
+        if (character === pasteEnd[this.#pasteMarker.length]) {
+          this.#pasteMarker += character;
+          if (this.#pasteMarker === pasteEnd) {
+            this.#pasteMarker = "";
+            if (this.#invalidPaste) {
+              this.#characters.fill(0, this.#pasteLength);
+              this.#characters.length = this.#pasteLength;
+              this.#pasteRejected = true;
+            }
+            this.#invalidPaste = false;
+            this.#pasting = false;
+            this.handleInput(data.slice(offset));
+            break;
+          }
+        } else if (this.#pasting) {
+          this.#append(character);
+        }
+      }
+      this.#requestRender();
+      return;
+    }
+    const start = data.indexOf(pasteStart);
+    if (start !== -1) {
+      if (start > 0) this.handleInput(data.slice(0, start));
+      if (this.#closed) return;
+      this.#pasting = true;
+      this.#pasteLength = this.#characters.length;
+      this.#invalidPaste = false;
+      this.#pasteRejected = false;
+      this.handleInput(data.slice(start + pasteStart.length));
+      return;
+    }
+    if (this.#keys.isKeyRelease(data)) return;
+    if (
+      this.#keys.matchesKey(data, "escape") ||
+      this.#keys.matchesKey(data, "ctrl+c")
+    ) {
+      this.#finish(undefined);
+      return;
+    }
+    if (this.#keys.matchesKey(data, "enter")) {
+      if (!this.#characters.length && !this.#existing) {
+        this.#required = true;
+        this.#requestRender();
+        return;
+      }
+      // Strings supplied by the terminal and returned to the caller are immutable;
+      // JavaScript cannot guarantee their erasure. Our retained numeric buffer can.
+      const result = this.#characters
+        .map((codepoint) => String.fromCodePoint(codepoint))
+        .join("");
+      this.#finish(result);
+      return;
+    }
+    if (this.#keys.matchesKey(data, "backspace")) {
+      if (this.#characters.length) {
+        this.#characters[this.#characters.length - 1] = 0;
+        this.#characters.pop();
+      }
+      this.#required = false;
+      this.#requestRender();
+      return;
+    }
+    const printable = this.#keys.decodePrintableKey(data);
+    if (printable !== undefined) this.#append(printable);
+    else if (
+      [...data].every((character) => {
+        const code = character.codePointAt(0) as number;
+        return code >= 0x20 && (code < 0x7f || code > 0x9f);
+      })
+    )
+      this.#append(data);
+    this.#requestRender();
+  }
+
+  #append(text: string): void {
+    for (const character of text) {
+      const code = character.codePointAt(0) as number;
+      if (this.#pasting && (code < 0x20 || (code >= 0x7f && code <= 0x9f))) {
+        this.#invalidPaste = true;
+        continue;
+      }
+      this.#characters.push(character.codePointAt(0) as number);
+    }
+    this.#required = false;
+  }
+
+  #finish(result: string | undefined): void {
+    this.dispose();
+    this.#done(result);
+  }
+
+  invalidate(): void {
+    // Rendering has no cache or theme-dependent state.
+  }
+
+  dispose(): void {
+    this.#characters.fill(0);
+    this.#characters.length = 0;
+    this.#pasteMarker = "";
+    this.#pasting = false;
+    this.#pasteLength = 0;
+    this.#invalidPaste = false;
+    this.#pasteRejected = false;
+    this.#required = false;
+    this.#closed = true;
+  }
+}
+
+/** Caller must restrict this to the host's interactive TUI mode. */
+export async function readSecret(
+  ctx: SecretUIContext,
+  title: string,
+  existing: boolean,
+): Promise<string | undefined> {
+  // Both hosts provide this module at runtime; pi exports decodeKittyPrintable and
+  // omp exports decodePrintableKey, so static package resolution cannot be used.
+  const hostKeys = await import("@earendil-works/pi-tui");
+  const decodePrintableKey =
+    hostKeys.decodeKittyPrintable ?? hostKeys.decodePrintableKey;
+  if (!decodePrintableKey) {
+    throw new Error(
+      "This host cannot decode printable keys for masked Jev setup; use environment variables.",
+    );
+  }
+  const keys: SecretKeyHelpers = { ...hostKeys, decodePrintableKey };
+  let input: MaskedSecretInput | undefined;
+  try {
+    return await ctx.ui.custom<string | undefined>(
+      (tui, _theme, _keybindings, done) => {
+        input = new MaskedSecretInput(title, existing, keys, done, () =>
+          tui.requestRender(),
+        );
+        return input;
+      },
+    );
+  } finally {
+    input?.dispose();
+  }
+}

package/src/setup.ts

@@ -0,0 +1,162 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { ConfigController, ConfigurationValues } from "./configuration.ts";
+import { readSecret } from "./secret-input.ts";
+
+type SetupContext = Pick<ExtensionContext, "ui" | "hasUI"> & {
+  mode?: string;
+  agent?: { kind: string };
+};
+type SetupAPI = Pick<
+  ExtensionAPI,
+  "on" | "registerFlag" | "getFlag" | "registerCommand"
+>;
+
+/** Setup never sends credentials to the conversation or starts a model turn. */
+export class Setup {
+  private offered = false;
+  private busy = false;
+  private readonly config: ConfigController;
+  private readonly promptSecret: typeof readSecret;
+  constructor(
+    config: ConfigController,
+    promptSecret: typeof readSecret = readSecret,
+  ) {
+    this.config = config;
+    this.promptSecret = promptSecret;
+  }
+
+  attach(api: SetupAPI): void {
+    api.registerFlag("jev-skip-setup", {
+      type: "boolean",
+      default: false,
+      description: "Skip the interactive Jev configuration offer",
+    });
+    api.registerFlag("jev-url", {
+      type: "string",
+      description:
+        "Jev endpoint URL for this run (environment takes precedence)",
+    });
+    api.registerFlag("jev-model", {
+      type: "string",
+      description: "Jev model for this run, not the conversation model",
+    });
+    const initialize = async () => {
+      const url = api.getFlag("jev-url");
+      const model = api.getFlag("jev-model");
+      await this.config.initialize({
+        ...(typeof url === "string" ? { url } : {}),
+        ...(typeof model === "string" ? { model } : {}),
+      });
+    };
+    api.on("session_start", async (_event, ctx) => {
+      try {
+        await initialize();
+        if (
+          !this.interactive(ctx) ||
+          this.offered ||
+          this.config.client ||
+          api.getFlag("jev-skip-setup")
+        )
+          return;
+        this.offered = true;
+        const choice = await ctx.ui.select(
+          "Jev Tools needs an endpoint and API key",
+          ["Configure now", "Later"],
+        );
+        if (choice === "Configure now") await this.configure(ctx);
+      } catch (error) {
+        if (this.interactive(ctx)) ctx.ui.notify(this.message(error), "error");
+      }
+    });
+    api.registerCommand("jev-setup", {
+      description: "Configure the Jev endpoint, model and API key",
+      handler: async (_args, ctx) => {
+        if (!this.interactive(ctx)) {
+          ctx.ui.notify(
+            "Jev setup requires the main interactive terminal. Use JEV_TOOLS_URL, JEV_TOOLS_MODEL and JEV_TOOLS_API_KEY for headless runs.",
+            "warning",
+          );
+          return;
+        }
+        try {
+          await initialize();
+          await this.configure(ctx);
+        } catch (error) {
+          ctx.ui.notify(this.message(error), "error");
+        }
+      },
+    });
+  }
+
+  private interactive(ctx: SetupContext): boolean {
+    return ctx.mode === "tui" && ctx.hasUI && ctx.agent?.kind !== "sub";
+  }
+
+  private message(error: unknown): string {
+    // Configuration errors are deliberately credential-free.
+    return error instanceof Error
+      ? error.message
+      : "Jev configuration failed; the previous configuration was kept.";
+  }
+
+  private async configure(ctx: SetupContext): Promise<void> {
+    if (this.busy) return;
+    this.busy = true;
+    try {
+      const values: ConfigurationValues = this.config.values();
+      for (const field of ["url", "model"] as const) {
+        if (this.config.locked(field)) {
+          ctx.ui.notify(
+            `Jev ${field} is controlled by the environment or a launch flag; change it before restarting.`,
+            "info",
+          );
+          continue;
+        }
+        const label =
+          field === "url"
+            ? "Complete Jev endpoint URL"
+            : "Jev model (not the conversation model)";
+        const answer = await ctx.ui.input(
+          label,
+          values[field] ||
+            (field === "model"
+              ? "openjev"
+              : "https://your-service.example/v1/systemone"),
+        );
+        if (answer === undefined) return;
+        values[field] = answer.trim() || values[field];
+      }
+      if (this.config.locked("apiKey")) {
+        ctx.ui.notify(
+          "The Jev API key is supplied by the environment and will not be saved.",
+          "info",
+        );
+      } else {
+        const key = await this.promptSecret(
+          ctx,
+          "Jev API key",
+          Boolean(values.apiKey),
+        );
+        if (key === undefined) return;
+        values.apiKey = key || values.apiKey;
+      }
+      const storage = await ctx.ui.select("Apply Jev configuration", [
+        "This session only",
+        "Save for future sessions (editable values and plaintext key in a private global file)",
+      ]);
+      if (storage === undefined) return;
+      await this.config.apply(values, storage !== "This session only");
+      ctx.ui.notify(
+        storage === "This session only"
+          ? "Jev configuration applied for this session; no file was written."
+          : "Jev configuration applied and saved outside the repository. The stored key is plaintext, not encrypted.",
+        "info",
+      );
+    } finally {
+      this.busy = false;
+    }
+  }
+}

package/src/texts/configuration.ts

@@ -1,2 +1,2 @@
 export const NOT_CONFIGURED =
-  "jev-tools is not configured: set JEV_TOOLS_URL and JEV_TOOLS_API_KEY.";
+  "jev-tools is not configured: set JEV_TOOLS_URL and JEV_TOOLS_API_KEY, or run /jev-setup in the main interactive terminal.";

package/src/tools/ask-files.ts

@@ -42,12 +42,8 @@ export interface AskFilesDetails {
   skipped: string[];
   envelope: Envelope;
 }
-export function createAskFilesTool({
-  client,
-  host,
-  runtime,
-  exec: execute,
-}: ToolDependencies) {
+export function createAskFilesTool(dependencies: ToolDependencies) {
+  const { host, runtime, exec: execute } = dependencies;
   return {
     name: "jev_ask_files",
     label: "Jev ask files",
@@ -70,6 +66,7 @@ export function createAskFilesTool({
       _update: unknown,
       ctx: { cwd: string } & GuideContext,
     ) {
+      const client = dependencies.client;
       const started = performance.now();
       const exec = shareGitInventory(execute);
       const totals = {

package/src/tools/ask.ts

@@ -67,12 +67,8 @@ export const askParameters = Type.Object(
 );
 export type AskArgs = Static<typeof askParameters>;
 
-export function createAskTool({
-  client,
-  host,
-  runtime,
-  exec: execute,
-}: ToolDependencies) {
+export function createAskTool(dependencies: ToolDependencies) {
+  const { host, runtime, exec: execute } = dependencies;
   const { isOmp, names } = host;
   const allowCommand = process.env.JEV_TOOLS_ALLOW_COMMAND !== "0";
   const parameters = allowCommand
@@ -120,6 +116,7 @@ export function createAskTool({
         };
       };
     }> {
+      const client = dependencies.client;
       const started = performance.now();
       const exec = shareGitInventory(execute);
       const finish = (

package/src/tools/check-diff.ts

@@ -83,12 +83,8 @@ function unitLabel(unit: EvidenceUnit): string {
     .slice(0, 8);
   return `${unit.file}${range ? `:${range.start}-${range.end}` : ""} ${unit.name} [${fingerprint}]`;
 }
-export function createCheckDiffTool({
-  client,
-  host,
-  runtime,
-  exec: execute,
-}: ToolDependencies) {
+export function createCheckDiffTool(dependencies: ToolDependencies) {
+  const { host, runtime, exec: execute } = dependencies;
   return {
     name: "jev_check_diff",
     label: "Jev check diff",
@@ -110,6 +106,7 @@ export function createCheckDiffTool({
       _update: unknown,
       ctx: { cwd: string } & GuideContext,
     ) {
+      const client = dependencies.client;
       const exec = shareGitInventory(execute);
       if (args.check === "docs" || args.check === "spec") {
         const deps = { client, host, runtime, exec };

package/src/tools/find.ts

@@ -46,12 +46,8 @@ export const findParameters = Type.Object(
   { additionalProperties: false },
 );
 export type FindArgs = Static<typeof findParameters>;
-export function createFindFilesTool({
-  client,
-  host,
-  runtime,
-  exec: execute,
-}: ToolDependencies) {
+export function createFindFilesTool(dependencies: ToolDependencies) {
+  const { host, runtime, exec: execute } = dependencies;
   return {
     name: "jev_find_files",
     label: "Jev find files",
@@ -77,6 +73,7 @@ export function createFindFilesTool({
       _update: unknown,
       ctx: { cwd: string } & GuideContext,
     ) {
+      const client = dependencies.client;
       const started = performance.now();
       const exec = shareGitInventory(execute);
       const totals = {

package/src/tools/locate.ts

@@ -43,9 +43,10 @@ const parameters = Type.Object(
 type LocateArgs = Static<typeof parameters>;
 
 export function createLocateTool(
-  { client, host, runtime, exec: execute }: ToolDependencies,
+  dependencies: ToolDependencies,
   loadParser: () => Promise<SyntaxParser | undefined> = loadSyntaxParser,
 ) {
+  const { host, runtime, exec: execute } = dependencies;
   return {
     name: "jev_locate_in_file",
     label: "Jev locate in file",
@@ -72,6 +73,7 @@ export function createLocateTool(
       _update: unknown,
       ctx: { cwd: string } & GuideContext,
     ) {
+      const client = dependencies.client;
       const started = performance.now();
       const exec = shareGitInventory(execute);
       const results: Judgment[] = [];

package/src/tools/select-tests.ts

@@ -104,12 +104,8 @@ function makeCandidate(
   };
 }
 
-export function createSelectTestsTool({
-  client,
-  host,
-  runtime,
-  exec: execute,
-}: ToolDependencies) {
+export function createSelectTestsTool(dependencies: ToolDependencies) {
+  const { host, runtime, exec: execute } = dependencies;
   return {
     name: "jev_select_tests",
     label: "Jev select tests",
@@ -128,6 +124,7 @@ export function createSelectTestsTool({
       _update: unknown,
       ctx: { cwd: string } & GuideContext,
     ) {
+      const client = dependencies.client;
       const started = performance.now();
       const exec = shareGitInventory(execute);
       const totals = {