@dharta/cli 0.6.77 → 0.6.78

package/src/commands/agents.ts

@@ -1,11 +1,31 @@
 import type { CliContext } from "../context.js";
+import type {
+  AgentChangeResponse,
+  AgentCreateParams,
+  AgentCreateResponse,
+  AgentDeployResponse,
+  AgentFromTemplateParams,
+  AgentFromTemplateResponse,
+  AgentLinkGithubResponse,
+  GithubRepository,
+  ReleaseRetryResponse,
+} from "@dharta/sdk";
+import { isAgentLinkGithubResponse } from "@dharta/sdk";
 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;
+import { CliUsageError } from "../exit-codes.js";
+import { closestChoice, normalizeNonBlank, parsePositiveInteger, parseReleaseVersion } from "../validators.js";
+import {
+  type ModelParameterOptions,
+  formatModelParameters,
+  modelParameterOptionPresent,
+  modelParameterPatch,
+  normalizeConnectorSlug,
+  normalizeModelParameterOptions,
+  normalizeModelReference,
+  parseConnectorOrder,
+  validateModelParameterOptions,
+} from "../model-settings.js";
 
 export interface AgentSummary {
   id: string | number;
@@ -38,16 +58,35 @@ export interface AgentDetail extends AgentSummary {
   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>;
-}
+// Either the route resolved, or it carries a stable failure code and nothing
+// else. Narrow on `error` before reading the rest, the same way the SDK's
+// ResolvedOrganizationModel is read.
+export type ResolvedAgentModel =
+  | {
+      error?: never;
+      model_id: string | null;
+      model_connection_id: number | null;
+      // The selected connector's slug, or `karta` for the platform connector.
+      connector: string | null;
+      credential_kind: string;
+      provider: string;
+      endpoint_url: string | null;
+      api_format: string;
+      custom_endpoint: boolean;
+      parameters: Record<string, unknown>;
+    }
+  | {
+      error: string;
+      model_id?: never;
+      model_connection_id?: never;
+      connector?: never;
+      credential_kind?: never;
+      provider?: never;
+      endpoint_url?: never;
+      api_format?: never;
+      custom_endpoint?: never;
+      parameters?: never;
+    };
 
 interface AgentShowEnvelope {
   agent: {
@@ -79,9 +118,11 @@ export interface AgentSettingsAgent {
   workspace_access?: WorkspaceAccessMatrix;
   model: {
     source: string;
-    key_id: number | null;
+    model_connection_id: number | null;
     model: string | null;
     parameters: Record<string, unknown>;
+    connector_order: string[];
+    model_reference: string;
   };
 }
 
@@ -182,11 +223,14 @@ export async function agentsShow(ctx: CliContext, slug: string): Promise<string>
 }
 
 function formatResolvedModel(route: ResolvedAgentModel): string {
+  // An organization with no resolvable model still has agents worth reading.
+  // Say which failure it is rather than printing a route made of blanks.
+  if (route.error !== undefined) {
+    return `Resolved model: unavailable (${route.error})`;
+  }
   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(", ");
+  const connector = resolvedConnectorLabel(route);
+  const parameters = formatModelParameters(route.parameters);
   return [
     `Resolved model: ${route.provider}/${model} (${route.api_format}, ${connector})`,
     route.endpoint_url ? `Model endpoint: ${route.endpoint_url}` : null,
@@ -194,6 +238,14 @@ function formatResolvedModel(route: ResolvedAgentModel): string {
   ].filter((line): line is string => line !== null).join("\n");
 }
 
+// Name the connector the way every other command does: by slug, which is
+// also what `--connector` and a model reference accept.
+function resolvedConnectorLabel(route: ResolvedAgentModel): string {
+  return route.connector === "karta" || route.connector === null
+    ? "platform"
+    : `connector ${route.connector}`;
+}
+
 function isReleaseScopeError(error: unknown): boolean {
   if (!(error instanceof Error)) return false;
   const status = (error as Error & { status?: unknown }).status;
@@ -263,7 +315,6 @@ export async function agentsActivateReleaseData(
   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() },
   });
 }
 
@@ -282,7 +333,6 @@ export async function agentsServingSetData(
   return ctx.http.request<{ agent: AgentSettingsAgent; changed: boolean }>({
     method: "PATCH",
     path: `/api/agents/${encodeURIComponent(normalizedSlug)}/serving`,
-    headers: { "Idempotency-Key": randomUUID() },
     body: { enabled },
   });
 }
@@ -302,7 +352,6 @@ export async function agentsDashboardEditsSetData(
   return ctx.http.request<{ agent: AgentSettingsAgent; changed: boolean }>({
     method: "PATCH",
     path: `/api/agents/${encodeURIComponent(normalizedSlug)}/dashboard_edits`,
-    headers: { "Idempotency-Key": randomUUID() },
     body: { enabled },
   });
 }
@@ -313,18 +362,9 @@ export async function agentsDashboardEditsSet(ctx: CliContext, slug: string, ena
   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 interface AgentModelSetOptions extends ModelParameterOptions {
+  connector?: string;
+  modelRef?: string;
 }
 
 export async function agentsModelSetData(
@@ -335,16 +375,17 @@ export async function agentsModelSetData(
   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.connector !== undefined) {
+    body.connector_order = parseConnectorOrder(normalized.connector, "--connector");
+  }
+  if (normalized.modelRef !== undefined) {
+    body.model_reference = normalizeModelReference(normalized.modelRef, "--model-ref");
   }
-  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,
   });
 }
