@ornncompute/cli 0.2.6 → 0.2.8

package/vendor/capabilities/capabilities/staff-fleet.js

@@ -0,0 +1,465 @@
+import { z } from "zod";
+import { defineStaffMcpCapability, preview } from "../capability.js";
+import { mapBody, seg } from "./staff-shared.js";
+// Staff fleet verbs: operators, facilities, nodes, node jobs, and enrollment
+// token revocation. MCP-only — see `defineStaffMcpCapability`.
+const slugSchema = z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9-]*$/, "slug must be lowercase alphanumeric with dashes")
+    .max(80);
+const operatorModeSchema = z.enum(["managed", "federated"]);
+const operatorStatusSchema = z.enum(["active", "unavailable", "revoked"]);
+export const enrollmentTokenRevokeInput = z.object({
+    tokenId: z.string(),
+    confirm: z.boolean().optional(),
+});
+export const enrollmentTokenRevokeCapability = defineStaffMcpCapability({
+    id: "enrollment.token.revoke",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: revoke an enrollment token.",
+    mutation: "preview-confirm",
+    http: { method: "POST", path: "/enrollment/tokens/{tokenId}/revoke" },
+    input: enrollmentTokenRevokeInput,
+    execute: async (ctx, input) => {
+        const parsed = enrollmentTokenRevokeInput.parse(input);
+        if (!ctx.confirmed)
+            return preview("enrollment.token.revoke", { tokenId: parsed.tokenId });
+        return ctx.fetch(`/enrollment/tokens/${seg(parsed.tokenId)}/revoke`, { method: "POST" });
+    },
+});
+export const operatorCreateInput = z.object({
+    slug: slugSchema,
+    displayName: z.string().min(1).max(160),
+    mode: operatorModeSchema.optional(),
+    status: operatorStatusSchema.optional(),
+    confirm: z.boolean().optional(),
+});
+export const operatorCreateCapability = defineStaffMcpCapability({
+    id: "operator.create",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: create an operator (managed or federated). Requires confirm: true. Does not touch any hardware.",
+    mutation: "preview-confirm",
+    http: { method: "POST", path: "/provisioning/operators" },
+    input: operatorCreateInput,
+    execute: async (ctx, input) => {
+        const parsed = operatorCreateInput.parse(input);
+        const body = {
+            slug: parsed.slug,
+            display_name: parsed.displayName,
+            ...mapBody(parsed, { mode: "mode", status: "status" }),
+        };
+        if (!ctx.confirmed)
+            return preview("operator.create", body);
+        return ctx.fetch("/provisioning/operators", { method: "POST", body });
+    },
+});
+export const operatorUpdateInput = z.object({
+    operatorId: z.string(),
+    displayName: z.string().min(1).max(160).optional(),
+    slug: slugSchema.optional(),
+    mode: operatorModeSchema.optional(),
+    status: operatorStatusSchema.optional(),
+    confirm: z.boolean().optional(),
+});
+export const operatorUpdateCapability = defineStaffMcpCapability({
+    id: "operator.update",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: update an operator's display name, slug, mode, or status. Requires confirm: true.",
+    mutation: "preview-confirm",
+    http: { method: "PATCH", path: "/provisioning/operators/{operatorId}" },
+    input: operatorUpdateInput,
+    execute: async (ctx, input) => {
+        const parsed = operatorUpdateInput.parse(input);
+        const body = mapBody(parsed, {
+            displayName: "display_name",
+            slug: "slug",
+            mode: "mode",
+            status: "status",
+        });
+        if (!ctx.confirmed)
+            return preview("operator.update", body);
+        return ctx.fetch(`/provisioning/operators/${seg(parsed.operatorId)}`, {
+            method: "PATCH",
+            body,
+        });
+    },
+});
+export const operatorDeleteInput = z.object({
+    operatorId: z.string(),
+    confirm: z.boolean().optional(),
+});
+export const operatorDeleteCapability = defineStaffMcpCapability({
+    id: "operator.delete",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: delete an operator. Requires confirm: true.",
+    mutation: "preview-confirm",
+    http: { method: "DELETE", path: "/provisioning/operators/{operatorId}" },
+    input: operatorDeleteInput,
+    execute: async (ctx, input) => {
+        const parsed = operatorDeleteInput.parse(input);
+        if (!ctx.confirmed)
+            return preview("operator.delete", { operatorId: parsed.operatorId });
+        return ctx.fetch(`/provisioning/operators/${seg(parsed.operatorId)}`, { method: "DELETE" });
+    },
+});
+export const facilityCreateInput = z.object({
+    operatorId: z.string(),
+    slug: slugSchema,
+    displayName: z.string().min(1).max(160),
+    region: z.string().min(1).max(120),
+    zone: z.string().max(120).optional(),
+    confirm: z.boolean().optional(),
+});
+export const facilityCreateCapability = defineStaffMcpCapability({
+    id: "facility.create",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: create a facility under an operator. Requires confirm: true. Does not touch any hardware.",
+    mutation: "preview-confirm",
+    http: { method: "POST", path: "/provisioning/facilities" },
+    input: facilityCreateInput,
+    execute: async (ctx, input) => {
+        const parsed = facilityCreateInput.parse(input);
+        const body = {
+            operator_id: parsed.operatorId,
+            slug: parsed.slug,
+            display_name: parsed.displayName,
+            region: parsed.region,
+            zone: parsed.zone ?? null,
+        };
+        if (!ctx.confirmed)
+            return preview("facility.create", body);
+        return ctx.fetch("/provisioning/facilities", { method: "POST", body });
+    },
+});
+export const facilityUpdateInput = z.object({
+    facilityId: z.string(),
+    displayName: z.string().min(1).max(160).optional(),
+    region: z.string().min(1).max(120).optional(),
+    zone: z.string().max(120).optional(),
+    confirm: z.boolean().optional(),
+});
+export const facilityUpdateCapability = defineStaffMcpCapability({
+    id: "facility.update",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: update a facility's display name, region, or zone. Pass zone as an empty string to clear it. Requires confirm: true.",
+    mutation: "preview-confirm",
+    http: { method: "PATCH", path: "/provisioning/facilities/{facilityId}" },
+    input: facilityUpdateInput,
+    execute: async (ctx, input) => {
+        const parsed = facilityUpdateInput.parse(input);
+        // "" clears zone; omitting it leaves zone unchanged (mirrors the dashboard PATCH).
+        const body = mapBody(parsed, {
+            displayName: "display_name",
+            region: "region",
+            zone: "zone",
+        });
+        if (!ctx.confirmed)
+            return preview("facility.update", body);
+        return ctx.fetch(`/provisioning/facilities/${seg(parsed.facilityId)}`, {
+            method: "PATCH",
+            body,
+        });
+    },
+});
+export const nodeShowInput = z.object({ nodeId: z.string() });
+export const nodeShowCapability = defineStaffMcpCapability({
+    id: "node.show",
+    domain: "fleet",
+    roles: ["reviewer", "admin"],
+    description: "Internal staff only: show details for a single GPU node.",
+    mutation: "read",
+    http: { method: "GET", path: "/internal/nodes/{nodeId}" },
+    input: nodeShowInput,
+    execute: async (ctx, input) => {
+        const parsed = nodeShowInput.parse(input);
+        return ctx.fetch(`/internal/nodes/${seg(parsed.nodeId)}`, { method: "GET" });
+    },
+});
+export const nodeDetailsUpdateInput = z.object({
+    nodeId: z.string(),
+    hostname: z.string().optional(),
+    publicLocation: z.string().optional(),
+    facilityId: z.string().optional(),
+    gpuType: z.string().optional(),
+    gpuCount: z.number().int().positive().optional(),
+    ornnMode: z.string().optional(),
+    cpu: z.string().optional(),
+    ram: z.string().optional(),
+    storage: z.string().optional(),
+    fabricType: z.string().optional(),
+    internet: z.string().optional(),
+    networkHardware: z.string().optional(),
+    buyNowPricePerGpuHour: z.number().nullable().optional(),
+    confirm: z.boolean().optional(),
+});
+export const nodeDetailsUpdateCapability = defineStaffMcpCapability({
+    id: "node.details-update",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: update core node fields and reserve-listing / spec-sheet values (hostname, location, GPUs, CPU/RAM/storage, buy-now price). Requires confirm: true.",
+    mutation: "preview-confirm",
+    http: { method: "PATCH", path: "/internal/nodes/{nodeId}/details" },
+    input: nodeDetailsUpdateInput,
+    execute: async (ctx, input) => {
+        const parsed = nodeDetailsUpdateInput.parse(input);
+        // Backend confirm is required for risky edits on reserved nodes; the caller's
+        // confirm already gated execution, so always send confirm: true on the wire.
+        const body = {
+            confirm: true,
+            ...mapBody(parsed, {
+                hostname: "hostname",
+                publicLocation: "public_location",
+                facilityId: "facility_id",
+                gpuType: "gpu_type",
+                gpuCount: "gpu_count",
+                ornnMode: "ornn_mode",
+                cpu: "cpu",
+                ram: "ram",
+                storage: "storage",
+                fabricType: "fabric_type",
+                internet: "internet",
+                networkHardware: "network_hardware",
+                buyNowPricePerGpuHour: "buy_now_price_per_gpu_hour",
+            }),
+        };
+        if (!ctx.confirmed)
+            return preview("node.details-update", body);
+        return ctx.fetch(`/internal/nodes/${seg(parsed.nodeId)}/details`, { method: "PATCH", body });
+    },
+});
+export const nodeReserveListingInput = z.object({
+    nodeId: z.string(),
+    availableFrom: z.string().optional(),
+    availableTo: z.string().nullable().optional(),
+    confirm: z.boolean().optional(),
+});
+export const nodeReserveListingCapability = defineStaffMcpCapability({
+    id: "node.reserve-listing",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: list a GPU node on the reserve marketplace inventory. Requires confirm: true.",
+    mutation: "preview-confirm",
+    http: { method: "POST", path: "/inventory/{nodeId}" },
+    input: nodeReserveListingInput,
+    execute: async (ctx, input) => {
+        const parsed = nodeReserveListingInput.parse(input);
+        const body = mapBody(parsed, {
+            availableFrom: "available_from",
+            availableTo: "available_to",
+        });
+        if (!ctx.confirmed)
+            return preview("node.reserve-listing", body);
+        return ctx.fetch(`/inventory/${seg(parsed.nodeId)}`, { method: "POST", body });
+    },
+});
+export const nodeTestTriggerInput = z.object({
+    nodeId: z.string(),
+    burnTimeMinutes: z.number().optional(),
+    constraints: z.record(z.string(), z.unknown()).optional(),
+    source: z.record(z.string(), z.unknown()).optional(),
+    confirm: z.boolean().optional(),
+});
+export const nodeTestTriggerCapability = defineStaffMcpCapability({
+    id: "node.test-trigger",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: start a node job (host checks + GPU suites; optional burn-in minutes). Requires confirm: true.",
+    mutation: "preview-confirm",
+    http: { method: "POST", path: "/jobs" },
+    input: nodeTestTriggerInput,
+    execute: async (ctx, input) => {
+        const parsed = nodeTestTriggerInput.parse(input);
+        let constraints = { ...(parsed.constraints ?? {}) };
+        if (parsed.burnTimeMinutes !== undefined) {
+            constraints = {
+                ...constraints,
+                burn_time_minutes: parsed.burnTimeMinutes,
+                include_burn_samples: true,
+            };
+        }
+        const body = {
+            node_id: parsed.nodeId,
+            constraints,
+            source: parsed.source ?? { mode: "no_spec" },
+            burn_time_minutes: parsed.burnTimeMinutes ?? 0,
+        };
+        if (!ctx.confirmed)
+            return preview("node.test-trigger", body);
+        return ctx.fetch("/jobs", { method: "POST", body });
+    },
+});
+export const nodeTestResultInput = z.object({
+    nodeId: z.string().optional(),
+    jobId: z.string(),
+    packetId: z.string().optional(),
+});
+export const nodeTestResultCapability = defineStaffMcpCapability({
+    id: "node.test-result",
+    domain: "fleet",
+    roles: ["reviewer", "admin"],
+    description: "Internal staff only: fetch a node job by id.",
+    mutation: "read",
+    http: { method: "GET", path: "/jobs/{jobId}" },
+    input: nodeTestResultInput,
+    execute: async (ctx, input) => {
+        const parsed = nodeTestResultInput.parse(input);
+        return ctx.fetch(`/jobs/${seg(parsed.jobId)}`, { method: "GET" });
+    },
+});
+export const nodeBenchmarkInput = z.object({ nodeId: z.string() });
+export const nodeBenchmarkCapability = defineStaffMcpCapability({
+    id: "node.benchmark",
+    domain: "fleet",
+    roles: ["reviewer", "admin"],
+    description: "Internal staff only: show the current burn-in / benchmark summary for a GPU node.",
+    mutation: "read",
+    http: { method: "GET", path: "/jobs" },
+    input: nodeBenchmarkInput,
+    execute: async (ctx, input) => {
+        const parsed = nodeBenchmarkInput.parse(input);
+        return ctx.fetch(`/jobs?node_id=${seg(parsed.nodeId)}`, { method: "GET" });
+    },
+});
+export const nodeDeployInput = z.object({
+    nodeId: z.string(),
+    targetTenantId: z.string(),
+    targetAuthUserId: z.string().optional(),
+    networkMode: z.enum(["public", "private"]).optional(),
+    notes: z.string().max(2000).optional(),
+    confirm: z.boolean().optional(),
+});
+export const nodeDeployCapability = defineStaffMcpCapability({
+    id: "node.deploy",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: deploy a free GPU node to a target tenant (create reservation + queue handoff). Does not accept a force override. Requires confirm: true.",
+    mutation: "preview-confirm",
+    http: { method: "POST", path: "/internal/nodes/{nodeId}/deploy" },
+    input: nodeDeployInput,
+    execute: async (ctx, input) => {
+        const parsed = nodeDeployInput.parse(input);
+        const body = {
+            target_tenant_id: parsed.targetTenantId,
+            ...mapBody(parsed, {
+                targetAuthUserId: "target_auth_user_id",
+                networkMode: "network_mode",
+                notes: "notes",
+            }),
+        };
+        if (!ctx.confirmed)
+            return preview("node.deploy", body);
+        return ctx.fetch(`/internal/nodes/${seg(parsed.nodeId)}/deploy`, { method: "POST", body });
+    },
+});
+export const nodeUpdateInput = z.object({
+    nodeId: z.string(),
+    targetVersion: z.string().optional(),
+    confirm: z.boolean().optional(),
+});
+export const nodeUpdateCapability = defineStaffMcpCapability({
+    id: "node.update",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: write the desired ornn-node version on the host row. Does not accept a force override. Requires confirm: true.",
+    mutation: "preview-confirm",
+    http: { method: "PATCH", path: "/internal/nodes/{nodeId}" },
+    input: nodeUpdateInput,
+    execute: async (ctx, input) => {
+        const parsed = nodeUpdateInput.parse(input);
+        const body = mapBody(parsed, { targetVersion: "desired_agent_version" });
+        if (!ctx.confirmed)
+            return preview("node.update", body);
+        return ctx.fetch(`/internal/nodes/${seg(parsed.nodeId)}`, { method: "PATCH", body });
+    },
+});
+const machineRebootInput = z.object({
+    instanceId: z.string(),
+    confirm: z.boolean().optional(),
+});
+export const nodeRebootInput = machineRebootInput;
+export const nodeHardResetInput = machineRebootInput;
+/**
+ * Reboot and hard-reset share one orchestrator endpoint and differ only by
+ * `mode`, but they stay separate verbs: "wipe the host" must never be one
+ * mistyped argument away from "restart the host".
+ */
+function rebootCapability(options) {
+    return defineStaffMcpCapability({
+        id: options.id,
+        domain: "fleet",
+        roles: ["admin"],
+        description: options.description,
+        mutation: "preview-confirm",
+        http: { method: "POST", path: "/internal/nodes/{instanceId}/reboot" },
+        input: machineRebootInput,
+        execute: async (ctx, input) => {
+            const parsed = machineRebootInput.parse(input);
+            const body = { mode: options.mode };
+            if (!ctx.confirmed)
+                return preview(options.id, { instanceId: parsed.instanceId, ...body });
+            return ctx.fetch(`/internal/nodes/${seg(parsed.instanceId)}/reboot`, {
+                method: "POST",
+                body,
+            });
+        },
+    });
+}
+export const nodeRebootCapability = rebootCapability({
+    id: "node.reboot",
+    mode: "reboot",
+    description: "Internal staff only: reboot a live machine (a node's running instance). Plain OS reboot -- keeps storage and SSH keys. Address the machine by its instance id (see ornn_admin_reservation_machines_list). Requires confirm: true.",
+});
+export const nodeHardResetCapability = rebootCapability({
+    id: "node.hard-reset",
+    mode: "hard_reset",
+    description: "Internal staff only: hard-reset a live machine (a node's running instance) -- clean the host (wipe tenant storage, users, keys, caches) then reboot. This does NOT restore SSH access; after the reset completes, run ornn_admin_ssh_key_push to re-push the reservation's organization SSH keys. The tenant KEEPS ownership. Address the machine by its instance id (see ornn_admin_reservation_machines_list). Requires confirm: true.",
+});
+export const nodeAdminKeyInput = z.object({
+    nodeId: z.string(),
+    generate: z.boolean().optional(),
+    confirm: z.boolean().optional(),
+});
+export const nodeAdminKeyCapability = defineStaffMcpCapability({
+    id: "node.admin-key",
+    domain: "fleet",
+    roles: ["admin"],
+    description: "Internal staff only: fetch the Ornn admin SSH keypair for a GPU node, including the decrypted PRIVATE key, so an operator can SSH into the host directly. Handle the private key as a secret. Set generate: true (requires confirm: true) to mint a new pair and install the public key on the live host.",
+    // Reading the stored pair is a GET; minting a new one is the same path as a POST.
+    mutation: "preview-confirm",
+    http: { method: "GET", path: "/enrollment/admin-ssh-key" },
+    input: nodeAdminKeyInput,
+    execute: async (ctx, input) => {
+        const parsed = nodeAdminKeyInput.parse(input);
+        if (parsed.generate && !ctx.confirmed) {
+            return preview("node.admin-key", { nodeId: parsed.nodeId, generate: true });
+        }
+        return ctx.fetch(`/enrollment/admin-ssh-key?node_id=${seg(parsed.nodeId)}`, {
+            method: parsed.generate ? "POST" : "GET",
+        });
+    },
+});
+export const staffFleetCapabilities = [
+    enrollmentTokenRevokeCapability,
+    operatorCreateCapability,
+    operatorUpdateCapability,
+    operatorDeleteCapability,
+    facilityCreateCapability,
+    facilityUpdateCapability,
+    nodeShowCapability,
+    nodeDetailsUpdateCapability,
+    nodeReserveListingCapability,
+    nodeTestTriggerCapability,
+    nodeTestResultCapability,
+    nodeBenchmarkCapability,
+    nodeDeployCapability,
+    nodeUpdateCapability,
+    nodeRebootCapability,
+    nodeHardResetCapability,
+    nodeAdminKeyCapability,
+];

