@dharta/cli 0.6.77 → 0.6.78

package/src/commands/model-connections.ts

@@ -0,0 +1,547 @@
+// Public model-connection CRUD for `dharta models auth`.
+import type { CliContext } from "../context.js";
+import type {
+  ModelConnectionApiFormat,
+  ModelConnection,
+  ModelConnectionOffers,
+  ModelConnectionOffersUpdateParams,
+  ModelConnectionProvider,
+  ModelConnectionRotateParams,
+} from "@dharta/sdk";
+import { fmtTs, table } from "../output.js";
+import { normalizeStoredConnectorSlug } from "../model-settings.js";
+import { CliUsageError } from "../exit-codes.js";
+import { closestChoice, normalizeHttpUrl, normalizeNonBlank, parsePositiveInteger } from "../validators.js";
+import { MODEL_CONNECTION_PROVIDERS } from "../model-auth.js";
+
+interface ListEnvelope<T> {
+  data: T[];
+}
+
+interface ModelConnectionEnvelope {
+  model_connection: ModelConnection;
+}
+
+// At most this many models in one enabled set, matching the server.
+const MAX_OFFER_MODELS = 256;
+
+export const MODEL_API_FORMATS = [
+  "anthropic_messages",
+  "openai_chat_completions",
+  "openai_responses",
+] as const satisfies readonly ModelConnectionApiFormat[];
+export interface ModelConnectionCreateOptions {
+  key?: string;
+  keyStdin?: boolean;
+  slug?: string;
+  endpointUrl?: string;
+  apiFormat?: string;
+}
+
+export interface ModelConnectionRotateOptions {
+  key?: string;
+  keyStdin?: boolean;
+  name?: string;
+}
+
+export interface ModelConnectionModelsOptions {
+  enable?: string;
+  enableStdin?: boolean;
+  default?: string;
+  clearDefault?: boolean;
+}
+
+export async function modelConnectionsListData(ctx: CliContext): Promise<ModelConnection[]> {
+  const res = await ctx.http.request<ListEnvelope<ModelConnection>>({ path: "/model_connections" });
+  return res.data;
+}
+
+export async function modelConnectionsList(ctx: CliContext): Promise<string> {
+  const keys = await modelConnectionsListData(ctx);
+  if (keys.length === 0) return "No model connections. Store one with: dharta models auth create <provider> <name> --key-stdin";
+  return table(keys.map((key) => ({
+    id: String(key.id),
+    slug: key.slug ?? "",
+    provider: key.provider,
+    name: key.name,
+    tail: key.tail,
+    created: fmtTs(key.created_at),
+    revoked: fmtTs(key.revoked_at),
+  })));
+}
+
+export async function modelConnectionsCreateData(
+  ctx: CliContext,
+  provider: ModelConnectionProvider,
+  name: string,
+  opts: ModelConnectionCreateOptions = {},
+): Promise<ModelConnection> {
+  validateModelConnectionsCreateOptions(provider, name, opts);
+  const normalizedProvider = normalizeProvider(provider);
+  const normalizedName = normalizeModelConnectionName(name);
+  const plaintext = await resolvePlaintext(opts);
+  const body: Record<string, string> = { provider: normalizedProvider, name: normalizedName, plaintext };
+  if (opts.slug !== undefined) body.slug = normalizeStoredConnectorSlug(opts.slug, "--slug");
+  if (opts.endpointUrl) body.endpoint_url = normalizeEndpointUrl(opts.endpointUrl);
+  if (opts.apiFormat) body.api_format = normalizeApiFormat(opts.apiFormat);
+  try {
+    const res = await ctx.http.request<ModelConnectionEnvelope>({
+      method: "POST",
+      path: "/model_connections",
+      body,
+    });
+    return res.model_connection;
+  } catch (error) {
+    throw addModelConnectionsWriteScopeGuidance(error);
+  }
+}
+
+export async function modelConnectionsCreate(
+  ctx: CliContext,
+  provider: ModelConnectionProvider,
+  name: string,
+  opts: ModelConnectionCreateOptions = {},
+): Promise<string> {
+  const key = await modelConnectionsCreateData(ctx, provider, name, opts);
+  // RFC 0070 §4.2.5: a stored connector with no enabled offer row resolves
+  // nothing, so name the command that finishes the job.
+  return `Stored ${key.provider} connector ${connectorLabel(key)} (${key.id}).\n` +
+    `It serves no turns until you enable a model: ${enableModelsHint(connectorLabel(key))}`;
+}
+
+// One spelling of the enable-and-default command, so every place that has to
+// point at it points at the same thing.
+function enableModelsHint(slug: string): string {
+  return `dharta models auth models ${slug} --enable <model> --default <model>`;
+}
+
+// Address the connector by its slug: that is what a model reference and a
+// connector order use.
+function connectorLabel(key: ModelConnection): string {
+  return key.slug;
+}
+
+export function validateModelConnectionsCreateOptions(provider: ModelConnectionProvider, name: string, opts: ModelConnectionCreateOptions = {}): void {
+  normalizeProvider(provider);
+  normalizeModelConnectionName(name);
+  if (opts.slug !== undefined) {
+    normalizeStoredConnectorSlug(opts.slug, "--slug");
+  }
+  if (opts.key !== undefined && opts.keyStdin) {
+    throw new CliUsageError("Use either --key or --key-stdin, not both.");
+  }
+  if (opts.key !== undefined) {
+    normalizePlaintext(opts.key, "--key");
+  } else if (!opts.keyStdin) {
+    throw new CliUsageError("Model connection plaintext is required. Pass --key or --key-stdin.");
+  } else if (process.stdin.isTTY) {
+    throw new CliUsageError(
+      "No piped input. Usage: echo $PROVIDER_API_KEY | dharta models auth create anthropic Claude --key-stdin",
+    );
+  }
+  if (opts.endpointUrl !== undefined) {
+    normalizeEndpointUrl(opts.endpointUrl);
+  }
+  if (opts.apiFormat !== undefined) {
+    normalizeApiFormat(opts.apiFormat);
+  }
+}
+
+function normalizeProvider(provider: ModelConnectionProvider): ModelConnectionProvider {
+  const normalized = normalizeNonBlank(provider, "Model connection provider");
+  if ((MODEL_CONNECTION_PROVIDERS as readonly string[]).includes(normalized)) {
+    return normalized as ModelConnectionProvider;
+  }
+  const suggestion = closestChoice(normalized, MODEL_CONNECTION_PROVIDERS);
+  throw new CliUsageError(
+    `Unknown model connection provider ${normalized}. Allowed providers: ${MODEL_CONNECTION_PROVIDERS.join(", ")}.` +
+      (suggestion ? ` Did you mean ${suggestion}?` : ""),
+  );
+}
+
+function normalizeApiFormat(apiFormat: string): ModelConnectionApiFormat {
+  const normalized = normalizeNonBlank(apiFormat, "--api-format");
+  if ((MODEL_API_FORMATS as readonly string[]).includes(normalized)) {
+    return normalized as ModelConnectionApiFormat;
+  }
+  const suggestion = closestChoice(normalized, MODEL_API_FORMATS);
+  throw new CliUsageError(
+    `Unknown --api-format ${normalized}. Allowed API formats: ${MODEL_API_FORMATS.join(", ")}.` +
+      (suggestion ? ` Did you mean ${suggestion}?` : ""),
+  );
+}
+
+export async function prepareModelConnectionsCreateOptions(
+  provider: ModelConnectionProvider,
+  name: string,
+  opts: ModelConnectionCreateOptions = {},
+  read: () => Promise<string> = readModelConnectionStdin,
+): Promise<ModelConnectionCreateOptions> {
+  validateModelConnectionsCreateOptions(provider, name, opts);
+  if (!opts.keyStdin) return opts;
+  return { ...opts, key: normalizeModelConnectionStdin(await read()), keyStdin: false };
+}
+
+export async function modelConnectionsRotateData(
+  ctx: CliContext,
+  reference: string,
+  opts: ModelConnectionRotateOptions,
+): Promise<ModelConnection> {
+  const normalizedReference = normalizeModelConnectionReference(reference);
+  validateModelConnectionsRotateOptions(reference, opts);
+  const body: ModelConnectionRotateParams = { plaintext: await resolveRotatePlaintext(opts) };
+  if (opts.name !== undefined) body.name = normalizeModelConnectionName(opts.name);
+  try {
+    // Through the SDK resource, not a hand-built request: a new endpoint ships
+    // an @dharta/sdk method and the curated command calls it (RFC 0048 D2), so
+    // the path, the wire shape, and the idempotency header have one owner.
+    return await ctx.sdk.modelConnections.rotate(modelConnectionReferenceId(normalizedReference), body);
+  } catch (error) {
+    throw addModelConnectionsWriteScopeGuidance(error);
+  }
+}
+
+export async function modelConnectionsRotate(
+  ctx: CliContext,
+  reference: string,
+  opts: ModelConnectionRotateOptions,
+): Promise<string> {
+  const key = await modelConnectionsRotateData(ctx, reference, opts);
+  return `Rotated ${key.provider} connector ${connectorLabel(key)} (${key.id}).`;
+}
+
+export function validateModelConnectionsRotateOptions(reference: string, opts: ModelConnectionRotateOptions): void {
+  normalizeModelConnectionReference(reference);
+  if (opts.name !== undefined) normalizeModelConnectionName(opts.name);
+  if (opts.key !== undefined && opts.keyStdin) {
+    throw new CliUsageError("Use either --key or --key-stdin, not both.");
+  }
+  if (opts.key !== undefined) {
+    normalizePlaintext(opts.key, "--key");
+  } else if (!opts.keyStdin) {
+    throw new CliUsageError("Model connection plaintext is required. Pass --key or --key-stdin.");
+  } else if (process.stdin.isTTY) {
+    throw new CliUsageError(ROTATE_STDIN.tty);
+  }
+}
+
+// Read the piped secret before the command runs so `--json` output stays a
+// single payload, mirroring prepareModelConnectionsCreateOptions.
+export async function prepareModelConnectionsRotateOptions(
+  reference: string,
+  opts: ModelConnectionRotateOptions,
+  read: () => Promise<string> = () => readPipedStdin(ROTATE_STDIN),
+): Promise<ModelConnectionRotateOptions> {
+  validateModelConnectionsRotateOptions(reference, opts);
+  if (!opts.keyStdin) return opts;
+  return { ...opts, key: normalizePipedStdin(await read(), ROTATE_STDIN), keyStdin: false };
+}
+
+export async function modelConnectionsModelsData(ctx: CliContext, reference: string): Promise<ModelConnectionOffers> {
+  const normalizedReference = normalizeModelConnectionReference(reference);
+  return ctx.sdk.modelConnections.models(modelConnectionReferenceId(normalizedReference));
+}
+
+export async function modelConnectionsModels(ctx: CliContext, reference: string): Promise<string> {
+  return formatModelConnectionOffers(await modelConnectionsModelsData(ctx, reference));
+}
+
+export async function modelConnectionsConfigureModelsData(
+  ctx: CliContext,
+  reference: string,
+  opts: ModelConnectionModelsOptions,
+): Promise<ModelConnectionOffers> {
+  const normalizedReference = normalizeModelConnectionReference(reference);
+  validateModelConnectionsModelsOptions(reference, opts);
+  const enabled = parseEnabledModels(await resolveEnabledModels(opts));
+  const body: ModelConnectionOffersUpdateParams = { enabled };
+  if (opts.clearDefault) body.default = null;
+  if (opts.default !== undefined) body.default = normalizeDefaultModel(opts.default, enabled);
+  try {
+    return await ctx.sdk.modelConnections.configureModels(modelConnectionReferenceId(normalizedReference), body);
+  } catch (error) {
+    throw addModelConnectionsWriteScopeGuidance(error);
+  }
+}
+
+export async function modelConnectionsConfigureModels(
+  ctx: CliContext,
+  reference: string,
+  opts: ModelConnectionModelsOptions,
+): Promise<string> {
+  return formatModelConnectionOffers(await modelConnectionsConfigureModelsData(ctx, reference, opts));
+}
+
+// `dharta models auth models <id|slug>` reads the offers; the same command
+// writes them once you pass an enabled set.
+export function modelConnectionsModelsWritesOffers(opts: ModelConnectionModelsOptions): boolean {
+  return opts.enable !== undefined || opts.enableStdin === true;
+}
+
+export function validateModelConnectionsModelsOptions(reference: string, opts: ModelConnectionModelsOptions): void {
+  normalizeModelConnectionReference(reference);
+  if (opts.enable !== undefined && opts.enableStdin) {
+    throw new CliUsageError("Use either --enable or --enable-stdin, not both.");
+  }
+  if (opts.default !== undefined && opts.clearDefault) {
+    throw new CliUsageError("Use either --default or --clear-default, not both.");
+  }
+  // A write replaces the whole enabled set, so a default-only call would
+  // disable every model. Make the caller state the set it wants.
+  if (!modelConnectionsModelsWritesOffers(opts)) {
+    if (opts.default !== undefined || opts.clearDefault) {
+      throw new CliUsageError(
+        "--default and --clear-default replace the enabled model set, so pass --enable <models> or --enable-stdin with them.",
+      );
+    }
+    return;
+  }
+  if (opts.enable !== undefined) parseEnabledModels(opts.enable);
+  if (opts.enableStdin && process.stdin.isTTY) {
+    throw new CliUsageError(ENABLE_STDIN.tty);
+  }
+  if (opts.default !== undefined && opts.enable !== undefined) {
+    normalizeDefaultModel(opts.default, parseEnabledModels(opts.enable));
+  }
+}
+
+// Read the piped model list before the command runs so `--json` output stays
+// a single payload.
+export async function prepareModelConnectionsModelsOptions(
+  reference: string,
+  opts: ModelConnectionModelsOptions,
+  read: () => Promise<string> = () => readPipedStdin(ENABLE_STDIN),
+): Promise<ModelConnectionModelsOptions> {
+  validateModelConnectionsModelsOptions(reference, opts);
+  if (!opts.enableStdin) return opts;
+  const piped = normalizePipedStdin(await read(), ENABLE_STDIN);
+  const prepared = { ...opts, enable: piped, enableStdin: false };
+  validateModelConnectionsModelsOptions(reference, prepared);
+  return prepared;
+}
+
+// Revoking returns 204 with no body, so the payload reports what you asked to
+// revoke: the numeric id for an all-digit argument, the slug otherwise.
+export async function modelConnectionsRevokeData(
+  ctx: CliContext,
+  reference: string,
+): Promise<{ id: number | string; revoked: boolean }> {
+  const normalizedReference = normalizeModelConnectionReference(reference);
+  try {
+    await ctx.http.request<void>({
+      method: "DELETE",
+      path: `/model_connections/${encodeURIComponent(normalizedReference)}`,
+    });
+  } catch (error) {
+    throw addModelConnectionsWriteScopeGuidance(error);
+  }
+  return { id: modelConnectionReferenceId(normalizedReference), revoked: true };
+}
+
+export async function modelConnectionsRevoke(ctx: CliContext, reference: string): Promise<string> {
+  const res = await modelConnectionsRevokeData(ctx, reference);
+  return `Revoked ${res.id}.`;
+}
+
+export function validateModelConnectionReference(reference: string): void {
+  normalizeModelConnectionReference(reference);
+}
+
+const CREATE_STDIN: StdinPrompt = {
+  tty: "No piped input. Usage: echo $PROVIDER_API_KEY | dharta models auth create anthropic Claude --key-stdin",
+  empty: "No model connection on stdin. Usage: echo $PROVIDER_API_KEY | dharta models auth create anthropic Claude --key-stdin",
+};
+const ROTATE_STDIN: StdinPrompt = {
+  tty: "No piped input. Usage: echo $PROVIDER_API_KEY | dharta models auth rotate openai-primary --key-stdin",
+  empty: "No model connection on stdin. Usage: echo $PROVIDER_API_KEY | dharta models auth rotate openai-primary --key-stdin",
+};
+const ENABLE_STDIN: StdinPrompt = {
+  tty: "No piped input. Usage: dharta models auth models openai-primary --enable-stdin < models.txt",
+  empty: "No model ids on stdin. Usage: dharta models auth models openai-primary --enable-stdin < models.txt",
+};
+
+function formatModelConnectionOffers(offers: ModelConnectionOffers): string {
+  const head = `Connector: ${offers.connector.slug} (${offers.connector.provider}, ${offers.connector.id})`;
+  const hint = enableModelsHint(offers.connector.slug);
+  if (offers.models.length === 0) {
+    return `${head}\n\nNo models. Enable some with: ${hint}`;
+  }
+  const rows = table(offers.models.map((offer) => ({
+    model: offer.model_id,
+    enabled: offer.enabled ? "yes" : "no",
+    default: offer.default ? "yes" : "",
+  })));
+  // A full catalog with nothing enabled reads as healthy but resolves nothing,
+  // so say it rather than leaving it to be read off the enabled column.
+  if (offers.models.every((offer) => !offer.enabled)) {
+    return `${head}\n\n${rows}\n\nNo models are enabled, so this connector serves no turns. Enable one with: ${hint}`;
+  }
+  return `${head}\n\n${rows}`;
+}
+
+// Accept the numeric connector id or its organization-unique slug; both
+// address the same connector on every /model_connections path. An all-digit argument
+// is always an id, never a slug, so there is nothing to disambiguate: the
+// console never mints an all-digit slug.
+function normalizeModelConnectionReference(reference: string): string {
+  const normalized = normalizeNonBlank(reference, "Model connection id");
+  if (/^\d+$/.test(normalized)) return String(parseModelConnectionId(normalized));
+  try {
+    return normalizeStoredConnectorSlug(normalized, "Model connection slug");
+  } catch (error) {
+    // The argument is neither shape, so name both rather than only the one
+    // the slug validator happened to check. CliUsageError, because the numeric
+    // branch above already exits 2 through parsePositiveInteger and the same
+    // argument must not exit differently depending on which shape it missed.
+    throw new CliUsageError(
+      `${error instanceof Error ? error.message : String(error)} ` +
+        "Pass the numeric connector id or its slug from `dharta models auth list`.",
+    );
+  }
+}
+
+function modelConnectionReferenceId(normalizedReference: string): number | string {
+  return /^\d+$/.test(normalizedReference) ? Number(normalizedReference) : normalizedReference;
+}
+
+// An empty value is a deliberate empty set: `--enable ""` disables every
+// model on the connector. It is not the same as omitting --enable, which
+// makes the command a read.
+function parseEnabledModels(value: string): string[] {
+  const models = value.split(/[\s,]+/).map((part) => part.trim()).filter(Boolean);
+  if (models.length > MAX_OFFER_MODELS) {
+    throw new CliUsageError(`--enable accepts at most ${MAX_OFFER_MODELS} models.`);
+  }
+  const seen = new Set<string>();
+  for (const model of models) {
+    if (seen.has(model)) throw new CliUsageError(`--enable lists ${model} more than once.`);
+    seen.add(model);
+  }
+  return models;
+}
+
+function normalizeDefaultModel(value: string, enabled: string[]): string {
+  const normalized = normalizeNonBlank(value, "--default");
+  if (enabled.length === 0) {
+    throw new CliUsageError(
+      "--default cannot be set when --enable is empty. Pass --clear-default to leave the connector with no default.",
+    );
+  }
+  if (!enabled.includes(normalized)) {
+    throw new CliUsageError(`--default ${normalized} is not in the enabled set. Add it to --enable, or pick one of: ${enabled.join(", ")}.`);
+  }
+  return normalized;
+}
+
+async function resolveRotatePlaintext(opts: ModelConnectionRotateOptions): Promise<string> {
+  if (opts.key !== undefined && opts.keyStdin) {
+    throw new CliUsageError("Use either --key or --key-stdin, not both.");
+  }
+  if (opts.key !== undefined) return normalizePlaintext(opts.key, "--key");
+  if (opts.keyStdin) return readPipedStdin(ROTATE_STDIN);
+  throw new CliUsageError("Model connection plaintext is required. Pass --key or --key-stdin.");
+}
+
+async function resolveEnabledModels(opts: ModelConnectionModelsOptions): Promise<string> {
+  if (opts.enable !== undefined && opts.enableStdin) {
+    throw new CliUsageError("Use either --enable or --enable-stdin, not both.");
+  }
+  if (opts.enable !== undefined) return opts.enable;
+  if (opts.enableStdin) return readPipedStdin(ENABLE_STDIN);
+  throw new CliUsageError("Pass --enable <models> or --enable-stdin to change the enabled model set.");
+}
+
+async function resolvePlaintext(opts: ModelConnectionCreateOptions): Promise<string> {
+  if (opts.key !== undefined && opts.keyStdin) {
+    throw new CliUsageError("Use either --key or --key-stdin, not both.");
+  }
+  if (opts.key !== undefined) return normalizePlaintext(opts.key, "--key");
+  if (opts.keyStdin) {
+    return readModelConnectionStdin();
+  }
+  throw new CliUsageError("Model connection plaintext is required. Pass --key or --key-stdin.");
+}
+
+// A piped input can fail two ways: nothing is piped at all (a TTY, which
+// would otherwise hang), or the pipe is empty. Each says what to run.
+interface StdinPrompt {
+  tty: string;
+  empty: string;
+}
+
+async function readModelConnectionStdin(): Promise<string> {
+  return readPipedStdin(CREATE_STDIN);
+}
+
+function normalizeModelConnectionStdin(value: string): string {
+  return normalizePipedStdin(value, CREATE_STDIN);
+}
+
+async function readPipedStdin(prompt: StdinPrompt): Promise<string> {
+  if (process.stdin.isTTY) throw new CliUsageError(prompt.tty);
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  return normalizePipedStdin(Buffer.concat(chunks).toString("utf8"), prompt);
+}
+
+function normalizePipedStdin(value: string, prompt: StdinPrompt): string {
+  const text = value.trim();
+  if (text) return text;
+  throw new CliUsageError(prompt.empty);
+}
+
+function normalizeModelConnectionName(name: string): string {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new CliUsageError("Model connection name cannot be blank.");
+  }
+  return normalized;
+}
+
+function parseModelConnectionId(id: string): number {
+  return parsePositiveInteger(id, "Model connection id");
+}
+
+function normalizePlaintext(value: string, flag: string): string {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new CliUsageError(`${flag} cannot be blank.`);
+  }
+  return normalized;
+}
+
+function normalizeEndpointUrl(value: string): string {
+  const normalized = normalizeHttpUrl(value, "--endpoint-url");
+  const parsed = new URL(normalized);
+  if (parsed.protocol !== "https:") {
+    throw new CliUsageError("--endpoint-url must use https.");
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new CliUsageError("--endpoint-url cannot include credentials, a query string, or a fragment.");
+  }
+  return normalized;
+}
+
+// Storing or revoking a connector needs `model_connections:write`, a tenant-admin
+// scope that the `dharta login` device-flow credential deliberately never
+// carries (that key is long-lived and non-admin, so it can't hold a
+// forced-expiry admin scope). A CLI login therefore always 403s here. The
+// generic scope hint says "manage key scopes", but the login key's scopes are
+// fixed — you cannot add the scope to it — so name the real path: store the
+// connector in the dashboard, or mint a bounded key and re-auth with a token.
+function addModelConnectionsWriteScopeGuidance(error: unknown): Error {
+  if (!(error instanceof Error)) return new Error(String(error));
+  const status = (error as Error & { status?: unknown }).status;
+  if (
+    status === 403 &&
+    /model_connections:write/.test(error.message) &&
+    !error.message.includes("dharta login --with-token")
+  ) {
+    error.message +=
+      `${error.message.endsWith(".") ? "" : "."} ` +
+      "The `dharta login` credential cannot hold model_connections:write. Store the connector from the dashboard " +
+      "(`dharta open model-connections`), or mint a bounded key with model_connections:write there (`dharta open api-keys`) " +
+      "and re-authenticate with `dharta login --with-token`.";
+  }
+  return error;
+}

