@ornncompute/cli 0.1.8 → 0.2.0

package/src/device-auth.mjs

@@ -44,10 +44,9 @@ export async function openBrowser(url, { platform = process.platform, spawnImpl
   }
 }
 
-export async function startDeviceFlow({ authBaseUrl, fetchImpl = fetch } = {}) {
-  const data = await postJson(fetchImpl, `${authBaseUrl}/api/cli/auth/device/start`, {
-    client: "ornn-cli",
-  });
+export async function startDeviceFlow({ apiBaseUrl, authBaseUrl, fetchImpl = fetch } = {}) {
+  const requestBaseUrl = apiBaseUrl || authBaseUrl;
+  const data = await postJson(fetchImpl, `${requestBaseUrl}/v1/cli/device/start`, {});
 
   const deviceCode = pickString(data, "deviceCode", "device_code");
   const userCode = pickString(data, "userCode", "user_code");
@@ -70,14 +69,16 @@ export async function startDeviceFlow({ authBaseUrl, fetchImpl = fetch } = {}) {
   };
 }
 
-export async function pollDeviceFlow({ authBaseUrl, deviceCode, fetchImpl = fetch } = {}) {
-  return postJson(fetchImpl, `${authBaseUrl}/api/cli/auth/device/poll`, {
-    deviceCode,
+export async function pollDeviceFlow({ apiBaseUrl, authBaseUrl, deviceCode, fetchImpl = fetch } = {}) {
+  const requestBaseUrl = apiBaseUrl || authBaseUrl;
+  return postJson(fetchImpl, `${requestBaseUrl}/v1/cli/device/poll`, {
+    device_code: deviceCode,
   });
 }
 
 export async function waitForDeviceApproval({
   authBaseUrl,
+  apiBaseUrl,
   deviceCode,
   expiresIn,
   fetchImpl = fetch,
@@ -92,7 +93,7 @@ export async function waitForDeviceApproval({
 
   while (Date.now() < deadline) {
     await sleep(pollIntervalMs);
-    const data = await pollDeviceFlow({ authBaseUrl, deviceCode, fetchImpl });
+    const data = await pollDeviceFlow({ apiBaseUrl, authBaseUrl, deviceCode, fetchImpl });
     const status = pickString(data, "status") || "pending";
 
     if (status === "pending") {
@@ -110,6 +111,7 @@ export async function waitForDeviceApproval({
 
       return {
         accessToken: token,
+        apiBaseUrl: apiBaseUrl || authBaseUrl,
         authBaseUrl,
         tokenType: pickString(data, "tokenType", "token_type") || "bearer",
         user: {

package/vendor/capabilities/capabilities/clusters.d.ts

@@ -0,0 +1,2 @@
+export declare const slurmCapabilities: import("../capability.ts").Capability<unknown, unknown>[];
+export declare const kubernetesCapabilities: import("../capability.ts").Capability<unknown, unknown>[];

package/vendor/capabilities/capabilities/clusters.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { defineCapability } from "../capability.js";
+const reservationInput = z.object({
+    reservation_id: z.string().min(1),
+    reservationId: z.string().optional(),
+});
+const launchInput = reservationInput.extend({
+    network_mode: z.enum(["public", "private"]).optional(),
+    node_count: z.number().int().positive().optional(),
+    node_ids: z.array(z.string()).optional(),
+});
+function reservationId(input) {
+    return (input.reservation_id || input.reservationId || "").trim();
+}
+function clusterPath(kind, id, suffix) {
+    return `/${kind}/reservations/${encodeURIComponent(id)}/${suffix}`;
+}
+function clusterPair(kind, domain) {
+    const label = kind === "slurm" ? "Slurm" : "Kubernetes";
+    return [
+        defineCapability({
+            id: `${kind}.eligible`,
+            domain,
+            roles: ["user"],
+            description: `${label} launch is blocked only when the reservation's nodes already belong to a different controller. Returns eligible=false with reason other_cluster in that case.`,
+            mutation: "read",
+            http: { method: "GET", path: `/${kind}/reservations/{id}/cluster/eligible` },
+            input: reservationInput,
+            execute: async (ctx, input) => {
+                const parsed = reservationInput.parse(input);
+                return ctx.fetch(clusterPath(kind, reservationId(parsed), "cluster/eligible"), {
+                    method: "GET",
+                });
+            },
+        }),
+        defineCapability({
+            id: `${kind}.launch`,
+            domain,
+            roles: ["user"],
+            description: `Launch a ${label} controller on a reservation. Blocked when ${kind}.eligible reports other_cluster.`,
+            mutation: "preview-confirm",
+            http: { method: "POST", path: `/${kind}/reservations/{id}/cluster/launch` },
+            input: launchInput,
+            execute: async (ctx, input) => {
+                const parsed = launchInput.parse(input);
+                const id = reservationId(parsed);
+                const eligibility = (await ctx.fetch(clusterPath(kind, id, "cluster/eligible"), {
+                    method: "GET",
+                }));
+                if (eligibility?.eligible === false && eligibility.reason === "other_cluster") {
+                    return { ok: false, error: "other_cluster", reason: "other_cluster" };
+                }
+                if (!ctx.confirmed) {
+                    return { ok: true, action: `${kind}.launch`, reservation_id: id };
+                }
+                return ctx.fetch(clusterPath(kind, id, "cluster/launch"), {
+                    method: "POST",
+                    body: {
+                        network_mode: parsed.network_mode ?? "public",
+                        ...(parsed.node_count != null ? { node_count: parsed.node_count } : {}),
+                        ...(parsed.node_ids?.length ? { node_ids: parsed.node_ids } : {}),
+                    },
+                });
+            },
+        }),
+        defineCapability({
+            id: `${kind}.teardown`,
+            domain,
+            roles: ["user"],
+            description: `Tear down the ${label} controller for a reservation.`,
+            mutation: "preview-confirm",
+            http: { method: "POST", path: `/${kind}/reservations/{id}/cluster/teardown` },
+            input: reservationInput,
+            execute: async (ctx, input) => {
+                const parsed = reservationInput.parse(input);
+                const id = reservationId(parsed);
+                if (!ctx.confirmed) {
+                    return { ok: true, action: `${kind}.teardown`, reservation_id: id };
+                }
+                return ctx.fetch(clusterPath(kind, id, "cluster/teardown"), { method: "POST" });
+            },
+        }),
+        defineCapability({
+            id: `${kind}.show`,
+            domain,
+            roles: ["user"],
+            description: `Show the ${label} controller for a reservation.`,
+            mutation: "read",
+            http: { method: "GET", path: `/${kind}/reservations/{id}/cluster` },
+            input: reservationInput,
+            execute: async (ctx, input) => {
+                const parsed = reservationInput.parse(input);
+                return ctx.fetch(clusterPath(kind, reservationId(parsed), "cluster"), { method: "GET" });
+            },
+        }),
+    ];
+}
+export const slurmCapabilities = clusterPair("slurm", "slurm");
+export const kubernetesCapabilities = clusterPair("kubernetes", "kubernetes");

package/vendor/capabilities/capabilities/fleet.d.ts

@@ -0,0 +1,5 @@
+export declare const listOperatorsCapability: import("../capability.ts").Capability<unknown, unknown>;
+export declare const listFacilitiesCapability: import("../capability.ts").Capability<unknown, unknown>;
+export declare const listNodesCapability: import("../capability.ts").Capability<unknown, unknown>;
+export declare const nodesConsoleCapability: import("../capability.ts").Capability<unknown, unknown>;
+export declare const fleetCapabilities: import("../capability.ts").Capability<unknown, unknown>[];

package/vendor/capabilities/capabilities/fleet.js

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import { defineCapability } from "../capability.js";
+function queryPath(path, params) {
+    const parts = [];
+    for (const [key, value] of Object.entries(params)) {
+        if (value?.trim())
+            parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(value.trim())}`);
+    }
+    return parts.length ? `${path}?${parts.join("&")}` : path;
+}
+const emptyInput = z.object({});
+const facilitiesInput = z.object({
+    operator_id: z.string().optional(),
+    operator: z.string().optional(),
+});
+const nodesInput = z.object({
+    operator_id: z.string().optional(),
+    operatorId: z.string().optional(),
+    operator: z.string().optional(),
+    facility_id: z.string().optional(),
+    facilityId: z.string().optional(),
+    status: z.string().optional(),
+    email: z.string().optional(),
+});
+const consoleInput = z.object({
+    node_id: z.string().min(1),
+    nodeId: z.string().optional(),
+});
+export const listOperatorsCapability = defineCapability({
+    id: "operator.list",
+    domain: "fleet",
+    roles: ["reviewer", "admin"],
+    description: "List GPU operators (id, slug, display name, status). Resolve operator names with this before nodes.list.",
+    mutation: "read",
+    http: { method: "GET", path: "/provisioning/operators" },
+    slack: { parameters: { type: "object", properties: {} } },
+    input: emptyInput,
+    execute: async (ctx) => ctx.fetch("/provisioning/operators", { method: "GET" }),
+});
+export const listFacilitiesCapability = defineCapability({
+    id: "facilities.list",
+    domain: "fleet",
+    roles: ["reviewer", "admin"],
+    description: "List facilities (id, display name, region, operator). Optional operator_id filter. Resolve facility names with this before nodes.list.",
+    mutation: "read",
+    http: { method: "GET", path: "/provisioning/facilities" },
+    slack: {
+        parameters: {
+            type: "object",
+            properties: {
+                operator_id: { type: "string", description: "Commerce operator UUID." },
+            },
+        },
+    },
+    input: facilitiesInput,
+    execute: async (ctx, input) => {
+        const parsed = facilitiesInput.parse(input);
+        return ctx.fetch(queryPath("/provisioning/facilities", {
+            operator_id: parsed.operator_id ?? parsed.operator,
+        }), { method: "GET" });
+    },
+});
+export const listNodesCapability = defineCapability({
+    id: "nodes.list",
+    domain: "fleet",
+    roles: ["user", "reviewer", "admin"],
+    description: "List nodes. Users see their own reserved machines. Reviewers and admins see enrolled, ghost, and off-grid nodes. Optional email lists nodes for that user's organizations. Optional operator_id, facility_id, and status (ghost, off-grid, bare-metal). Never invent nodes. Never print private keys.",
+    mutation: "read",
+    http: { method: "GET", path: "/internal/nodes" },
+    slack: {
+        parameters: {
+            type: "object",
+            properties: {
+                operator_id: { type: "string", description: "Commerce operator UUID from operator.list." },
+                facility_id: { type: "string", description: "Commerce facility UUID from facilities.list." },
+                email: { type: "string", description: "List nodes for this user's organizations." },
+                status: {
+                    type: "string",
+                    enum: ["ghost", "off-grid", "bare-metal"],
+                    description: "Optional orchestrator status filter. Default is all statuses.",
+                },
+            },
+        },
+    },
+    input: nodesInput,
+    execute: async (ctx, input) => {
+        const parsed = nodesInput.parse(input);
+        if (ctx.role === "user") {
+            return ctx.fetch("/nodes", { method: "GET" });
+        }
+        return ctx.fetch(queryPath("/internal/nodes", {
+            operator_id: parsed.operator_id ?? parsed.operatorId ?? parsed.operator,
+            facility_id: parsed.facility_id ?? parsed.facilityId,
+            status: parsed.status,
+            email: parsed.email,
+        }), { method: "GET" });
+    },
+});
+export const nodesConsoleCapability = defineCapability({
+    id: "nodes.console",
+    domain: "fleet",
+    roles: ["user", "reviewer", "admin"],
+    description: "Open an authenticated WebSocket into the node's real host shell (PTY), not ssh(1) and not the agent packet bus. Returns a short-lived wss URL plus ticket. CLI attaches an interactive TTY. MCP and Slack return a command loop over the same socket.",
+    mutation: "read",
+    http: { method: "POST", path: "/v1/nodes/{id}/console" },
+    slack: {
+        parameters: {
+            type: "object",
+            properties: {
+                node_id: { type: "string", description: "Node UUID from nodes.list." },
+            },
+            required: ["node_id"],
+        },
+    },
+    input: consoleInput,
+    execute: async (ctx, input) => {
+        const parsed = consoleInput.parse(input);
+        const id = (parsed.node_id || parsed.nodeId || "").trim();
+        return ctx.fetch(`/v1/nodes/${encodeURIComponent(id)}/console`, {
+            method: "POST",
+            body: { node_id: id },
+        });
+    },
+});
+export const fleetCapabilities = [
+    listOperatorsCapability,
+    listFacilitiesCapability,
+    listNodesCapability,
+    nodesConsoleCapability,
+];

package/vendor/capabilities/capabilities/identity.d.ts

@@ -0,0 +1,3 @@
+export declare const whoamiCapability: import("../capability.ts").Capability<unknown, unknown>;
+export declare const statusCapability: import("../capability.ts").Capability<unknown, unknown>;
+export declare const identityCapabilities: import("../capability.ts").Capability<unknown, unknown>[];

package/vendor/capabilities/capabilities/identity.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { defineCapability } from "../capability.js";
+const emptyInput = z.object({});
+export const whoamiCapability = defineCapability({
+    id: "identity.whoami",
+    domain: "identity",
+    roles: ["user", "reviewer", "admin"],
+    description: "Show the signed-in Ornn user and organization.",
+    mutation: "read",
+    http: { method: "GET", path: "/v1/cli/session" },
+    input: emptyInput,
+    execute: async (ctx) => ctx.fetch("/v1/cli/session", { method: "GET" }),
+});
+export const statusCapability = defineCapability({
+    id: "identity.status",
+    domain: "identity",
+    roles: ["user", "reviewer", "admin"],
+    description: "Show Ornn platform status.",
+    mutation: "read",
+    http: { method: "GET", path: "/v1/cli/status" },
+    input: emptyInput,
+    execute: async (ctx) => ctx.fetch("/v1/cli/status", { method: "GET" }),
+});
+export const identityCapabilities = [whoamiCapability, statusCapability];

package/vendor/capabilities/capabilities/listings.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+export declare const listingCreateInput: z.ZodObject<{
+    kind: z.ZodOptional<z.ZodEnum<{
+        link: "link";
+        gpu: "gpu";
+        cpu: "cpu";
+        node: "node";
+    }>>;
+    gpu: z.ZodOptional<z.ZodString>;
+    cpu: z.ZodOptional<z.ZodString>;
+    site: z.ZodOptional<z.ZodString>;
+    fabric: z.ZodOptional<z.ZodString>;
+    min_nodes: z.ZodOptional<z.ZodNumber>;
+    starts_after: z.ZodOptional<z.ZodString>;
+    starts_before: z.ZodOptional<z.ZodString>;
+    ends_after: z.ZodOptional<z.ZodString>;
+    ends_before: z.ZodOptional<z.ZodString>;
+    gpu_type: z.ZodOptional<z.ZodString>;
+    node_model: z.ZodOptional<z.ZodString>;
+    fabric_type: z.ZodOptional<z.ZodString>;
+    node_count: z.ZodOptional<z.ZodNumber>;
+    gpus_per_node: z.ZodOptional<z.ZodNumber>;
+    site_nickname: z.ZodOptional<z.ZodString>;
+    site_operator: z.ZodOptional<z.ZodString>;
+    ram: z.ZodOptional<z.ZodString>;
+    storage: z.ZodOptional<z.ZodString>;
+    internet: z.ZodOptional<z.ZodString>;
+    network_hardware: z.ZodOptional<z.ZodString>;
+    available_start_at: z.ZodOptional<z.ZodString>;
+    available_end_at: z.ZodOptional<z.ZodString>;
+    available_from: z.ZodOptional<z.ZodString>;
+    available_to: z.ZodOptional<z.ZodString>;
+    buy_now_price_per_gpu_hour: z.ZodOptional<z.ZodNumber>;
+    cost_per_gpu_hour: z.ZodOptional<z.ZodNumber>;
+    deposit_percent: z.ZodOptional<z.ZodNumber>;
+    price_omitted: z.ZodOptional<z.ZodBoolean>;
+    announce: z.ZodOptional<z.ZodBoolean>;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const listCatalogTermsCapability: import("../capability.ts").Capability<unknown, unknown>;
+export declare const listListingsCapability: import("../capability.ts").Capability<unknown, unknown>;
+export declare const createListingCapability: import("../capability.ts").Capability<unknown, unknown>;
+export declare const listingCapabilities: import("../capability.ts").Capability<unknown, unknown>[];
+/** @deprecated Use createListingCapability. */
+export declare const proposeListingCapability: import("../capability.ts").Capability<unknown, unknown>;

package/vendor/capabilities/capabilities/listings.js

@@ -0,0 +1,161 @@
+import { z } from "zod";
+import { defineCapability } from "../capability.js";
+import { bindHardwareFields, HARDWARE_LISTING_FIELDS, HARDWARE_LISTING_FILTERS, loadHardwareCatalog, projectCatalogTerms, } from "../spec-catalog.js";
+export const listingCreateInput = z.object({
+    kind: z.enum(["gpu", "cpu", "node", "link"]).optional(),
+    gpu: z.string().optional(),
+    cpu: z.string().optional(),
+    site: z.string().optional(),
+    fabric: z.string().optional(),
+    min_nodes: z.number().int().optional(),
+    starts_after: z.string().optional(),
+    starts_before: z.string().optional(),
+    ends_after: z.string().optional(),
+    ends_before: z.string().optional(),
+    gpu_type: z.string().optional(),
+    node_model: z.string().optional(),
+    fabric_type: z.string().optional(),
+    node_count: z.number().int().optional(),
+    gpus_per_node: z.number().int().optional(),
+    site_nickname: z.string().optional(),
+    site_operator: z.string().optional(),
+    ram: z.string().optional(),
+    storage: z.string().optional(),
+    internet: z.string().optional(),
+    network_hardware: z.string().optional(),
+    available_start_at: z.string().optional(),
+    available_end_at: z.string().optional(),
+    available_from: z.string().optional(),
+    available_to: z.string().optional(),
+    buy_now_price_per_gpu_hour: z.number().optional(),
+    cost_per_gpu_hour: z.number().optional(),
+    deposit_percent: z.number().optional(),
+    price_omitted: z.boolean().optional(),
+    announce: z.boolean().optional(),
+    text: z.string().optional(),
+});
+const catalogTermsInput = z.object({ kind: z.enum(["gpu", "cpu", "node", "link"]).optional() });
+const slackListingCreateParams = {
+    type: "object",
+    properties: {
+        gpu_type: { type: "string" },
+        cpu: { type: "string" },
+        node_model: { type: "string" },
+        fabric_type: { type: "string" },
+        node_count: { type: "integer" },
+        gpus_per_node: { type: "integer" },
+        site_nickname: { type: "string" },
+        site_operator: { type: "string" },
+        ram: { type: "string" },
+        storage: { type: "string" },
+        available_start_at: { type: "string" },
+        available_end_at: { type: "string" },
+        buy_now_price_per_gpu_hour: { type: "number" },
+        cost_per_gpu_hour: { type: "number" },
+        deposit_percent: { type: "number" },
+        price_omitted: { type: "boolean" },
+        announce: { type: "boolean" },
+        text: { type: "string" },
+    },
+};
+export const listCatalogTermsCapability = defineCapability({
+    id: "listings.catalog_terms",
+    domain: "listings",
+    roles: ["reviewer", "admin"],
+    description: "Dump the orchestrator hardware dictionary (display name + aliases). Call once and pick from it. Hardware fields on listings must match a term. Optional kind filter: gpu, cpu, node, or link.",
+    mutation: "read",
+    http: { method: "GET", path: "/v1/orchestrator/catalog" },
+    slack: {
+        parameters: {
+            type: "object",
+            properties: {
+                kind: { type: "string", enum: ["gpu", "cpu", "node", "link"] },
+            },
+        },
+    },
+    input: catalogTermsInput,
+    execute: async (ctx, input) => {
+        const parsed = catalogTermsInput.parse(input);
+        const hardware = await loadHardwareCatalog(ctx.fetch);
+        return projectCatalogTerms(hardware.terms, parsed.kind);
+    },
+});
+export const listListingsCapability = defineCapability({
+    id: "listings.available",
+    domain: "listings",
+    roles: ["reviewer", "admin"],
+    description: "List currently available marketplace listings. GPU, CPU, and fabric filters must be orchestrator catalog display names, canonicals, or aliases — not raw slang or spec-sheet text. Site may be a facility nickname. Returns spec-shaped JSON plus public reserve/OG/PDF URLs. Filters combine as AND. Date filters are inclusive YYYY-MM-DD.",
+    mutation: "read",
+    slack: {
+        parameters: {
+            type: "object",
+            properties: {
+                gpu: { type: "string", description: "Catalog GPU term such as H100 or NVIDIA H100." },
+                cpu: { type: "string", description: "Catalog CPU term such as Xeon or EPYC." },
+                site: { type: "string", description: "Location / facility filter such as Dallas." },
+                fabric: { type: "string", description: "Catalog link term such as XDR or NDR." },
+                min_nodes: { type: "integer", description: "Minimum total nodes." },
+                starts_after: {
+                    type: "string",
+                    description: "YYYY-MM-DD. Keep listings that start on or after this date.",
+                },
+                starts_before: {
+                    type: "string",
+                    description: "YYYY-MM-DD. Keep listings that start on or before this date.",
+                },
+                ends_after: {
+                    type: "string",
+                    description: "YYYY-MM-DD. Keep listings that end on or after this date.",
+                },
+                ends_before: {
+                    type: "string",
+                    description: "YYYY-MM-DD. Keep listings that end on or before this date.",
+                },
+            },
+        },
+    },
+    input: listingCreateInput,
+    execute: async (ctx, input) => {
+        const parsed = listingCreateInput.parse(input);
+        const hardware = await loadHardwareCatalog(ctx.fetch);
+        const bound = bindHardwareFields(hardware.terms, parsed, HARDWARE_LISTING_FILTERS);
+        if (!bound.ok)
+            return bound;
+        return ctx.fetch("/listings/available", { method: "GET", body: bound.payload });
+    },
+});
+export const createListingCapability = defineCapability({
+    id: "listings.create",
+    domain: "listings",
+    roles: ["reviewer", "admin"],
+    description: "Create a marketplace listing. gpu_type, cpu, node_model, and fabric_type must exact-match an orchestrator catalog display name, canonical, or alias. CLI asks y/N. Slack never POSTs until a human replies confirm. MCP creates on this tool call.",
+    mutation: "preview-confirm",
+    http: { method: "POST", path: "/inventory" },
+    slack: { parameters: slackListingCreateParams },
+    input: listingCreateInput,
+    execute: async (ctx, input) => {
+        const parsed = listingCreateInput.parse(input);
+        const hardware = await loadHardwareCatalog(ctx.fetch);
+        const { gpu, fabric, ...rest } = parsed;
+        const normalized = {
+            ...rest,
+            gpu_type: parsed.gpu_type ?? gpu,
+            fabric_type: parsed.fabric_type ?? fabric,
+        };
+        const bound = bindHardwareFields(hardware.terms, normalized, HARDWARE_LISTING_FIELDS);
+        if (!bound.ok)
+            return bound;
+        const payload = { backing_mode: "forward", ...bound.payload };
+        if (!ctx.confirmed) {
+            return { ok: true, action: "create_listing", payload };
+        }
+        return ctx.fetch("/inventory", { method: "POST", body: payload });
+    },
+});
+export const listingCapabilities = [
+    listCatalogTermsCapability,
+    listListingsCapability,
+    createListingCapability,
+];
+/** @deprecated Use createListingCapability. */
+export const proposeListingCapability = createListingCapability;

package/vendor/capabilities/capabilities/users.d.ts

@@ -0,0 +1,2 @@
+export declare const usersQueryCapability: import("../capability.ts").Capability<unknown, unknown>;
+export declare const userCapabilities: import("../capability.ts").Capability<unknown, unknown>[];

package/vendor/capabilities/capabilities/users.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { defineCapability } from "../capability.js";
+function queryPath(path, params) {
+    const parts = [];
+    for (const [key, value] of Object.entries(params)) {
+        if (value?.trim())
+            parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(value.trim())}`);
+    }
+    return parts.length ? `${path}?${parts.join("&")}` : path;
+}
+const usersQueryInput = z.object({
+    name: z.string().optional(),
+    email: z.string().optional(),
+    organization: z.string().optional(),
+    q: z.string().optional(),
+    max: z.number().int().positive().max(1000).optional(),
+    limit: z.number().int().positive().max(1000).optional(),
+});
+export const usersQueryCapability = defineCapability({
+    id: "users.query",
+    domain: "users",
+    roles: ["admin"],
+    description: "Admin-only directory search. Filter by name, email, or organization. Optional max (default 100, cap 1000). Returns matching users and organizations.",
+    mutation: "read",
+    http: { method: "GET", path: "/internal/users" },
+    slack: {
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                email: { type: "string" },
+                organization: { type: "string" },
+                max: { type: "integer", description: "Maximum rows to return (1-1000)." },
+            },
+        },
+    },
+    input: usersQueryInput,
+    execute: async (ctx, input) => {
+        const parsed = usersQueryInput.parse(input);
+        const q = [parsed.q, parsed.name, parsed.email, parsed.organization].find((value) => value?.trim());
+        return ctx.fetch(queryPath("/internal/users", {
+            q,
+            email: parsed.email,
+            organization: parsed.organization,
+            limit: String(parsed.max ?? parsed.limit ?? 100),
+        }), { method: "GET" });
+    },
+});
+export const userCapabilities = [usersQueryCapability];

package/vendor/capabilities/capability.d.ts

@@ -0,0 +1,61 @@
+import type { ZodType } from "zod";
+import type { ClientKind, Role } from "./role.ts";
+export declare const DOMAINS: readonly ["identity", "listings", "fleet", "users", "reservations", "bids", "access", "clusters", "slurm", "kubernetes", "networks", "storage", "vpn", "billing"];
+export type Domain = (typeof DOMAINS)[number];
+export type Mutation = "read" | "preview-confirm" | "local";
+export type HttpSpec = {
+    method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+    path: string;
+};
+export type CapabilityTransport = (path: string, init?: {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}) => Promise<unknown>;
+export type CapabilityContext = {
+    actor: string;
+    role: Role;
+    fetch: CapabilityTransport;
+    /** Human (or MCP) confirmed a preview-confirm mutation. Execute never POSTs without this. */
+    confirmed?: boolean;
+};
+export type JsonSchema = {
+    type: "object";
+    properties?: Record<string, unknown>;
+    required?: string[];
+};
+export type CapabilityBindings = {
+    cli?: {
+        command: string[];
+    };
+    mcp?: {
+        name: string;
+    };
+    slack?: {
+        name: string;
+        parameters?: JsonSchema;
+    };
+};
+export type Capability<I = unknown, O = unknown> = CapabilityBindings & {
+    id: string;
+    domain: Domain;
+    roles: readonly Role[];
+    description: string;
+    mutation: Mutation;
+    http?: HttpSpec;
+    input: ZodType<I>;
+    execute: (ctx: CapabilityContext, input: I) => Promise<O>;
+};
+export type CapabilitySpec<I = unknown, O = unknown> = Omit<Capability<I, O>, "cli" | "mcp" | "slack"> & {
+    slack?: {
+        parameters?: JsonSchema;
+    };
+};
+/** Fill CLI/MCP/Slack names from `id`. Slack parameters stay optional. */
+export declare function defineCapability<I, O>(spec: CapabilitySpec<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[];
+export declare function byMcpName(catalog: readonly Capability[], name: string): Capability | undefined;
+export declare function bySlackName(catalog: readonly Capability[], name: string): Capability | undefined;
+export declare function byCliCommand(catalog: readonly Capability[], command: string[]): Capability | undefined;