package/vendor/capabilities/capabilities/staff-shared.d.ts

@@ -0,0 +1,18 @@
+/** Helpers shared by the staff MCP verbs in `staff-*.ts`. */
+/**
+ * Build a request body from the fields that were actually supplied.
+ *
+ * Staff writes are almost all "PATCH the fields the caller named": `undefined`
+ * means leave alone, and `null` is a real value that clears the field. So the
+ * check is `!== undefined`, never truthiness.
+ */
+export declare function mapBody(input: Record<string, unknown>, mapping: Record<string, string>): Record<string, unknown>;
+/** Path segment escape. */
+export declare function seg(value: string): string;
+/**
+ * A transport failure's HTTP status, when it carries one.
+ *
+ * Capabilities cannot import a surface's error class (`apps/mcp`'s
+ * `WebApiError`, say), so read the status structurally.
+ */
+export declare function statusOf(error: unknown): number | undefined;

package/vendor/capabilities/capabilities/staff-shared.js

@@ -0,0 +1,34 @@
+/** Helpers shared by the staff MCP verbs in `staff-*.ts`. */
+/**
+ * Build a request body from the fields that were actually supplied.
+ *
+ * Staff writes are almost all "PATCH the fields the caller named": `undefined`
+ * means leave alone, and `null` is a real value that clears the field. So the
+ * check is `!== undefined`, never truthiness.
+ */
+export function mapBody(input, mapping) {
+    const body = {};
+    for (const [field, wire] of Object.entries(mapping)) {
+        if (input[field] !== undefined)
+            body[wire] = input[field];
+    }
+    return body;
+}
+/** Path segment escape. */
+export function seg(value) {
+    return encodeURIComponent(value);
+}
+/**
+ * A transport failure's HTTP status, when it carries one.
+ *
+ * Capabilities cannot import a surface's error class (`apps/mcp`'s
+ * `WebApiError`, say), so read the status structurally.
+ */
+export function statusOf(error) {
+    if (error && typeof error === "object" && "status" in error) {
+        const status = error.status;
+        if (typeof status === "number")
+            return status;
+    }
+    return undefined;
+}