package/src/commands/open.ts

@@ -5,6 +5,7 @@
 import type { CliContext } from "../context.js";
 import { openBrowser } from "../browser.js";
 import { inferAgentSlug, type AgentInferOptions } from "../agent.js";
+import { CliUsageError } from "../exit-codes.js";
 
 export interface OpenOptions extends AgentInferOptions {
   openBrowserImpl?: (url: string) => Promise<boolean>;
@@ -19,7 +20,7 @@ interface ProjectShow {
 
 export interface OpenData {
   slug?: string;
-  target: "agent" | "console" | "billing" | "security" | "api-keys" | "model-keys" | "webhooks" | "connected-accounts";
+  target: "agent" | "console" | "billing" | "security" | "api-keys" | "model-connections" | "webhooks" | "connected-accounts";
   url: string;
   // null until the first deploy; the agent target falls back to the
   // console rather than opening a dead chat page.
@@ -31,7 +32,7 @@ const HANDOFF_TARGETS = {
   billing: "/billing",
   security: "/account/security",
   "api-keys": "/api_keys",
-  "model-keys": "/model_keys",
+  "model-connections": "/model_connections",
   webhooks: "/webhook_endpoints",
   "connected-accounts": "/account/connected_accounts",
 } as const;
@@ -50,11 +51,11 @@ export function normalizeOpenTarget(target: string | undefined): string | undefi
 export function validateOpenTarget(target: string | undefined): void {
   const normalizedTarget = normalizeOpenTarget(target);
   if (target !== undefined && normalizedTarget === "") {
-    throw new Error("target cannot be blank.");
+    throw new CliUsageError("target cannot be blank.");
   }
   if (normalizedTarget !== undefined && normalizedTarget !== "console" && !isHandoffTarget(normalizedTarget)) {
     const suggestion = closestTarget(normalizedTarget);
-    throw new Error(
+    throw new CliUsageError(
       `Unknown target '${normalizedTarget}'. Use one of: ${OPEN_TARGETS_HELP}.` +
         (suggestion ? ` Did you mean '${suggestion}'?` : ""),
     );

package/src/commands/org.ts

@@ -0,0 +1,57 @@
+import type { CliContext } from "../context.js";
+import type {
+  OrganizationRenameResult,
+  SupportAccessResult,
+  TranscriptAccessResult,
+} from "@dharta/sdk";
+import { normalizeNonBlank } from "../validators.js";
+import { CliUsageError } from "../exit-codes.js";
+
+// Mirrors Organization's name validation server-side, so a name that cannot
+// land is rejected before it costs a round trip.
+const MAX_ORGANIZATION_NAME_LENGTH = 200;
+
+export async function orgRenameData(ctx: CliContext, name: string): Promise<OrganizationRenameResult> {
+  return ctx.sdk.organization.rename(normalizeOrganizationName(name));
+}
+
+export async function orgRename(ctx: CliContext, name: string): Promise<string> {
+  const res = await orgRenameData(ctx, name);
+  if (!res.changed) return `${res.organization.name} is already the organization name.`;
+  return `Renamed the organization to ${res.organization.name}. The slug stays ${res.organization.slug}.`;
+}
+
+export async function orgSupportAccessData(ctx: CliContext, allowed: boolean): Promise<SupportAccessResult> {
+  return ctx.sdk.organization.setSupportAccess(allowed);
+}
+
+export async function orgSupportAccess(ctx: CliContext, allowed: boolean): Promise<string> {
+  const res = await orgSupportAccessData(ctx, allowed);
+  const state = res.support_access.allowed
+    ? "Dharta support may access your session data for support tickets (always audited)"
+    : "Dharta support is blocked from accessing your session data";
+  return `${state}${res.changed ? "" : " (unchanged)"}.`;
+}
+
+export async function orgTranscriptAccessData(
+  ctx: CliContext,
+  enabled: boolean,
+): Promise<TranscriptAccessResult> {
+  return ctx.sdk.organization.setTranscriptAccess(enabled);
+}
+
+export async function orgTranscriptAccess(ctx: CliContext, enabled: boolean): Promise<string> {
+  const res = await orgTranscriptAccessData(ctx, enabled);
+  const state = res.transcript_access.enabled
+    ? "API keys may now read end-user transcripts (dharta sessions show)"
+    : "API transcript access disabled. Session metadata stays readable";
+  return `${state}${res.changed ? "" : " (unchanged)"}.`;
+}
+
+export function normalizeOrganizationName(name: string): string {
+  const normalized = normalizeNonBlank(name, "Organization name");
+  if ([...normalized].length > MAX_ORGANIZATION_NAME_LENGTH) {
+    throw new CliUsageError(`Organization name cannot exceed ${MAX_ORGANIZATION_NAME_LENGTH} characters.`);
+  }
+  return normalized;
+}