@dharta/cli 0.6.77

package/src/commands/agents.ts

@@ -0,0 +1,635 @@
+import type { CliContext } from "../context.js";
+import { fmtTs, table } from "../output.js";
+import { validateAgentSlug } from "../agent.js";
+import { closestChoice, parseReleaseVersion } from "../validators.js";
+import { randomUUID } from "node:crypto";
+
+const AGENT_MODEL_SOURCES = ["inherit", "platform"] as const;
+const MAX_OUTPUT_TOKENS = 1_000_000;
+
+export interface AgentSummary {
+  id: string | number;
+  slug: string;
+  name: string;
+  deploy_branch: string;
+  current_version: number | null;
+  current_status: string | null;
+  archived_at?: string | null;
+}
+
+export interface ReleaseSummary {
+  id: string;
+  version: number;
+  status: string;
+  commit_sha: string;
+  current?: boolean;
+  activatable?: boolean;
+  created_at?: string | null;
+  error_message?: string | null;
+}
+
+export interface AgentDetail extends AgentSummary {
+  clone_url: string;
+  agent_url: string;
+  console_url: string;
+  live_version: number | null;
+  releases: ReleaseSummary[];
+  releases_error?: string;
+  resolved_model?: ResolvedAgentModel;
+}
+
+export interface ResolvedAgentModel {
+  model_id: string | null;
+  model_key_id: number | null;
+  auth_type: string;
+  provider: string;
+  endpoint_url: string | null;
+  api_format: string;
+  custom_endpoint: boolean;
+  parameters: Record<string, unknown>;
+}
+
+interface AgentShowEnvelope {
+  agent: {
+    id: string | number;
+    slug: string;
+    name: string;
+    deploy_branch: string;
+    resolved_model?: ResolvedAgentModel;
+  };
+  clone_url: string;
+  agent_url: string;
+  console_url: string;
+  live_version: number | null;
+}
+
+export interface WorkspaceAccessMatrix {
+  owners: { git: boolean; api: boolean };
+  users: { widget: boolean; agent_definition: boolean };
+}
+
+export interface AgentSettingsAgent {
+  id: string;
+  slug: string;
+  name: string;
+  deploy_enabled: boolean;
+  serving_status: string;
+  dashboard_edits_enabled: boolean;
+  workspace_inspectable?: boolean;
+  workspace_access?: WorkspaceAccessMatrix;
+  model: {
+    source: string;
+    key_id: number | null;
+    model: string | null;
+    parameters: Record<string, unknown>;
+  };
+}
+
+interface ActivationAgent {
+  id: string;
+  slug: string;
+  name: string;
+}
+
+interface ListEnvelope<T> {
+  data: T[];
+}
+
+export async function agentsListData(ctx: CliContext): Promise<AgentSummary[]> {
+  try {
+    const res = await ctx.http.request<ListEnvelope<AgentSummary>>({
+      path: "/api/agents",
+    });
+    return res.data;
+  } catch (error) {
+    throw addAgentsListNotFoundGuidance(error);
+  }
+}
+
+export async function agentsList(ctx: CliContext): Promise<string> {
+  const data = await agentsListData(ctx);
+  if (data.length === 0) return "No agents yet. Create one with: dharta create";
+  return table(
+    data.map((p) => ({
+      slug: p.slug,
+      name: p.name,
+      branch: p.deploy_branch,
+      current: p.current_version == null ? "—" : `v${p.current_version}`,
+      status: p.current_status ?? "—",
+    })),
+  );
+}
+
+export async function agentsShowData(
+  ctx: CliContext,
+  slug: string,
+): Promise<AgentDetail> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  const shown = await ctx.http.request<AgentShowEnvelope>({
+    path: `/api/agents/${encodeURIComponent(normalizedSlug)}`,
+  });
+  const releasesResult = await agentsReleasesData(ctx, normalizedSlug)
+    .then((releases) => ({ releases, error: undefined }))
+    .catch((error: unknown) => {
+      if (isReleaseScopeError(error)) {
+        return { releases: [], error: error instanceof Error ? error.message : String(error) };
+      }
+      throw error;
+    });
+  const releases = releasesResult.releases;
+  const current = releases.find((release) => release.current) ?? null;
+  return {
+    ...shown.agent,
+    clone_url: shown.clone_url,
+    agent_url: shown.agent_url,
+    console_url: shown.console_url,
+    live_version: shown.live_version ?? null,
+    current_version: shown.live_version ?? current?.version ?? null,
+    current_status: current?.status ?? null,
+    releases,
+    releases_error: releasesResult.error,
+  };
+}
+
+export async function agentsShow(ctx: CliContext, slug: string): Promise<string> {
+  const p = await agentsShowData(ctx, slug);
+  const current =
+    p.current_version == null
+      ? "—"
+      : p.current_status
+        ? `v${p.current_version} (${p.current_status})`
+        : `v${p.current_version}`;
+  const head = [
+    `Agent: ${p.name} (${p.slug})`,
+    `Deploy branch: ${p.deploy_branch}`,
+    `Current release: ${current}`,
+    ...(p.resolved_model ? [formatResolvedModel(p.resolved_model)] : []),
+  ].join("\n");
+  const releases = p.releases_error
+    ? `Unavailable: ${p.releases_error}`
+    : p.releases.length
+    ? table(
+        p.releases.map((r) => ({
+          version: `v${r.version}`,
+          status: r.status,
+          error: releaseError(r),
+          commit: r.commit_sha.slice(0, 8),
+          created: fmtTs(r.created_at),
+        })),
+      )
+    : `No releases yet. Deploy it with: dharta deploy ${p.slug}`;
+  return `${head}\n\nRecent releases:\n${releases}`;
+}
+
+function formatResolvedModel(route: ResolvedAgentModel): string {
+  const model = route.model_id ?? "provider default";
+  const connector = route.model_key_id == null ? "platform" : `connector ${route.model_key_id}`;
+  const parameters = Object.entries(route.parameters)
+    .map(([name, value]) => `${name}=${JSON.stringify(value)}`)
+    .join(", ");
+  return [
+    `Resolved model: ${route.provider}/${model} (${route.api_format}, ${connector})`,
+    route.endpoint_url ? `Model endpoint: ${route.endpoint_url}` : null,
+    parameters ? `Model parameters: ${parameters}` : null,
+  ].filter((line): line is string => line !== null).join("\n");
+}
+
+function isReleaseScopeError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const status = (error as Error & { status?: unknown }).status;
+  return status === 403 && /releases:read|releases:write|required scopes/i.test(error.message);
+}
+
+function addAgentsListNotFoundGuidance(error: unknown): Error {
+  if (error instanceof Error) {
+    const status = (error as Error & { status?: unknown }).status;
+    if (status === 404 && !error.message.includes("Could not list agents")) {
+      const guided = new Error(
+        "Could not list agents: the active Dharta host returned 404 for /api/agents. " +
+          "Run `dharta auth status` to confirm DHARTA_BASE_URL points at the Dharta control API; " +
+          "if it does, the server needs the public API route deployed for this CLI version.",
+      ) as Error & { status?: unknown; body?: unknown };
+      guided.status = status;
+      guided.body = (error as Error & { body?: unknown }).body;
+      return guided;
+    }
+    return error;
+  }
+  return new Error(String(error));
+}
+
+export async function agentsReleasesData(
+  ctx: CliContext,
+  slug: string,
+): Promise<ReleaseSummary[]> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  const res = await ctx.http.request<ListEnvelope<ReleaseSummary>>({
+    path: `/api/agents/${encodeURIComponent(normalizedSlug)}/releases`,
+  });
+  return res.data;
+}
+
+export async function agentsReleases(
+  ctx: CliContext,
+  slug: string,
+): Promise<string> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  const data = await agentsReleasesData(ctx, normalizedSlug);
+  if (data.length === 0) return `No releases for ${normalizedSlug}. Deploy it with: dharta deploy ${normalizedSlug}`;
+  return table(
+    data.map((r) => ({
+      version: `v${r.version}`,
+      status: r.status,
+      error: releaseError(r),
+      commit: r.commit_sha.slice(0, 8),
+      created: fmtTs(r.created_at),
+    })),
+  );
+}
+
+function releaseError(release: ReleaseSummary): string {
+  if (release.status !== "failed" || !release.error_message) return "";
+  const oneLine = release.error_message.replace(/\s+/g, " ").trim();
+  return oneLine.length > 96 ? `${oneLine.slice(0, 93)}...` : oneLine;
+}
+
+export async function agentsActivateReleaseData(
+  ctx: CliContext,
+  slug: string,
+  version: string,
+): Promise<{ agent: ActivationAgent; release: ReleaseSummary; previous_release: ReleaseSummary | null }> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  const releaseVersion = parseReleaseVersion(version, "release version");
+  return ctx.http.request<{ agent: ActivationAgent; release: ReleaseSummary; previous_release: ReleaseSummary | null }>({
+    method: "POST",
+    path: `/api/agents/${encodeURIComponent(normalizedSlug)}/releases/${encodeURIComponent(releaseVersion)}/activate`,
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+}
+
+export async function agentsActivateRelease(ctx: CliContext, slug: string, version: string): Promise<string> {
+  const res = await agentsActivateReleaseData(ctx, slug, version);
+  const previous = res.previous_release ? ` Previous: v${res.previous_release.version}.` : "";
+  return `Activated ${res.agent.slug} v${res.release.version}.${previous}`;
+}
+
+export async function agentsServingSetData(
+  ctx: CliContext,
+  slug: string,
+  enabled: boolean,
+): Promise<{ agent: AgentSettingsAgent; changed: boolean }> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  return ctx.http.request<{ agent: AgentSettingsAgent; changed: boolean }>({
+    method: "PATCH",
+    path: `/api/agents/${encodeURIComponent(normalizedSlug)}/serving`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: { enabled },
+  });
+}
+
+export async function agentsServingSet(ctx: CliContext, slug: string, enabled: boolean): Promise<string> {
+  const res = await agentsServingSetData(ctx, slug, enabled);
+  const verb = enabled ? "serving" : "paused";
+  return `${res.agent.slug} is ${verb}${res.changed ? "" : " (unchanged)"}.`;
+}
+
+export async function agentsDashboardEditsSetData(
+  ctx: CliContext,
+  slug: string,
+  enabled: boolean,
+): Promise<{ agent: AgentSettingsAgent; changed: boolean }> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  return ctx.http.request<{ agent: AgentSettingsAgent; changed: boolean }>({
+    method: "PATCH",
+    path: `/api/agents/${encodeURIComponent(normalizedSlug)}/dashboard_edits`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: { enabled },
+  });
+}
+
+export async function agentsDashboardEditsSet(ctx: CliContext, slug: string, enabled: boolean): Promise<string> {
+  const res = await agentsDashboardEditsSetData(ctx, slug, enabled);
+  const state = enabled ? "enabled" : "disabled";
+  return `Dashboard edits ${state} for ${res.agent.slug}${res.changed ? "" : " (unchanged)"}.`;
+}
+
+export interface AgentModelSetOptions {
+  source?: string;
+  connectorId?: string;
+  model?: string;
+  temperature?: string;
+  clearTemperature?: boolean;
+  topP?: string;
+  clearTopP?: boolean;
+  maxOutputTokens?: string;
+  clearMaxOutputTokens?: boolean;
+  reasoningEffort?: string;
+  clearReasoningEffort?: boolean;
+}
+
+export async function agentsModelSetData(
+  ctx: CliContext,
+  slug: string,
+  opts: AgentModelSetOptions,
+): Promise<{ agent: AgentSettingsAgent }> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  const normalized = validateAgentModelSetOptions(opts);
+  const body: Record<string, unknown> = {};
+  if (normalized.source !== undefined || normalized.connectorId !== undefined) {
+    body.model_connector = modelConnector(normalized);
+  }
+  if (normalized.model !== undefined) body.default_model_id = normalized.model;
+  const modelParameters = modelParameterPatch(normalized);
+  if (Object.keys(modelParameters).length > 0) body.model_parameters = modelParameters;
+  return ctx.http.request<{ agent: AgentSettingsAgent }>({
+    method: "PATCH",
+    path: `/api/agents/${encodeURIComponent(normalizedSlug)}/model`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body,
+  });
+}
+
+export async function agentsModelSet(ctx: CliContext, slug: string, opts: AgentModelSetOptions): Promise<string> {
+  const res = await agentsModelSetData(ctx, slug, opts);
+  const model = res.agent.model.model ? ` model ${res.agent.model.model}` : "";
+  return `Model override for ${res.agent.slug}: ${res.agent.model.source}${model}.`;
+}
+
+export function validateAgentModelSetOptions(opts: AgentModelSetOptions): AgentModelSetOptions {
+  const normalized = normalizeModelSetOptions(opts);
+  validateModelSetOptions(normalized);
+  return normalized;
+}
+
+export async function agentsWorkspaceInspectableSetData(
+  ctx: CliContext,
+  slug: string,
+  enabled: boolean,
+): Promise<{ agent: AgentSettingsAgent; changed: boolean }> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  return ctx.http.request<{ agent: AgentSettingsAgent; changed: boolean }>({
+    method: "PATCH",
+    path: `/api/agents/${encodeURIComponent(normalizedSlug)}/workspace_inspectable`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: { enabled },
+  });
+}
+
+export async function agentsWorkspaceInspectableSet(ctx: CliContext, slug: string, enabled: boolean): Promise<string> {
+  const res = await agentsWorkspaceInspectableSetData(ctx, slug, enabled);
+  const state = enabled ? "enabled" : "disabled";
+  return `Workspace inspection ${state} for ${res.agent.slug}${res.changed ? "" : " (unchanged)"}.`;
+}
+
+// RFC 0060 D1 — the audience x channel grant matrix. The four dotted grants map
+// onto the nested `workspace_access` shape the API PATCHes.
+export const WORKSPACE_ACCESS_PATHS = [
+  "owners.git",
+  "owners.api",
+  "users.widget",
+  "users.agent_definition",
+] as const;
+
+export type WorkspaceAccessPatch = Record<string, Record<string, boolean>>;
+
+// Parse `path=on|off` assignments (e.g. "users.widget=on") into the nested patch
+// the API merges. Unknown paths and non-on/off values fail loud with a suggestion.
+export function parseWorkspaceAccessAssignments(assignments: string[]): WorkspaceAccessPatch {
+  if (assignments.length === 0) {
+    throw new Error("Provide at least one grant, e.g. users.widget=on");
+  }
+  const patch: WorkspaceAccessPatch = {};
+  for (const raw of assignments) {
+    const eq = raw.indexOf("=");
+    if (eq === -1) {
+      throw new Error(`Invalid grant "${raw}". Use <path>=<on|off>, e.g. users.widget=on.`);
+    }
+    const path = raw.slice(0, eq).trim();
+    const value = raw.slice(eq + 1);
+    if (!WORKSPACE_ACCESS_PATHS.includes(path as (typeof WORKSPACE_ACCESS_PATHS)[number])) {
+      const suggestion = closestChoice(path, WORKSPACE_ACCESS_PATHS);
+      throw new Error(
+        `Unknown grant "${path}". One of: ${WORKSPACE_ACCESS_PATHS.join(", ")}.` +
+          (suggestion ? ` Did you mean ${suggestion}?` : ""),
+      );
+    }
+    const [audience, channel] = path.split(".");
+    (patch[audience] ??= {})[channel] = parseGrantValue(value, path);
+  }
+  return patch;
+}
+
+function parseGrantValue(value: string, path: string): boolean {
+  const normalized = value.trim().toLowerCase();
+  if (["on", "true", "enabled", "enable", "1"].includes(normalized)) return true;
+  if (["off", "false", "disabled", "disable", "0"].includes(normalized)) return false;
+  throw new Error(`Grant "${path}" must be on/off, enabled/disabled, or true/false (got "${value}").`);
+}
+
+export async function agentsWorkspaceAccessShowData(ctx: CliContext, slug: string): Promise<WorkspaceAccessMatrix> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  const res = await ctx.http.request<{ agent: { workspace_access?: WorkspaceAccessMatrix } }>({
+    path: `/api/agents/${encodeURIComponent(normalizedSlug)}`,
+  });
+  const matrix = res.agent.workspace_access;
+  if (!matrix) {
+    throw new Error("This Dharta server does not report workspace access. Upgrade the server (RFC 0060).");
+  }
+  return matrix;
+}
+
+export async function agentsWorkspaceAccessShow(ctx: CliContext, slug: string): Promise<string> {
+  const wa = await agentsWorkspaceAccessShowData(ctx, slug);
+  const onoff = (granted: boolean): string => (granted ? "on" : "off");
+  return [
+    "Workspace access grants:",
+    `  owners.git:              ${onoff(wa.owners.git)}`,
+    `  owners.api:              ${onoff(wa.owners.api)}`,
+    `  users.widget:            ${onoff(wa.users.widget)}`,
+    `  users.agent_definition:  ${onoff(wa.users.agent_definition)}`,
+  ].join("\n");
+}
+
+export async function agentsWorkspaceAccessSetData(
+  ctx: CliContext,
+  slug: string,
+  patch: WorkspaceAccessPatch,
+): Promise<{ agent: AgentSettingsAgent; changed: boolean }> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  return ctx.http.request<{ agent: AgentSettingsAgent; changed: boolean }>({
+    method: "PATCH",
+    path: `/api/agents/${encodeURIComponent(normalizedSlug)}/workspace_access`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: { workspace_access: patch },
+  });
+}
+
+export async function agentsWorkspaceAccessSet(
+  ctx: CliContext,
+  slug: string,
+  patch: WorkspaceAccessPatch,
+): Promise<string> {
+  const res = await agentsWorkspaceAccessSetData(ctx, slug, patch);
+  const paths = Object.entries(patch).flatMap(([audience, channels]) =>
+    Object.entries(channels).map(([channel, granted]) => `${audience}.${channel}=${granted ? "on" : "off"}`),
+  );
+  return `Workspace access updated for ${res.agent.slug}: ${paths.join(", ")}${res.changed ? "" : " (unchanged)"}.`;
+}
+
+export async function agentsDeleteData(ctx: CliContext, slug: string): Promise<{ agent: AgentSettingsAgent; archived: boolean }> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  return ctx.http.request<{ agent: AgentSettingsAgent; archived: boolean }>({
+    method: "DELETE",
+    path: `/api/agents/${encodeURIComponent(normalizedSlug)}`,
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+}
+
+export async function agentsDelete(ctx: CliContext, slug: string): Promise<string> {
+  const res = await agentsDeleteData(ctx, slug);
+  return `Archived ${res.agent.slug}.`;
+}
+
+function modelConnector(opts: AgentModelSetOptions): string {
+  if (opts.connectorId) return `key:${opts.connectorId}`;
+  if (opts.source === "platform") return "platform";
+  if (opts.source === "inherit" || !opts.source) return "inherit";
+  throw new Error("--source must be inherit or platform.");
+}
+
+function validateModelSetOptions(opts: AgentModelSetOptions): void {
+  const hasSource = opts.source !== undefined;
+  const hasConnector = opts.connectorId !== undefined;
+  const hasModel = opts.model !== undefined;
+  const hasParameters = modelParameterOptionPresent(opts);
+
+  if (!hasSource && !hasConnector && !hasModel && !hasParameters) {
+    throw new Error(
+      "Pass at least one model option, connector option, or parameter option.",
+    );
+  }
+  if (hasSource && hasConnector) {
+    throw new Error("Use either --source or --connector-id, not both.");
+  }
+  if (hasSource && !(AGENT_MODEL_SOURCES as readonly string[]).includes(opts.source as string)) {
+    const suggestion = closestChoice(opts.source as string, AGENT_MODEL_SOURCES);
+    throw new Error(
+      `Unknown --source ${opts.source}. Allowed sources: ${AGENT_MODEL_SOURCES.join(", ")}.` +
+        (suggestion ? ` Did you mean ${suggestion}?` : ""),
+    );
+  }
+  if (hasConnector && !isPositiveNumericId(opts.connectorId as string)) {
+    throw new Error("--connector-id must be a positive numeric model connector id from `dharta model-keys list`.");
+  }
+  validateParameterPair(opts.temperature, opts.clearTemperature, "--temperature", "--clear-temperature");
+  validateParameterPair(opts.topP, opts.clearTopP, "--top-p", "--clear-top-p");
+  validateParameterPair(
+    opts.maxOutputTokens,
+    opts.clearMaxOutputTokens,
+    "--max-output-tokens",
+    "--clear-max-output-tokens",
+  );
+  validateParameterPair(
+    opts.reasoningEffort,
+    opts.clearReasoningEffort,
+    "--reasoning-effort",
+    "--clear-reasoning-effort",
+  );
+  if (opts.temperature !== undefined) parseBoundedNumber(opts.temperature, "--temperature", 0, 2, false);
+  if (opts.topP !== undefined) parseBoundedNumber(opts.topP, "--top-p", 0, 1, true);
+  if (opts.maxOutputTokens !== undefined) {
+    const value = parsePositiveInteger(opts.maxOutputTokens, "--max-output-tokens");
+    if (value > MAX_OUTPUT_TOKENS) {
+      throw new Error(`--max-output-tokens must be at most ${MAX_OUTPUT_TOKENS}.`);
+    }
+  }
+  if (opts.reasoningEffort !== undefined && !["low", "medium", "high"].includes(opts.reasoningEffort)) {
+    throw new Error("--reasoning-effort must be low, medium, or high.");
+  }
+}
+
+function isPositiveNumericId(value: string): boolean {
+  if (!/^\d+$/.test(value)) return false;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0;
+}
+
+function normalizeModelSetOptions(opts: AgentModelSetOptions): AgentModelSetOptions {
+  return {
+    source: normalizeOptionalFlag(opts.source, "--source"),
+    connectorId: normalizeOptionalFlag(opts.connectorId, "--connector-id"),
+    model: normalizeOptionalFlag(opts.model, "--model"),
+    temperature: normalizeOptionalFlag(opts.temperature, "--temperature"),
+    clearTemperature: opts.clearTemperature,
+    topP: normalizeOptionalFlag(opts.topP, "--top-p"),
+    clearTopP: opts.clearTopP,
+    maxOutputTokens: normalizeOptionalFlag(opts.maxOutputTokens, "--max-output-tokens"),
+    clearMaxOutputTokens: opts.clearMaxOutputTokens,
+    reasoningEffort: normalizeOptionalFlag(opts.reasoningEffort, "--reasoning-effort"),
+    clearReasoningEffort: opts.clearReasoningEffort,
+  };
+}
+
+function modelParameterOptionPresent(opts: AgentModelSetOptions): boolean {
+  return opts.temperature !== undefined || opts.clearTemperature === true ||
+    opts.topP !== undefined || opts.clearTopP === true ||
+    opts.maxOutputTokens !== undefined || opts.clearMaxOutputTokens === true ||
+    opts.reasoningEffort !== undefined || opts.clearReasoningEffort === true;
+}
+
+function modelParameterPatch(opts: AgentModelSetOptions): Record<string, number | string | null> {
+  const patch: Record<string, number | string | null> = {};
+  if (opts.temperature !== undefined) patch.temperature = Number(opts.temperature);
+  if (opts.clearTemperature) patch.temperature = null;
+  if (opts.topP !== undefined) patch.top_p = Number(opts.topP);
+  if (opts.clearTopP) patch.top_p = null;
+  if (opts.maxOutputTokens !== undefined) patch.max_output_tokens = Number(opts.maxOutputTokens);
+  if (opts.clearMaxOutputTokens) patch.max_output_tokens = null;
+  if (opts.reasoningEffort !== undefined) patch.reasoning_effort = opts.reasoningEffort;
+  if (opts.clearReasoningEffort) patch.reasoning_effort = null;
+  return patch;
+}
+
+function validateParameterPair(
+  value: string | undefined,
+  clear: boolean | undefined,
+  setFlag: string,
+  clearFlag: string,
+): void {
+  if (value !== undefined && clear) throw new Error(`Use either ${setFlag} or ${clearFlag}, not both.`);
+}
+
+function parseBoundedNumber(
+  value: string,
+  flag: string,
+  minimum: number,
+  maximum: number,
+  exclusiveMinimum: boolean,
+): number {
+  const parsed = Number(value);
+  const minimumOk = exclusiveMinimum ? parsed > minimum : parsed >= minimum;
+  if (!Number.isFinite(parsed) || !minimumOk || parsed > maximum) {
+    const lower = exclusiveMinimum ? `greater than ${minimum}` : `at least ${minimum}`;
+    throw new Error(`${flag} must be a finite number ${lower} and at most ${maximum}.`);
+  }
+  return parsed;
+}
+
+function parsePositiveInteger(value: string, flag: string): number {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new Error(`${flag} must be a positive whole number.`);
+  }
+  return parsed;
+}
+
+function normalizeOptionalFlag(value: string | undefined, flag: string): string | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.trim();
+  if (normalized.length === 0) throw new Error(`${flag} cannot be blank.`);
+  return normalized;
+}
+
+function normalizeAgentSlug(slug: string): string {
+  return validateAgentSlug(slug, "agent slug");
+}