package/vendor/capabilities/capabilities/tokens.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { defineCapability } from "../capability.js";
+import { defineCapability, preview } from "../capability.js";
 const optionalText = z.string().nullish();
 const tokenCreateInput = z.object({
     operator_id: z.string().min(1),
@@ -107,7 +107,7 @@ export const tokensCreateCapability = defineCapability({
             remote: hosts.length > 0 && privateKey.length > 0,
         };
         if (!ctx.confirmed) {
-            return { ok: true, action: "tokens.create", payload: { ...payload, private_key: privateKey ? "[redacted]" : "" } };
+            return preview("tokens.create", { ...payload, private_key: privateKey ? "[redacted]" : "" });
         }
         const minted = (await ctx.fetch("/internal/enrollment-tokens", {
             method: "POST",

package/vendor/capabilities/capability.d.ts

@@ -19,6 +19,24 @@ export type CapabilityContext = {
     /** Human (or MCP) confirmed a preview-confirm mutation. Execute never POSTs without this. */
     confirmed?: boolean;
 };
+/** The un-executed result of a `preview-confirm` capability. */
+export type PreviewResult = {
+    status: "preview";
+    requiresConfirm: true;
+    confirmed: false;
+    action: string;
+    payload: unknown;
+};
+/**
+ * Build a preview-confirm capability's un-executed result.
+ *
+ * Previews used to return `{ ok: true, action, payload }`, which is
+ * indistinguishable from a completed mutation to anyone skimming the JSON --
+ * a human, or an LLM deciding whether its call took effect. ORN-3417 recorded
+ * a live `node.off-grid` preview as a confirm-gate failure for exactly that
+ * reason. `status: "preview"` states it outright, and carries no `ok`.
+ */
+export declare function preview(action: string, payload: unknown): PreviewResult;
 export type JsonSchema = {
     type: "object";
     properties?: Record<string, unknown>;
@@ -53,6 +71,20 @@ export type CapabilitySpec<I = unknown, O = unknown> = Omit<Capability<I, O>, "c
 };
 /** Fill CLI/MCP/Slack names from `id`. Slack parameters stay optional. */
 export declare function defineCapability<I, O>(spec: CapabilitySpec<I, O>): Capability;
+/** A staff verb that only MCP dispatches: an MCP name, no Slack or CLI binding. */
+export type StaffMcpCapabilitySpec<I = unknown, O = unknown> = Omit<CapabilitySpec<I, O>, "slack">;
+/**
+ * Fill only the MCP name from `id`.
+ *
+ * `visibleToClient` gates Slack on `capability.slack != null` and CLI on
+ * `capability.cli != null`, so omitting a binding is how the catalog already
+ * says "not on that surface" — `defineCapability` just happens to set all
+ * three unconditionally. Staff admin verbs need the MCP one only: Slack's
+ * staff surface is a deliberately small, human-confirmed set, and `apps/cli`
+ * writes each command by hand, so a CLI binding here would advertise a
+ * command that does not exist.
+ */
+export declare function defineStaffMcpCapability<I, O>(spec: StaffMcpCapabilitySpec<I, O>): Capability;
 export declare function slackStaffVisible(capability: Pick<Capability, "roles">): boolean;
 export declare function visibleToClient(capability: Pick<Capability, "roles" | "cli" | "mcp" | "slack">, client: ClientKind, role: Role): boolean;
 export declare function forRole(catalog: readonly Capability[], role: Role, client: ClientKind): Capability[];

package/vendor/capabilities/capability.js

@@ -16,6 +16,18 @@ export const DOMAINS = [
     "billing",
     "observability",
 ];
+/**
+ * Build a preview-confirm capability's un-executed result.
+ *
+ * Previews used to return `{ ok: true, action, payload }`, which is
+ * indistinguishable from a completed mutation to anyone skimming the JSON --
+ * a human, or an LLM deciding whether its call took effect. ORN-3417 recorded
+ * a live `node.off-grid` preview as a confirm-gate failure for exactly that
+ * reason. `status: "preview"` states it outright, and carries no `ok`.
+ */
+export function preview(action, payload) {
+    return { status: "preview", requiresConfirm: true, confirmed: false, action, payload };
+}
 /** Fill CLI/MCP/Slack names from `id`. Slack parameters stay optional. */
 export function defineCapability(spec) {
     const names = namesFromId(spec.id);
@@ -29,6 +41,20 @@ export function defineCapability(spec) {
         },
     };
 }
+/**
+ * Fill only the MCP name from `id`.
+ *
+ * `visibleToClient` gates Slack on `capability.slack != null` and CLI on
+ * `capability.cli != null`, so omitting a binding is how the catalog already
+ * says "not on that surface" — `defineCapability` just happens to set all
+ * three unconditionally. Staff admin verbs need the MCP one only: Slack's
+ * staff surface is a deliberately small, human-confirmed set, and `apps/cli`
+ * writes each command by hand, so a CLI binding here would advertise a
+ * command that does not exist.
+ */
+export function defineStaffMcpCapability(spec) {
+    return { ...spec, mcp: { name: namesFromId(spec.id).mcp } };
+}
 export function slackStaffVisible(capability) {
     return capability.roles.some((role) => role === "reviewer" || role === "admin");
 }

package/vendor/capabilities/catalog.js

@@ -4,6 +4,9 @@ import { tokenCapabilities } from "./capabilities/tokens.js";
 import { identityCapabilities } from "./capabilities/identity.js";
 import { listingCapabilities } from "./capabilities/listings.js";
 import { observabilityCapabilities } from "./capabilities/observability.js";
+import { staffAccessCapabilities } from "./capabilities/staff-access.js";
+import { staffCommerceCapabilities } from "./capabilities/staff-commerce.js";
+import { staffFleetCapabilities } from "./capabilities/staff-fleet.js";
 import { userCapabilities } from "./capabilities/users.js";
 /** System of record for CLI, MCP, and Slack verbs. Add capabilities here. */
 export const catalog = [
@@ -15,4 +18,7 @@ export const catalog = [
     ...observabilityCapabilities,
     ...slurmCapabilities,
     ...kubernetesCapabilities,
+    ...staffFleetCapabilities,
+    ...staffCommerceCapabilities,
+    ...staffAccessCapabilities,
 ];

package/vendor/capabilities/index.d.ts

@@ -1,4 +1,4 @@
-export { byCliCommand, byMcpName, bySlackName, defineCapability, forRole, slackStaffVisible, visibleToClient, type Capability, type CapabilityBindings, type CapabilityContext, type CapabilitySpec, type JsonSchema, type CapabilityTransport, type Domain, type HttpSpec, type Mutation, } from "./capability.ts";
+export { byCliCommand, byMcpName, bySlackName, defineCapability, defineStaffMcpCapability, forRole, preview, slackStaffVisible, visibleToClient, type Capability, type CapabilityBindings, type CapabilityContext, type CapabilitySpec, type StaffMcpCapabilitySpec, type JsonSchema, type CapabilityTransport, type Domain, type HttpSpec, type Mutation, type PreviewResult, } from "./capability.ts";
 export { namesFromId } from "./names.ts";
 export { catalog } from "./catalog.ts";
 export { fleetCapabilities, listFacilitiesCapability, listNodesCapability, listOperatorsCapability, nodeExecCapability, nodeOffGridCapability, nodeOnGridCapability, nodeTerminateCapability, } from "./capabilities/fleet.ts";
@@ -8,5 +8,8 @@ export { createListingCapability, listingCreateInput, listCatalogTermsCapability
 export { userCapabilities, usersQueryCapability } from "./capabilities/users.ts";
 export { kubernetesCapabilities, slurmCapabilities } from "./capabilities/clusters.ts";
 export { logsLatestCapability, logsTailCapability, observabilityCapabilities, telemetryLatestCapability, telemetryTailCapability, } from "./capabilities/observability.ts";
+export { enrollmentTokenRevokeCapability, enrollmentTokenRevokeInput, facilityCreateCapability, facilityCreateInput, facilityUpdateCapability, facilityUpdateInput, nodeAdminKeyCapability, nodeAdminKeyInput, nodeBenchmarkCapability, nodeBenchmarkInput, nodeDeployCapability, nodeDeployInput, nodeDetailsUpdateCapability, nodeDetailsUpdateInput, nodeHardResetCapability, nodeHardResetInput, nodeRebootCapability, nodeRebootInput, nodeReserveListingCapability, nodeReserveListingInput, nodeShowCapability, nodeShowInput, nodeTestResultCapability, nodeTestResultInput, nodeTestTriggerCapability, nodeTestTriggerInput, nodeUpdateCapability, nodeUpdateInput, operatorCreateCapability, operatorCreateInput, operatorDeleteCapability, operatorDeleteInput, operatorUpdateCapability, operatorUpdateInput, staffFleetCapabilities, } from "./capabilities/staff-fleet.ts";
+export { bidAcceptCapability, bidAcceptInput, bidRejectCapability, bidRejectInput, inventoryUpdateCapability, inventoryUpdateInput, reservationCancelCapability, reservationCancelInput, reservationMachinesListCapability, reservationMachinesListInput, reservationPublishCapability, reservationPublishInput, reservationSshKeyAddCapability, reservationSshKeyAddInput, reservationSshKeyRemoveCapability, reservationSshKeyRemoveInput, reservationTransferCapability, reservationTransferInput, staffCommerceCapabilities, tenantCreditProfileShowCapability, tenantCreditProfileShowInput, } from "./capabilities/staff-commerce.ts";
+export { sshKeyAddCapability, sshKeyAddInput, sshKeyPushCapability, sshKeyPushInput, sshKeyRevokeCapability, sshKeyRevokeInput, staffAccessCapabilities, } from "./capabilities/staff-access.ts";
 export { CLIENTS, parseRole, roleAtLeast, ROLES, type ClientKind, type Role } from "./role.ts";
 export { bindHardwareFields, HARDWARE_CATALOG_PATH, HARDWARE_KINDS, HARDWARE_LISTING_FIELDS, HARDWARE_LISTING_FILTERS, loadHardwareCatalog, looksLikeSpecDump, normalizeCatalogQuery, parseHardwareCatalog, projectCatalogTerms, proposeListingPayload, resolveCatalogTerm, UNRESOLVED_CATALOG_HINT, type CatalogBindResult, type CatalogTerm, type HardwareCatalog, type HardwareKind, type ResolvedCatalogTerm, } from "./spec-catalog.ts";