@k2b/cloud 0.42.0 → 0.44.0

package/src/cli/account.ts

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
+import { type PersonAvatar, randomizePersonAvatar, startPersonAvatar } from "../contracts/avatar";
 import { isModelsOnlyApiKey } from "../contracts/shared";
+import { applyAvatarParts, avatarRows, type CliAvatarState, readAvatarPhoto } from "./avatar";
 import { arg, type CliInputFlagValue, type CloudCliContext, command, confirmFlag, defineCliCommands, flag, readCliInput } from "./index";
 
 type User = {
@@ -229,6 +231,7 @@ export default defineCliCommands({
   summary: "Manage the authenticated account, profile, personal API keys, and SSH keys.",
   groupSummaries: {
     profile: "Show and update the account profile",
+    avatar: "Show and change the profile picture: photo, built avatar, or initials",
     "api-keys": "Manage personal API keys",
     "ssh-keys": "Manage SSH public keys",
     password: "Change the account password",
@@ -264,6 +267,60 @@ export default defineCliCommands({
         await updateProfile(ctx, buildProfileUpdate(flags));
       },
     }),
+    command("avatar show", {
+      summary: "Show which profile picture others see and the parts of the built avatar",
+      run: async ({ ctx }) => {
+        const state = await readApi<CliAvatarState>(ctx, "/avatar");
+        printJsonOrTable(ctx, state, avatarRows(state), [{ key: "key" }, { key: "value" }]);
+      },
+    }),
+    command("avatar use", {
+      summary: "Show the stored photo, the built avatar, or initials",
+      args: { kind: arg.required({ valueLabel: "photo|avatar|initials", description: "Picture to show" }) },
+      run: async ({ ctx, args }) => {
+        const use = { photo: "photo", avatar: "built", initials: "initials" }[args.kind];
+        if (!use) throw new Error(`Choose photo, avatar, or initials, not "${args.kind}".`);
+        const state = await readApi<CliAvatarState>(ctx, "/avatar", jsonRequest("PUT", { use }));
+        printJsonOrTable(ctx, state, avatarRows(state), [{ key: "key" }, { key: "value" }]);
+      },
+    }),
+    command("avatar random", {
+      summary: "Build a random avatar, keep the skin tone, and show it",
+      run: async ({ ctx }) => {
+        const current = await readApi<CliAvatarState>(ctx, "/avatar");
+        const base = current.built?.kind === "person" ? current.built : startPersonAvatar();
+        const state = await readApi<CliAvatarState>(ctx, "/avatar", jsonRequest("PUT", { built: randomizePersonAvatar(base) }));
+        printJsonOrTable(ctx, state, avatarRows(state), [{ key: "key" }, { key: "value" }]);
+      },
+    }),
+    command("avatar set", {
+      summary: "Change parts of the built avatar, for example hair=curly hairColor=red, and show it",
+      args: { parts: arg.rest({ valueLabel: "part=value", description: "Parts to change; an unknown value lists the choices" }) },
+      run: async ({ ctx, args }) => {
+        const current = await readApi<CliAvatarState>(ctx, "/avatar");
+        const base: PersonAvatar = current.built?.kind === "person" ? current.built : startPersonAvatar();
+        const state = await readApi<CliAvatarState>(ctx, "/avatar", jsonRequest("PUT", { built: applyAvatarParts(base, args.parts) }));
+        printJsonOrTable(ctx, state, avatarRows(state), [{ key: "key" }, { key: "value" }]);
+      },
+    }),
+    command("avatar photo", {
+      summary: "Store a small square PNG, JPEG, or WebP (at most 48 KiB) and show it",
+      args: { file: arg.required({ valueLabel: "file", description: "Image file" }) },
+      run: async ({ ctx, args }) => {
+        const state = await readApi<CliAvatarState>(ctx, "/avatar", jsonRequest("PUT", { dataUrl: await readAvatarPhoto(args.file) }));
+        printJsonOrTable(ctx, state, avatarRows(state), [{ key: "key" }, { key: "value" }]);
+      },
+    }),
+    command("avatar delete-photo", {
+      summary: "Delete the stored photo; when it was showing, initials show",
+      flags: { yes: confirmFlag("Delete the stored photo") },
+      run: async ({ ctx, flags }) => {
+        if (!flags.yes) throw new Error("Pass --yes to delete the stored photo.");
+        await readApi(ctx, "/avatar", jsonRequest("DELETE"));
+        const state = await readApi<CliAvatarState>(ctx, "/avatar");
+        printJsonOrTable(ctx, state, avatarRows(state), [{ key: "key" }, { key: "value" }]);
+      },
+    }),
     command("activity", {
       summary: "List recent account activity",
       flags: {

package/src/cli/admin/agents.ts

@@ -5,6 +5,8 @@
  * `cld` profile through the host; the secret is never printed.
  */
 import { z } from "zod";
+import { type RobotAvatar, randomRobotAvatar } from "../../contracts/avatar";
+import { applyAvatarParts, avatarRows, type CliAvatarState, readAvatarPhoto } from "../avatar";
 import { arg, cliText, command, confirmFlag, flag, printStructured } from "../index";
 import { apiGet, apiJson, queryString } from "./shared";
 
@@ -62,6 +64,12 @@ const resolveAgent = async (ctx: Ctx, reference: string): Promise<Account> => {
   throw new Error(`Several agents match "${reference}": ${matches.map((item) => `${item.name} (${item.id})`).join(", ")}.`);
 };
 
+const avatarPath = (id: string) => `${accountsRoot}/${encodeURIComponent(id)}/avatar`;
+
+const printAvatar = (ctx: Ctx, state: CliAvatarState) => {
+  if (!printStructured(ctx, state)) ctx.table(avatarRows(state), [{ key: "key" }, { key: "value" }]);
+};
+
 const disableAccount = (ctx: Ctx, id: string) => apiJson(ctx, "PATCH", `${accountsRoot}/${encodeURIComponent(id)}`, { status: "disabled" });
 
 const requireProfileName = (flags: { profile?: string }): string => {
@@ -216,4 +224,62 @@ export const agentCommands = [
       }
     },
   }),
+  command("agents avatar show", {
+    summary: "Show an agent's picture: its robot parts, and whether a photo is stored and showing",
+    args: { agent: arg.required({ valueLabel: "agent-id-or-name" }) },
+    async run({ ctx, args }) {
+      const agent = await resolveAgent(ctx, args.agent);
+      printAvatar(ctx, await apiGet<CliAvatarState>(ctx, avatarPath(agent.id)));
+    },
+  }),
+  command("agents avatar random", {
+    summary: "Give an agent a new random robot and show it",
+    args: { agent: arg.required({ valueLabel: "agent-id-or-name" }) },
+    async run({ ctx, args }) {
+      const agent = await resolveAgent(ctx, args.agent);
+      printAvatar(ctx, await apiJson<CliAvatarState>(ctx, "PUT", avatarPath(agent.id), { built: randomRobotAvatar() }));
+    },
+  }),
+  command("agents avatar set", {
+    summary: "Change parts of an agent's robot, for example head=round color=teal, and show it",
+    args: {
+      agent: arg.required({ valueLabel: "agent-id-or-name" }),
+      parts: arg.rest({ valueLabel: "part=value", description: "Parts to change; an unknown value lists the choices" }),
+    },
+    async run({ ctx, args }) {
+      const agent = await resolveAgent(ctx, args.agent);
+      const current = await apiGet<CliAvatarState>(ctx, avatarPath(agent.id));
+      if (current.built?.kind !== "robot") throw new Error(`Agent "${agent.name}" has no robot to change.`);
+      const built = applyAvatarParts<RobotAvatar>(current.built, args.parts);
+      printAvatar(ctx, await apiJson<CliAvatarState>(ctx, "PUT", avatarPath(agent.id), { built }));
+    },
+  }),
+  command("agents avatar photo", {
+    summary: "Store a small square PNG, JPEG, or WebP (at most 48 KiB) as an agent's picture and show it",
+    args: { agent: arg.required({ valueLabel: "agent-id-or-name" }), file: arg.required({ valueLabel: "file" }) },
+    async run({ ctx, args }) {
+      const agent = await resolveAgent(ctx, args.agent);
+      printAvatar(ctx, await apiJson<CliAvatarState>(ctx, "PUT", avatarPath(agent.id), { dataUrl: await readAvatarPhoto(args.file) }));
+    },
+  }),
+  command("agents avatar use", {
+    summary: "Show an agent's stored photo or its robot",
+    args: { agent: arg.required({ valueLabel: "agent-id-or-name" }), kind: arg.required({ valueLabel: "photo|robot" }) },
+    async run({ ctx, args }) {
+      const use = { photo: "photo", robot: "built" }[args.kind];
+      if (!use) throw new Error(`Choose photo or robot, not "${args.kind}".`);
+      const agent = await resolveAgent(ctx, args.agent);
+      printAvatar(ctx, await apiJson<CliAvatarState>(ctx, "PUT", avatarPath(agent.id), { use }));
+    },
+  }),
+  command("agents avatar delete-photo", {
+    summary: "Delete an agent's stored photo; its robot shows again",
+    args: { agent: arg.required({ valueLabel: "agent-id-or-name" }) },
+    flags: { yes: confirmFlag("Delete this agent's photo") },
+    async run({ ctx, args, flags }) {
+      requireYes(ctx, flags.yes, "Deleting a photo requires --yes.", "Foto löschen erfordert --yes.");
+      const agent = await resolveAgent(ctx, args.agent);
+      printAvatar(ctx, await apiJson<CliAvatarState>(ctx, "DELETE", avatarPath(agent.id)));
+    },
+  }),
 ];

package/src/cli/admin/ai-models.ts

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import {
+  AI_MODEL_SLOTS,
+  AiDeleteModelSchema,
+  AiModelAccessDraftSchema,
+  AiModelInputSchema,
+  AiModelPatchSchema,
+  AiProviderInputSchema,
+  AiProviderPatchSchema,
+  AiVariantInputSchema,
+  AiVariantPatchSchema,
+} from "../../shared/ai-models";
+import { arg, type CloudCliContext, command, confirmFlag, flag, printStructured, readCliInput } from "../index";
+import { apiGet, apiJson, readJsonInput } from "./shared";
+
+const base = "/api/admin/core/ai";
+const print = (ctx: CloudCliContext, result: unknown) => {
+  if (!printStructured(ctx, result)) ctx.print(JSON.stringify(result, null, 2));
+};
+const confirm = (yes: boolean) => {
+  if (!yes) throw new Error("AI configuration changes require --yes.");
+};
+const id = { id: arg.required({ valueLabel: "id" }) };
+const input = flag.input({ required: true, description: "JSON input: --input, --input-file or --stdin" });
+const yes = confirmFlag("Confirm AI configuration change");
+const endpoint = (area: string, id: string) => `${base}/${area}/${encodeURIComponent(id)}`;
+export const aiModelCommands = [
+  command("ai providers list", {
+    summary: "List provider connections and their status",
+    async run({ ctx }) {
+      print(ctx, await apiGet(ctx, `${base}/providers`));
+    },
+  }),
+  command("ai providers show", {
+    summary: "Show a provider; credential and header values stay private",
+    args: id,
+    async run({ ctx, args }) {
+      print(ctx, await apiGet(ctx, endpoint("providers", args.id)));
+    },
+  }),
+  command("ai providers add", {
+    summary: "Create a provider connection",
+    flags: { input, yes },
+    async run({ ctx, flags }) {
+      confirm(flags.yes);
+      print(
+        ctx,
+        await apiJson(ctx, "POST", `${base}/providers`, AiProviderInputSchema.parse(await readJsonInput<unknown>(flags.input, "provider"))),
+      );
+    },
+  }),
+  command("ai providers update", {
+    summary: "Update a provider with optimistic concurrency",
+    args: id,
+    flags: { input, yes },
+    async run({ ctx, args, flags }) {
+      confirm(flags.yes);
+      const patch = AiProviderPatchSchema.parse(await readJsonInput<unknown>(flags.input, "provider patch"));
+      const current = await apiGet<{ revision: number }>(ctx, endpoint("providers", args.id));
+      print(ctx, await apiJson(ctx, "PATCH", endpoint("providers", args.id), { ...patch, revision: current.revision }));
+    },
+  }),
+  command("ai providers test", {
+    summary: "Test a saved provider connection (10 second timeout)",
+    args: id,
+    async run({ ctx, args }) {
+      print(ctx, await apiJson(ctx, "POST", `${endpoint("providers", args.id)}/test`, {}));
+    },
+  }),
+  command("ai providers key", {
+    summary: "Replace a provider key from protected input",
+    args: id,
+    flags: { key: flag.input({ required: true, description: "API key: use --key-file or --stdin" }), yes },
+    async run({ ctx, args, flags }) {
+      confirm(flags.yes);
+      const apiKey = await readCliInput(flags.key, { required: true, label: "API key" });
+      const current = await apiGet<{ revision: number }>(ctx, endpoint("providers", args.id));
+      print(
+        ctx,
+        await apiJson(ctx, "PUT", `${endpoint("providers", args.id)}/credential`, {
+          apiKey: apiKey?.trim() ?? "",
+          revision: current.revision,
+        }),
+      );
+    },
+  }),
+  command("ai providers models", {
+    summary: "List the models advertised by a provider",
+    args: id,
+    async run({ ctx, args }) {
+      print(ctx, await apiGet(ctx, `${endpoint("providers", args.id)}/available-models`));
+    },
+  }),
+  command("ai models list", {
+    summary: "List configured models",
+    async run({ ctx }) {
+      print(ctx, await apiGet(ctx, `${base}/models`));
+    },
+  }),
+  command("ai models show", {
+    summary: "Show a model, variants and access",
+    args: id,
+    async run({ ctx, args }) {
+      print(ctx, await apiGet(ctx, endpoint("models", args.id)));
+    },
+  }),
+  command("ai models add", {
+    summary: "Add a model to a provider",
+    args: { provider: arg.required() },
+    flags: { input, yes },
+    async run({ ctx, args, flags }) {
+      confirm(flags.yes);
+      const data = z
+        .union([AiModelInputSchema, z.array(AiModelInputSchema).min(1)])
+        .parse(await readJsonInput<unknown>(flags.input, "models"));
+      print(ctx, await apiJson(ctx, "POST", `${endpoint("providers", args.provider)}/models`, data));
+    },
+  }),
+  command("ai models update", {
+    summary: "Update one model and its shared prices",
+    args: id,
+    flags: { input, yes },
+    async run({ ctx, args, flags }) {
+      confirm(flags.yes);
+      const data = AiModelPatchSchema.extend({ access: AiModelAccessDraftSchema.optional() }).parse(
+        await readJsonInput<unknown>(flags.input, "model patch"),
+      );
+      const current = await apiGet<{ revision: number }>(ctx, endpoint("models", args.id));
+      print(ctx, await apiJson(ctx, "PATCH", endpoint("models", args.id), { ...data, revision: current.revision }));
+    },
+  }),
+  command("ai variants add", {
+    summary: "Create a named model variant",
+    args: { model: arg.required() },
+    flags: { input, yes },
+    async run({ ctx, args, flags }) {
+      confirm(flags.yes);
+      print(
+        ctx,
+        await apiJson(
+          ctx,
+          "POST",
+          `${endpoint("models", args.model)}/variants`,
+          AiVariantInputSchema.parse(await readJsonInput<unknown>(flags.input, "variant")),
+        ),
+      );
+    },
+  }),
+  command("ai variants update", {
+    summary: "Update a variant's overrides",
+    args: id,
+    flags: { input, yes },
+    async run({ ctx, args, flags }) {
+      confirm(flags.yes);
+      const data = AiVariantPatchSchema.parse(await readJsonInput<unknown>(flags.input, "variant patch"));
+      const current = await apiGet<{ variants: { id: string; revision: number }[] }>(ctx, endpoint("models", args.id.split(":")[0]!));
+      const variant = current.variants.find((v) => v.id === args.id);
+      if (!variant) throw new Error("Variant not found.");
+      print(ctx, await apiJson(ctx, "PATCH", endpoint("variants", args.id), { ...data, revision: variant.revision }));
+    },
+  }),
+  ...(["providers", "models", "variants"] as const).map((area) =>
+    command(`ai ${area} delete`, {
+      summary: "Delete with explicit assignment replacements and retargeting choice",
+      args: id,
+      flags: { input, yes },
+      async run({ ctx, args, flags }) {
+        confirm(flags.yes);
+        const data = AiDeleteModelSchema.parse(await readJsonInput<unknown>(flags.input, "delete consequences"));
+        print(ctx, await apiJson(ctx, "DELETE", endpoint(area, args.id), data));
+      },
+    }),
+  ),
+  command("ai classes show", {
+    summary: "Show class and tool assignments, fallback chains and recent callers",
+    async run({ ctx }) {
+      print(ctx, await apiGet(ctx, `${base}/assignments`));
+    },
+  }),
+  command("ai classes set", {
+    summary: "Assign a class or tool slot to a variant or none",
+    args: { slot: arg.required(), variant: arg.required() },
+    flags: { yes },
+    async run({ ctx, args, flags }) {
+      confirm(flags.yes);
+      const slot = z.enum(AI_MODEL_SLOTS).parse(args.slot);
+      const current = await apiGet<{ assignments: { slot: string; revision: number }[] }>(ctx, `${base}/assignments`);
+      const assignment = current.assignments.find((a) => a.slot === slot);
+      if (!assignment) throw new Error("Assignment missing.");
+      print(
+        ctx,
+        await apiJson(ctx, "PUT", `${base}/assignments/${slot}`, {
+          variantId: args.variant === "none" ? null : args.variant,
+          revision: assignment.revision,
+        }),
+      );
+    },
+  }),
+];

package/src/cli/admin/ai-quotas.ts

@@ -1,9 +1,5 @@
-import { type AiModelPricing, AiModelPricingSchema } from "../../shared/ai-costs";
-import {
-  type AiModelRequestSettings,
-  AiModelRequestSettingsSchema,
-  AiModelRequestSettingsUpdateSchema,
-} from "../../shared/ai-model-request-settings";
+import type { AiModelPricing } from "../../shared/ai-costs";
+
 import {
   type AiQuotaConfig,
   AiQuotaConfigSchema,
@@ -12,7 +8,7 @@ import {
   AiQuotaReportQuerySchema,
   AiQuotaResetSchema,
 } from "../../shared/ai-quotas";
-import { type CloudCliContext, cliText, command, confirmFlag, flag, printRows, printStructured, readCliInput } from "../index";
+import { type CloudCliContext, cliText, command, confirmFlag, flag, printRows, printStructured } from "../index";
 import { apiGet, apiJson, queryString, readJsonInput } from "./shared";
 
 const path = "/api/admin/core/ai-quotas";
@@ -28,98 +24,6 @@ const confirm = (ctx: CloudCliContext, yes: boolean) => {
 };
 
 export const aiQuotaCommands = [
-  command("ai models settings get", {
-    summary: "Read model thinking level, extra parameters and configured header names",
-    flags: { id: flag.string({ required: true, description: "Model profile ID" }) },
-    async run({ ctx, flags }) {
-      print(ctx, AiModelRequestSettingsSchema.parse(await apiGet(ctx, `${path}/models/${encodeURIComponent(flags.id!)}/settings`)));
-    },
-  }),
-  command("ai models settings set", {
-    summary: "Patch one model's request settings; header values are write-only",
-    flags: {
-      id: flag.string({ required: true, description: "Model profile ID" }),
-      thinkingLevel: flag.string({ name: "thinking-level", description: "Provider-specific thinking level" }),
-      clearThinkingLevel: flag.boolean({ name: "clear-thinking-level", description: "Use the model's default thinking level" }),
-      extraBody: flag.input({ name: "extra-body", description: "Extra parameters JSON: --extra-body, --extra-body-file or --stdin" }),
-      clearExtraBody: flag.boolean({ name: "clear-extra-body", description: "Remove extra parameters" }),
-      headers: flag.input({
-        stdinName: "headers-stdin",
-        description: "Header patch JSON; use --headers-file or --headers-stdin for secrets",
-      }),
-      clearHeaders: flag.boolean({ name: "clear-headers", description: "Remove all configured extra headers before applying the patch" }),
-      yes: confirmFlag("Confirm model request settings change"),
-    },
-    async run({ ctx, flags }) {
-      if (!flags.yes) throw new Error("Model request settings changes require --yes.");
-      if (flags.thinkingLevel !== undefined && flags.clearThinkingLevel)
-        throw new Error("Choose --thinking-level or --clear-thinking-level.");
-      if (flags.extraBody.provided && flags.clearExtraBody) throw new Error("Choose --extra-body or --clear-extra-body.");
-      if (
-        !flags.extraBody.provided &&
-        !flags.headers.provided &&
-        flags.thinkingLevel === undefined &&
-        !flags.clearThinkingLevel &&
-        !flags.clearExtraBody &&
-        !flags.clearHeaders
-      )
-        throw new Error("Select at least one model request setting to change.");
-      if (flags.extraBody.source === "stdin" && flags.headers.source === "stdin")
-        throw new Error("Read one JSON input from stdin and supply the other from a file.");
-      const parseInput = async (input: typeof flags.headers, label: string): Promise<unknown> => {
-        const raw = await readCliInput(input, { required: true, label });
-        try {
-          return JSON.parse(raw!);
-        } catch {
-          throw new Error(`Invalid ${label} JSON.`);
-        }
-      };
-      const patch: Record<string, unknown> = {};
-      if (flags.thinkingLevel !== undefined || flags.clearThinkingLevel)
-        patch.reasoningEffort = flags.clearThinkingLevel ? null : flags.thinkingLevel;
-      if (flags.extraBody.provided || flags.clearExtraBody)
-        patch.extraBody = flags.clearExtraBody ? null : await parseInput(flags.extraBody, "extra parameters");
-      if (flags.headers.provided) patch.requestHeaders = await parseInput(flags.headers, "extra headers");
-      if (flags.clearHeaders) patch.clearRequestHeaders = true;
-      // Validate locally before reading the current revision or sending secrets.
-      const valid = AiModelRequestSettingsUpdateSchema.parse({ ...patch, expected: "pending" });
-      const current = await apiGet<AiModelRequestSettings>(ctx, `${path}/models/${encodeURIComponent(flags.id!)}/settings`);
-      print(
-        ctx,
-        AiModelRequestSettingsSchema.parse(
-          await apiJson(ctx, "PUT", `${path}/models/${encodeURIComponent(flags.id!)}/settings`, { ...valid, expected: current.revision }),
-        ),
-      );
-    },
-  }),
-  command("ai models pricing get", {
-    summary: "List configured model input/output reference prices per million tokens",
-    async run({ ctx }) {
-      print(ctx, await apiGet(ctx, `${path}/models`));
-    },
-  }),
-  command("ai models pricing set", {
-    summary: "Set one model's reference prices; JSON null removes prices and makes it unlimited",
-    flags: {
-      id: flag.string({ required: true, description: "Model profile ID" }),
-      pricing: flag.input({
-        required: true,
-        description: "{inputPerMillion,outputPerMillion} or null: --pricing, --pricing-file or --stdin",
-      }),
-      yes: confirmFlag("Confirm model price change"),
-    },
-    async run({ ctx, flags }) {
-      confirm(ctx, flags.yes);
-      const pricing = AiModelPricingSchema.nullable().parse(await readJsonInput<unknown>(flags.pricing, "model pricing"));
-      const current = await apiGet<{ models: { id: string; pricing?: AiModelPricing }[] }>(ctx, `${path}/models`);
-      const model = current.models.find((model) => model.id === flags.id);
-      if (!model) throw new Error("Model not found.");
-      print(
-        ctx,
-        await apiJson(ctx, "PUT", `${path}/models/${encodeURIComponent(flags.id!)}/pricing`, { pricing, expected: model.pricing ?? null }),
-      );
-    },
-  }),
   command("ai quotas background status", {
     summary: "Show rolling 24-hour background costs and emergency-stop state",
     async run({ ctx }) {
@@ -153,7 +57,7 @@ export const aiQuotaCommands = [
     },
   }),
   command("ai quotas models", {
-    summary: "List configured model profiles; only priced chat models support cost rules",
+    summary: "List configured models; only priced chat models support cost rules",
     async run({ ctx }) {
       const result = await apiGet<{ models: { id: string; label: string; pricing?: AiModelPricing }[] }>(ctx, `${path}/models`);
       printRows(
@@ -170,7 +74,7 @@ export const aiQuotaCommands = [
       range: flag.enum(["24h", "7d", "30d", "90d"] as const, { default: "30d" }),
       until: flag.string({ description: "ISO period end; reuse query.until for consistent pagination" }),
       search: flag.string({ description: "Search identity labels" }),
-      model: flag.string({ description: "Model profile ID" }),
+      model: flag.string({ description: "Model ID" }),
       status: flag.enum(["all", "available", "exhausted", "unknown", "unlimited", "disabled"] as const, { default: "all" }),
       sort: flag.enum(["label", "cost", "lastUsed"] as const, { default: "lastUsed" }),
       direction: flag.enum(["asc", "desc"] as const, { default: "desc" }),
@@ -216,7 +120,7 @@ export const aiQuotaCommands = [
     summary: "Reset one identity and quota scope; reuse request ID when retrying",
     flags: {
       ...identity,
-      scope: flag.string({ required: true, description: "Model profile ID or * (quote the wildcard)" }),
+      scope: flag.string({ required: true, description: "Model ID or * (quote the wildcard)" }),
       requestId: flag.string({ required: true, description: "UUID for this reset; reuse for retries, use a new UUID for a new reset" }),
       yes: confirmFlag("Confirm reset of this identity and quota scope"),
     },

package/src/cli/admin/ai-usage.ts

@@ -7,7 +7,7 @@ const filters = {
   range: flag.enum(AI_USAGE_RANGES, { default: "30d", description: "Response/run period" }),
   until: flag.string({ description: "Fixed ISO end time; reuse report.query.until across pages" }),
   userId: flag.string({ name: "user", description: "User UUID or unassigned" }),
-  modelProfileId: flag.string({ name: "model", description: "Model profile ID" }),
+  modelId: flag.string({ name: "model", description: "Model profile ID" }),
   providerModel: flag.string({ name: "provider-model", description: "Actual provider model" }),
   workflowId: flag.string({ name: "workflow", description: "Workflow definition UUID" }),
   workflowRunId: flag.string({ name: "workflow-run", description: "Workflow run UUID" }),
@@ -75,7 +75,7 @@ export const aiUsageCommands = [
               { key: "task" },
               { key: "status" },
               { key: "userLabel" },
-              { key: "modelProfileId" },
+              { key: "modelId" },
               { key: "cost" },
               { key: "unit" },
               { key: "error" },
@@ -85,7 +85,7 @@ export const aiUsageCommands = [
           ctx.table(report.feedback.items, [
             { key: "id" },
             { key: "userLabel" },
-            { key: "modelProfileId" },
+            { key: "modelId" },
             { key: "rating" },
             { key: "comment" },
           ]);
@@ -125,7 +125,7 @@ export const aiUsageCommands = [
   command("ai usage facets", {
     summary: "Find user IDs, model profiles, provider models, apps or tasks for filtering",
     flags: {
-      field: flag.enum(["userId", "modelProfileId", "providerModel", "appId", "task"] as const, { required: true }),
+      field: flag.enum(["userId", "modelId", "providerModel", "appId", "task"] as const, { required: true }),
       search: flag.string(),
       range: filters.range,
     },

package/src/cli/admin/app-credentials.ts

@@ -51,7 +51,7 @@ export const appCredentialCommands = [
     },
     async run({ ctx, args, flags }) {
       if (!flags.yes)
-        throw new Error(cliText(ctx, { en: "Creating an app credential requires --yes.", de: "App-Zugang erstellen erfordert --yes." }));
+        throw new Error(cliText(ctx, { en: "Creating an app credential requires --yes.", de: "App-Schlüssel erstellen erfordert --yes." }));
       const result = z.object({ credential: metadata, token: z.string() }).parse(
         await apiJson(ctx, "POST", path(args.app), {
           name: flags.name,
@@ -68,10 +68,12 @@ export const appCredentialCommands = [
     flags: { yes: confirmFlag("Revoke this app credential") },
     async run({ ctx, args, flags }) {
       if (!flags.yes)
-        throw new Error(cliText(ctx, { en: "Revoking an app credential requires --yes.", de: "App-Zugang widerrufen erfordert --yes." }));
+        throw new Error(
+          cliText(ctx, { en: "Revoking an app credential requires --yes.", de: "App-Schlüssel widerrufen erfordert --yes." }),
+        );
       const credentialId = z.uuid().parse(args.credential);
       const result = await apiJson(ctx, "DELETE", `${path(args.app)}/${credentialId}`);
-      if (!printStructured(ctx, result)) ctx.print(cliText(ctx, { en: "Credential revoked.", de: "Zugang widerrufen." }));
+      if (!printStructured(ctx, result)) ctx.print(cliText(ctx, { en: "Credential revoked.", de: "Schlüssel widerrufen." }));
     },
   }),
 ];

package/src/cli/admin/index.ts

@@ -9,6 +9,7 @@ import { defineCliCommands } from "../commands";
 import { accountAdministrationCommands } from "./account-administration";
 import { accountCategoryCommands } from "./account-categories";
 import { agentCommands } from "./agents";
+import { aiModelCommands } from "./ai-models";
 import { aiQuotaCommands } from "./ai-quotas";
 import { aiSkillCommands } from "./ai-skills";
 import { aiUsageCommands } from "./ai-usage";
@@ -39,14 +40,16 @@ export default defineCliCommands({
     accounts: "Manage account policy and account administration.",
     ai: "Manage AI models, quotas, Skills, and usage.",
     "ai models": "Manage AI model configuration.",
-    "ai models pricing": "Manage model reference prices.",
-    "ai models settings": "Manage model thinking levels, extra parameters, and extra headers.",
+    "ai providers": "Manage AI provider connections.",
+    "ai variants": "Manage named model variants.",
+    "ai classes": "Manage model classes and tools.",
     "ai quotas background": "Inspect and release the background emergency stop.",
     "ai skills": "Inspect Assistant Skills and trusted templates.",
     "ai usage": "Inspect AI runs and usage facets.",
     announcements: "Manage platform announcements and banners.",
     "app-credentials": "Manage per-application credentials for background work.",
-    agents: "Create, list, revoke, and re-key agent accounts with OAuth client credentials.",
+    agents: "Create, list, revoke, and re-key agent accounts with OAuth client credentials, and change their pictures.",
+    "agents avatar": "Show and change an agent's picture: its robot parts or a photo.",
     "app-sign-in": "Manage app sign-in and pairing.",
     apps: "Inspect and remove registered apps.",
     documentation: "Manage the administration documentation website.",
@@ -93,6 +96,7 @@ export default defineCliCommands({
     ...accountCategoryCommands,
     ...accountAdministrationCommands,
     ...aiUsageCommands,
+    ...aiModelCommands,
     ...aiQuotaCommands,
     ...aiSkillCommands,
     ...instanceCommands,

package/src/cli/app-access.ts

@@ -0,0 +1,60 @@
+import type { AccessEntry } from "../contracts/shared";
+import type { AppAccessChange, AppAccessSnapshot } from "../services/app-access-management";
+import { createAccessCommands } from "./access";
+import { flag } from "./commands";
+import type { CloudCliContext } from "./index";
+
+/** Add to an app's CLI module; the same audited access API serves the editor and these commands. */
+export const createAppAccessCommands = (appId: string) => {
+  const path = `/_cloud/app-access/${encodeURIComponent(appId)}`;
+  const change = async (ctx: CloudCliContext, input: AppAccessChange) =>
+    ctx.readJson<{ entry?: AccessEntry; canUse: boolean }>(
+      await ctx.fetch(path, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(input),
+      }),
+    );
+  const commands = createAccessCommands({
+    resourceLabel: "app",
+    allowedPermissions: ["read", "admin"],
+    allowAuthenticated: true,
+    allowPublic: false,
+    allowServiceAccounts: true,
+    resolveResource: async (_ctx, args) => {
+      if (args.length) throw new Error("App access takes no resource argument.");
+      return { id: appId, label: appId };
+    },
+    list: async (ctx) => (await ctx.readJson<AppAccessSnapshot>(await ctx.fetch(path))).entries,
+    grant: async (ctx, _resource, principal, permission) => {
+      if (permission !== "read" && permission !== "admin") throw new Error("App permissions are use or manage.");
+      const result = await change(ctx, { action: "grant", principal, permission });
+      if (!result.entry) throw new Error("The access change returned no entry. Read the list before retrying.");
+      return result.entry;
+    },
+    update: async (ctx, _resource, accessId, permission) => {
+      if (permission !== "read" && permission !== "admin") throw new Error("App permissions are use or manage.");
+      await change(ctx, { action: "update", accessId, permission });
+    },
+    revoke: async (ctx, _resource, accessId) => {
+      await change(ctx, { action: "revoke", accessId });
+    },
+  });
+  // Product vocabulary at the CLI boundary; stored permission levels remain read/admin.
+  return commands.map((definition) =>
+    !definition.flags?.permission
+      ? definition
+      : {
+          ...definition,
+          flags: {
+            ...definition.flags,
+            permission: flag.enum(["use", "manage"], {
+              required: true,
+              description: "use: open the app; manage: use it and manage access",
+            }),
+          },
+          run: (input: Parameters<typeof definition.run>[0]) =>
+            definition.run({ ...input, flags: { ...input.flags, permission: input.flags.permission === "use" ? "read" : "admin" } }),
+        },
+  );
+};