@labelbox/horizon-cli 0.0.0-stage → 0.0.1

package/dist/compute-session.js

@@ -0,0 +1,373 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+import { z } from 'zod';
+import { supportUrl } from './manifest.js';
+import { gatedSummary, missingRequiredPermission, permissionDeniedMessage, permissionHelpNote, UNAVAILABLE_HELP_GROUP, } from './permissions.js';
+import { resolveCommandAuth } from './resolve.js';
+// ── bespoke `horizon computes open/tools` commands (hand-written, not spec-derived) ──
+//
+// `computes mint-access-session` stops at the redemption URL. Turning that into a
+// usable session means issuing a second request purely to capture a `Set-Cookie`
+// off a 302 — a header-shaped result the manifest-driven dispatch loop (JSON in,
+// JSON out) has no way to express. Hence a hand-written command, same as `skills`.
+//
+// The mint→redeem flow, its origin binding, and its cookie parsing are a port of
+// `proxyUrlFromRedemption` / `redeemComputeSession` in `tools/dx/src/commands/devbox.ts`.
+// `tools/dx` is a dev tool and this is a published package, so the code cannot be
+// shared; the safeguards are kept identical on purpose, and a change to either
+// should be mirrored.
+/** The only credential the compute edge's ingress accepts, set on redemption. */
+const SESSION_COOKIE_NAME = '__Secure-compute_session';
+/**
+ * The session cookie in a `Set-Cookie` header, anchored at the header's start and
+ * requiring at least one character of value.
+ *
+ * Anchoring is what `split(';')` parsing cannot do: it would also match the edge's
+ * *deletion* cookie (`__Secure-compute_session=; Max-Age=0`) and hand back a
+ * perfectly-formatted empty credential. Built from `SESSION_COOKIE_NAME` (which
+ * contains no regex metacharacters) so a rename cannot leave the two disagreeing.
+ */
+const SESSION_COOKIE_PATTERN = new RegExp(`^${SESSION_COOKIE_NAME}=([^;\\r\\n]+)(?:;|$)`, 'u');
+/** The permission `POST /computes/:id/access/sessions` requires — the one the
+ *  mint call would 403 on. Declared here because a hand-written command has no
+ *  manifest entry to read `requiredPermissions` from. */
+const COMPUTES_ACCESS_PERMISSION = 'computes:access';
+// Bound both hops for the same reason as every other fetch in this package
+// (dispatch.ts, manifest.ts, permissions.ts, skills.ts): a server that accepts the
+// connection but never answers would otherwise hang the CLI forever. It matters
+// more here than elsewhere — the redemption URL is single-use, so a hang burns it
+// permanently rather than merely stalling.
+const SESSION_FETCH_TIMEOUT_MS = 30_000;
+/** Mirrors `ComputeAccessSessionDto`; `mintAccessSession`'s 201 body. */
+const AccessSessionSchema = z.object({
+    // Mirrors the DTO's own `z.string().url()`; `redemptionUrlExpiresAt` is an
+    // undecorated string there too, so it stays one here — the mirror has to stay
+    // truthful, and claiming a format the server never promised would be a lie the
+    // parser enforces.
+    redemptionUrl: z.url(),
+    redemptionUrlExpiresAt: z.string(),
+});
+export const SESSION_FORMATS = ['header-file', 'claude-code', 'json', 'cookie'];
+/** The default, and the reason it is the default: every other format puts a
+ *  bearer-equivalent credential somewhere durable. */
+export const DEFAULT_SESSION_FORMAT = 'header-file';
+/**
+ * Bind the redemption origin **before** anything is sent to it.
+ *
+ * The redemption URL comes back over the wire, and the next thing the CLI does is
+ * make a request to it — so it is untrusted input on the way in and a request
+ * target on the way out. Everything downstream (the MCP endpoint, the cookie's
+ * eventual destination) is derived from this origin, which makes a bad one a
+ * credential-exfiltration primitive rather than a cosmetic error.
+ *
+ * Port of `proxyUrlFromRedemption` (devbox.ts): TLS only, no userinfo (which would
+ * let `https://c-<id>@attacker.example/` read as the expected host), a hostname
+ * that *starts with* `c-<computeId>.` and is strictly longer than that prefix (so
+ * the compute the caller named is the compute the session is for, and a bare
+ * `c-<id>.` with no domain is refused), and the exact redemption pathname.
+ */
+export function redemptionOrigin(redemptionUrl, computeId) {
+    let parsed;
+    try {
+        parsed = new URL(redemptionUrl);
+    }
+    catch {
+        throw new Error(`the server returned an unparseable redemption URL for compute ${computeId}`);
+    }
+    // `URL` normalises the hostname to lower case, so the expected prefix has to be
+    // normalised too. A UUID is case-insensitive and the schema accepts either, so
+    // an id typed or pasted in upper case mints fine and would then fail this check
+    // — after the single-use URL has already been spent.
+    const expectedPrefix = `c-${computeId.toLowerCase()}.`;
+    if (parsed.protocol !== 'https:' ||
+        parsed.username !== '' ||
+        parsed.password !== '' ||
+        !parsed.hostname.startsWith(expectedPrefix) ||
+        parsed.hostname.length <= expectedPrefix.length ||
+        parsed.pathname !== '/__redeem') {
+        throw new Error(`the server returned an invalid redemption origin for compute ${computeId} — ` +
+            'refusing to send the redemption request.');
+    }
+    return `https://${parsed.host}`;
+}
+/** `POST /v1/computes/:computeId/access/sessions` — mints a short-lived,
+ *  single-use redemption URL for a running compute the caller owns. */
+export async function mintAccessSession(args) {
+    const url = supportUrl(args.baseUrl, `/computes/${encodeURIComponent(args.computeId)}/access/sessions`);
+    const res = await fetch(url, {
+        method: 'POST',
+        // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+        headers: { Authorization: `Bearer ${args.apiKey}` },
+        signal: AbortSignal.timeout(SESSION_FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`could not mint an access session for compute ${args.computeId} — HTTP ${res.status} ${text.slice(0, 200)}`);
+    }
+    const parsed = AccessSessionSchema.safeParse(await res.json());
+    if (!parsed.success) {
+        throw new Error(`unexpected response shape from ${url}`);
+    }
+    return parsed.data;
+}
+/** Redeem a minted URL into the edge session cookie.
+ *
+ *  `computeId` is not decoration: the URL is validated against it *before* the
+ *  request goes out (see `redemptionOrigin`), because sending it is the act that
+ *  would leak.
+ *
+ *  `redirect: 'manual'` is load-bearing: the cookie rides on the 302 itself, and
+ *  following the redirect would consume the only header this request exists to
+ *  read. The URL is single-use and TTL-bounded (60s upstream), so a failure here
+ *  is not retryable with the same URL — mint a fresh one. */
+export async function redeemSession(redemptionUrl, computeId) {
+    redemptionOrigin(redemptionUrl, computeId);
+    const res = await fetch(redemptionUrl, {
+        redirect: 'manual',
+        signal: AbortSignal.timeout(SESSION_FETCH_TIMEOUT_MS),
+    });
+    // A 4xx/5xx is a refusal, not a cookie-less success. Reported by its status,
+    // because "expired, mint another" is the wrong advice for a 403 and sends the
+    // caller into a retry loop against a permission they don't have.
+    if (res.status < 200 || res.status >= 400) {
+        throw new Error(`redeeming the access session for compute ${computeId} failed — HTTP ${res.status}.`);
+    }
+    const value = res.headers
+        .getSetCookie()
+        .map((header) => SESSION_COOKIE_PATTERN.exec(header)?.[1])
+        .find((match) => match !== undefined);
+    if (value === undefined) {
+        throw new Error(`redemption returned HTTP ${res.status} but no session cookie. The URL is single-use ` +
+            'and expires within a minute of minting; mint a new one and redeem it immediately.');
+    }
+    return `${SESSION_COOKIE_NAME}=${value}`;
+}
+/** Mint and redeem in one step, returning everything an MCP client needs. */
+export async function openComputeSession(args) {
+    const minted = await mintAccessSession(args);
+    // Bound before the redemption request is sent, and reused afterwards so the
+    // origin the cookie was fetched from is exactly the origin it will be sent to.
+    const origin = redemptionOrigin(minted.redemptionUrl, args.computeId);
+    const cookie = await redeemSession(minted.redemptionUrl, args.computeId);
+    return {
+        origin,
+        mcpEndpoint: `${origin}/mcp/`,
+        toolsEndpoint: `${origin}/mcp-health/tools`,
+        cookie,
+    };
+}
+/** One tool as the world's MCP server reports it on `/health/tools`.
+ *
+ *  Mirrors `MCPToolHealth` in `worldsim_platform/mcp/server.py`. Only the fields the
+ *  grouped view reads are modelled, and the object is *loose* on purpose: the world
+ *  ships on its own cadence, so a tool gaining a field must neither break enumeration
+ *  nor silently vanish. A stripping object would drop `method`, `path` and
+ *  `example_arguments` — exactly the call-shape fields `--json` exists to carry. */
+const WorldToolSchema = z.looseObject({
+    service: z.string(),
+    name: z.string(),
+    description: z.string().nullish(),
+});
+// `tools` alone is the shape guard — it is what rejects `{ nope: true }`. The
+// server also sends `total_tools`, deliberately not required here: it is never
+// read, and requiring it would let a rename upstream break enumeration for a
+// field nothing depends on.
+const WorldToolsSchema = z.object({ tools: z.array(WorldToolSchema) });
+/** Every tool the world currently serves.
+ *
+ *  This is the post-allowlist set: the MCP server filters by `WORLDSIM_MCP_TOOLS_FILE`
+ *  before registering, so it answers what an agent in this world can actually call,
+ *  not what the bake could expose. The bake's full catalogue is a different question,
+ *  answered by `run-config-versions discover-mcp-tools`.
+ *
+ *  Plain JSON over the same session cookie as `/mcp/` — no MCP handshake, so no
+ *  `initialize` round-trip and no JSON-RPC pagination to unroll. */
+export async function fetchWorldTools(session) {
+    const res = await fetch(session.toolsEndpoint, {
+        // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+        headers: { Cookie: session.cookie },
+        signal: AbortSignal.timeout(SESSION_FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        throw new Error(`could not list tools at ${session.toolsEndpoint} — HTTP ${res.status}. A running ` +
+            'compute serves this only once its MCP service is up; check `computes get` for status.');
+    }
+    const parsed = WorldToolsSchema.safeParse(await res.json());
+    if (!parsed.success) {
+        throw new Error(`unexpected tool-listing shape from ${session.toolsEndpoint}`);
+    }
+    return parsed.data.tools;
+}
+/** Group by service, because a world's tools are namespaced by the service that
+ *  backs them (`gitea.create_user`) and a flat list of 200 hides that structure. */
+export function formatWorldTools(tools) {
+    if (tools.length === 0)
+        return 'This world serves no MCP tools.\n';
+    const byService = new Map();
+    for (const tool of tools) {
+        const existing = byService.get(tool.service);
+        if (existing === undefined)
+            byService.set(tool.service, [tool]);
+        else
+            existing.push(tool);
+    }
+    const services = [...byService.entries()].sort(([a], [b]) => a.localeCompare(b));
+    const plural = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
+    const lines = [
+        `${plural(tools.length, 'tool')} across ${plural(services.length, 'service')}\n`,
+    ];
+    for (const [service, serviceTools] of services) {
+        lines.push(`${service} (${serviceTools.length})`);
+        for (const tool of [...serviceTools].sort((a, b) => a.name.localeCompare(b.name))) {
+            const description = tool.description?.split('\n')[0]?.trim();
+            lines.push(`  ${tool.name}${description ? `  — ${description}` : ''}`);
+        }
+        lines.push('');
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+/** Single-quote for a POSIX shell, closing the quote around each embedded quote. */
+function shellQuote(value) {
+    return `'${value.replace(/'/gu, "'\\''")}'`;
+}
+/**
+ * The MCP server name a compute registers under when `--name` isn't given.
+ *
+ * A compute is a generic remote machine — `tools/dx devbox` runs devboxes on the
+ * same primitive — so the name is derived from the compute rather than from any
+ * one workload that happens to run on it. Derived rather than fixed so two open
+ * computes don't collide under one name in the client's config.
+ */
+export function defaultServerName(computeId) {
+    return `compute-${computeId.replace(/[^A-Za-z0-9._-]/gu, '-')}`;
+}
+/** MCP client configs key servers by this name; keep it to what every client and
+ *  the shell agree is one bare word. */
+const SERVER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+export function parseServerName(value) {
+    if (!SERVER_NAME_PATTERN.test(value)) {
+        throw new Error(`invalid --name "${value}" — use letters, digits, ".", "_" or "-", starting with a letter or digit`);
+    }
+    return value;
+}
+/**
+ * Write the `Cookie:` request header to a file only the current user can read,
+ * and return its path.
+ *
+ * In its own `mkdtempSync` directory (mode 0700) rather than a fixed, guessable
+ * path under `tmpdir()`, and with the `wx` flag, which refuses to follow or
+ * overwrite an existing path — the same shape `git-host.ts` uses for its askpass
+ * helper, and for the same local-attacker-pre-plants-a-symlink reason. Unlike that
+ * one, this file *is* the secret, hence 0600.
+ */
+export function writeSessionHeaderFile(session) {
+    const dir = mkdtempSync(join(tmpdir(), 'horizon-compute-session-'));
+    const path = join(dir, 'headers.txt');
+    writeFileSync(path, `Cookie: ${session.cookie}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    return path;
+}
+// Exhaustive by construction: a new SessionFormat that isn't handled fails to
+// typecheck here rather than falling through to a default branch at runtime.
+const FORMATTERS = {
+    // The default. The cookie is bearer-equivalent, so it goes to a 0600 file and
+    // the command interpolates it at run time: nothing here reaches `~/.zsh_history`
+    // or a `ps` listing, which is what every other format cannot avoid. Mirrors
+    // devbox's `--http-headers-file`, whose test asserts argv never carries a cookie.
+    'header-file': ({ session, serverName }) => {
+        const path = writeSessionHeaderFile(session);
+        return (`# Session header written to ${path} (mode 0600). Delete it when you're done.\n` +
+            `claude mcp add --transport http ${serverName} ${shellQuote(session.mcpEndpoint)} ` +
+            `--header "$(cat ${shellQuote(path)})"\n` +
+            `# List every tool this world serves:\n` +
+            `# curl -sS -H "$(cat ${shellQuote(path)})" ${shellQuote(session.toolsEndpoint)}\n`);
+    },
+    'claude-code': ({ session, serverName }) => `claude mcp add --transport http ${serverName} ${shellQuote(session.mcpEndpoint)} --header ${shellQuote(`Cookie: ${session.cookie}`)}\n`,
+    json: ({ session, serverName }) => `${JSON.stringify({
+        mcpServers: {
+            [serverName]: {
+                type: 'http',
+                url: session.mcpEndpoint,
+                // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+                headers: { Cookie: session.cookie },
+            },
+        },
+    }, null, 2)}\n`,
+    cookie: ({ session }) => `${session.cookie}\n`,
+};
+export function formatSession(session, format, serverName) {
+    return FORMATTERS[format]({ session, serverName });
+}
+/** Attach `open` and `tools` to the manifest-built `computes` group.
+ *
+ *  Registered after the operation loop, so the group already exists — unless the
+ *  backend serves no compute operations at all, in which case there is nothing to
+ *  attach to and nothing to offer. A name collision means the backend grew its own
+ *  `computes open` or `computes tools`; fail loudly rather than let commander silently shadow one,
+ *  mirroring `claim()` in program.ts.
+ *
+ *  Returns the `computes` group and number of gated commands when they were
+ *  registered in their gated form, so the caller can fold them into that group's
+ *  "N commands require permissions" banner; `undefined` otherwise. */
+export function addComputeSessionCommands(program, helpGroup, granted) {
+    const computes = program.commands.find((command) => command.name() === 'computes');
+    if (computes === undefined)
+        return undefined;
+    for (const name of ['open', 'tools']) {
+        if (computes.commands.some((command) => command.name() === name)) {
+            throw new Error(`the backend spec now defines a "computes ${name}" operation, which collides with the ` +
+                'hand-written one in compute-session.ts — rename one.');
+        }
+    }
+    // The same gate the manifest loop applies to `computes mint-access-session`,
+    // which both commands' first hop *is*. Without it they advertise themselves as
+    // runnable and then die on a raw HTTP 403 from the mint call.
+    const missing = missingRequiredPermission(granted, COMPUTES_ACCESS_PERMISSION);
+    const open = computes
+        .command('open <computeId>')
+        .helpGroup(missing === undefined ? helpGroup : UNAVAILABLE_HELP_GROUP)
+        .description(gatedSummary("Open an MCP session against a running compute's HTTP surface", missing))
+        .addHelpText('after', '\nMints an access session and redeems it, printing connection details for an MCP client.\n' +
+        'The session is bearer-equivalent and expires after roughly an hour; re-run to renew.\n')
+        .option(`--format <${SESSION_FORMATS.join('|')}>`, 'Output shape: a command reading the header from a 0600 file (default), an inline ' +
+        'claude-code command, an mcpServers config, or the bare cookie', DEFAULT_SESSION_FORMAT)
+        // No commander default: the default depends on the `<computeId>` argument,
+        // which is only known at action time, so it is applied there instead.
+        .option('--name <name>', 'MCP server name to register the compute under (default: compute-<computeId>)');
+    if (missing !== undefined)
+        open.addHelpText('after', permissionHelpNote(missing));
+    open.action(async (computeId, opts) => {
+        if (missing !== undefined)
+            throw new Error(permissionDeniedMessage(missing));
+        const format = SESSION_FORMATS.find((candidate) => candidate === opts.format);
+        if (format === undefined) {
+            throw new Error(`unknown --format "${opts.format}" — expected one of ${SESSION_FORMATS.join(', ')}`);
+        }
+        const serverName = opts.name === undefined ? defaultServerName(computeId) : parseServerName(opts.name);
+        const { apiKey, baseUrl } = resolveCommandAuth(program);
+        const session = await openComputeSession({ apiKey, baseUrl, computeId });
+        process.stdout.write(formatSession(session, format, serverName));
+    });
+    const tools = computes
+        .command('tools <computeId>')
+        .helpGroup(missing === undefined ? helpGroup : UNAVAILABLE_HELP_GROUP)
+        .description(gatedSummary('List every MCP tool a running compute serves', missing))
+        .addHelpText('after', '\nOpens a session and enumerates the tools the world currently serves, grouped by\n' +
+        'service. This is the post-allowlist set — what an agent in this world can actually\n' +
+        'call. Use --json to pipe it.\n')
+        .option('--json', 'Emit the raw tool array instead of the grouped summary');
+    if (missing !== undefined)
+        tools.addHelpText('after', permissionHelpNote(missing));
+    tools.action(async (computeId, opts) => {
+        if (missing !== undefined)
+            throw new Error(permissionDeniedMessage(missing));
+        const { apiKey, baseUrl } = resolveCommandAuth(program);
+        const session = await openComputeSession({ apiKey, baseUrl, computeId });
+        const worldTools = await fetchWorldTools(session);
+        process.stdout.write(opts.json === true
+            ? `${JSON.stringify(worldTools, null, 2)}\n`
+            : formatWorldTools(worldTools));
+    });
+    return missing === undefined ? undefined : { parent: computes, gatedCount: 2 };
+}

package/dist/default-base-url.generated.d.ts

@@ -0,0 +1,5 @@
+/**
+ * AUTO-GENERATED by 'yarn generate cli:manifest'.
+ * Do not edit manually — this committed projection only bootstraps the live manifest fetch.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.horizon.labelbox.com";

package/dist/default-base-url.generated.js

@@ -0,0 +1,5 @@
+/**
+ * AUTO-GENERATED by 'yarn generate cli:manifest'.
+ * Do not edit manually — this committed projection only bootstraps the live manifest fetch.
+ */
+export const DEFAULT_BASE_URL = 'https://api.horizon.labelbox.com';

package/dist/dispatch.d.ts

@@ -0,0 +1,40 @@
+import { type ManifestOperation } from './manifest.js';
+export interface DispatchContext {
+    baseUrl: string;
+    apiKey: string;
+    /** Permit binary multipart fields to read local paths. Terminal CLI only. */
+    allowFileInputs?: boolean;
+    /**
+     * Scope headers, sent only when set.
+     *
+     * Some operations require a scope header the body cannot carry: `createCompute`
+     * is `@AllowE2E(requireEnvironmentScope)`, which reads
+     * `X-Environment-External-Id` and 403s without it — the `environmentId` in the
+     * body is the target, not the caller's scope, and does not satisfy it.
+     *
+     * Sent only when supplied because the requirement is per-operation and has a
+     * negative form: `rejectEnvironmentScope` 403s an operation that receives the
+     * header. Always attaching one would trade this failure for its mirror image.
+     */
+    organizationExternalId?: string;
+    environmentExternalId?: string;
+}
+/** The generic operation result; no HTTP semantics are discarded at dispatch. */
+export interface DispatchResponse {
+    readonly data: unknown;
+    readonly status: number;
+    /** Present response headers declared for this status, under their contract names. */
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** Build the full request URL: base + path (params substituted) + query string. */
+export declare function buildUrl(op: ManifestOperation, params: Record<string, unknown>, baseUrl: string): string;
+/**
+ * Build and send the request for one operation, returning its status, declared
+ * headers, and parsed data without collapsing HTTP semantics. Conditional 304 is
+ * successful only when the generated contract declares it. Binary bodies remain
+ * bytes; empty non-JSON text remains an empty string. On an undeclared response the
+ * parsed error body is thrown (so `formatError` prints the server's JSON detail);
+ * `fetch` rejecting for an unreachable server propagates and is mapped to the
+ * standard "could not be reached" message by `formatError`.
+ */
+export declare function dispatchOperation(op: ManifestOperation, params: Record<string, unknown>, ctx: DispatchContext): Promise<DispatchResponse>;