@@ -352,7 +393,9 @@ export async function agentsModelSetData(
 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}.`;
+  const order = res.agent.model.connector_order;
+  const source = order.length > 0 ? order.join(", ") : res.agent.model.source;
+  return `Model override for ${res.agent.slug}: ${source}${model}.`;
 }
 
 export function validateAgentModelSetOptions(opts: AgentModelSetOptions): AgentModelSetOptions {
@@ -370,7 +413,6 @@ export async function agentsWorkspaceInspectableSetData(
   return ctx.http.request<{ agent: AgentSettingsAgent; changed: boolean }>({
     method: "PATCH",
     path: `/api/agents/${encodeURIComponent(normalizedSlug)}/workspace_inspectable`,
-    headers: { "Idempotency-Key": randomUUID() },
     body: { enabled },
   });
 }
@@ -396,19 +438,19 @@ export type WorkspaceAccessPatch = Record<string, Record<string, boolean>>;
 // 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");
+    throw new CliUsageError("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.`);
+      throw new CliUsageError(`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(
+      throw new CliUsageError(
         `Unknown grant "${path}". One of: ${WORKSPACE_ACCESS_PATHS.join(", ")}.` +
           (suggestion ? ` Did you mean ${suggestion}?` : ""),
       );
@@ -423,7 +465,7 @@ 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}").`);
+  throw new CliUsageError(`Grant "${path}" must be on/off, enabled/disabled, or true/false (got "${value}").`);
 }
 
 export async function agentsWorkspaceAccessShowData(ctx: CliContext, slug: string): Promise<WorkspaceAccessMatrix> {
@@ -459,7 +501,6 @@ export async function agentsWorkspaceAccessSetData(
   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 },
   });
 }
