@k2b/cloud 0.15.0 → 0.17.0

package/src/api/admin-identity.ts

@@ -6,11 +6,12 @@ import { z } from "zod";
 import { listApps } from "../_internal/registry";
 import { CapabilityAppIdSchema } from "../contracts/capabilities";
 import { type AuthContext, auth, err, respond, v } from "../server";
+import { audit } from "../services/audit";
 import { getIdentitySigningKeyStatus, identityMetrics, revokeIdentitySigningKey, rewrapIdentitySigningKeys } from "../services/identity";
 import { WORKLOAD_SCOPES } from "../services/identity/workload-auth";
 import { mandateMetrics, mandates } from "../services/mandates";
 import { serviceAccountCredentials } from "../services/service-account-credentials";
-import { serviceAccounts } from "../services/service-accounts";
+import { isStandaloneServiceAccountKind, STANDALONE_SERVICE_ACCOUNT_KINDS, serviceAccounts } from "../services/service-accounts";
 
 const WorkloadCredentialInputSchema = z
   .object({
@@ -41,14 +42,44 @@ const MandateListQuerySchema = z
   })
   .strict();
 
+const StandaloneServiceAccountKindSchema = z.enum(STANDALONE_SERVICE_ACCOUNT_KINDS);
+const ServiceAccountParamsSchema = z.object({ id: z.uuid() }).strict();
+const ServiceAccountListQuerySchema = z
+  .object({
+    page: z.coerce.number().int().min(1).default(1),
+    perPage: z.coerce.number().int().min(1).max(500).default(100),
+    kind: StandaloneServiceAccountKindSchema.optional(),
+    status: z.enum(["active", "disabled"]).optional(),
+    search: z.string().trim().max(200).optional(),
+  })
+  .strict();
+const ServiceAccountInputSchema = z
+  .object({
+    name: z.string().trim().min(1).max(120),
+    kind: StandaloneServiceAccountKindSchema.default("standalone"),
+  })
+  .strict();
+const ServiceAccountStatusInputSchema = z.object({ status: z.enum(["active", "disabled"]) }).strict();
+const ServiceAccountApiKeyInputSchema = z
+  .object({
+    name: z.string().trim().min(1).max(120),
+    scopes: z.array(z.string().trim().min(1).max(64)).max(20).default([]),
+    expiresAt: z.iso.datetime().nullable().optional(),
+  })
+  .strict();
+
 type IdentityAdminDependencies = {
   apps: () => Promise<Array<{ id: string; name: string }>>;
   status: typeof getIdentitySigningKeyStatus;
   rewrap: typeof rewrapIdentitySigningKeys;
   revoke: typeof revokeIdentitySigningKey;
-  serviceAccounts: Pick<typeof serviceAccounts, "getOrCreateResourceBound">;
-  credentials: Pick<typeof serviceAccountCredentials, "createResourceApiToken" | "getOverview" | "listOverview" | "revoke">;
+  serviceAccounts: Pick<typeof serviceAccounts, "getOrCreateResourceBound" | "createStandalone" | "listStandalone" | "get" | "setStatus">;
+  credentials: Pick<
+    typeof serviceAccountCredentials,
+    "createResourceApiToken" | "createStandaloneApiToken" | "getOverview" | "listOverview" | "revoke"
+  >;
   mandates: Pick<typeof mandates, "list">;
+  audit: Pick<typeof audit, "record">;
 };
 
 const dependencies: IdentityAdminDependencies = {
@@ -59,8 +90,16 @@ const dependencies: IdentityAdminDependencies = {
   serviceAccounts,
   credentials: serviceAccountCredentials,
   mandates,
+  audit,
 };
 
+const auditActor = (user: AuthContext["Variables"]["user"]) => ({
+  userId: user.id,
+  uid: user.uid,
+  provider: user.provider,
+  roles: user.roles,
+});
+
 export const createAdminIdentityRoutes = (
   authenticate: MiddlewareHandler<AuthContext> = auth.requireRole("admin"),
   service: IdentityAdminDependencies = dependencies,
@@ -158,6 +197,95 @@ export const createAdminIdentityRoutes = (
           return revoked.ok ? ok({ revoked: true as const }) : revoked;
         }),
     )
