@lattices/cli 0.6.0 → 0.6.1

package/bin/cli/helpers.ts

@@ -0,0 +1,105 @@
+import { execSync } from "node:child_process";
+
+export interface ExecOpts {
+  encoding?: string;
+  stdio?: string | string[];
+  cwd?: string;
+  [key: string]: any;
+}
+
+export function run(cmd: string, opts: ExecOpts = {}): string {
+  return execSync(cmd, { encoding: "utf8", ...opts } as any).trim();
+}
+
+export function runQuiet(cmd: string): string | null {
+  try {
+    return run(cmd, { stdio: "pipe" });
+  } catch {
+    return null;
+  }
+}
+
+export function parseFlagValue(args: string[], name: string): string | undefined {
+  const prefix = `--${name}=`;
+  const exact = `--${name}`;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith(prefix)) return args[i].slice(prefix.length);
+    if (args[i] === exact) return args[i + 1];
+  }
+  return undefined;
+}
+
+export function parseOptionalNumber(args: string[], ...names: string[]): number | undefined {
+  for (const name of names) {
+    const raw = parseFlagValue(args, name);
+    if (raw === undefined || raw === "") continue;
+    const value = Number(raw);
+    if (Number.isFinite(value)) return value;
+  }
+  return undefined;
+}
+
+export function hasFlag(args: string[], name: string): boolean {
+  return args.includes(`--${name}`);
+}
+
+export function nonFlagArgs(args: string[]): string[] {
+  const valueFlags = new Set([
+    "id", "state", "ttl", "ttlMs", "x", "y", "gap", "placement", "style", "name", "scale",
+    "hud-url", "hudUrl", "hud-html", "hudHTML", "hudHtml", "hud-title", "hudTitle",
+    "hud-width", "hudWidth", "hud-height", "hudHeight", "width", "height",
+    "manifest", "root", "max-depth", "maxDepth", "read-access", "readAccess",
+    "pause", "limit", "session", "app", "name", "bundle-id", "bundleId", "bundleIdentifier",
+    "path", "app-path", "appPath", "title", "filename", "run-id", "runId",
+    "text", "tty", "wid", "treatment", "mode", "phase", "transport", "capture",
+    "appearance", "cursor-style", "cursorStyle", "shape", "marker-shape", "markerShape",
+    "cursor-shape", "cursorShape", "angle-deg", "angleDeg", "rotation-deg", "rotationDeg",
+    "rotation", "angle", "color", "duration-ms", "durationMs",
+    "type-interval-ms", "typeIntervalMs", "typing-interval-ms", "typingIntervalMs", "label",
+    "caption", "treatment-label", "treatmentLabel", "variant",
+    "caption-title", "captionTitle", "caption-body", "captionBody",
+    "caption-detail", "captionDetail", "caption-tags", "captionTags",
+    "caption-mode", "captionMode", "caption-eyebrow", "captionEyebrow",
+    "caption-lead-ms", "captionLeadMs", "caption-sound", "captionSound",
+    "caption-placement", "captionPlacement", "caption-margin", "captionMargin",
+    "caption-x", "captionX", "caption-y", "captionY",
+    "caption-x-ratio", "captionXRatio", "caption-y-ratio", "captionYRatio",
+    "caption-left-ratio", "captionLeftRatio", "caption-top-ratio", "captionTopRatio",
+    "sound", "sfx",
+    "trail", "effect", "path-style", "pathStyle", "motion", "easing", "velocity",
+    "trajectory", "curve", "arc", "glow", "bloom", "idle", "settle", "presence",
+    "edge", "edge-effect", "edgeEffect", "arrival",
+    "fps", "w", "h", "stop-file", "stopFile", "finished-file", "finishedFile",
+    "timeout-ms", "timeoutMs", "duration",
+    "x", "y", "x-ratio", "xRatio", "y-ratio", "yRatio",
+    "relative-x", "relativeX", "relative-y", "relativeY",
+    "window-x", "windowX", "window-y", "windowY", "button",
+  ]);
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) {
+      out.push(arg);
+      continue;
+    }
+    const flagName = arg.slice(2);
+    if (!arg.includes("=") && valueFlags.has(flagName)) i++;
+  }
+  return out;
+}
+
+export function relativeTime(iso: string): string {
+  const ms = Date.now() - new Date(iso).getTime();
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return "just now";
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  return `${d}d ago`;
+}
+
+export function pause(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/bin/cli/layer.ts

@@ -0,0 +1,178 @@
+import { withDaemon, type DaemonClient } from "./daemon.ts";
+
+export async function layerCommand(sub?: string, ...rest: string[]): Promise<void> {
+  await withDaemon(async (client) => {
+    const { daemonCall } = client;
+
+    if (sub === "create") {
+      await layerCreateCommand(client, rest);
+      return;
+    }
+    if (sub === "snap") {
+      await layerSnapCommand(client, rest[0]);
+      return;
+    }
+    if (sub === "session" || sub === "sessions") {
+      await layerSessionCommand(client, rest[0]);
+      return;
+    }
+    if (sub === "clear") {
+      await daemonCall("session.layers.clear");
+      console.log("Cleared all session layers.");
+      return;
+    }
+    if (sub === "delete" || sub === "rm") {
+      if (!rest[0]) { console.log("Usage: lattices layer delete <name>"); return; }
+      await daemonCall("session.layers.delete", { name: rest[0] });
+      console.log(`Deleted session layer "${rest[0]}".`);
+      return;
+    }
+
+    if (sub === undefined || sub === null || sub === "") {
+      const result = await daemonCall("layers.list") as any;
+      if (!result.layers.length) {
+        console.log("No layers configured.");
+        return;
+      }
+      console.log("Layers:\n");
+      for (const layer of result.layers) {
+        const active = layer.index === result.active ? " \x1b[32m● active\x1b[0m" : "";
+        console.log(`  [${layer.index}] ${layer.label}  (${layer.projectCount} projects)${active}`);
+      }
+      return;
+    }
+    const idx = parseInt(sub, 10);
+    if (!isNaN(idx)) {
+      await daemonCall("layer.activate", { index: idx, mode: "launch" });
+      console.log(`Activated layer ${idx}`);
+    } else {
+      await daemonCall("layer.activate", { name: sub, mode: "launch" });
+      console.log(`Activated layer "${sub}"`);
+    }
+  });
+}
+
+// ── Layer create: build a session layer from window specs ────────────
+// Usage: lattices layer create <name> [wid:123 wid:456 ...]
+//        lattices layer create <name> --json '[{"app":"Chrome","tile":"left"},...]'
+export async function layerCreateCommand(client: DaemonClient, args: string[]): Promise<void> {
+  const { daemonCall } = client;
+  const name = args[0];
+  if (!name) {
+    console.log("Usage: lattices layer create <name> [wid:123 ...] [--json '<specs>']");
+    return;
+  }
+
+  const jsonIdx = args.indexOf("--json");
+  if (jsonIdx !== -1 && args[jsonIdx + 1]) {
+    // JSON mode: parse window specs with tile positions
+    const specs = JSON.parse(args[jsonIdx + 1]) as Array<{
+      wid?: number; app?: string; title?: string; tile?: string;
+    }>;
+
+    // Collect wids, resolve app-based specs
+    const windowIds: number[] = [];
+    const windows: Array<{ app: string; contentHint?: string }> = [];
+    const tiles: Array<{ wid?: number; app?: string; title?: string; tile: string }> = [];
+
+    for (const spec of specs) {
+      if (spec.wid) {
+        windowIds.push(spec.wid);
+        if (spec.tile) tiles.push({ wid: spec.wid, tile: spec.tile });
+      } else if (spec.app) {
+        windows.push({ app: spec.app, contentHint: spec.title });
+        if (spec.tile) tiles.push({ app: spec.app, title: spec.title, tile: spec.tile });
+      }
+    }
+
+    await daemonCall("session.layers.create", {
+      name,
+      ...(windowIds.length ? { windowIds } : {}),
+      ...(windows.length ? { windows } : {}),
+    }) as any;
+
+    console.log(`Created session layer "${name}" with ${specs.length} window(s).`);
+
+    // Apply tile positions
+    for (const t of tiles) {
+      try {
+        await daemonCall("window.place", {
+          ...(t.wid ? { wid: t.wid } : { app: t.app, title: t.title }),
+          placement: t.tile,
+        });
+      } catch { /* window may not be resolved yet */ }
+    }
+
+    if (tiles.length) console.log(`Tiled ${tiles.length} window(s).`);
+    return;
+  }
+
+  // Simple wid mode: lattices layer create <name> wid:123 wid:456
+  const wids = args.slice(1)
+    .filter(a => a.startsWith("wid:"))
+    .map(a => parseInt(a.slice(4), 10))
+    .filter(n => !isNaN(n));
+
+  await daemonCall("session.layers.create", {
+    name,
+    ...(wids.length ? { windowIds: wids } : {}),
+  }) as any;
+
+  console.log(`Created session layer "${name}"${wids.length ? ` with ${wids.length} window(s)` : ""}.`);
+}
+
+// ── Layer snap: snapshot current visible windows into a session layer ─
+export async function layerSnapCommand(client: DaemonClient, name?: string): Promise<void> {
+  const { daemonCall } = client;
+  const layerName = name || `snap-${new Date().toISOString().slice(11, 19).replace(/:/g, "")}`;
+
+  // Get all current windows
+  const windows = await daemonCall("windows.list") as any[];
+  const visibleWids = windows
+    .filter((w: any) => !w.isMinimized && w.app !== "lattices")
+    .map((w: any) => w.wid);
+
+  if (!visibleWids.length) {
+    console.log("No visible windows to snapshot.");
+    return;
+  }
+
+  await daemonCall("session.layers.create", {
+    name: layerName,
+    windowIds: visibleWids,
+  });
+
+  console.log(`Snapped ${visibleWids.length} window(s) → session layer "${layerName}".`);
+}
+
+// ── Layer session: list or switch session layers ─────────────────────
+export async function layerSessionCommand(client: DaemonClient, nameOrIndex?: string): Promise<void> {
+  const { daemonCall } = client;
+  const result = await daemonCall("session.layers.list") as any;
+
+  if (!nameOrIndex) {
+    // List session layers
+    if (!result.layers.length) {
+      console.log("No session layers. Create one with: lattices layer create <name>");
+      return;
+    }
+    console.log("Session layers:\n");
+    for (let i = 0; i < result.layers.length; i++) {
+      const l = result.layers[i];
+      const active = i === result.activeIndex ? " \x1b[32m● active\x1b[0m" : "";
+      const winCount = l.windows?.length || 0;
+      console.log(`  [${i}] ${l.name}  (${winCount} windows)${active}`);
+    }
+    return;
+  }
+
+  // Switch by index or name
+  const idx = parseInt(nameOrIndex, 10);
+  if (!isNaN(idx)) {
+    await daemonCall("session.layers.switch", { index: idx });
+    console.log(`Switched to session layer ${idx}.`);
+  } else {
+    await daemonCall("session.layers.switch", { name: nameOrIndex });
+    console.log(`Switched to session layer "${nameOrIndex}".`);
+  }
+}

package/bin/cli/runs.ts

@@ -0,0 +1,43 @@
+import { hasFlag, nonFlagArgs, parseFlagValue } from "./helpers.ts";
+import { withDaemon } from "./daemon.ts";
+
+function runLine(run: any): string {
+  const count = Array.isArray(run.artifacts) ? run.artifacts.length : 0;
+  const completed = run.completedAt ? ` completed=${run.completedAt}` : "";
+  return `  ${run.id}  ${run.state || "?"}  artifacts=${count}  ${run.title || "Untitled run"}${completed}`;
+}
+
+export async function runsCommand(rawArgs: string[] = []): Promise<void> {
+  const jsonFlag = hasFlag(rawArgs, "json");
+  const positional = nonFlagArgs(rawArgs);
+  const sub = positional[0];
+
+  await withDaemon(async ({ daemonCall }) => {
+    if (sub && sub !== "list") {
+      const run = await daemonCall("runs.get", { id: sub }) as any;
+      if (jsonFlag) {
+        console.log(JSON.stringify(run, null, 2));
+        return;
+      }
+      console.log(runLine(run));
+      console.log(`  artifacts: ${run.artifactDirectoryPath}`);
+      for (const artifact of run.artifacts || []) {
+        console.log(`    ${artifact.kind}  ${artifact.path}`);
+      }
+      return;
+    }
+
+    const limit = Number(parseFlagValue(rawArgs, "limit") || 20);
+    const runs = await daemonCall("runs.list", { limit }) as any[];
+    if (jsonFlag) {
+      console.log(JSON.stringify(runs, null, 2));
+      return;
+    }
+    if (!runs.length) {
+      console.log("No runs yet.");
+      return;
+    }
+    console.log(`Runs (${runs.length}):\n`);
+    for (const run of runs) console.log(runLine(run));
+  });
+}

package/bin/cli/search.ts

@@ -0,0 +1,141 @@
+import { relativeTime } from "./helpers.ts";
+import { withDaemon, type DaemonClient } from "./daemon.ts";
+
+export interface SearchResult {
+  score: number;
+  window: any;
+  tabs: { tab: number; cwd: string; title: string; hasClaude: boolean; tmuxSession: string }[];
+  reasons: string[];
+}
+
+export interface SearchOptions {
+  sources?: string[];
+  after?: string;
+  before?: string;
+  recency?: boolean;
+  mode?: string;
+}
+
+async function searchWithClient(client: DaemonClient, query: string, opts: SearchOptions = {}): Promise<SearchResult[]> {
+  const { daemonCall } = client;
+  const params: Record<string, any> = { query };
+  if (opts.sources) params.sources = opts.sources;
+  if (opts.after) params.after = opts.after;
+  if (opts.before) params.before = opts.before;
+  if (opts.recency !== undefined) params.recency = opts.recency;
+  if (opts.mode) params.mode = opts.mode;
+  const hits = await daemonCall("lattices.search", params, 10000) as any[];
+  return hits.map((w: any) => ({
+    score: w.score || 0,
+    window: w,
+    tabs: (w.terminalTabs || []).map((t: any) => ({
+      tab: t.tabIndex, cwd: t.cwd, title: t.tabTitle, hasClaude: t.hasClaude, tmuxSession: t.tmuxSession,
+    })),
+    reasons: w.matchSources || [],
+  }));
+}
+
+export async function search(query: string, opts: SearchOptions = {}): Promise<SearchResult[]> {
+  return withDaemon(client => searchWithClient(client, query, opts));
+}
+
+export async function deepSearch(query: string): Promise<SearchResult[]> {
+  return search(query, { sources: ["all"] });
+}
+
+export function printResults(ranked: SearchResult[]): void {
+  if (!ranked.length) return;
+  for (const r of ranked) {
+    const w = r.window;
+    const age = w.lastInteraction ? ` \x1b[2m${relativeTime(w.lastInteraction)}\x1b[0m` : "";
+    console.log(`  \x1b[1m${w.app}\x1b[0m  "${w.title}"  wid:${w.wid}  score:${r.score}  (${r.reasons.join(", ")})${age}`);
+    for (const t of r.tabs) {
+      const claude = t.hasClaude ? " \x1b[32m●\x1b[0m" : "";
+      const tmux = t.tmuxSession ? ` \x1b[36m[${t.tmuxSession}]\x1b[0m` : "";
+      console.log(`    tab ${t.tab}: ${t.cwd || t.title}${claude}${tmux}`);
+    }
+    if (w.ocrSnippet) console.log(`    ocr: "${w.ocrSnippet}"`);
+  }
+  console.log();
+}
+
+export async function searchCommand(
+  query: string | undefined,
+  flags: Set<string>,
+  rawArgs: string[] = []
+): Promise<void> {
+  if (!query) {
+    console.log("Usage: lattices search <query> [--quick | --terminal | --all | --deep | --sources=... | --after=... | --before=... | --json | --wid]");
+    return;
+  }
+
+  const opts: SearchOptions = {};
+
+  const sourcesFlag = rawArgs.find(a => a.startsWith("--sources="));
+  if (sourcesFlag) {
+    opts.sources = sourcesFlag.slice("--sources=".length).split(",");
+  } else if (flags.has("--all") || flags.has("--deep")) {
+    opts.sources = ["all"];
+  } else if (flags.has("--quick")) {
+    opts.sources = ["titles", "apps", "sessions"];
+  } else if (flags.has("--terminal")) {
+    opts.sources = ["terminals"];
+  }
+
+  const afterFlag = rawArgs.find(a => a.startsWith("--after="));
+  if (afterFlag) opts.after = afterFlag.slice("--after=".length);
+  const beforeFlag = rawArgs.find(a => a.startsWith("--before="));
+  if (beforeFlag) opts.before = beforeFlag.slice("--before=".length);
+
+  if (flags.has("--no-recency")) opts.recency = false;
+
+  const ranked = await search(query, opts);
+  const jsonOut = flags.has("--json");
+  const widOnly = flags.has("--wid");
+
+  if (jsonOut) {
+    console.log(JSON.stringify(ranked.map(r => ({
+      wid: r.window.wid, app: r.window.app, title: r.window.title,
+      score: r.score, reasons: r.reasons, tabs: r.tabs, ocrSnippet: r.window.ocrSnippet,
+    })), null, 2));
+    return;
+  }
+
+  if (widOnly) {
+    for (const r of ranked) console.log(r.window.wid);
+    return;
+  }
+
+  if (!ranked.length) {
+    console.log(`No results for "${query}"`);
+    return;
+  }
+
+  printResults(ranked);
+}
+
+export async function placeCommand(query?: string, tilePosition?: string): Promise<void> {
+  if (!query) {
+    console.log("Usage: lattices place <query> [position]");
+    return;
+  }
+
+  await withDaemon(async (client) => {
+    const { daemonCall } = client;
+    const ranked = await searchWithClient(client, query, { sources: ["all"] });
+
+    if (!ranked.length) {
+      console.log(`No window matching "${query}"`);
+      return;
+    }
+
+    const pos = tilePosition || "bottom-right";
+    const win = ranked[0].window;
+    await daemonCall("window.focus", { wid: win.wid });
+    await daemonCall("intents.execute", {
+      intent: "tile_window",
+      slots: { position: pos, wid: win.wid }
+    }, 3000);
+    console.log(`${win.app} "${win.title}" (wid:${win.wid}) → ${pos}`);
+  });
+}

package/bin/cli/session.ts

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+import { basename, resolve } from "node:path";
+import { runQuiet } from "./helpers.ts";
+
+export function pathHash(dir: string): string {
+  return createHash("sha256").update(resolve(dir)).digest("hex").slice(0, 6);
+}
+
+export function toSessionName(dir: string): string {
+  const base = basename(dir).replace(/[^a-zA-Z0-9_-]/g, "-");
+  return `${base}-${pathHash(dir)}`;
+}
+
+export function esc(str: string): string {
+  return str.replace(/'/g, "'\\''");
+}
+
+export function slugify(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/\.app$/i, "")
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "app";
+}
+
+export function sessionExists(name: string): boolean {
+  return runQuiet(`tmux has-session -t "${name}" 2>&1`) !== null;
+}
+
+export function toGroupSessionName(groupId: string): string {
+  return `lattices-group-${groupId}`;
+}

package/bin/client.ts

@@ -1,5 +1,6 @@
 // Public API — re-exports from daemon-client for a cleaner import path.
-// Usage: import { daemonCall, isDaemonRunning } from '@lattices/cli'
+// Usage: import { daemonCall, isDaemonRunning } from '@arach/lattices'
+// Also published as @lattices/cli for back-compat.
 
 export { daemonCall, isDaemonRunning } from "./daemon-client.ts";
 export {

package/bin/cua.ts

@@ -0,0 +1,26 @@
+export {
+  click,
+  computerClickParamsSchema,
+  computerClickTransportSchema,
+  computerMagicCursorParamsSchema,
+  computerTreatmentSchema,
+  createCuaClient,
+  cua,
+  cursorEdgeSchema,
+  cursorGlowSchema,
+  cursorIdleSchema,
+  cursorMotionSchema,
+  cursorShapeSchema,
+  cursorSizeSchema,
+  cursorStyleSchema,
+  cursorTrailSchema,
+  cursorTrajectorySchema,
+  magicCursor,
+  type ComputerClickParams,
+  type ComputerMagicCursorParams,
+  type CursorEdge,
+  type CursorGlow,
+  type CursorIdle,
+  type CuaClient,
+  type CuaClientOptions,
+} from "../packages/npm/sdk/cua.mjs";

package/bin/infer.ts

@@ -16,6 +16,7 @@ import { createXai } from "@ai-sdk/xai";
 import { readFileSync, existsSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+import { getKeychainSecret } from "./keychain";
 
 // ── Types ──────────────────────────────────────────────────────────
 
@@ -49,20 +50,23 @@ export interface InferResult {
 // ── Default models per provider ────────────────────────────────────
 
 const PROVIDER_NAMES: ProviderName[] = ["groq", "openai", "anthropic", "google", "xai", "minimax"];
-const VOICE_PROVIDER_PRIORITY: ProviderName[] = ["groq", "xai", "openai", "google", "anthropic", "minimax"];
+const VOICE_PROVIDER_PRIORITY: ProviderName[] = ["xai", "groq", "openai", "google", "anthropic", "minimax"];
 
 const DEFAULT_MODELS: Record<ProviderName, string> = {
   groq: "llama-3.3-70b-versatile",
   openai: "gpt-4o-mini",
   anthropic: "claude-sonnet-4-6",
   google: "gemini-2.0-flash",
-  xai: "grok-4-1-fast-non-reasoning",
+  xai: "grok-4.20-reasoning",
   minimax: "MiniMax-M2.5-highspeed",
 };
 
+// Voice paths use the same models as default — earlier we forced groq to
+// llama-3.1-8b-instant for latency, but its 6k TPM cap couldn't fit a real
+// desktop snapshot (saw 7174-token requests rejected). 70B versatile fits
+// 128k context and Groq still serves it fast.
 const VOICE_DEFAULT_MODELS: Record<ProviderName, string> = {
   ...DEFAULT_MODELS,
-  groq: "llama-3.1-8b-instant",
 };
 
 // ── Credential loading ─────────────────────────────────────────────
@@ -163,7 +167,10 @@ function loadCredentials(): CredentialStore {
   const openaiKey = getInferenceEnv("OPENAI_API_KEY");
   const anthropicKey = getInferenceEnv("ANTHROPIC_API_KEY");
   const googleKey = getInferenceEnv("GOOGLE_GENERATIVE_AI_API_KEY");
-  const xaiKey = getInferenceEnv("XAI_API_KEY");
+  // SUPERGROK_API_KEY (SuperGrok Heavy tier) takes precedence over the
+  // standard XAI_API_KEY when both are present.
+  const xaiKey =
+    getInferenceEnv("SUPERGROK_API_KEY") || getInferenceEnv("XAI_API_KEY");
   const minimaxKey = getInferenceEnv("MINIMAX_API_KEY");
   if (groqKey) creds.groq = groqKey;
   if (openaiKey) creds.openai = openaiKey;
@@ -204,6 +211,17 @@ function loadCredentials(): CredentialStore {
     } catch {}
   }
 
+  // Layer 4 — macOS keychain via built-in `/usr/bin/security` under the
+  // `lattices.inference` service. One read per missing provider, cached
+  // in `_cachedCreds` for the process lifetime. Keys never touch disk.
+  // Portable across machines (no external CLI dep).
+  if (!creds.xai) creds.xai = getKeychainSecret("xai");
+  if (!creds.groq) creds.groq = getKeychainSecret("groq");
+  if (!creds.openai) creds.openai = getKeychainSecret("openai");
+  if (!creds.anthropic) creds.anthropic = getKeychainSecret("anthropic");
+  if (!creds.google) creds.google = getKeychainSecret("google");
+  if (!creds.minimax) creds.minimax = getKeychainSecret("minimax");
+
   _cachedCreds = creds;
   return creds;
 }

package/bin/keychain.ts

@@ -0,0 +1,75 @@
+/**
+ * Tiny Lattices keychain helper.
+ *
+ * Reads and writes generic passwords under the `lattices.inference` service
+ * via the built-in macOS `/usr/bin/security` CLI. No external dependencies,
+ * universally available on macOS (so portable across user machines without
+ * the user installing anything personal).
+ *
+ * Items are stored as a single keychain entry per provider — account = provider
+ * name (xai, groq, openai, anthropic, google, minimax). The macOS keychain
+ * does the encrypt-at-rest + ACL work; this file is only a thin shell-out.
+ *
+ * Usage in code:
+ *   const key = getKeychainSecret("xai");
+ *   setKeychainSecret("xai", "xai-foo...");
+ *   deleteKeychainSecret("xai");
+ *
+ * Usage from a terminal (no Lattices wrapper needed — pure macOS):
+ *   security add-generic-password -s lattices.inference -a xai -w <key> -U
+ *   security find-generic-password -s lattices.inference -a xai -w
+ *   security delete-generic-password -s lattices.inference -a xai
+ */
+
+import { execFileSync } from "child_process";
+
+export const KEYCHAIN_SERVICE = "lattices.inference";
+const SECURITY_BIN = "/usr/bin/security";
+const TIMEOUT_MS = 1500;
+
+export function getKeychainSecret(account: string): string | undefined {
+  try {
+    const value = execFileSync(
+      SECURITY_BIN,
+      ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account, "-w"],
+      { encoding: "utf-8", timeout: TIMEOUT_MS, stdio: ["ignore", "pipe", "ignore"] },
+    ).trim();
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function setKeychainSecret(account: string, value: string): boolean {
+  try {
+    // -U updates if the item already exists; otherwise adds. The value is
+    // passed via env to keep it out of `ps`/argv.
+    execFileSync(
+      SECURITY_BIN,
+      ["add-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account, "-w", value, "-U"],
+      { timeout: TIMEOUT_MS, stdio: ["ignore", "ignore", "ignore"] },
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function deleteKeychainSecret(account: string): boolean {
+  try {
+    execFileSync(
+      SECURITY_BIN,
+      ["delete-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account],
+      { timeout: TIMEOUT_MS, stdio: ["ignore", "ignore", "ignore"] },
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function listKeychainAccounts(): string[] {
+  // `security dump-keychain` is heavy; instead probe each known account.
+  // Callers pass the candidate list explicitly to keep this stateless.
+  return [];
+}