@@ -476,160 +517,317 @@ export async function agentsWorkspaceAccessSet(
   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 }> {
+// RFC 0048 P4. From here down the commands go through the SDK resource rather
+// than a hand-built request: every new endpoint ships an @dharta/sdk method and
+// the curated command calls it, so the wire shape and the idempotency header
+// have one owner.
+
+export async function agentsRenameData(
+  ctx: CliContext,
+  slug: string,
+  name: string,
+): Promise<AgentChangeResponse> {
   const normalizedSlug = normalizeAgentSlug(slug);
-  return ctx.http.request<{ agent: AgentSettingsAgent; archived: boolean }>({
-    method: "DELETE",
-    path: `/api/agents/${encodeURIComponent(normalizedSlug)}`,
-    headers: { "Idempotency-Key": randomUUID() },
-  });
+  return ctx.sdk.agents.rename(normalizedSlug, normalizeAgentName(name));
 }
 
-export async function agentsDelete(ctx: CliContext, slug: string): Promise<string> {
-  const res = await agentsDeleteData(ctx, slug);
-  return `Archived ${res.agent.slug}.`;
+export async function agentsRename(ctx: CliContext, slug: string, name: string): Promise<string> {
+  const res = await agentsRenameData(ctx, slug, name);
+  const unchanged = res.changed ? "" : " (unchanged)";
+  return `${res.agent.slug} is now displayed as ${JSON.stringify(res.agent.name)}${unchanged}. The slug is unchanged.`;
 }
 
-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.");
+export async function agentsDurableWorkspaceSetData(
+  ctx: CliContext,
+  slug: string,
+  enabled: boolean,
+): Promise<AgentChangeResponse> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  return ctx.sdk.agents.setDurableWorkspace(normalizedSlug, enabled);
 }
 
-function validateModelSetOptions(opts: AgentModelSetOptions): void {
-  const hasSource = opts.source !== undefined;
-  const hasConnector = opts.connectorId !== undefined;
-  const hasModel = opts.model !== undefined;
-  const hasParameters = modelParameterOptionPresent(opts);
+export async function agentsDurableWorkspaceSet(
+  ctx: CliContext,
+  slug: string,
+  enabled: boolean,
+): Promise<string> {
+  const res = await agentsDurableWorkspaceSetData(ctx, slug, enabled);
+  const state = enabled ? "enabled" : "disabled";
+  if (!res.changed) return `Durable workspace already ${state} for ${res.agent.slug}.`;
+  const effect = enabled
+    ? "Takes effect on the next release."
+    : "Takes effect on the next release; stored data is kept.";
+  return `Durable workspace ${state} for ${res.agent.slug}. ${effect}`;
+}
 
-  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.");
+export interface AgentCreateOptions {
+  slug?: string;
+  githubRepo?: string;
+  branch?: string;
+}
+
+export async function agentsCreateData(
+  ctx: CliContext,
+  name: string | undefined,
+  opts: AgentCreateOptions = {},
+): Promise<AgentCreateResponse | AgentLinkGithubResponse> {
+  const params = validateAgentCreateInput(name, opts);
+  if (typeof params.githubRepositoryId === "string") {
+    params.githubRepositoryId = await resolveGithubRepositoryId(ctx, params.githubRepositoryId);
   }
-  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}?` : ""),
-    );
+  return ctx.sdk.agents.create(params);
+}
+
+// `--github-repo` takes either the numeric id or the owner/name a person can
+// actually read off GitHub. The name is resolved through the same listing
+// `dharta agent github-repos` prints, so an unknown one names the alternatives
+// rather than reaching the server as a 404.
+async function resolveGithubRepositoryId(ctx: CliContext, fullName: string): Promise<number> {
+  let data: GithubRepository[];
+  try {
+    ({ data } = await ctx.sdk.githubRepositories.list());
+  } catch (error) {
+    // The listing rides source_repos:read, which a deploy key holding only
+    // agents:write does not have. Without this the command fails naming a scope
+    // the user never asked for, on a step they did not know it was taking.
+    if ((error as { status?: number }).status === 403) {
+      throw new CliUsageError(
+        `Resolving --github-repo ${fullName} needs the source_repos:read scope, because it looks the ` +
+          "repository up in your installations. This key does not have it. Pass the numeric id " +
+          "instead, which needs no extra scope, or use a key with source_repos:read.",
+      );
+    }
+    throw error;
   }
-  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`.");
+  const wanted = fullName.toLowerCase();
+  const match = data.find((repo) => repo.full_name.toLowerCase() === wanted);
+  if (match) return match.id;
+
+  const known = data.map((repo) => repo.full_name);
+  const suggestion = closestChoice(fullName, known);
+  const tail = suggestion
+    ? ` Did you mean ${suggestion}?`
+    : known.length > 0
+      ? ` Installed: ${known.slice(0, 10).join(", ")}.`
+      : " No repositories are installed for this organization; install the Dharta GitHub App first.";
+  // A usage error, not a failure: the user typed a name that does not exist, so
+  // this exits 2 like every other bad-argument path rather than 1.
+  throw new CliUsageError(`${fullName} is not an installed GitHub repository.${tail}`);
+}
+
+export async function agentsGithubReposData(ctx: CliContext): Promise<{ data: GithubRepository[] }> {
+  return ctx.sdk.githubRepositories.list();
+}
+
+export async function agentsGithubRepos(ctx: CliContext): Promise<string> {
+  const { data } = await agentsGithubReposData(ctx);
+  if (data.length === 0) {
+    return "No GitHub repositories are installed for this organization. Install the Dharta GitHub App, then try again.";
   }
-  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",
+  return table(
+    data.map((repo) => ({
+      id: String(repo.id),
+      repository: repo.full_name,
+      branch: repo.default_branch,
+      account: repo.installation?.account_login ?? "-",
+      linked: repo.linked ? "yes" : "no",
+    })),
   );
-  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}.`);
-    }
+}
+
+export async function agentsCreate(
+  ctx: CliContext,
+  name: string | undefined,
+  opts: AgentCreateOptions = {},
+): Promise<string> {
+  const res = await agentsCreateData(ctx, name, opts);
+  if (isAgentLinkGithubResponse(res)) {
+    const verb = res.created ? "Linked" : "Re-linked";
+    // A sync that could not be queued is a 503 from the server, so it never
+    // reaches here: it throws, and the command exits non-zero. Re-running the
+    // command is the right retry - the server never stores a 5xx, so a retry
+    // re-drives the sync whether it reuses the key or mints a new one.
+    return [
+      `${verb} ${res.source_repo.github_repository} as ${res.source_repo.slug} ` +
+        `(branch ${res.source_repo.deploy_branch}).`,
+      "An agent appears after the sync, when the deploy branch has exactly one enabled dharta.toml.",
+      "Watch for it with: dharta agent list",
+    ].join("\n");
+  }
+  const verb = res.created ? "Created" : "Already exists:";
+  return [
+    `${verb} ${res.agent.slug} (branch ${res.agent.deploy_branch}).`,
+    `Clone: ${res.clone_url}`,
+  ].join("\n");
+}
+
+// Exported so the command layer can reject bad input before it costs a request.
+export function validateAgentCreateInput(
+  name: string | undefined,
+  opts: AgentCreateOptions = {},
+): AgentCreateParams {
+  const params: AgentCreateParams = {};
+  if (opts.githubRepo !== undefined) {
+    // An owner/name is kept as a string and resolved against the installed
+    // listing later; a bare number is validated here so a typo costs no request.
+    params.githubRepositoryId = opts.githubRepo.includes("/")
+      ? normalizeGithubFullName(opts.githubRepo)
+      : parsePositiveInteger(opts.githubRepo, "--github-repo");
+  }
+  if (name !== undefined) params.name = normalizeAgentName(name);
+  if (params.name === undefined && params.githubRepositoryId === undefined) {
+    throw new CliUsageError("Pass a name, or --github-repo <id> to link an installed GitHub repository.");
   }
-  if (opts.reasoningEffort !== undefined && !["low", "medium", "high"].includes(opts.reasoningEffort)) {
-    throw new Error("--reasoning-effort must be low, medium, or high.");
+  if (opts.slug !== undefined) params.slug = normalizeAgentSlug(opts.slug);
+  if (opts.branch !== undefined) {
+    if (opts.githubRepo === undefined) {
+      throw new CliUsageError("--branch needs --github-repo: the deploy branch belongs to the linked repository.");
+    }
+    params.deployBranch = normalizeNonBlank(opts.branch, "--branch");
   }
+  return params;
 }
 
-function isPositiveNumericId(value: string): boolean {
-  if (!/^\d+$/.test(value)) return false;
-  const parsed = Number(value);
-  return Number.isSafeInteger(parsed) && parsed > 0;
+export interface AgentCreateFromTemplateOptions {
+  slug?: string;
+  description?: string;
+  harness?: string;
+  harnessVersion?: string;
 }
 
-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,
+export async function agentsCreateFromTemplateData(
+  ctx: CliContext,
+  template: string,
+  name: string,
+  opts: AgentCreateFromTemplateOptions = {},
+): Promise<AgentFromTemplateResponse> {
+  const params = validateAgentCreateFromTemplateInput(template, name, opts);
+  return ctx.sdk.agents.createFromTemplate(params);
+}
+
+export async function agentsCreateFromTemplate(
+  ctx: CliContext,
+  template: string,
+  name: string,
+  opts: AgentCreateFromTemplateOptions = {},
+): Promise<string> {
+  const res = await agentsCreateFromTemplateData(ctx, template, name, opts);
+  const version = res.release ? `v${res.release.version}` : "the first release";
+  const state = res.release?.status === "active" && !res.state
+    ? `${version} is live.`
+    : `${version} is still building - watch it with \`dharta agent releases ${res.agent.slug}\`.`;
+  return [
+    `Created ${res.agent.slug} from the '${normalizeNonBlank(template, "template")}' template. ${state}`,
+    `Clone: ${res.clone_url}`,
+    `Open it with: dharta open ${res.agent.slug}`,
+  ].join("\n");
+}
+
+// Exported so the command layer can reject bad input before it costs a request.
+export function validateAgentCreateFromTemplateInput(
+  template: string,
+  name: string,
+  opts: AgentCreateFromTemplateOptions = {},
+): AgentFromTemplateParams {
+  const params: AgentFromTemplateParams = {
+    template: normalizeNonBlank(template, "template"),
+    name: normalizeAgentName(name),
   };
+  if (opts.slug !== undefined) params.slug = normalizeAgentSlug(opts.slug);
+  if (opts.description !== undefined) params.description = normalizeNonBlank(opts.description, "--description");
+  if (opts.harness !== undefined) params.harness = normalizeNonBlank(opts.harness, "--harness");
+  if (opts.harnessVersion !== undefined) {
+    if (opts.harness === undefined) {
+      throw new CliUsageError("--harness-version needs --harness: a version belongs to one harness.");
+    }
+    params.harnessVersion = normalizeNonBlank(opts.harnessVersion, "--harness-version");
+  }
+  return params;
 }
 
