jev-agent-tools 0.1.3 → 0.2.0

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/session.ts

@@ -1,4 +1,5 @@
 import type { Envelope } from "./core/output.ts";
+import type { JudgmentOptions } from "./jev/types.ts";
 import type { Result } from "./result.ts";
 
 export interface SessionLimits {
@@ -53,6 +54,10 @@ export class Session {
     cacheHits: 0,
   };
   private readonly limits: SessionLimits;
+  // USD gate: at most one admitted request in flight under a USD limit.
+  private gateHeld = false;
+  private gateEpoch = 0;
+  private gateWaiters = new Set<() => void>();
   constructor(limits: SessionLimits) {
     this.limits = limits;
   }
@@ -75,6 +80,56 @@ export class Session {
     this.counters.questions += questions;
     return { ok: true };
   }
+  /**
+   * Under a USD limit, admit one request at a time so each admission sees the
+   * cost reported by every earlier request; without it, concurrent batches are
+   * all admitted before any cost arrives and overshoot the limit. Only the
+   * final admitted request can then exceed the limit, as documented.
+   *
+   * `awaitAdmission` reserves the gate atomically: the availability check and
+   * `gateHeld = true` run with no await between them, so two callers cannot
+   * both pass. It resolves to a release function that the client calls on
+   * every exit path (response, refusal, failure, abort); release is
+   * idempotent and ignores a gate that `reset()` already replaced.
+   */
+  requestGate(): Pick<JudgmentOptions, "awaitAdmission"> {
+    return {
+      awaitAdmission: async (signal) => {
+        if (this.limits.maxUsd === undefined) return undefined;
+        while (this.gateHeld) {
+          signal?.throwIfAborted();
+          await new Promise<void>((resolve, reject) => {
+            const onAbort = () => {
+              this.gateWaiters.delete(wake);
+              reject(signal?.reason);
+            };
+            const wake = () => {
+              signal?.removeEventListener("abort", onAbort);
+              resolve();
+            };
+            this.gateWaiters.add(wake);
+            signal?.addEventListener("abort", onAbort, { once: true });
+          });
+        }
+        signal?.throwIfAborted();
+        this.gateHeld = true;
+        const epoch = this.gateEpoch;
+        let released = false;
+        return () => {
+          if (released || epoch !== this.gateEpoch) return;
+          released = true;
+          this.gateHeld = false;
+          this.wakeGateWaiters();
+        };
+      },
+    };
+  }
+  // Every waiter rechecks; the first to run reserves, the rest wait again.
+  private wakeGateWaiters(): void {
+    const waiters = [...this.gateWaiters];
+    this.gateWaiters.clear();
+    for (const wake of waiters) wake();
+  }
   recordUsage(usage: { costUsd: number }): void {
     this.counters.costUsd += usage.costUsd;
   }
@@ -93,6 +148,10 @@ export class Session {
     return { ...this.counters };
   }
   reset(): void {
+    // A new session generation: outstanding release functions become no-ops.
+    this.gateEpoch++;
+    this.gateHeld = false;
+    this.wakeGateWaiters();
     this.counters = {
       calls: 0,
       questions: 0,

package/src/setup.ts

@@ -0,0 +1,170 @@
+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;
+        // Host event deadlines bound work, not the time needed to find credentials.
+        // Return before waiting for input so omp clears the handler's UI abort timer.
+        void this.offer(ctx).catch((error: unknown) => {
+          ctx.ui.notify(this.message(error), "error");
+        });
+      } 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 offer(ctx: SetupContext): Promise<void> {
+    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);
+  }
+
+  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

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "@sinclair/typebox";
 import { collectAskFiles } from "../adapters/ask-files.ts";
+import { canonicalPath } from "../adapters/canonical-path.ts";
 import { shareGitInventory } from "../adapters/git-inventory.ts";
 import { hostUsage } from "../adapters/usage.ts";
 import { compileAsks, readAsks, reverseQuestions } from "../core/asks.ts";
@@ -42,12 +43,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 +67,8 @@ export function createAskFilesTool({
       _update: unknown,
       ctx: { cwd: string } & GuideContext,
     ) {
+      const client = dependencies.client;
+      const cwd = await canonicalPath(ctx.cwd);
       const started = performance.now();
       const exec = shareGitInventory(execute);
       const totals = {
@@ -102,12 +101,7 @@ export function createAskFilesTool({
       if (!client) return finish({ refusal: NOT_CONFIGURED });
       const plan = compileAsks(args.asks, { surface: "files" });
       if (!plan.ok) return finish({ refusal: plan.error });
-      const collected = await collectAskFiles(
-        ctx.cwd,
-        args.paths,
-        signal,
-        exec,
-      );
+      const collected = await collectAskFiles(cwd, args.paths, signal, exec);
       if (!collected.ok) return finish({ refusal: collected.error });
       skipped = collected.skipped;
       if (!collected.files.length && skipped.length)
@@ -118,6 +112,7 @@ export function createAskFilesTool({
       let budget: BudgetRefusal | undefined;
       const options = {
         signal,
+        ...runtime.session.requestGate(),
         beforeRequest: (count: number) => {
           if (args.max_calls !== undefined && sent >= args.max_calls) {
             budget = {
@@ -151,7 +146,7 @@ export function createAskFilesTool({
           const integrity = checkIntegrity(state, plan.asks, [
             {
               ...file.identity,
-              insertedPath: resolve(ctx.cwd, state.path),
+              insertedPath: resolve(cwd, state.path),
               content: state.content,
               insertedSha256: createHash("sha256")
                 .update(state.content)