+    // Standalone principals: service accounts with no delegated user and no
+    // resource binding. Access is granted to them like to a user; a new account
+    // starts with nothing. Credentials: OAuth client (OAuth admin API) or the
+    // API key minted below.
+    .get(
+      "/service-accounts",
+      describeRoute({ tags: ["Service accounts"], summary: "List standalone service accounts (kind standalone or agent)" }),
+      v("query", ServiceAccountListQuerySchema),
+      async (c) => c.json(await service.serviceAccounts.listStandalone(c.req.valid("query"))),
+    )
+    .post(
+      "/service-accounts",
+      describeRoute({ tags: ["Service accounts"], summary: "Create a standalone service account without any access" }),
+      v("json", ServiceAccountInputSchema),
+      async (c) =>
+        respond(
+          c,
+          async () => {
+            const input = c.req.valid("json");
+            const actor = c.get("user");
+            const created = await service.serviceAccounts.createStandalone({ ...input, createdBy: actor.id });
+            if (!created.ok) return created;
+            await service.audit.record({
+              action: "service_account.create",
+              outcome: "allowed",
+              actor: auditActor(actor),
+              target: { type: "service_account", id: created.data.id, label: created.data.name },
+              metadata: { serviceAccountId: created.data.id, serviceAccountKind: created.data.kind },
+            });
+            return created;
+          },
+          201,
+        ),
+    )
+    .get(
+      "/service-accounts/:id",
+      describeRoute({ tags: ["Service accounts"], summary: "Read one standalone service account" }),
+      v("param", ServiceAccountParamsSchema),
+      async (c) =>
+        respond(c, async () => {
+          const account = await service.serviceAccounts.get({ id: c.req.valid("param").id });
+          return account && isStandaloneServiceAccountKind(account.kind) ? ok(account) : fail(err.notFound("Service account"));
+        }),
+    )
+    .patch(
+      "/service-accounts/:id",
+      describeRoute({
+        tags: ["Service accounts"],
+        summary: "Enable or disable a standalone service account; disabled accounts reject every credential immediately",
+      }),
+      v("param", ServiceAccountParamsSchema),
+      v("json", ServiceAccountStatusInputSchema),
+      async (c) =>
+        respond(c, async () => {
+          const { id } = c.req.valid("param");
+          const { status } = c.req.valid("json");
+          const actor = c.get("user");
+          const account = await service.serviceAccounts.get({ id });
+          if (!account || !isStandaloneServiceAccountKind(account.kind)) return fail(err.notFound("Service account"));
+          const updated = await service.serviceAccounts.setStatus({ id, status });
+          if (!updated.ok) return updated;
+          await service.audit.record({
+            action: status === "disabled" ? "service_account.disable" : "service_account.enable",
+            outcome: "allowed",
+            actor: auditActor(actor),
+            target: { type: "service_account", id: account.id, label: account.name },
+            metadata: { serviceAccountId: account.id, serviceAccountKind: account.kind, status },
+          });
+          return ok({ ...account, status });
+        }),
+    )
+    .post(
+      "/service-accounts/:id/api-keys",
+      describeRoute({ tags: ["Service accounts"], summary: "Create an API key for a standalone service account; return its token once" }),
+      v("param", ServiceAccountParamsSchema),
+      v("json", ServiceAccountApiKeyInputSchema),
+      async (c) =>
+        respond(
+          c,
+          // The raw token intentionally appears only in this one create response.
+          () =>
+            service.credentials.createStandaloneApiToken({
+              serviceAccountId: c.req.valid("param").id,
+              actor: c.get("user"),
+              ...c.req.valid("json"),
+            }),
+          201,
+        ),
+    )
     .get("/mandates", v("query", MandateListQuerySchema), async (c) => {
       const query = c.req.valid("query");
       return c.json(

package/src/api/cli-plugins.ts

@@ -0,0 +1,17 @@
+import { Hono } from "hono";
+import { requireCliPluginAccess } from "../_internal/cli-plugins";
+import { listApps } from "../_internal/registry";
+import type { CloudCliPluginSummary } from "../cli/plugin";
+import type { AuthContext } from "../server/middleware/auth";
+
+/**
+ * `GET /cli/plugins`: the `cld` plugins that live applications serve, under
+ * the same access rule as the plugin downloads. Core mounts this list; each
+ * application serves its own plugin files.
+ */
+export const cliPluginListRoutes = new Hono<AuthContext>().get("/", requireCliPluginAccess, async (c) => {
+  const plugins: CloudCliPluginSummary[] = (await listApps())
+    .flatMap((app) => (app.cliModules ?? []).map((name) => ({ name, app: app.id, version: app.runtime?.version ?? "unknown" })))
+    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  return c.json({ plugins }, 200, { "cache-control": "private, no-store" });
+});

package/src/api/index.ts

@@ -43,6 +43,7 @@ import { createSyncOpsProxyRoutes } from "./sync-ops";
 import { createWidgetRoutes } from "./widgets";
 
 export { type CapabilityDispatchDependencies, dispatchCapability } from "./capabilities";
+export { cliPluginListRoutes } from "./cli-plugins";
 
 /**
  * Single-expression chain so `typeof buildCoreApi()` captures every route's

package/src/cli/access.ts

@@ -234,9 +234,17 @@ export const resolveAccessPrincipal = async (
   return resolveEntityPrincipal(ctx, "service_account", flags.serviceAccount!);
 };
 
+const entryTypeLabel = (entry: AccessEntry): string => {
+  if (entry.principal.type !== "service_account") return entry.principal.type;
+  if (entry.serviceAccountKind === "agent") return "agent";
+  if (entry.serviceAccountKind === "resource_bound") return "resource-bound";
+  return "service account";
+};
+
+// Resource-bound service accounts back resource API keys, which are managed with those keys.
 const accessRows = (entries: AccessEntry[], options: { includeServiceAccounts?: boolean } = {}) =>
   entries
-    .filter((entry) => options.includeServiceAccounts || entry.principal.type !== "service_account")
+    .filter((entry) => options.includeServiceAccounts || entry.serviceAccountKind !== "resource_bound")
     .sort((a, b) => {
       const rank = permissionRank(b.permission) - permissionRank(a.permission);
       if (rank !== 0) return rank;
@@ -245,7 +253,7 @@ const accessRows = (entries: AccessEntry[], options: { includeServiceAccounts?:
     .map((entry) => ({
       accessId: entry.id,
       principal: entryDisplayName(entry),
-      type: entry.principal.type,
+      type: entryTypeLabel(entry),
       permission: entry.permission,
       createdAt: entry.createdAt,
     }));
@@ -355,7 +363,7 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
     flags: {
       includeServiceAccounts: flag.boolean({
         name: "include-service-accounts",
-        description: "Include resource-bound service account grants that the UI normally hides.",
+        description: "Also show grants of resource-bound service accounts (resource API keys).",
       }),
     },
     examples: adapter.examples?.list,

package/src/cli/account.ts

@@ -224,6 +224,12 @@ const readRequiredSecret = async (input: CliInputFlagValue, label: string): Prom
 export default defineCliCommands({
   name: "account",
   summary: "Manage the authenticated account, profile, personal API keys, and SSH keys.",
+  groupSummaries: {
+    profile: "Show and update the account profile",
+    "api-keys": "Manage personal API keys",
+    "ssh-keys": "Manage SSH public keys",
+    password: "Change the account password",
+  },
   commands: [
     command("whoami", {
       summary: "Show the authenticated account",

package/src/cli/admin/agents.ts

@@ -0,0 +1,219 @@
+/**
+ * `cld admin agents` — standalone service accounts of kind `agent` with an
+ * OAuth client. `create` provisions the account and the client under the
+ * administrator's authority and writes the client credentials into a local
+ * `cld` profile through the host; the secret is never printed.
+ */
+import { z } from "zod";
+import { arg, cliText, command, confirmFlag, flag, printStructured } from "../index";
+import { apiGet, apiJson, queryString } from "./shared";
+
+const accountsRoot = "/api/admin/identity/service-accounts";
+const clientsRoot = "/api/oauth/admin/clients";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The scopes a `cld login` device session receives; an agent may do what a signed-in person's `cld` may do. */
+export const AGENT_CLIENT_SCOPES = ["openid", "profile", "email", "offline_access", "read", "write"] as const;
+
+const account = z.object({
+  id: z.string(),
+  name: z.string(),
+  kind: z.string(),
+  status: z.enum(["active", "disabled"]),
+  createdBy: z.string().nullable(),
+  createdAt: z.string(),
+});
+type Account = z.infer<typeof account>;
+const accountPage = z.object({ items: z.array(account), page: z.number(), perPage: z.number(), total: z.number(), hasNext: z.boolean() });
+const client = z.object({ id: z.string(), clientId: z.string(), name: z.string(), scopes: z.array(z.string()) });
+const clientPage = z.object({ clients: z.array(client) });
+const createdClient = client.extend({ clientSecret: z.string().min(1) });
+const rotatedSecret = z.object({ clientSecret: z.string().min(1) });
+
+type Ctx = Parameters<Parameters<typeof command>[1]["run"]>[0]["ctx"];
+
+const requireProfiles = (ctx: Ctx) => {
+  if (!ctx.profiles) {
+    throw new Error(
+      cliText(ctx, {
+        en: "This cld cannot store agent profiles. Update cld and retry.",
+        de: "Dieses cld kann keine Agent-Profile speichern. Aktualisiere cld und versuche es erneut.",
+      }),
+    );
+  }
+  return ctx.profiles;
+};
+
+const requireYes = (ctx: Ctx, yes: boolean | undefined, en: string, de: string) => {
+  if (!yes) throw new Error(cliText(ctx, { en, de }));
+};
+
+/** Resolve an agent by ID or exact name; ambiguity is an error, nothing is guessed. */
+const resolveAgent = async (ctx: Ctx, reference: string): Promise<Account> => {
+  if (UUID_PATTERN.test(reference)) {
+    const found = account.parse(await apiGet(ctx, `${accountsRoot}/${encodeURIComponent(reference)}`));
+    if (found.kind !== "agent") throw new Error(`Service account ${reference} is not an agent (kind ${found.kind}).`);
+    return found;
+  }
+  const page = accountPage.parse(await apiGet(ctx, `${accountsRoot}${queryString({ kind: "agent", search: reference, perPage: 50 })}`));
+  const matches = page.items.filter((item) => item.name.toLowerCase() === reference.toLowerCase());
+  if (matches.length === 1) return matches[0]!;
+  if (matches.length === 0) throw new Error(`No agent named "${reference}". Run \`cld admin agents ls\`.`);
+  throw new Error(`Several agents match "${reference}": ${matches.map((item) => `${item.name} (${item.id})`).join(", ")}.`);
+};
+
+const disableAccount = (ctx: Ctx, id: string) => apiJson(ctx, "PATCH", `${accountsRoot}/${encodeURIComponent(id)}`, { status: "disabled" });
+
+const requireProfileName = (flags: { profile?: string }): string => {
+  if (!flags.profile) throw new Error("Missing required flag --profile.");
+  return flags.profile;
+};
+
+const fd0Target = (flags: { fd0?: boolean; fd0Name?: string; fd0Scope?: string }, profile: string) =>
+  flags.fd0 || flags.fd0Name
+    ? { name: flags.fd0Name ?? `cloud-${profile}-oauth-client-secret`, ...(flags.fd0Scope ? { scope: flags.fd0Scope } : {}) }
+    : undefined;
+
+const profileFlags = {
+  profile: flag.string({ required: true, description: "Local cld profile that receives the client credentials" }),
+  server: flag.string({ description: "Cloud origin for that profile (default: the current server)" }),
+  fd0: flag.boolean({ description: "Keep the client secret in fd0 instead of the config file" }),
+  fd0Name: flag.string({ name: "fd0-name", description: "fd0 secret name (default: cloud-<profile>-oauth-client-secret)" }),
+  fd0Scope: flag.string({ name: "fd0-scope", description: "fd0 scope for the secret" }),
+};
+
+export const agentCommands = [
+  command("agents create", {
+    summary: "Create an agent account with an OAuth client and write its credentials into a local cld profile",
+    args: { name: arg.required({ valueLabel: "name" }) },
+    flags: { ...profileFlags, yes: confirmFlag("Create this agent and its OAuth client") },
+    async run({ ctx, args, flags }) {
+      requireYes(ctx, flags.yes, "Creating an agent requires --yes.", "Agent erstellen erfordert --yes.");
+      const profileName = requireProfileName(flags);
+      const profiles = requireProfiles(ctx);
+      const server = flags.server ?? ctx.options.server;
+      const created = account.parse(await apiJson(ctx, "POST", accountsRoot, { name: args.name, kind: "agent" }));
+
+      let oauthClient: z.infer<typeof createdClient>;
+      try {
+        oauthClient = createdClient.parse(
+          await apiJson(ctx, "POST", clientsRoot, {
+            name: `Agent: ${args.name}`,
+            description: `Client credentials of the agent "${args.name}" (cld admin agents).`,
+            redirectUris: [],
+            scopes: [...AGENT_CLIENT_SCOPES],
+            audiences: ["cloud"],
+            serviceAccountId: created.id,
+            allowedProfiles: [],
+            accessMode: "profiles",
+            allowedUserIds: [],
+            allowedGroupIds: [],
+            isPublic: false,
+          }),
+        );
+      } catch (error) {
+        await disableAccount(ctx, created.id).catch(() => undefined);
+        throw new Error(
+          `Created the agent account ${created.id} but not its OAuth client; the account was disabled. ${(error as Error).message}`,
+        );
+      }
+
+      try {
+        await profiles.saveClientCredentials({
+          name: profileName,
+          server,
+          clientId: oauthClient.clientId,
+          clientSecret: oauthClient.clientSecret,
+          scope: oauthClient.scopes.join(" "),
+          fd0: fd0Target(flags, profileName),
+        });
+      } catch (error) {
+        await disableAccount(ctx, created.id).catch(() => undefined);
+        throw new Error(
+          `Could not save profile "${profileName}"; the agent account ${created.id} was disabled. ${(error as Error).message}`,
+        );
+      }
+
+      const summary = {
+        account: created,
+        client: { id: oauthClient.id, clientId: oauthClient.clientId, scopes: oauthClient.scopes },
+        profile: { name: profileName, server, secretStorage: fd0Target(flags, profileName) ? "fd0" : "config" },
+      };
+      if (!printStructured(ctx, summary)) {
+        ctx.print(`Created agent "${created.name}" (${created.id}) with OAuth client ${oauthClient.clientId}.`);
+        ctx.print(`Profile "${profileName}" holds its client credentials. The agent has no access yet; grant it like a user.`);
+        ctx.print(`Try: cld --profile ${profileName} account whoami`);
+      }
+    },
+  }),
+  command("agents ls", {
+    summary: "List agent accounts",
+    flags: {
+      status: flag.enum(["active", "disabled"] as const),
+      search: flag.string({ aliases: ["q"] }),
+      page: flag.int({ min: 1, default: 1 }),
+      perPage: flag.int({ min: 1, max: 500, default: 100 }),
+    },
+    async run({ ctx, flags }) {
+      const page = accountPage.parse(
+        await apiGet(
+          ctx,
+          `${accountsRoot}${queryString({ kind: "agent", status: flags.status, search: flags.search, page: flags.page, perPage: flags.perPage })}`,
+        ),
+      );
+      if (!printStructured(ctx, page))
+        ctx.table(page.items, [
+          { key: "status", label: "Status" },
+          { key: "name", label: "Name" },
+          { key: "id", label: "ID" },
+          { key: "createdAt", label: "Created" },
+        ]);
+    },
+  }),
+  command("agents revoke", {
+    summary: "Disable an agent; every token, secret, and API key of it stops working at once",
+    args: { agent: arg.required({ valueLabel: "agent-id-or-name" }) },
+    flags: { yes: confirmFlag("Disable this agent") },
+    async run({ ctx, args, flags }) {
+      requireYes(ctx, flags.yes, "Revoking an agent requires --yes.", "Agent widerrufen erfordert --yes.");
+      const agent = await resolveAgent(ctx, args.agent);
+      const updated = account.parse(await disableAccount(ctx, agent.id));
+      if (!printStructured(ctx, updated)) ctx.print(`Disabled agent "${updated.name}" (${updated.id}).`);
+    },
+  }),
+  command("agents rotate-secret", {
+    summary: "Regenerate an agent's OAuth client secret and update the local cld profile",
+    args: { agent: arg.required({ valueLabel: "agent-id-or-name" }) },
+    flags: { ...profileFlags, yes: confirmFlag("Rotate this agent's client secret") },
+    async run({ ctx, args, flags }) {
+      requireYes(ctx, flags.yes, "Rotating a secret requires --yes.", "Secret rotieren erfordert --yes.");
+      const profileName = requireProfileName(flags);
+      const profiles = requireProfiles(ctx);
+      const agent = await resolveAgent(ctx, args.agent);
+      const { clients } = clientPage.parse(await apiGet(ctx, `${clientsRoot}${queryString({ serviceAccountId: agent.id, per_page: 50 })}`));
+      if (clients.length !== 1) {
+        throw new Error(
+          clients.length === 0
+            ? `Agent "${agent.name}" has no OAuth client.`
+            : `Agent "${agent.name}" has several OAuth clients: ${clients.map((item) => item.clientId).join(", ")}. Rotate one with cld oauth clients regenerate-secret.`,
+        );
+      }
+      const oauthClient = clients[0]!;
+      const rotated = rotatedSecret.parse(
+        await apiJson(ctx, "POST", `${clientsRoot}/${encodeURIComponent(oauthClient.id)}/regenerate-secret`),
+      );
+      await profiles.saveClientCredentials({
+        name: profileName,
+        server: flags.server ?? ctx.options.server,
+        clientId: oauthClient.clientId,
+        clientSecret: rotated.clientSecret,
+        scope: oauthClient.scopes.join(" "),
+        fd0: fd0Target(flags, profileName),
+      });
+      const summary = { account: agent, client: { id: oauthClient.id, clientId: oauthClient.clientId }, profile: profileName };
+      if (!printStructured(ctx, summary)) {
+        ctx.print(`Rotated the client secret of agent "${agent.name}"; profile "${profileName}" holds the new secret.`);
+      }
+    },
+  }),
+];

package/src/cli/admin/index.ts

@@ -8,6 +8,7 @@
 import { defineCliCommands } from "../commands";
 import { accountAdministrationCommands } from "./account-administration";
 import { accountCategoryCommands } from "./account-categories";
+import { agentCommands } from "./agents";
 import { aiQuotaCommands } from "./ai-quotas";
 import { aiSkillCommands } from "./ai-skills";
 import { aiUsageCommands } from "./ai-usage";
@@ -33,7 +34,39 @@ export default defineCliCommands({
   name: "admin",
   summary: "Inspect and operate Cloud administration surfaces.",
   groupSummaries: {
+    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 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.",
+    "app-sign-in": "Manage app sign-in and pairing.",
+    apps: "Inspect and remove registered apps.",
+    documentation: "Manage the administration documentation website.",
+    jobs: "Inspect background jobs and their runs.",
+    logs: "Search, inspect, and clean up retained logs.",
+    metrics: "Inspect collectors and manage metrics access.",
+    "metrics tokens": "Manage metrics bearer tokens.",
+    nats: "Inspect NATS nodes, streams, and consumers.",
+    "nats consumers": "Inspect NATS consumers.",
+    "nats streams": "Find NATS streams and buckets.",
+    "notification-batches": "Manage account notification batches.",
+    notifications: "Inspect and resend email notifications.",
+    postgres: "Inspect Postgres diagnostics.",
+    redis: "Inspect Valkey diagnostics.",
+    routes: "Inspect gateway routes.",
+    sync: "Inspect Sync resources, schedules, and dead letters.",
+    "sync dead-letters": "Inspect, replay, requeue, or remove dead letters.",
+    "sync resources": "List Sync resource declarations.",
+    "sync schedules": "Inspect and run Sync schedules.",
+    "sync schedules runs": "Read Sync schedule run results.",
+    telemetry: "Inspect request telemetry.",
+    webhooks: "Manage gateway health webhooks.",
+    workflows: "Inspect and operate workflow runs and effects.",
     "app-sign-in config": "Manage the trusted app website and pairing policy.",
     "accounts config": "Manage account types and sign-in visibility.",
     "accounts administration": "Manage account requests and account/group follow-up notices.",
@@ -45,6 +78,7 @@ export default defineCliCommands({
   },
   commands: [
     ...appCredentialCommands,
+    ...agentCommands,
     ...documentationCommands,
     ...appSignInCommands,
     ...accountCategoryCommands,

package/src/cli/index.ts

@@ -43,6 +43,28 @@ export type CloudCliContext = {
   /** Print one compact JSON value followed by a newline. */
   jsonLine: (value: unknown) => void;
   table: <TRow extends Record<string, unknown>>(rows: TRow[], columns: CloudCliTableColumn<TRow>[]) => void;
+  /**
+   * The host's local profile store, when it has one. A command that provisions
+   * a machine credential hands the secret here instead of printing it; the host
+   * stores it like a refresh token. Absent in hosts without profiles.
+   */
+  profiles?: {
+    saveClientCredentials: (input: CloudCliClientCredentialsProfile) => Promise<void>;
+  };
+};
+
+/** A profile that signs in with the OAuth client-credentials grant. */
+export type CloudCliClientCredentialsProfile = {
+  /** Profile name in the host's config. */
+  name: string;
+  /** Cloud origin the credentials belong to. */
+  server: string;
+  clientId: string;
+  clientSecret: string;
+  /** Space-separated scopes the client is allowed to request. */
+  scope: string;
+  /** Keep the secret in fd0 under this name instead of the config file. */
+  fd0?: { name: string; scope?: string };
 };
 
 export type CloudCliModule = {
@@ -61,3 +83,4 @@ export * from "./address";
 export * from "./commands";
 export * from "./locale";
 export * from "./output";
+export * from "./plugin";