-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;
+export async function agentsRedeployData(ctx: CliContext, slug: string): Promise<AgentDeployResponse> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  return ctx.sdk.agents.deploy(normalizedSlug);
 }
 
-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;
+export async function agentsRedeploy(ctx: CliContext, slug: string): Promise<string> {
+  const res = await agentsRedeployData(ctx, slug);
+  const repo = res.source_repo.github_repository ?? res.source_repo.slug;
+  return [
+    `Re-sync queued for ${repo}; ${res.agent.slug} rebuilds from ${res.source_repo.deploy_branch}.`,
+    `Watch it with: dharta agent releases ${res.agent.slug}`,
+  ].join("\n");
 }
 
-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;
+export async function agentsRetryReleaseData(
+  ctx: CliContext,
+  slug: string,
+  version: string,
+): Promise<ReleaseRetryResponse> {
+  const normalizedSlug = normalizeAgentSlug(slug);
+  const releaseVersion = parseReleaseVersion(version, "release version");
+  return ctx.sdk.releases.retry(normalizedSlug, releaseVersion);
+}
+
+export async function agentsRetryRelease(ctx: CliContext, slug: string, version: string): Promise<string> {
+  const res = await agentsRetryReleaseData(ctx, slug, version);
+  const state = res.state === "pending" ? "is still building" : "is built";
+  return `Retried v${res.retried_release.version} as v${res.release.version}, which ${state}.`;
 }
 
