@shardflux/sdk 0.5.0

package/dist/tools.js

@@ -0,0 +1,313 @@
+export class ToolArgumentError extends Error {
+    tool;
+    issues;
+    constructor(tool, issues) {
+        super(`Invalid arguments for ${tool}: ${issues.join('; ')}`);
+        this.name = 'ToolArgumentError';
+        this.tool = tool;
+        this.issues = issues;
+    }
+}
+/** Validates the JSON-Schema subset used by the tool definitions. Returns problems (empty = valid). */
+export function validateArgs(schema, value, path = '$') {
+    const issues = [];
+    const t = schema.type;
+    if (t === 'object') {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return [`${path} must be an object`];
+        const obj = value;
+        for (const r of schema.required ?? [])
+            if (obj[r] === undefined)
+                issues.push(`${path}.${r} is required`);
+        for (const [k, v] of Object.entries(obj)) {
+            const sub = schema.properties?.[k];
+            if (!sub) {
+                if (schema.additionalProperties === false)
+                    issues.push(`${path}.${k} is not allowed`);
+                continue;
+            }
+            if (v !== undefined)
+                issues.push(...validateArgs(sub, v, `${path}.${k}`));
+        }
+        return issues;
+    }
+    if (t === 'string') {
+        if (typeof value !== 'string')
+            return [`${path} must be a string`];
+        if (schema.minLength !== undefined && value.length < schema.minLength)
+            issues.push(`${path} is too short`);
+        if (schema.maxLength !== undefined && value.length > schema.maxLength)
+            issues.push(`${path} is too long`);
+    }
+    else if (t === 'integer' || t === 'number') {
+        if (typeof value !== 'number' || !Number.isFinite(value) || (t === 'integer' && !Number.isInteger(value)))
+            return [`${path} must be ${t === 'integer' ? 'an integer' : 'a number'}`];
+        if (schema.minimum !== undefined && value < schema.minimum)
+            issues.push(`${path} must be >= ${schema.minimum}`);
+        if (schema.maximum !== undefined && value > schema.maximum)
+            issues.push(`${path} must be <= ${schema.maximum}`);
+    }
+    else if (t === 'boolean') {
+        if (typeof value !== 'boolean')
+            return [`${path} must be a boolean`];
+    }
+    else if (t === 'array') {
+        if (!Array.isArray(value))
+            return [`${path} must be an array`];
+        if (schema.minItems !== undefined && value.length < schema.minItems)
+            issues.push(`${path} needs at least ${schema.minItems} items`);
+        if (schema.maxItems !== undefined && value.length > schema.maxItems)
+            issues.push(`${path} allows at most ${schema.maxItems} items`);
+        if (schema.items)
+            value.forEach((v, i) => issues.push(...validateArgs(schema.items, v, `${path}[${i}]`)));
+    }
+    if (schema.enum && !schema.enum.includes(value))
+        issues.push(`${path} must be one of ${schema.enum.join(', ')}`);
+    return issues;
+}
+const ALL = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
+const obj = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const path = (description = 'Absolute path inside the workspace, e.g. /home/user/project/main.py') => ({ type: 'string', minLength: 1, maxLength: 4096, description });
+const signal = { type: 'string', description: 'Signal name such as SIGTERM, SIGINT or SIGKILL.', minLength: 2, maxLength: 12 };
+function clip(text, max) {
+    const bytes = Buffer.from(text, 'utf8');
+    if (bytes.length <= max)
+        return { text, truncated: false };
+    return { text: bytes.subarray(0, max).toString('utf8'), truncated: true };
+}
+/** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
+export function workspaceTools(workspace, opts = {}) {
+    const cell = () => workspace.cell(opts.agentLabel !== undefined ? { agentLabel: opts.agentLabel } : {});
+    const max = opts.maxOutputBytes ?? 65_536;
+    const prefix = opts.prefix ?? '';
+    const allowed = new Set(opts.tools ?? workspace.grantedTools ?? ALL);
+    const defs = [
+        {
+            name: 'exec',
+            permission: 'exec',
+            description: 'Run a shell command in the persistent remote workspace (Linux; bash -lc) and return its exit code, stdout and stderr. Files, installed packages and background processes persist between calls.',
+            parameters: obj({
+                command: { type: 'string', minLength: 1, maxLength: 100_000, description: 'Shell command line, e.g. "pip install -r requirements.txt && pytest -q".' },
+                cwd: { type: 'string', maxLength: 4096, description: 'Working directory (absolute).' },
+                timeout_ms: { type: 'integer', minimum: 1000, maximum: 3_600_000, description: 'Kill the command after this long (default 600000).' },
+                stdin: { type: 'string', maxLength: 1_000_000, description: 'Text written to stdin.' },
+            }, ['command']),
+            run: async (a, o) => {
+                const r = await cell().exec.run(['bash', '-lc', String(a.command)], {
+                    ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
+                    timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
+                    ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
+                    maxOutputBytes: max,
+                    ...(o.signal ? { signal: o.signal } : {}),
+                });
+                return { exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, session_id: r.sessionId };
+            },
+        },
+        {
+            name: 'read_file',
+            permission: 'files',
+            description: 'Read a text file from the workspace (UTF-8). Use offset/length for large files.',
+            parameters: obj({ path: path(), offset: { type: 'integer', minimum: 0 }, length: { type: 'integer', minimum: 1, maximum: 10_485_760 } }, ['path']),
+            run: async (a) => {
+                const bytes = await cell().files.read(String(a.path), {
+                    ...(typeof a.offset === 'number' ? { offset: a.offset } : {}),
+                    length: typeof a.length === 'number' ? Math.min(a.length, max) : max + 1,
+                });
+                const c = clip(new TextDecoder().decode(bytes), max);
+                return { path: a.path, content: c.text, truncated: c.truncated || bytes.length > max };
+            },
+        },
+        {
+            name: 'write_file',
+            permission: 'files',
+            description: 'Create or replace a file in the workspace (atomic, durable once acknowledged). Set append to add to the end instead.',
+            parameters: obj({
+                path: path(),
+                content: { type: 'string', maxLength: 10_485_760, description: 'Full file content (UTF-8).' },
+                append: { type: 'boolean', description: 'Append instead of replacing.' },
+                create_parents: { type: 'boolean', description: 'Create missing parent directories (default true).' },
+            }, ['path', 'content']),
+            run: async (a) => {
+                const r = await cell().files.write(String(a.path), String(a.content), { append: a.append === true, createParents: a.create_parents !== false });
+                return { path: r.path, bytes_written: r.bytes_written, sha256: r.sha256, durable: r.durable };
+            },
+        },
+        {
+            name: 'list_files',
+            permission: 'files',
+            description: 'List a directory in the workspace.',
+            parameters: obj({ path: path('Absolute directory path.'), limit: { type: 'integer', minimum: 1, maximum: 10_000 } }, ['path']),
+            run: async (a) => {
+                const r = await cell().files.list(String(a.path), typeof a.limit === 'number' ? { limit: a.limit } : { limit: 500 });
+                return { entries: r.entries.map((e) => ({ name: e.name, path: e.path, type: e.type, size: e.size, modified_at: e.modified_at })), truncated: r.truncated };
+            },
+        },
+        {
+            name: 'list_processes',
+            permission: 'process',
+            description: 'List processes running in the workspace.',
+            parameters: obj({}),
+            run: async () => {
+                const r = await cell().processes.list();
+                return { processes: r.data.map((p) => ({ pid: p.pid, ppid: p.ppid, comm: p.comm, cmdline: p.cmdline, state: p.state, rss_bytes: p.rss_bytes })) };
+            },
+        },
+        {
+            name: 'signal_process',
+            permission: 'process',
+            description: 'Send a signal to a process in the workspace (e.g. stop a server).',
+            parameters: obj({ pid: { type: 'integer', minimum: 2 }, signal }, ['pid', 'signal']),
+            run: async (a) => {
+                await cell().processes.signal(Number(a.pid), String(a.signal));
+                return { signalled: true };
+            },
+        },
+        {
+            name: 'terminal_open',
+            permission: 'pty',
+            description: 'Open an interactive terminal (PTY) in the workspace; returns a session_id for terminal_send/terminal_read.',
+            parameters: obj({ command: { type: 'string', maxLength: 10_000, description: 'Program to run (default: login shell).' }, rows: { type: 'integer', minimum: 1, maximum: 1000 }, cols: { type: 'integer', minimum: 1, maximum: 1000 } }),
+            run: async (a) => {
+                const s = await cell().pty.open({
+                    ...(typeof a.command === 'string' ? { argv: ['bash', '-lc', a.command] } : {}),
+                    ...(typeof a.rows === 'number' ? { rows: a.rows } : {}),
+                    ...(typeof a.cols === 'number' ? { cols: a.cols } : {}),
+                });
+                return { session_id: s.session_id, state: s.state, next_offset: s.output_size };
+            },
+        },
+        {
+            name: 'terminal_send',
+            permission: 'pty',
+            description: 'Type input into a terminal session (include "\\n" to press Enter).',
+            parameters: obj({ session_id: { type: 'string', minLength: 1, maxLength: 64 }, input: { type: 'string', maxLength: 1_000_000 } }, ['session_id', 'input']),
+            run: async (a) => {
+                const s = await cell().pty.input(String(a.session_id), String(a.input));
+                return { state: s.state, next_offset: s.output_size };
+            },
+        },
+        {
+            name: 'terminal_read',
+            permission: 'pty',
+            description: 'Read terminal output from an offset (returns next_offset to continue). Waits briefly for new output.',
+            parameters: obj({ session_id: { type: 'string', minLength: 1, maxLength: 64 }, offset: { type: 'integer', minimum: 0 }, wait_ms: { type: 'integer', minimum: 0, maximum: 60_000 } }, ['session_id']),
+            run: async (a) => {
+                const r = await cell().pty.read(String(a.session_id), {
+                    offset: typeof a.offset === 'number' ? a.offset : 0,
+                    timeoutMs: typeof a.wait_ms === 'number' ? Math.max(100, a.wait_ms) : 3_000,
+                    maxBytes: max,
+                });
+                return { output: r.output, next_offset: r.nextOffset, exited: r.exited, exit_code: r.session?.exit_code ?? null };
+            },
+        },
+        {
+            name: 'terminal_close',
+            permission: 'pty',
+            description: 'Close a terminal session.',
+            parameters: obj({ session_id: { type: 'string', minLength: 1, maxLength: 64 } }, ['session_id']),
+            run: async (a) => {
+                const s = await cell().pty.close(String(a.session_id));
+                return { state: s.state };
+            },
+        },
+        {
+            name: 'git_clone',
+            permission: 'git',
+            description: 'Clone a git repository (HTTPS) into the workspace.',
+            parameters: obj({ url: { type: 'string', minLength: 9, maxLength: 2048, description: 'https:// remote URL.' }, path: path('Destination directory.'), branch: { type: 'string', maxLength: 255 }, depth: { type: 'integer', minimum: 1 } }, ['url', 'path']),
+            run: async (a) => {
+                const r = await cell().git.clone({
+                    url: String(a.url),
+                    path: String(a.path),
+                    ...(typeof a.branch === 'string' ? { branch: a.branch } : {}),
+                    ...(typeof a.depth === 'number' ? { depth: a.depth } : {}),
+                });
+                return { exit_code: r.exit_code, stdout: clip(r.stdout, max).text, stderr: clip(r.stderr, max).text };
+            },
+        },
+        {
+            name: 'git_status',
+            permission: 'git',
+            description: 'Show the git status of a repository in the workspace.',
+            parameters: obj({ path: path('Repository directory.') }, ['path']),
+            run: async (a) => cell().git.status(String(a.path)),
+        },
+        {
+            name: 'git_commit',
+            permission: 'git',
+            description: 'Stage all changes and commit in a repository in the workspace.',
+            parameters: obj({ path: path('Repository directory.'), message: { type: 'string', minLength: 1, maxLength: 65_536 } }, ['path', 'message']),
+            run: async (a) => {
+                const r = await cell().git.commit({ path: String(a.path), message: String(a.message), all: true });
+                return { exit_code: r.exit_code, commit: r.commit ?? null, stdout: clip(r.stdout, max).text, stderr: clip(r.stderr, max).text };
+            },
+        },
+        {
+            name: 'browser_screenshot',
+            permission: 'browser',
+            description: 'Open a URL in the workspace’s headless browser and return a PNG screenshot (base64).',
+            parameters: obj({ url: { type: 'string', minLength: 8, maxLength: 8192 }, width: { type: 'integer', minimum: 100, maximum: 3840 }, height: { type: 'integer', minimum: 100, maximum: 2160 } }, ['url']),
+            run: async (a) => {
+                const png = await cell().browser.screenshot({
+                    url: String(a.url),
+                    ...(typeof a.width === 'number' ? { width: a.width } : {}),
+                    ...(typeof a.height === 'number' ? { height: a.height } : {}),
+                });
+                return { mime_type: 'image/png', bytes: png.length, data_base64: Buffer.from(png).toString('base64') };
+            },
+        },
+        {
+            name: 'browser_content',
+            permission: 'browser',
+            description: 'Open a URL in the workspace’s headless browser and return the rendered page as text or HTML.',
+            parameters: obj({ url: { type: 'string', minLength: 8, maxLength: 8192 }, format: { type: 'string', enum: ['text', 'html'] } }, ['url']),
+            run: async (a) => {
+                const r = await cell().browser.content({ url: String(a.url), format: a.format === 'html' ? 'html' : 'text' });
+                const c = clip(r.content, max);
+                return { url: r.url, format: r.format, content: c.text, truncated: r.truncated || c.truncated };
+            },
+        },
+    ];
+    return defs
+        .filter((d) => allowed.has(d.permission))
+        .map((d) => ({
+        name: `${prefix}${d.name}`,
+        description: d.description,
+        parameters: d.parameters,
+        permission: d.permission,
+        execute: async (args, options = {}) => {
+            const issues = validateArgs(d.parameters, args);
+            if (issues.length > 0)
+                throw new ToolArgumentError(`${prefix}${d.name}`, issues);
+            return d.run(args, options);
+        },
+    }));
+}
+/** OpenAI tool definitions: Chat Completions (`{type:'function', function:{...}}`) or Responses API. */
+export function toOpenAITools(tools, opts = {}) {
+    return opts.api === 'responses'
+        ? tools.map((t) => ({ type: 'function', name: t.name, description: t.description, parameters: t.parameters, strict: false }))
+        : tools.map((t) => ({ type: 'function', function: { name: t.name, description: t.description, parameters: t.parameters } }));
+}
+/** Anthropic Messages API tool definitions (`{ name, description, input_schema }`). */
+export function toAnthropicTools(tools) {
+    return tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.parameters }));
+}
+/**
+ * Runs a model's tool call: `arguments` may be the JSON string (OpenAI) or an object (Anthropic
+ * `input`). Throws for unknown tools and invalid arguments (ToolArgumentError).
+ */
+export async function executeToolCall(tools, call, options = {}) {
+    const tool = tools.find((t) => t.name === call.name);
+    if (!tool)
+        throw new ToolArgumentError(call.name, [`unknown tool ${call.name}`]);
+    const raw = call.input ?? call.arguments ?? {};
+    let args;
+    try {
+        args = typeof raw === 'string' ? (raw.trim() === '' ? {} : JSON.parse(raw)) : raw;
+    }
+    catch {
+        throw new ToolArgumentError(call.name, ['arguments are not valid JSON']);
+    }
+    return tool.execute(args, options);
+}

