@dharta/cli 0.6.77 → 0.6.78

package/src/commands/deploy.ts

@@ -9,8 +9,10 @@ import type { CliContext } from "../context.js";
 import { slugFromRemote, deriveSlug, validateAgentName, validateAgentSlug } from "../agent.js";
 import { findGitRoot, scanAgentFolders } from "../setup-scan.js";
 import { harnessPreflight } from "../harness-preflight.js";
+import { genuiPreflight } from "../genui.js";
 import { cliFormatRawError } from "../api-error.js";
 import { normalizeNonBlank } from "../validators.js";
+import { CliUsageError } from "../exit-codes.js";
 
 // `dharta deploy [slug]` deploys the ONE agent folder at/above --dir (or cwd).
 // The legacy slug argument may assert that folder's manifest identity, but it
@@ -110,7 +112,7 @@ export async function deploy(
     );
   }
   if (opts.reconcileSource && mode !== "git") {
-    throw new Error(
+    throw new CliUsageError(
       "--reconcile-source is only valid for git deploys. " +
         "Remove it, or use `--mode git` to reconcile Dharta's hosted source branch.",
     );
@@ -119,8 +121,17 @@ export async function deploy(
   // RFC 0035 D7: advisory harness-version pre-flight for the selected agent. A
   // no-op unless [harness] declares a version; throws to abort on an unsatisfiable
   // pin or a declined local-vs-cloud gap.
-  const preflight = (d: string) =>
-    harnessPreflight({
+  // RFC 0056: the [genui] catalog is checked first - it is purely local, so a
+  // broken bundle fails instantly and before the harness check can prompt. The
+  // deploy's own file list is handed in because every genui check reads the
+  // WORKING tree while deploy ships a Git-filtered one (committed HEAD, or a
+  // gitignore-honoring tarball), so a bundle this deploy will not carry passes
+  // locally and arrives missing. Asking the shipping list, rather than
+  // re-deriving the answer from ignore rules, is right by construction for a
+  // force-added file and for a non-ASCII name.
+  const preflight = async (d: string) => {
+    await genuiPreflight(d, { deployFiles: () => listDeployFiles(d, git) });
+    await harnessPreflight({
       dir: d,
       baseUrl: ctx.baseUrl,
       log,
@@ -128,6 +139,7 @@ export async function deploy(
       detectLocalVersion: opts.detectLocalVersion,
       confirm: opts.confirm,
     });
+  };
 
   if (mode === "folder") {
     await preflight(target.dir);
@@ -361,7 +373,9 @@ async function resolveDeployTarget(
       ? validateAgentSlug(manifest.slug, `${manifestPath} slug`)
       : validateAgentSlug(deriveSlug(manifestName), "dharta.toml name");
   if (explicitSlug && explicitSlug !== manifestSlug) {
-    throw new Error(
+    // `explicitSlug` is the positional the caller typed, and the message tells
+    // them to change it, so this is exit 2 like every other rejected argument.
+    throw new CliUsageError(
       `Agent slug '${explicitSlug}' does not match ${manifestPath} identity ` +
         `'${manifestSlug}' (name '${manifestName}'). The manifest identity is authoritative; ` +
         `set a top-level slug in dharta.toml to pin it explicitly.`,

package/src/commands/dev.ts

@@ -9,7 +9,6 @@ import { promises as fs } from "node:fs";
 import * as path from "node:path";
 import * as net from "node:net";
 import * as readline from "node:readline";
-import { randomUUID } from "node:crypto";
 import TOML from "@iarna/toml";
 import { resolveRuntime, spawnRuntime } from "../runtime.js";
 import { buildContext } from "../context.js";
@@ -18,6 +17,15 @@ import { parseDotenvFile } from "./env.js";
 import { describeFolder } from "../setup-scan.js";
 import { hasAgentMarker } from "../harnesses.js";
 import { normalizeNonBlank } from "../validators.js";
+import { mintIdempotencyKey } from "../config.js";
+import { checkGenui } from "../genui.js";
+import { CliUsageError } from "../exit-codes.js";
+import {
+  formatModelAuthCapability,
+  resolveDevModelAuth,
+  type DevModelAuth,
+  type RunCommandStatus,
+} from "../model-auth.js";
 
 export interface DevOptions {
   dir?: string;
@@ -30,6 +38,7 @@ export interface DevOptions {
   envRemote?: boolean; // --env remote: bind prod env vars instead of .env
   includeSecrets?: boolean; // with --env remote: fetch secret values (env:secrets:read)
   project?: string; // -p override for the parity flags' project inference
+  modelAuth?: DevModelAuth;
   // Test seams. `attach` skips the spawn and drives an existing server.
   attach?: string;
   fetchImpl?: typeof fetch;
@@ -38,6 +47,7 @@ export interface DevOptions {
   log?: (line: string) => void;
   healthTimeoutMs?: number;
   turnIdleMs?: number; // abort a turn with no output for this long (default 60s)
+  modelAuthCommand?: RunCommandStatus;
 }
 
 interface SseEvent {
@@ -45,6 +55,10 @@ interface SseEvent {
   data: Record<string, unknown>;
 }
 
+export function devServeArgs(dir: string, port: number, modelAuth: DevModelAuth): string[] {
+  return ["dev-serve", dir, "--host", "127.0.0.1", "--port", String(port), "--model-auth", modelAuth];
+}
+
 // `dharta dev [path]` in a multi-agent repo (RFC 0024 DEP-8): with no path
 // given, serve cwd if it is itself an agent; else the sole agent folder
 // directly below it; else ask which one. An explicit path always wins (the
@@ -81,12 +95,12 @@ export async function dev(opts: DevOptions = {}): Promise<void> {
   const fetchImpl = (opts.fetchImpl ?? globalThis.fetch).bind(globalThis);
 
   if (opts.port !== undefined && (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535)) {
-    throw new Error("--port must be an integer between 1 and 65535.");
+    throw new CliUsageError("--port must be an integer between 1 and 65535.");
   }
   const normalizedDir = opts.dir === undefined ? undefined : normalizeNonBlank(opts.dir, "--dir");
   const normalizedUser = opts.user === undefined ? undefined : normalizeNonBlank(opts.user, "--user");
   const normalizedMessage = opts.message === undefined ? undefined : normalizeNonBlank(opts.message, "--message");
-  if (opts.includeSecrets && !opts.envRemote) throw new Error("--include-secrets requires --env remote.");
+  if (opts.includeSecrets && !opts.envRemote) throw new CliUsageError("--include-secrets requires --env remote.");
 
   let dir = path.resolve(normalizedDir ?? process.cwd());
   if (normalizedDir !== undefined) {
@@ -96,6 +110,7 @@ export async function dev(opts: DevOptions = {}): Promise<void> {
   // ask) - RFC 0024 DEP-8. An explicit --dir / [path] is served as-is.
   if (normalizedDir === undefined) dir = await resolveAgentDir(dir, log);
   let childEnv: NodeJS.ProcessEnv | undefined;
+  let selectedModelAuth: DevModelAuth | undefined;
   if (opts.release || opts.envRemote) {
     const ctx = await buildContext({ fetch: opts.fetchImpl });
     const inferOpts = { dir: normalizedDir, project: opts.project, fetchImpl: opts.fetchImpl };
@@ -121,6 +136,17 @@ export async function dev(opts: DevOptions = {}): Promise<void> {
     }
   }
 
+  if (!opts.attach) {
+    let authEnv = childEnv ?? process.env;
+    if (!opts.envRemote) {
+      authEnv = await devModelAuthEnv(dir, authEnv);
+    }
+    const resolvedAuth = resolveDevModelAuth(opts.modelAuth, authEnv, opts.modelAuthCommand);
+    childEnv = resolvedAuth.env;
+    selectedModelAuth = resolvedAuth.selection;
+    log(`✓ Model auth: ${formatModelAuthCapability(resolvedAuth.capability)}`);
+  }
+
   const agentName = (await describeFolder(dir, ".")).name ?? path.basename(dir);
   log(`Dharta dev mode: ${agentName}`);
   log("");
@@ -137,7 +163,7 @@ export async function dev(opts: DevOptions = {}): Promise<void> {
     const port = opts.port ?? (await freePort());
     baseUrl = `http://127.0.0.1:${port}`;
     log(`✓ Starting agent runtime (${runtime.description})…`);
-    child = spawnRuntime(runtime, ["dev-serve", dir, "--host", "127.0.0.1", "--port", String(port)], {
+    child = spawnRuntime(runtime, devServeArgs(dir, port, selectedModelAuth as DevModelAuth), {
       stdio: "pipe",
       env: childEnv,
     });
@@ -180,19 +206,6 @@ export async function dev(opts: DevOptions = {}): Promise<void> {
       log("  Preview parity is code + config, not infrastructure: no microVM, no per-user");
       log("  workspaces, and turns run on YOUR harness credentials (prod injects its own).");
     }
-    // The agent turn spawns `claude` on YOUR credentials; with none it exits 1.
-    // Hard-stop here rather than drop into a chat that can only fail (spawn
-    // path only - an attached runtime carries its own credentials).
-    if (child && !process.env.ANTHROPIC_API_KEY && !process.env.CLAUDE_CODE_OAUTH_TOKEN) {
-      log("");
-      log("! Error: No model credential found. Two options -");
-      log("  export ANTHROPIC_API_KEY=<your Anthropic API key>");
-      log("  OR");
-      log("  export CLAUDE_CODE_OAUTH_TOKEN=<Claude Code token from `claude setup-token`>");
-      process.exitCode = 1;
-      return;
-    }
-
     const session = await createSession(baseUrl, fetchImpl, normalizedUser);
     if (normalizedUser) log(`Simulating end user '${normalizedUser}'.`);
 
@@ -216,7 +229,12 @@ export async function dev(opts: DevOptions = {}): Promise<void> {
     // Run one turn but never hang: abort if the runtime crashes (onFatal) or
     // goes silent for idleMs, then surface the buffered runtime output. The
     // idle timer pauses while we wait on a human (approval prompt).
+    // Counts turns in this REPL session. One root --idempotency-key covers the
+    // whole process, so without the index every turn after the first would
+    // replay the first turn's answer instead of running.
+    let turnIndex = 0;
     const runTurnWatched = async (turnText: string, prefix: string): Promise<void> => {
+      turnIndex += 1;
       const controller = new AbortController();
       let idle: ReturnType<typeof setTimeout> | undefined;
       let produced = false; // did the agent write any content this turn?
@@ -243,7 +261,14 @@ export async function dev(opts: DevOptions = {}): Promise<void> {
       const aborted = new Promise<never>((_, reject) => {
         controller.signal.addEventListener("abort", () => reject(new Error("turn aborted")), { once: true });
       });
-      const turn = runTurn(baseUrl as string, fetchImpl, session, turnText, { write: tracked, log, ask: pausedAsk }, controller.signal);
+      const turn = runTurn(
+        baseUrl as string,
+        fetchImpl,
+        session,
+        turnText,
+        { write: tracked, log, ask: pausedAsk },
+        { signal: controller.signal, operation: `turn.${turnIndex}` },
+      );
       try {
         // Race the turn against the abort. A real fetch unblocks its body read
         // on signal, but racing also covers a stream that wedges open without
@@ -261,7 +286,7 @@ export async function dev(opts: DevOptions = {}): Promise<void> {
           runtimeOutput?.dump();
           throw new Error(
             "No response - the agent runtime errored or went silent (see [runtime] output above). " +
-              "A missing model credential (ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN) is the usual cause.",
+              "Check the selected model authentication with `dharta doctor`, then retry.",
           );
         }
         throw err;
@@ -299,6 +324,14 @@ export async function dev(opts: DevOptions = {}): Promise<void> {
   }
 }
 
+export async function devModelAuthEnv(
+  dir: string,
+  baseEnv: NodeJS.ProcessEnv,
+): Promise<NodeJS.ProcessEnv> {
+  const localEnv = await readOptionalLocalFile(path.join(dir, ".env"), ".env");
+  return { ...parseDotenvFile(localEnv.content), ...baseEnv };
+}
+
 async function validateExplicitDevDir(dir: string): Promise<void> {
   try {
     const stat = await fs.stat(dir);
@@ -321,7 +354,8 @@ async function validateExplicitDevDir(dir: string): Promise<void> {
 export async function miniDoctor(dir: string): Promise<string[]> {
   const warnings: string[] = [];
 
-  const karta = await readOptionalLocalFile(path.join(dir, "dharta.toml"), "dharta.toml");
+  const manifestPath = path.join(dir, "dharta.toml");
+  const karta = await readOptionalLocalFile(manifestPath, "dharta.toml");
   if (karta.warning) warnings.push(karta.warning);
   const kartaToml = karta.content;
   if (kartaToml === null) {
@@ -331,6 +365,14 @@ export async function miniDoctor(dir: string): Promise<string[]> {
   } else {
     try {
       const parsed = TOML.parse(kartaToml) as Record<string, unknown>;
+
+      // RFC 0056: the same [genui] problems the deploy pre-flight refuses on,
+      // said as warnings here so a broken component catalog surfaces while you
+      // develop. The manifest this doctor already read is handed straight in
+      // rather than read and parsed a second time.
+      const genui = await checkGenui({ path: manifestPath, text: kartaToml, parsed });
+      warnings.push(...genui.problems);
+
       const env = parsed.env as Record<string, unknown> | undefined;
       if (env) {
         const localEnv = await readOptionalLocalFile(path.join(dir, ".env"), ".env");
@@ -493,7 +535,10 @@ async function createSession(
 ): Promise<string> {
   const res = await fetchAgentApi(baseUrl, fetchImpl, "/v1/sessions", "create a session", {
     method: "POST",
-    headers: { "Content-Type": "application/json", "Idempotency-Key": randomUUID() },
+    headers: {
+      "Content-Type": "application/json",
+      "Idempotency-Key": mintIdempotencyKey("session"),
+    },
     body: JSON.stringify({ metadata: endUserId ? { end_user_id: endUserId } : {} }),
   });
   if (!res.ok) {
@@ -523,13 +568,21 @@ interface PendingInput {
   target?: string;
 }
 
+export interface RunTurnOptions {
+  signal?: AbortSignal;
+  // The idempotency operation this turn writes under. A REPL that sends many
+  // turns under one root key has to distinguish them, or every turn after the
+  // first replays the first one's answer, so `dharta dev` passes `turn.<n>`.
+  operation?: string;
+}
+
 export async function runTurn(
   baseUrl: string,
   fetchImpl: typeof fetch,
   sessionId: string,
   text: string,
   io: TurnIo,
-  signal?: AbortSignal,
+  { signal, operation = "turn" }: RunTurnOptions = {},
 ): Promise<void> {
   const res = await fetchAgentApi(
     baseUrl,
@@ -541,7 +594,7 @@ export async function runTurn(
       headers: {
         "Content-Type": "application/json",
         Accept: "text/event-stream",
-        "Idempotency-Key": randomUUID(),
+        "Idempotency-Key": mintIdempotencyKey(operation),
       },
       body: JSON.stringify({ text, stream: true }),
       signal,
@@ -555,7 +608,7 @@ export async function runTurn(
   }
 
   const pending = await renderEventStream(parseSse(res.body), io);
-  await resolvePendingInputs(baseUrl, fetchImpl, sessionId, pending, io);
+  await resolvePendingInputs(baseUrl, fetchImpl, sessionId, pending, io, operation);
 }
 
 // Approval loop: the harness pauses on tool permissions; the decision
@@ -567,10 +620,15 @@ async function resolvePendingInputs(
   sessionId: string,
   first: PendingInput | null,
   io: TurnIo,
+  operation: string,
 ): Promise<void> {
   let pending = first;
   let abortHintShown = false;
+  // Counts the decisions in THIS turn. The request id is unique too, but it is
+  // minted per run, so a key built from it would never match on a rerun.
+  let decisionIndex = 0;
   while (pending) {
+    decisionIndex += 1;
     const prompt = pending.message ?? `The agent wants to use ${pending.tool ?? "a tool"}`;
     const answer = await io.ask(`\n${prompt} - approve? [y=once / s=session / n=deny] `);
     if (answer === null && !abortHintShown) {
@@ -601,7 +659,10 @@ async function resolvePendingInputs(
       "deliver the decision",
       {
         method: "PUT",
-        headers: { "Content-Type": "application/json", "Idempotency-Key": randomUUID() },
+        headers: {
+          "Content-Type": "application/json",
+          "Idempotency-Key": mintIdempotencyKey(`${operation}.input.${decisionIndex}`),
+        },
         body: JSON.stringify({ decision }),
       },
     );

package/src/commands/doctor.ts

@@ -8,6 +8,30 @@ import { loadConfig } from "../config.js";
 import { resolveRuntime, whichAll, type RuntimeResolveOptions } from "../runtime.js";
 import { installChannel, packageRoot } from "./update.js";
 import { checkNpmLatestVersion, NPM_LATEST_URL } from "../version-check.js";
+import {
+  capabilityFor,
+  checkClaudeAuth,
+  formatModelAuthCapability,
+  MODEL_AUTH_MISSING,
+  runtimeSwitchOpen,
+  type RunCommandStatus,
+} from "../model-auth.js";
+
+// A malformed `DHARTA_MODEL_AUTH_*_ENABLED` is exactly the class of problem
+// doctor exists to explain, so it is reported as a failed line rather than
+// thrown: `runtimeSwitchOpen` raises on any value outside its two lists, and an
+// unguarded call took out the whole report over one typo. A capability whose
+// switch cannot be read counts as closed.
+function readRuntimeSwitch(
+  capability: Parameters<typeof runtimeSwitchOpen>[0],
+  env: NodeJS.ProcessEnv,
+): { open: boolean; problem?: string } {
+  try {
+    return { open: runtimeSwitchOpen(capability, env) };
+  } catch (err) {
+    return { open: false, problem: err instanceof Error ? err.message : String(err) };
+  }
+}
 
 export interface DoctorReport {
   lines: string[];
@@ -20,6 +44,7 @@ export interface DoctorOptions extends RuntimeResolveOptions {
   currentVersion?: string;
   fetchImpl?: typeof fetch;
   latestUrl?: string;
+  modelAuthCommand?: RunCommandStatus;
 }
 
 export async function doctor(opts: DoctorOptions = {}): Promise<DoctorReport> {
@@ -69,6 +94,50 @@ export async function doctor(opts: DoctorOptions = {}): Promise<DoctorReport> {
     }
   }
 
+  const apiKeyCapability = capabilityFor("api-key");
+  const apiKeySwitch = readRuntimeSwitch(apiKeyCapability, env);
+  if (apiKeySwitch.problem) {
+    ok = false;
+    lines.push(`✗ ${apiKeySwitch.problem}`);
+    lines.push("  Fix: set it to true or false, or unset it.");
+  }
+  const apiKeyPresent = Boolean(env.ANTHROPIC_API_KEY?.trim());
+  const apiKeyReady =
+    apiKeyPresent && apiKeyCapability.admission === "enabled" && apiKeySwitch.open;
+  if (!apiKeyPresent) {
+    lines.push(`- ${MODEL_AUTH_MISSING}: ANTHROPIC_API_KEY is not set.`);
+  } else if (!apiKeyReady) {
+    lines.push(`- ANTHROPIC_API_KEY is set, but ${apiKeyCapability.id} is disabled (model_auth_capability_disabled).`);
+    lines.push(`  ${formatModelAuthCapability(apiKeyCapability)}`);
+  } else {
+    lines.push(`✓ Anthropic API key auth: ${formatModelAuthCapability(apiKeyCapability)}`);
+  }
+
+  const claude = checkClaudeAuth(env, opts.modelAuthCommand);
+  const claudeCapability = capabilityFor("claude");
+  const claudeSwitch = readRuntimeSwitch(claudeCapability, env);
+  if (claudeSwitch.problem) {
+    ok = false;
+    lines.push(`✗ ${claudeSwitch.problem}`);
+    lines.push("  Fix: set it to true or false, or unset it.");
+  }
+  let claudeReady = false;
+  if (!claude.installed) {
+    lines.push(`- ${MODEL_AUTH_MISSING}: Claude client is not on PATH. Install it, then run \`claude auth login\` to use \`dharta dev --model-auth claude\`.`);
+  } else if (!claude.authenticated) {
+    lines.push(`- ${MODEL_AUTH_MISSING}: Claude client is not logged in. Run \`claude auth login\`, then retry \`dharta dev --model-auth claude\`.`);
+  } else if (claudeCapability.admission !== "enabled" || !claudeSwitch.open) {
+    lines.push(`- Claude client is logged in, but ${claudeCapability.id} is disabled (model_auth_capability_disabled).`);
+    lines.push(`  ${formatModelAuthCapability(claudeCapability)}`);
+  } else {
+    claudeReady = true;
+    lines.push(`✓ Claude client auth: ${formatModelAuthCapability(claudeCapability)}`);
+  }
+  if (!apiKeyReady && !claudeReady) {
+    ok = false;
+    lines.push("  Fix: export ANTHROPIC_API_KEY or run `claude auth login` before `dharta dev`.");
+  }
+
   if (opts.checkLatest !== false) {
     const version = await checkLatestVersion(opts);
     if (version.status === "outdated") {

package/src/commands/embed-keys.ts

@@ -1,8 +1,8 @@
-import { randomUUID } from "node:crypto";
 import { inferAgentSlug, type AgentInferOptions } from "../agent.js";
 import type { CliContext } from "../context.js";
 import { fmtTs, table } from "../output.js";
 import { normalizeHttpUrl, normalizeNonBlank } from "../validators.js";
+import { CliUsageError } from "../exit-codes.js";
 
 export interface EmbedKey {
   id: string;
@@ -63,7 +63,6 @@ export async function embedKeysCreateData(
   const res = await ctx.http.request<EmbedKeyEnvelope>({
     method: "POST",
     path: `/api/agents/${encodeURIComponent(slug)}/embed_keys`,
-    headers: idempotencyHeader(),
     body: {
       name: normalizedName,
       allowed_origins: normalizedOrigins,
@@ -92,7 +91,6 @@ export async function embedKeysRotateData(ctx: CliContext, id: string, opts: Age
   const res = await ctx.http.request<EmbedKeyEnvelope>({
     method: "POST",
     path: `/api/agents/${encodeURIComponent(slug)}/embed_keys/${encodeURIComponent(normalizedId)}/rotate`,
-    headers: idempotencyHeader(),
   });
   return { slug, ...res };
 }
@@ -117,7 +115,6 @@ export async function embedKeysToggleData(
   const res = await ctx.http.request<EmbedKeyEnvelope>({
     method: "POST",
     path: `/api/agents/${encodeURIComponent(slug)}/embed_keys/${encodeURIComponent(normalizedId)}/${action}`,
-    headers: idempotencyHeader(),
   });
   return { slug, ...res };
 }
@@ -142,7 +139,6 @@ export async function embedKeysSetIdentityData(
   const res = await ctx.http.request<IdentityEnvelope>({
     method: "POST",
     path: `/api/agents/${encodeURIComponent(slug)}/embed_keys/${encodeURIComponent(normalizedId)}/identity`,
-    headers: idempotencyHeader(),
   });
   return { slug, ...res };
 }
@@ -166,7 +162,6 @@ export async function embedKeysClearIdentityData(
   const res = await ctx.http.request<EmbedKeyEnvelope>({
     method: "DELETE",
     path: `/api/agents/${encodeURIComponent(slug)}/embed_keys/${encodeURIComponent(normalizedId)}/identity`,
-    headers: idempotencyHeader(),
   });
   return { slug, ...res };
 }
@@ -182,7 +177,6 @@ export async function embedKeysRevokeData(ctx: CliContext, id: string, opts: Age
   await ctx.http.request<void>({
     method: "DELETE",
     path: `/api/agents/${encodeURIComponent(slug)}/embed_keys/${encodeURIComponent(normalizedId)}`,
-    headers: idempotencyHeader(),
   });
   return { slug, id: normalizedId, revoked: true };
 }
@@ -199,7 +193,7 @@ export function parseOrigins(input: string[] | undefined): string[] {
     .map((value) => value.trim())
     .filter(Boolean);
   if (origins.length === 0) {
-    throw new Error("--origin must include at least one origin, e.g. --origin https://app.example.com.");
+    throw new CliUsageError("--origin must include at least one origin, e.g. --origin https://app.example.com.");
   }
   return origins.map((origin) => normalizeOrigin(origin));
 }
@@ -208,7 +202,7 @@ function normalizeOrigin(origin: string): string {
   const normalized = normalizeHttpUrl(origin, "--origin");
   const parsed = new URL(normalized);
   if (parsed.pathname !== "/" || parsed.search || parsed.hash) {
-    throw new Error("--origin must be an origin like https://app.example.com, without a path, query, or fragment.");
+    throw new CliUsageError("--origin must be an origin like https://app.example.com, without a path, query, or fragment.");
   }
   return parsed.origin;
 }
@@ -224,14 +218,10 @@ function row(key: EmbedKey): Record<string, string> {
   };
 }
 
-function idempotencyHeader(): Record<string, string> {
-  return { "Idempotency-Key": randomUUID() };
-}
-
 function normalizeEmbedKeyName(name: string): string {
   const normalized = name.trim();
   if (!normalized) {
-    throw new Error("Embed key name cannot be blank.");
+    throw new CliUsageError("Embed key name cannot be blank.");
   }
   return normalized;
 }

package/src/commands/env.ts

@@ -4,12 +4,12 @@
 
 import { promises as fs } from "node:fs";
 import * as path from "node:path";
-import { randomUUID } from "node:crypto";
 import TOML from "@iarna/toml";
 import type { CliContext } from "../context.js";
 import { inferAgentSlug, validateAgentSelectorOptions, type AgentInferOptions } from "../agent.js";
 import { table } from "../output.js";
 import { normalizeNonBlank } from "../validators.js";
+import { CliUsageError } from "../exit-codes.js";
 
 export interface EnvOptions extends AgentInferOptions {
   force?: boolean; // pull: overwrite an existing .env
@@ -22,7 +22,7 @@ export interface EnvOptions extends AgentInferOptions {
 // (a GitHub PAT, a webhook signing key). `list` therefore masks EVERY value by
 // default - a routine listing must never dump a live secret to the terminal or
 // CI logs. A short tail is kept so an operator can still tell two bindings
-// apart (matching how `whoami`/model keys show only a tail); `--reveal` prints
+// apart (matching how `whoami`/model connections show only a tail); `--reveal` prints
 // the full value for the rare time it is actually needed.
 export function maskEnvValue(v: { secret: boolean; value?: string | null }, reveal: boolean): string {
   if (reveal) return v.value ?? "";
@@ -78,7 +78,6 @@ export async function envSetData(
     method: "PUT",
     path: `/api/agents/${encodeURIComponent(slug)}/env/${encodeURIComponent(name)}`,
     body,
-    headers: { "Idempotency-Key": randomUUID() },
   });
   return { slug, name, secret: !!opts.secret };
 }
@@ -94,7 +93,7 @@ export function validateEnvName(name: string): void {
 function parseEnvAssignment(assignment: string): { name: string; value: string } {
   const eq = assignment.indexOf("=");
   if (eq <= 0) {
-    throw new Error("Usage: dharta env set NAME=value [--secret]");
+    throw new CliUsageError("Usage: dharta env set NAME=value [--secret]");
   }
   const name = normalizeEnvName(assignment.slice(0, eq));
   const value = assignment.slice(eq + 1);
@@ -123,7 +122,6 @@ export async function envUnsetData(
   await ctx.http.request({
     method: "DELETE",
     path: `/api/agents/${encodeURIComponent(slug)}/env/${encodeURIComponent(normalizedName)}`,
-    headers: { "Idempotency-Key": randomUUID() },
   });
   return { slug, name: normalizedName, removed: true };
 }
@@ -154,7 +152,6 @@ export async function envPullData(
     method: "POST",
     path: `/api/agents/${encodeURIComponent(slug)}/env/pull`,
     body: { include_secrets: !!opts.includeSecrets },
-    headers: { "Idempotency-Key": randomUUID() },
   });
 
   const bound = body.env.filter((v) => !v.withheld);
@@ -347,7 +344,7 @@ async function validateEnvPullTarget(dir: string, target: string, force: boolean
       throw new Error(`Cannot write .env to ${target}: expected a file, got a directory.`);
     }
     if (!force) {
-      throw new Error(
+      throw new CliUsageError(
         `${target} already exists. Re-run with --force to overwrite it (local-only keys are lost).`,
       );
     }

package/src/commands/files.ts

@@ -1,10 +1,10 @@
 import { HttpClient } from "@dharta/sdk";
-import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
 import type { CliContext } from "../context.js";
 import { cliFormatError, cliFormatNetworkError, cliFormatRawError } from "../api-error.js";
 import { table } from "../output.js";
 import { validateAgentSlug } from "../agent.js";
+import { CliUsageError } from "../exit-codes.js";
 
 // `dharta files ls|get <agent> <karta>` - the owner file-read channel (RFC 0060 D3/P3).
 //
@@ -35,7 +35,6 @@ async function mintFilesToken(ctx: CliContext, agent: string, instance: string):
   const res = await ctx.http.request<{ token?: string; files_url?: string }>({
     method: "POST",
     path: `/api/agents/${encodeURIComponent(agent)}/workspace_tokens`,
-    headers: { "Idempotency-Key": randomUUID() },
     body: { instance, scope: "workspace_read" },
   });
   if (!res.token) {
@@ -65,7 +64,7 @@ function filesClient(ctx: CliContext, mint: FilesMint): { http: HttpClient; base
 
 function normalizeInstance(instance: string): string {
   const trimmed = instance.trim();
-  if (!trimmed) throw new Error("A dharta id is required.");
+  if (!trimmed) throw new CliUsageError("A dharta id is required.");
   return trimmed;
 }
 
@@ -109,7 +108,7 @@ export async function filesGet(
   const slug = validateAgentSlug(agent, "agent slug");
   const karta = normalizeInstance(instance);
   const filePath = path.trim();
-  if (!filePath) throw new Error("A file path is required.");
+  if (!filePath) throw new CliUsageError("A file path is required.");
   const mint = await mintFilesToken(ctx, slug, karta);
   const { http, basePath } = filesClient(ctx, mint);
   const res = await http.raw(`${basePath}/file?path=${encodeURIComponent(filePath)}`);