-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.`);
+function normalizeGithubFullName(value: string): string {
+  const normalized = normalizeNonBlank(value, "--github-repo");
+  if (!/^[^/\s]+\/[^/\s]+$/.test(normalized)) {
+    throw new CliUsageError("--github-repo must be a repository id or an owner/name, e.g. acme-eng/support-bot.");
   }
-  return parsed;
+  return normalized;
 }
 
-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.`);
+function normalizeAgentName(name: string): string {
+  const normalized = normalizeNonBlank(name, "agent name");
+  if (normalized.length > 100) throw new CliUsageError("Agent name must be 1-100 characters.");
   return normalized;
 }
 
+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)}`,
+  });
+}
+
+export async function agentsDelete(ctx: CliContext, slug: string): Promise<string> {
+  const res = await agentsDeleteData(ctx, slug);
+  return `Archived ${res.agent.slug}.`;
+}
+
+function validateModelSetOptions(opts: AgentModelSetOptions): void {
+  const hasConnector = opts.connector !== undefined;
+  const hasModelRef = opts.modelRef !== undefined;
+  const hasParameters = modelParameterOptionPresent(opts);
+
+  if (!hasConnector && !hasModelRef && !hasParameters) {
+    throw new CliUsageError(
+      "Pass at least one connector option, model reference option, or parameter option.",
+    );
+  }
+  if (hasConnector) parseConnectorOrder(opts.connector as string, "--connector");
+  if (hasModelRef) normalizeModelReference(opts.modelRef as string, "--model-ref");
+  validateModelParameterOptions(opts);
+}
+
+function normalizeModelSetOptions(opts: AgentModelSetOptions): AgentModelSetOptions {
+  return {
+    ...normalizeModelParameterOptions(opts),
+    // `--connector ""` and `--model-ref ""` are meaningful: an empty
+    // connector order inherits from the organization, and an empty model
+    // reference falls back to the connector default.
+    connector: opts.connector?.trim(),
+    modelRef: opts.modelRef?.trim(),
+  };
+}
+
 function normalizeAgentSlug(slug: string): string {
   return validateAgentSlug(slug, "agent slug");
 }