package/dist/usage.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Usage, allowances, estimates, grants and spend (Phase 9 application API).
+ *
+ *   const s = await cloud.usage.summary(orgId);
+ *   if (s.allowance_exhausted) ... // opens/resumes answer 402 allowance_exhausted
+ *
+ * Every response carries `measurement.measured_through` (usage is complete up to it) and both raw
+ * (fractional) and billable (whole-unit) quantities. API keys read organization totals but only
+ * their own project's workspaces.
+ */
+import type { operations } from './generated/app-api.js';
+import type { ClientContext } from './client.js';
+type JsonOf<R> = R extends {
+    content: {
+        'application/json': infer T;
+    };
+} ? T : never;
+type Ok<Op> = Op extends {
+    responses: infer R;
+} ? {
+    [K in keyof R]: K extends 200 | 201 | 202 ? JsonOf<R[K]> : never;
+}[keyof R] : never;
+export type UsageSummary = Ok<operations['getV1OrganizationsOrganizationIdUsageSummary']>;
+export type UsageSeries = Ok<operations['getV1OrganizationsOrganizationIdUsage']>;
+export type UsageEstimate = Ok<operations['getV1OrganizationsOrganizationIdUsageEstimate']>;
+export type Grants = Ok<operations['getV1OrganizationsOrganizationIdGrants']>;
+export type Spend = Ok<operations['getV1OrganizationsOrganizationIdSpend']>;
+export type SpendPolicy = Ok<operations['getV1OrganizationsOrganizationIdSpendPolicy']>;
+export type UsageMeter = UsageSummary['meters'][number]['meter'];
+export interface UsageSeriesParams {
+    /** RFC 3339; defaults to the current period's start. */
+    from?: string;
+    to?: string;
+    granularity?: 'hour' | 'day';
+    meter?: UsageMeter;
+    workspaceId?: string;
+    projectId?: string;
+}
+export declare class UsageApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    /** Current-period usage per meter, allowances with enforcement and cap state, measurement freshness. */
+    summary(organizationId: string): Promise<UsageSummary>;
+    /** Time series from the ledger (hour: <= 31 days, day: <= 400 days per request). */
+    series(organizationId: string, params?: UsageSeriesParams): Promise<UsageSeries>;
+    /** Usage of one workspace. */
+    workspace(workspaceId: string, params?: Omit<UsageSeriesParams, 'workspaceId' | 'projectId'>): Promise<UsageSeries>;
+    /** Subscription fee, usage charges (0 while overage is disabled) and projected allowance use. */
+    estimate(organizationId: string): Promise<UsageEstimate>;
+    /** Quotas, per-workspace ceilings/reservations/grants and the compute budget leases granted to the cell. */
+    grants(organizationId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Grants>;
+    /** Spend policy, charges this period, cap state and enforcement (leases, overshoot bound). */
+    spend(organizationId: string): Promise<Spend>;
+    /** Usage alert thresholds (changing them is an owner/billing browser action). */
+    spendPolicy(organizationId: string): Promise<SpendPolicy>;
+}
+export {};

