@shardflux/cli 0.1.0

package/dist/commands.js

@@ -0,0 +1,349 @@
+/**
+ * Command implementations. Everything goes through @shardflux/sdk (the same
+ * client, retries, idempotency keys, operation polling and tool-token
+ * management as SDK users get); `cloud.request()` covers the two endpoints
+ * the SDK has no typed method for yet (GET /v1/operations/{id}, usage summary).
+ */
+import { randomUUID } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { SDK_VERSION, ShardfluxApiError } from '@shardflux/sdk';
+import { CLI_VERSION, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
+import { InterruptedError, NotFoundError, UsageError } from "./errors.js";
+import { fileTable, json, kv, operationDetail, operationTable, sessionTable, usageText, workspaceDetail, workspaceTable } from "./format.js";
+const DEFAULT_WAIT_MS = 300_000;
+const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
+const MAX_STDIN = 1024 * 1024;
+const str = (v) => (typeof v === 'string' ? v : undefined);
+function out(ctx, human, machine) {
+    ctx.io.stdout.write(ctx.json ? json(machine) : human);
+}
+function caps(values) {
+    const c = {};
+    const cpu = str(values['cpu-millis']);
+    const mem = str(values['memory-mib']);
+    const disk = str(values['disk-gib']);
+    if (cpu !== undefined)
+        c.cpu_millis = parsePositiveInt(cpu, 'cpu-millis', 1_000_000);
+    if (mem !== undefined)
+        c.memory_mib = parsePositiveInt(mem, 'memory-mib', 16_777_216);
+    if (disk !== undefined)
+        c.disk_gib = parsePositiveInt(disk, 'disk-gib', 1_000_000);
+    return Object.keys(c).length ? c : undefined;
+}
+function waitTimeout(values) {
+    const t = str(values.timeout);
+    return t === undefined ? DEFAULT_WAIT_MS : parseDuration(t, 'timeout');
+}
+/** `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key. */
+export async function resolveWorkspace(ctx, ref) {
+    const cloud = ctx.cloud();
+    if (UUID.test(ref)) {
+        try {
+            return await cloud.workspaces.get(ref);
+        }
+        catch (err) {
+            if (!(err instanceof ShardfluxApiError && err.status === 404))
+                throw err;
+        }
+    }
+    for await (const w of cloud.workspaces.listAll({ keyPrefix: ref, includeDeleted: true, limit: 200 })) {
+        if (w.key === ref)
+            return w;
+        if (ctx.signal.aborted)
+            throw new InterruptedError('interrupted');
+    }
+    throw new NotFoundError(`No workspace with id or key "${ref}" in this project.`);
+}
+/** Waits with the SDK's backoff; Ctrl-C reports the operation that keeps running. */
+async function waitOperation(ctx, operationId, timeoutMs) {
+    try {
+        return await ctx.cloud().workspaces.waitForOperation(operationId, { timeoutMs, signal: ctx.signal });
+    }
+    catch (err) {
+        if (ctx.signal.aborted)
+            throw new InterruptedError(`Interrupted; operation ${operationId} continues server side.`, operationId);
+        throw err;
+    }
+}
+async function getOperation(ctx, operationId) {
+    if (!UUID.test(operationId))
+        throw new UsageError(`<operation-id> must be a UUID (got "${operationId}")`);
+    const body = await ctx.cloud().request('GET', `/v1/operations/${encodeURIComponent(operationId)}`);
+    return body.operation;
+}
+async function readAll(stream, max, what) {
+    const chunks = [];
+    let n = 0;
+    for await (const c of stream) {
+        const b = typeof c === 'string' ? Buffer.from(c) : c;
+        n += b.length;
+        if (n > max)
+            throw new UsageError(`${what} exceeds ${max} bytes`);
+        chunks.push(b);
+    }
+    return new Uint8Array(Buffer.concat(chunks));
+}
+async function readInput(ctx, source, max, what) {
+    if (source === '-') {
+        if (ctx.io.stdin.isTTY)
+            throw new UsageError(`${what}: standard input is a terminal; pipe data in or pass a file`);
+        return readAll(ctx.io.stdin, max, what);
+    }
+    const data = await readFile(source).catch((e) => {
+        throw new UsageError(`${what}: cannot read "${source}" (${e.code ?? e.message})`);
+    });
+    if (data.length > max)
+        throw new UsageError(`${what} exceeds ${max} bytes`);
+    return new Uint8Array(data);
+}
+async function principal(ctx) {
+    const me = await ctx.cloud().me();
+    if (me.type !== 'api_key' || !me.api_key)
+        throw new UsageError('SHARDFLUX_API_KEY did not authenticate as an API key');
+    return {
+        api_url: ctx.apiUrl,
+        organization_id: me.api_key.organization_id,
+        project_id: me.api_key.project_id,
+        api_key: { id: me.api_key.id, key_id: me.api_key.key_id },
+        tool_permissions: me.api_key.tool_permissions,
+    };
+}
+function principalText(p) {
+    return kv([
+        ['api', p.api_url],
+        ['organization', p.organization_id],
+        ['project', p.project_id],
+        ['api key', `${p.api_key.key_id} (${p.api_key.id})`],
+        ['tools', p.tool_permissions.length ? p.tool_permissions.join(', ') : '(none: read-only key)'],
+    ]);
+}
+/** The exit code `shard exec` returns for a finished command. */
+export function execExitCode(r) {
+    if (r.timedOut)
+        return 124;
+    if (typeof r.exitCode === 'number' && r.exitCode >= 0)
+        return Math.min(r.exitCode, 255);
+    if (typeof r.termSignal === 'number' && r.termSignal > 0)
+        return 128 + r.termSignal;
+    return 1;
+}
+async function bestEffortCancel(cell, sessionId) {
+    await Promise.race([cell.exec.cancel(sessionId).catch(() => undefined), new Promise((r) => setTimeout(r, 3_000).unref())]);
+}
+function lifecycleText(verb, w, op) {
+    const finished = op.state === 'succeeded' || op.state === 'failed' || op.state === 'canceled';
+    return `${verb} ${w.key} (${w.id}): operation ${op.id} ${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}\n${finished ? '' : `wait with: shard operations wait ${op.id}\n`}`;
+}
+export const HANDLERS = {
+    async login(ctx) {
+        const p = await principal(ctx);
+        out(ctx, `Authenticated.\n${principalText(p)}shard stores nothing; it reads SHARDFLUX_API_KEY on every run.\n`, p);
+        return 0;
+    },
+    async whoami(ctx) {
+        const p = await principal(ctx);
+        out(ctx, principalText(p), p);
+        return 0;
+    },
+    version(ctx) {
+        out(ctx, `shard ${CLI_VERSION} (@shardflux/sdk ${SDK_VERSION})\n`, { cli: CLI_VERSION, sdk: SDK_VERSION });
+        return Promise.resolve(0);
+    },
+    async usage(ctx, values) {
+        const org = str(values.org) ?? (await principal(ctx)).organization_id;
+        if (!UUID.test(org))
+            throw new UsageError(`--org must be an organization id (UUID)`);
+        const summary = await ctx.cloud().request('GET', `/v1/organizations/${encodeURIComponent(org)}/usage/summary`);
+        out(ctx, usageText(summary), summary);
+        return 0;
+    },
+    async 'workspaces open'(ctx, values, [key]) {
+        const template = str(values.template);
+        if (!template)
+            throw new UsageError('--template <slug> is required for "shard workspaces open"');
+        const c = caps(values);
+        const timeoutMs = waitTimeout(values);
+        const cloud = ctx.cloud();
+        let ws = await cloud.workspaces.open({ key: key, template, ...(c ? { caps: c } : {}), agentLabel: ctx.agentLabel, wait: false });
+        const op = ws.activeOperation;
+        if (values.wait !== false && !ws.ready && op) {
+            await waitOperation(ctx, op.id, timeoutMs);
+            ws = await cloud.workspaces.get(ws.id);
+        }
+        const view = ws.data;
+        const human = ws.ready
+            ? `Workspace ${ws.key} (${ws.id}) is ready.\n${workspaceDetail(view)}`
+            : `Workspace ${ws.key} (${ws.id}) is ${ws.state}${op ? `; operation ${op.id} ${op.kind} ${op.state}` : ''}.\n${op ? `wait with: shard operations wait ${op.id}\n` : ''}`;
+        out(ctx, human, view);
+        return 0;
+    },
+    async 'workspaces list'(ctx, values) {
+        const cloud = ctx.cloud();
+        const state = str(values.state);
+        const prefix = str(values.prefix);
+        const limitText = str(values.limit);
+        const params = {
+            ...(state ? { state: state } : {}),
+            ...(prefix ? { keyPrefix: prefix } : {}),
+            ...(values['include-deleted'] === true ? { includeDeleted: true } : {}),
+            ...(limitText ? { limit: parsePositiveInt(limitText, 'limit', 200) } : {}),
+        };
+        let views = [];
+        let next = null;
+        if (values.all === true) {
+            for await (const w of cloud.workspaces.listAll(params)) {
+                views.push(w.data);
+                if (ctx.signal.aborted)
+                    throw new InterruptedError('Interrupted.');
+            }
+        }
+        else {
+            const cursor = str(values.cursor);
+            const page = await cloud.workspaces.list({ ...params, ...(cursor ? { cursor } : {}) });
+            views = page.data.map((w) => w.data);
+            next = page.nextCursor;
+        }
+        out(ctx, views.length ? workspaceTable(views) : 'No workspaces.\n', { data: views, next_cursor: next });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard workspaces list --cursor ${next}\n`);
+        return 0;
+    },
+    async 'workspaces get'(ctx, _values, [ref]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        out(ctx, workspaceDetail(ws.data), ws.data);
+        return 0;
+    },
+    async 'workspaces exec'(ctx, values, [ref, ...argv]) {
+        const env = parseEnvPairs(values.env ?? []);
+        const timeout = str(values.timeout);
+        const timeoutMs = timeout === undefined ? undefined : parseDuration(timeout, 'timeout');
+        const stdinSource = str(values.stdin);
+        const stdin = stdinSource === undefined ? undefined : await readInput(ctx, stdinSource, MAX_STDIN, '--stdin');
+        const ws = await resolveWorkspace(ctx, ref);
+        const cell = ws.cell({ agentLabel: ctx.agentLabel });
+        const sessionId = `cli-${randomUUID().replace(/-/g, '').slice(0, 24)}`;
+        let r;
+        try {
+            r = await cell.exec.run(argv, {
+                sessionId,
+                ...(str(values.cwd) !== undefined ? { cwd: str(values.cwd) } : {}),
+                ...(Object.keys(env).length ? { env } : {}),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                ...(stdin !== undefined ? { stdin } : {}),
+                maxOutputBytes: ctx.json ? MAX_JSON_OUTPUT : 0,
+                ...(ctx.json ? {} : { onOutput: (stream, chunk) => void (stream === 'stderr' ? ctx.io.stderr : ctx.io.stdout).write(chunk) }),
+                signal: ctx.signal,
+            });
+        }
+        catch (err) {
+            if (ctx.signal.aborted) {
+                await bestEffortCancel(cell, sessionId);
+                throw new InterruptedError(`Interrupted; sent cancel to exec session ${sessionId}.`);
+            }
+            throw err;
+        }
+        const code = execExitCode(r);
+        if (ctx.json) {
+            ctx.io.stdout.write(json({ session_id: r.sessionId, exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, canceled: r.canceled, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, reconnects: r.reconnects }));
+        }
+        return code;
+    },
+    async 'files read'(ctx, values, [ref, path]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const bytes = await ws.cell({ agentLabel: ctx.agentLabel }).files.read(path);
+        const dest = str(values.out);
+        if (dest !== undefined) {
+            await writeFile(dest, bytes);
+            out(ctx, `wrote ${bytes.length} bytes to ${dest}\n`, { path, bytes: bytes.length, out: dest });
+        }
+        else if (ctx.json) {
+            ctx.io.stdout.write(json({ path, bytes: bytes.length, content_base64: Buffer.from(bytes).toString('base64') }));
+        }
+        else {
+            ctx.io.stdout.write(bytes);
+        }
+        return 0;
+    },
+    async 'files write'(ctx, values, [ref, path]) {
+        const data = await readInput(ctx, str(values.from) ?? '-', 1024 * 1024 * 1024, 'input');
+        const ws = await resolveWorkspace(ctx, ref);
+        const r = await ws.cell({ agentLabel: ctx.agentLabel }).files.write(path, data, { append: values.append === true, createParents: values.parents !== false });
+        out(ctx, `wrote ${r.bytes_written} bytes to ${r.path}${r.sha256 ? ` (sha256 ${r.sha256})` : ''}\n`, r);
+        return 0;
+    },
+    async 'files ls'(ctx, values, [ref, path]) {
+        const limitText = str(values.limit);
+        const ws = await resolveWorkspace(ctx, ref);
+        const list = await ws.cell({ agentLabel: ctx.agentLabel }).files.list(path, { limit: limitText ? parsePositiveInt(limitText, 'limit', 10_000) : 1000 });
+        out(ctx, `${fileTable(list)}${list.truncated ? '(truncated)\n' : ''}`, list);
+        return 0;
+    },
+    async 'workspaces suspend'(ctx, values, [ref]) {
+        return lifecycle(ctx, values, ref, 'Suspending', (ws) => ctx.cloud().workspaces.suspend(ws.id));
+    },
+    async 'workspaces resume'(ctx, values, [ref]) {
+        return lifecycle(ctx, values, ref, 'Resuming', (ws) => ctx.cloud().workspaces.resume(ws.id));
+    },
+    async 'workspaces delete'(ctx, values, [ref]) {
+        if (values.yes !== true)
+            throw new UsageError('refusing to delete without --yes (deletion revokes tool access immediately and cannot be undone)');
+        return lifecycle(ctx, values, ref, 'Deleting', (ws) => ctx.cloud().workspaces.delete(ws.id));
+    },
+    async 'workspaces fork'(ctx, values, [ref, newKey]) {
+        const c = caps(values);
+        const timeoutMs = waitTimeout(values);
+        const source = await resolveWorkspace(ctx, ref);
+        const res = await ctx.cloud().workspaces.fork(source.id, { key: newKey, ...(c ? { caps: c } : {}) });
+        let op = res.operation;
+        if (values.wait === true)
+            op = await waitOperation(ctx, op.id, timeoutMs);
+        out(ctx, lifecycleText(`Forking ${source.key} into`, res.workspace, op), { operation: op, workspace: res.workspace.data });
+        return 0;
+    },
+    async 'workspaces sessions'(ctx, _values, [ref]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const sessions = [];
+        let cursor;
+        do {
+            const page = await ctx.cloud().workspaces.agentSessions(ws.id, { limit: 200, ...(cursor ? { cursor } : {}) });
+            sessions.push(...page.data);
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor);
+        out(ctx, sessions.length ? sessionTable(sessions) : 'No agent sessions (no tool token was issued for this workspace yet).\n', { data: sessions });
+        return 0;
+    },
+    async 'operations list'(ctx, values, [ref]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const limitText = str(values.limit);
+        const state = str(values.state);
+        const kind = str(values.kind);
+        const page = await ctx.cloud().workspaces.operations(ws.id, {
+            ...(limitText ? { limit: parsePositiveInt(limitText, 'limit', 200) } : {}),
+            ...(state ? { state: state } : {}),
+            ...(kind ? { kind: kind } : {}),
+        });
+        out(ctx, page.data.length ? operationTable(page.data) : 'No operations.\n', { data: page.data, next_cursor: page.nextCursor });
+        return 0;
+    },
+    async 'operations get'(ctx, _values, [id]) {
+        const op = await getOperation(ctx, id);
+        out(ctx, operationDetail(op), op);
+        return 0;
+    },
+    async 'operations wait'(ctx, values, [id]) {
+        if (!UUID.test(id))
+            throw new UsageError(`<operation-id> must be a UUID (got "${id}")`);
+        const op = await waitOperation(ctx, id, waitTimeout(values));
+        out(ctx, operationDetail(op), op);
+        return 0;
+    },
+};
+async function lifecycle(ctx, values, ref, verb, start) {
+    const timeoutMs = waitTimeout(values);
+    const ws = await resolveWorkspace(ctx, ref);
+    let op = await start(ws);
+    if (values.wait === true)
+        op = await waitOperation(ctx, op.id, timeoutMs);
+    out(ctx, lifecycleText(verb, ws, op), op);
+    return 0;
+}

package/dist/errors.d.ts

@@ -0,0 +1,51 @@
+export declare const EXIT: {
+    readonly ok: 0;
+    /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
+    readonly error: 1;
+    /** Bad command line, missing/invalid arguments, or input the API rejected as invalid (422). */
+    readonly usage: 2;
+    /** The workspace, operation or route does not exist in this project. */
+    readonly notFound: 3;
+    /** Missing, malformed, revoked or insufficient API key. */
+    readonly auth: 4;
+    /** Waiting ran out of time (the operation continues server side), or a request timed out. */
+    readonly timeout: 5;
+    /** The awaited operation ended `failed` or `canceled`. */
+    readonly operationFailed: 6;
+    /** SIGINT (Ctrl-C). */
+    readonly interrupted: 130;
+};
+export declare class UsageError extends Error {
+    name: string;
+}
+/** SHARDFLUX_API_KEY missing or malformed (never carries the key). */
+export declare class AuthConfigError extends Error {
+    name: string;
+}
+/** A workspace key that no workspace of this project has. */
+export declare class NotFoundError extends Error {
+    name: string;
+}
+/** The user pressed Ctrl-C; `operationId` is set when a server-side operation keeps running. */
+export declare class InterruptedError extends Error {
+    name: string;
+    readonly operationId: string | undefined;
+    constructor(message: string, operationId?: string);
+}
+export interface ErrorInfo {
+    code: string;
+    message: string;
+    status?: number;
+    request_id?: string;
+    retryable?: boolean;
+    operation_id?: string;
+    details?: Record<string, unknown>;
+    source?: 'api' | 'cell';
+    last_state?: string;
+    operation?: unknown;
+}
+/** Removes anything shaped like a Shardflux API key (and the configured key itself) from text. */
+export declare function redact(text: string, key?: string): string;
+export declare function describeError(err: unknown): ErrorInfo;
+/** Maps an error to the documented exit code. */
+export declare function exitCodeFor(err: unknown, interrupted?: boolean): number;

package/dist/errors.js

@@ -0,0 +1,117 @@
+/**
+ * Exit codes and error description for `shard`. Every failure is reported on
+ * stderr with the API's error code, message and request id; the process exit
+ * code tells scripts what kind of failure it was (README "Exit codes").
+ */
+import { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from '@shardflux/sdk';
+export const EXIT = {
+    ok: 0,
+    /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
+    error: 1,
+    /** Bad command line, missing/invalid arguments, or input the API rejected as invalid (422). */
+    usage: 2,
+    /** The workspace, operation or route does not exist in this project. */
+    notFound: 3,
+    /** Missing, malformed, revoked or insufficient API key. */
+    auth: 4,
+    /** Waiting ran out of time (the operation continues server side), or a request timed out. */
+    timeout: 5,
+    /** The awaited operation ended `failed` or `canceled`. */
+    operationFailed: 6,
+    /** SIGINT (Ctrl-C). */
+    interrupted: 130,
+};
+export class UsageError extends Error {
+    name = 'UsageError';
+}
+/** SHARDFLUX_API_KEY missing or malformed (never carries the key). */
+export class AuthConfigError extends Error {
+    name = 'AuthConfigError';
+}
+/** A workspace key that no workspace of this project has. */
+export class NotFoundError extends Error {
+    name = 'NotFoundError';
+}
+/** The user pressed Ctrl-C; `operationId` is set when a server-side operation keeps running. */
+export class InterruptedError extends Error {
+    name = 'InterruptedError';
+    operationId;
+    constructor(message, operationId) {
+        super(message);
+        this.operationId = operationId;
+    }
+}
+const AUTH_CODES = new Set(['unauthenticated', 'invalid_credentials', 'token_invalid', 'forbidden', 'mfa_required', 'email_unverified', 'step_up_required', 'csrf_failed']);
+const KEY_PATTERN = /sfk_[A-Za-z0-9]{8,}_[A-Za-z0-9]+/g;
+/** Removes anything shaped like a Shardflux API key (and the configured key itself) from text. */
+export function redact(text, key) {
+    let out = text.replace(KEY_PATTERN, 'sfk_[redacted]');
+    if (key && key.length >= 8)
+        out = out.split(key).join('[redacted]');
+    return out;
+}
+function isNamed(err, name) {
+    return typeof err === 'object' && err !== null && err.name === name;
+}
+export function describeError(err) {
+    if (err instanceof ShardfluxApiError) {
+        return {
+            code: err.code,
+            message: err.message,
+            status: err.status,
+            request_id: err.requestId,
+            retryable: err.retryable,
+            ...(err.operationId ? { operation_id: err.operationId } : {}),
+            ...(err.details ? { details: err.details } : {}),
+            source: err.source,
+        };
+    }
+    if (err instanceof OperationTimeoutError)
+        return { code: 'timeout', message: err.message, operation_id: err.operationId, last_state: err.lastState };
+    if (err instanceof OperationFailedError) {
+        return { code: 'operation_failed', message: err.message, operation_id: err.operationId, ...(err.errorCode ? { details: { error_code: err.errorCode } } : {}), operation: err.operation };
+    }
+    if (err instanceof UsageError)
+        return { code: 'usage', message: err.message };
+    if (err instanceof AuthConfigError)
+        return { code: 'unauthenticated', message: err.message };
+    if (err instanceof NotFoundError)
+        return { code: 'not_found', message: err.message };
+    if (err instanceof InterruptedError)
+        return { code: 'interrupted', message: err.message, ...(err.operationId ? { operation_id: err.operationId } : {}) };
+    if (err instanceof ShardfluxProtocolError)
+        return { code: 'protocol_error', message: err.message, status: err.status };
+    if (isNamed(err, 'TimeoutError'))
+        return { code: 'timeout', message: 'The request timed out.' };
+    if (isNamed(err, 'AbortError'))
+        return { code: 'interrupted', message: 'Interrupted.' };
+    if (err instanceof TypeError && err.message === 'fetch failed') {
+        const cause = err.cause;
+        return { code: 'network_error', message: `Cannot reach the Shardflux API (${cause?.code ?? cause?.message ?? 'network error'}).` };
+    }
+    return { code: 'internal_error', message: err instanceof Error ? err.message : String(err) };
+}
+/** Maps an error to the documented exit code. */
+export function exitCodeFor(err, interrupted = false) {
+    if (interrupted || err instanceof InterruptedError)
+        return EXIT.interrupted;
+    if (err instanceof UsageError)
+        return EXIT.usage;
+    if (err instanceof AuthConfigError)
+        return EXIT.auth;
+    if (err instanceof NotFoundError)
+        return EXIT.notFound;
+    if (err instanceof OperationTimeoutError || isNamed(err, 'TimeoutError'))
+        return EXIT.timeout;
+    if (err instanceof OperationFailedError)
+        return EXIT.operationFailed;
+    if (err instanceof ShardfluxApiError) {
+        if (AUTH_CODES.has(err.code) || err.status === 401)
+            return EXIT.auth;
+        if (err.code === 'not_found' || err.status === 404)
+            return EXIT.notFound;
+        if (err.code === 'validation_failed')
+            return EXIT.usage;
+    }
+    return EXIT.error;
+}

package/dist/format.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Human-readable output (aligned tables, key/value blocks) and the error line.
+ * `--json` output is the API's own objects (see README "JSON output"), so
+ * these functions only shape what people read.
+ */
+import type { AgentSession, FileList, Operation, WorkspaceView } from '@shardflux/sdk';
+import type { ErrorInfo } from './errors.js';
+export declare function json(value: unknown): string;
+export declare function table(headers: readonly string[], rows: readonly (readonly string[])[]): string;
+export declare function kv(pairs: readonly (readonly [string, string])[]): string;
+/** ISO timestamp to second precision ("2026-09-26 12:00:00Z"), "-" when absent. */
+export declare function time(iso: string | null | undefined): string;
+/** { a: 1, b: 2 } -> "a=1 b=2" */
+export declare function pairs(obj: Record<string, unknown> | null | undefined): string;
+export declare function operationSummary(op: Operation | null | undefined): string;
+export declare const WORKSPACE_HEADERS: readonly ["ID", "KEY", "STATE", "DESIRED", "TEMPLATE", "OPERATION", "CREATED"];
+export declare function workspaceRow(w: WorkspaceView): string[];
+export declare function workspaceTable(ws: readonly WorkspaceView[]): string;
+export declare function isReady(w: WorkspaceView): boolean;
+export declare function workspaceDetail(w: WorkspaceView): string;
+export declare const OPERATION_HEADERS: readonly ["ID", "KIND", "STATE", "REASON", "CREATED", "COMPLETED"];
+export declare function operationTable(ops: readonly Operation[]): string;
+export declare function operationDetail(op: Operation): string;
+export declare function sessionTable(sessions: readonly AgentSession[]): string;
+export declare function fileTable(list: FileList): string;
+/**
+ * The usage summary (GET /v1/organizations/{id}/usage/summary): plan, period, measurement
+ * freshness, then meters and allowances as tables. Columns absent from the response are omitted.
+ */
+export declare function usageText(summary: unknown): string;
+/** One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. */
+export declare function errorText(e: ErrorInfo, hint?: string): string;