package/dist/usage.js

@@ -0,0 +1,45 @@
+export class UsageApi {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    #get(path, query) {
+        const c = this.#ctx();
+        return c.http.json('GET', path, query ? { query } : {}, c.authorization);
+    }
+    /** Current-period usage per meter, allowances with enforcement and cap state, measurement freshness. */
+    summary(organizationId) {
+        return this.#get(`/v1/organizations/${encodeURIComponent(organizationId)}/usage/summary`);
+    }
+    /** Time series from the ledger (hour: <= 31 days, day: <= 400 days per request). */
+    series(organizationId, params = {}) {
+        return this.#get(`/v1/organizations/${encodeURIComponent(organizationId)}/usage`, {
+            from: params.from,
+            to: params.to,
+            granularity: params.granularity,
+            meter: params.meter,
+            workspace_id: params.workspaceId,
+            project_id: params.projectId,
+        });
+    }
+    /** Usage of one workspace. */
+    workspace(workspaceId, params = {}) {
+        return this.#get(`/v1/workspaces/${encodeURIComponent(workspaceId)}/usage`, { from: params.from, to: params.to, granularity: params.granularity, meter: params.meter });
+    }
+    /** Subscription fee, usage charges (0 while overage is disabled) and projected allowance use. */
+    estimate(organizationId) {
+        return this.#get(`/v1/organizations/${encodeURIComponent(organizationId)}/usage/estimate`);
+    }
+    /** Quotas, per-workspace ceilings/reservations/grants and the compute budget leases granted to the cell. */
+    grants(organizationId, params = {}) {
+        return this.#get(`/v1/organizations/${encodeURIComponent(organizationId)}/grants`, { limit: params.limit, cursor: params.cursor });
+    }
+    /** Spend policy, charges this period, cap state and enforcement (leases, overshoot bound). */
+    spend(organizationId) {
+        return this.#get(`/v1/organizations/${encodeURIComponent(organizationId)}/spend`);
+    }
+    /** Usage alert thresholds (changing them is an owner/billing browser action). */
+    spendPolicy(organizationId) {
+        return this.#get(`/v1/organizations/${encodeURIComponent(organizationId)}/spend-policy`);
+    }
+}

package/dist/volumes.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared volumes over the application API (/v1, contracts §15). Types come from
+ * the generated OpenAPI document (schemas `Volume` and `VolumeAttachment`).
+ *
+ * A volume is persistent shared storage (EFS-backed) owned by a project. It is
+ * attached to workspaces of the same project — or of any project of the
+ * organization when `org_shared` — at a guest `mount_path`, read-only or
+ * read-write. Every mutation is an asynchronous operation executed by the cell:
+ * create/attach/detach/delete return at once with the operation; the `wait`
+ * option (default on) polls it to completion like `workspaces.open`.
+ *
+ *   const { volume } = await cloud.volumes.create({ name: 'datasets', quotaGib: 20 });
+ *   await cloud.volumes.attach(workspace.id, { volumeId: volume.id, mountPath: '/mnt/datasets', mode: 'ro' });
+ *
+ * Shared data is outside checkpoint/fork atomicity: suspend/fork keep the
+ * attachment (a fork gets the volumes its project may use), never a copy of the
+ * contents.
+ */
+import type { ClientContext, Operation, Page, WaitOptions } from './client.js';
+import type { components } from './generated/app-api.js';
+export type Volume = components['schemas']['Volume'];
+export type VolumeAttachment = components['schemas']['VolumeAttachment'];
+export type VolumeState = Volume['state'];
+export type VolumeAttachmentState = VolumeAttachment['state'];
+export interface CreateVolumeParams {
+    name: string;
+    quotaGib: number;
+    /** Attachable from every project of the organization (owners/admins only; API keys get 403). */
+    orgShared?: boolean;
+    /** Defaults to the API key's project. */
+    projectId?: string;
+    /** `false`: return while `creating`. Default: wait until the cell made it available (or failed). */
+    wait?: false | WaitOptions;
+    idempotencyKey?: string;
+}
+export interface AttachVolumeParams {
+    volumeId: string;
+    /** Absolute guest path, e.g. /mnt/data (system directories and nested mounts are refused). */
+    mountPath: string;
+    /** Default 'rw'. */
+    mode?: 'ro' | 'rw';
+    wait?: false | WaitOptions;
+    idempotencyKey?: string;
+}
+export interface DeleteVolumeParams {
+    projectId?: string;
+    /** Detach it from every workspace as part of the delete (guests see I/O errors on the mount). */
+    force?: boolean;
+    wait?: false | WaitOptions;
+    idempotencyKey?: string;
+}
+export interface VolumeResult {
+    volume: Volume;
+    operation: Operation;
+}
+export interface AttachmentResult {
+    attachment: VolumeAttachment;
+    /** null only when the volume was already attached with the same mount_path and mode. */
+    operation: Operation | null;
+}
+export declare class VolumesApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    /** Creates a volume (202) and, unless `wait: false`, waits until the cell reports it available. */
+    create(params: CreateVolumeParams): Promise<VolumeResult>;
+    get(volumeId: string, params?: {
+        projectId?: string;
+    }): Promise<Volume>;
+    /** The project's volumes; `includeOrgShared` adds the organization's org-shared volumes (attachable here). */
+    list(params?: {
+        projectId?: string;
+        includeOrgShared?: boolean;
+        includeDeleted?: boolean;
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<Volume>>;
+    listAll(params?: {
+        projectId?: string;
+        includeOrgShared?: boolean;
+        includeDeleted?: boolean;
+    }): AsyncGenerator<Volume>;
+    /** Deletes the volume and its data (refused with 409 volume_attached while attached, unless `force`). */
+    delete(volumeId: string, params?: DeleteVolumeParams): Promise<VolumeResult>;
+    /** Where a volume is attached (API keys: only their project's workspaces). */
+    attachments(volumeId: string, params?: {
+        projectId?: string;
+        includeDetached?: boolean;
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<VolumeAttachment>>;
+    /** Volumes attached to a workspace. */
+    listAttached(workspaceId: string, params?: {
+        includeDetached?: boolean;
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<VolumeAttachment>>;
+    /**
+     * Attaches a volume at mountPath and, unless `wait: false`, waits until the cell mounted it (or,
+     * for a workspace without a running VM, recorded it for the next start: `mounted: false`).
+     * 409 operation_in_progress while another lifecycle operation of the workspace runs.
+     */
+    attach(workspaceId: string, params: AttachVolumeParams): Promise<AttachmentResult>;
+    /** Detaches a volume and, unless `wait: false`, waits until the cell unmounted it. */
+    detach(workspaceId: string, volumeId: string, params?: {
+        wait?: false | WaitOptions;
+        idempotencyKey?: string;
+    }): Promise<AttachmentResult>;
+}

package/dist/volumes.js

@@ -0,0 +1,120 @@
+import { randomId } from "./http.js";
+const enc = encodeURIComponent;
+export class VolumesApi {
+    #ctx;
+    #projectId = null;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    /** The API key's project (from GET /v1/me, fetched once). */
+    #project(projectId) {
+        if (projectId !== undefined)
+            return Promise.resolve(projectId);
+        this.#projectId ??= this.#ctx()
+            .http.json('GET', '/v1/me', {}, this.#ctx().authorization)
+            .then((me) => {
+            if (!me.api_key)
+                throw new Error('projectId is required (the credential is not a project API key)');
+            return me.api_key.project_id;
+        })
+            .catch((err) => {
+            this.#projectId = null;
+            throw err;
+        });
+        return this.#projectId;
+    }
+    async #settle(operation, wait) {
+        if (wait === false)
+            return operation;
+        return this.#ctx().workspaces.waitForOperation(operation.id, wait ?? {});
+    }
+    /** Creates a volume (202) and, unless `wait: false`, waits until the cell reports it available. */
+    async create(params) {
+        const projectId = await this.#project(params.projectId);
+        const body = { name: params.name, quota_gib: params.quotaGib };
+        if (params.orgShared !== undefined)
+            body.org_shared = params.orgShared;
+        const res = await this.#ctx().http.json('POST', `/v1/projects/${enc(projectId)}/volumes`, { json: body, idempotencyKey: params.idempotencyKey ?? randomId('volume-') }, this.#ctx().authorization);
+        if (params.wait === false)
+            return res;
+        const operation = await this.#settle(res.operation, params.wait);
+        return { volume: await this.get(res.volume.id, { projectId }), operation };
+    }
+    async get(volumeId, params = {}) {
+        const projectId = await this.#project(params.projectId);
+        return this.#ctx().http.json('GET', `/v1/projects/${enc(projectId)}/volumes/${enc(volumeId)}`, {}, this.#ctx().authorization);
+    }
+    /** The project's volumes; `includeOrgShared` adds the organization's org-shared volumes (attachable here). */
+    async list(params = {}) {
+        const projectId = await this.#project(params.projectId);
+        const page = await this.#ctx().http.json('GET', `/v1/projects/${enc(projectId)}/volumes`, { query: { include_org_shared: params.includeOrgShared, include_deleted: params.includeDeleted, limit: params.limit, cursor: params.cursor } }, this.#ctx().authorization);
+        return { data: page.data, nextCursor: page.next_cursor };
+    }
+    async *listAll(params = {}) {
+        let cursor;
+        do {
+            const page = await this.list({ ...params, limit: 200, ...(cursor === undefined ? {} : { cursor }) });
+            yield* page.data;
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor !== undefined);
+    }
+    /** Deletes the volume and its data (refused with 409 volume_attached while attached, unless `force`). */
+    async delete(volumeId, params = {}) {
+        const projectId = await this.#project(params.projectId);
+        let query = {};
+        if (params.force) {
+            const v = await this.get(volumeId, { projectId });
+            query = { force: true, confirm_name: v.name };
+        }
+        const res = await this.#ctx().http.json('DELETE', `/v1/projects/${enc(projectId)}/volumes/${enc(volumeId)}`, { query, idempotencyKey: params.idempotencyKey ?? randomId('volume-delete-') }, this.#ctx().authorization);
+        if (params.wait === false)
+            return res;
+        const operation = await this.#settle(res.operation, params.wait);
+        return { volume: await this.get(volumeId, { projectId }), operation };
+    }
+    /** Where a volume is attached (API keys: only their project's workspaces). */
+    async attachments(volumeId, params = {}) {
+        const projectId = await this.#project(params.projectId);
+        const page = await this.#ctx().http.json('GET', `/v1/projects/${enc(projectId)}/volumes/${enc(volumeId)}/attachments`, { query: { include_detached: params.includeDetached, limit: params.limit, cursor: params.cursor } }, this.#ctx().authorization);
+        return { data: page.data, nextCursor: page.next_cursor };
+    }
+    /** Volumes attached to a workspace. */
+    async listAttached(workspaceId, params = {}) {
+        const page = await this.#ctx().http.json('GET', `/v1/workspaces/${enc(workspaceId)}/volumes`, { query: { include_detached: params.includeDetached, limit: params.limit, cursor: params.cursor } }, this.#ctx().authorization);
+        return { data: page.data, nextCursor: page.next_cursor };
+    }
+    /**
+     * Attaches a volume at mountPath and, unless `wait: false`, waits until the cell mounted it (or,
+     * for a workspace without a running VM, recorded it for the next start: `mounted: false`).
+     * 409 operation_in_progress while another lifecycle operation of the workspace runs.
+     */
+    async attach(workspaceId, params) {
+        const body = { volume_id: params.volumeId, mount_path: params.mountPath };
+        if (params.mode !== undefined)
+            body.mode = params.mode;
+        const res = await this.#ctx().http.json('POST', `/v1/workspaces/${enc(workspaceId)}/volumes`, { json: body, idempotencyKey: params.idempotencyKey ?? randomId('volume-attach-') }, this.#ctx().authorization);
+        if (params.wait === false || res.operation === null)
+            return res;
+        const operation = await this.#settle(res.operation, params.wait);
+        return { attachment: await this.#attachment(workspaceId, res.attachment.id), operation };
+    }
+    /** Detaches a volume and, unless `wait: false`, waits until the cell unmounted it. */
+    async detach(workspaceId, volumeId, params = {}) {
+        const res = await this.#ctx().http.json('DELETE', `/v1/workspaces/${enc(workspaceId)}/volumes/${enc(volumeId)}`, { idempotencyKey: params.idempotencyKey ?? randomId('volume-detach-') }, this.#ctx().authorization);
+        if (params.wait === false)
+            return res;
+        const operation = await this.#settle(res.operation, params.wait);
+        return { attachment: await this.#attachment(workspaceId, res.attachment.id), operation };
+    }
+    async #attachment(workspaceId, attachmentId) {
+        let cursor;
+        do {
+            const page = await this.listAttached(workspaceId, { includeDetached: true, limit: 200, ...(cursor === undefined ? {} : { cursor }) });
+            const hit = page.data.find((a) => a.id === attachmentId);
+            if (hit)
+                return hit;
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor !== undefined);
+        throw new Error(`attachment ${attachmentId} not found on workspace ${workspaceId}`);
+    }
+}