@shardflux/sdk 0.5.0

package/dist/templates.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Template registry and custom template builds over the application API (/v1).
+ * Types are written by hand.
+ *
+ * Publishing/archiving an organization template version is a browser-only
+ * owner/admin action (it changes what `open` resolves for every project), so
+ * it is not exposed here.
+ */
+import type { ClientContext, Page } from './client.js';
+export type TemplateOwner = 'platform' | 'organization';
+export type TemplateVersionState = 'unpublished' | 'published' | 'archived';
+export type CeilingSource = 'template' | 'user' | 'plan';
+export interface TemplateVersion {
+    id: string;
+    version: number;
+    state: TemplateVersionState;
+    architecture: string;
+    /** SHA-256 of the version manifest: its immutable identity. */
+    artifact_sha256: string;
+    description: string | null;
+    created_at: string;
+    published_at: string | null;
+    archived_at: string | null;
+    /** The version `open` picks for a new workspace of this template. */
+    is_open_version: boolean;
+    caps: {
+        cpu_millis_max: number | null;
+        memory_mib_max: number | null;
+        disk_gib_max: number | null;
+    };
+    default_caps: {
+        cpu_millis_ceiling: number | null;
+        memory_mib_base: number | null;
+        memory_mib_ceiling: number | null;
+        disk_gib: number | null;
+    } | null;
+    effective_ceilings: {
+        cpu_millis: number;
+        memory_mib: number;
+        disk_gib: number;
+        sources: {
+            cpu_millis: CeilingSource;
+            memory_mib: CeilingSource;
+            disk_gib: CeilingSource;
+        };
+    } | null;
+    /** Resources where your plan is below what the template states, with the plan value. */
+    plan_clamped: {
+        cpu_millis?: number;
+        memory_mib?: number;
+        disk_gib?: number;
+    };
+    compatibility: {
+        manifest_schema: string | null;
+        architecture: string;
+        kernel: {
+            release: string | null;
+            sha256: string | null;
+        } | null;
+        guest_agent: {
+            version: string | null;
+            sha256: string | null;
+            vsock_port: number | null;
+        } | null;
+        rootfs: {
+            format: string | null;
+            bytes: number | null;
+            sha256: string | null;
+        } | null;
+        firecracker: string | null;
+        runtime_class: string | null;
+    };
+    installed_tools: Array<{
+        name: string;
+        version: string;
+    }>;
+    build_id: string | null;
+    publishable: boolean;
+}
+export interface TemplateSummary {
+    id: string;
+    slug: string;
+    name: string;
+    owner: TemplateOwner;
+    organization_id: string | null;
+    created_at: string;
+    archived_at: string | null;
+    shadowed_by_organization_template: boolean;
+    open_version: TemplateVersion | null;
+}
+export interface TemplateDetail extends TemplateSummary {
+    plan: {
+        plan_key: string;
+        catalog_version: string;
+    } | null;
+    /** What `open({ template: slug })` resolves to for the organization right now. */
+    open_resolves_to: {
+        template_id: string;
+        template_version_id: string;
+        version: number;
+        owner: TemplateOwner;
+    } | null;
+    versions: TemplateVersion[];
+    versions_truncated: boolean;
+}
+/**
+ * queued -> building -> testing -> publishing -> published (the cell stored the artifact; the API then registers the
+ * template version: see `registration`) | failed | canceled. `succeeded` = legacy (pre-0.5) builds.
+ */
+export type TemplateBuildState = 'queued' | 'building' | 'testing' | 'publishing' | 'published' | 'succeeded' | 'failed' | 'canceled';
+export type TemplateBuildRegistrationState = 'not_applicable' | 'pending' | 'registered' | 'failed';
+export interface BuilderAvailability {
+    state: 'available' | 'unavailable';
+    reason: 'no_builder_registered' | 'no_recent_heartbeat' | null;
+    active_builders: number;
+    last_heartbeat_at: string | null;
+}
+export interface TemplateBuild {
+    id: string;
+    organization_id: string;
+    template: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+    state: TemplateBuildState;
+    /** Version number this build produces in its organization template (assigned at request time; null for legacy builds). */
+    target_version: number | null;
+    /** The registered version is published at once (default) or left for the owner/admin publish route. */
+    auto_publish: boolean;
+    published_at: string | null;
+    /** Creation of the immutable template version from a published build (by the API worker, within seconds). */
+    registration: {
+        state: TemplateBuildRegistrationState;
+        registered_at: string | null;
+        error: {
+            code: string;
+            message: string;
+        } | null;
+    };
+    /** The template version this build produced, once registered. */
+    template_version: {
+        id: string;
+        version: number;
+        published: boolean;
+    } | null;
+    cancel_requested_at: string | null;
+    created_at: string;
+    updated_at: string;
+    started_at: string | null;
+    completed_at: string | null;
+    requested_by: {
+        type: 'user' | 'api_key';
+        id: string;
+    };
+    base: {
+        ref: string;
+        template_id: string;
+        template_version_id: string;
+        slug: string;
+        version: number;
+        artifact_sha256: string;
+    };
+    architecture: string;
+    bounds: {
+        cpu_millis: number;
+        memory_mib: number;
+        disk_gib: number;
+        timeout_seconds: number;
+    };
+    requested_bounds: {
+        cpu_millis: number | null;
+        memory_mib: number | null;
+        disk_gib: number | null;
+        timeout_seconds: number | null;
+    };
+    bound_sources: Record<'cpu_millis' | 'memory_mib' | 'disk_gib' | 'timeout_seconds', 'request' | 'plan' | 'platform'>;
+    network: {
+        mode: 'none' | 'egress_allowlist';
+        allow_hosts: string[];
+    };
+    provenance: {
+        recipe_schema: string;
+        recipe_sha256: string;
+        base_artifact_sha256: string;
+        builder_id: string | null;
+        attempt: number;
+    };
+    /** Present on create and get of one build. */
+    recipe?: {
+        dockerfile: string;
+    };
+    result: {
+        artifact_sha256: string | null;
+        scan: ({
+            passed: boolean;
+        } & Record<string, unknown>) | null;
+        compatibility: ({
+            passed: boolean;
+        } & Record<string, unknown>) | null;
+        produced_version: {
+            id: string;
+            version: number;
+            state: TemplateVersionState;
+            published_at: string | null;
+            archived_at: string | null;
+        } | null;
+    };
+    failure: {
+        code: string;
+        message: string;
+    } | null;
+    log: {
+        state: 'none' | 'available' | 'expired';
+        bytes: number | null;
+        sha256: string | null;
+        expires_at: string | null;
+        downloadable: boolean;
+        tail?: string | null;
+    };
+    publishable: boolean;
+    builder_availability: BuilderAvailability;
+}
+export interface TemplateRecipe {
+    /** `<template slug>@<version>`, referenced in the Dockerfile as `FROM shardflux-base`. */
+    base: string;
+    /** Dockerfile (<= 64 KiB, no build context; external images pinned by @sha256 digest; final stage FROM shardflux-base). */
+    dockerfile: string;
+    architecture?: 'x86_64';
+    resources?: {
+        cpu_millis?: number;
+        memory_mib?: number;
+        disk_gib?: number;
+        timeout_seconds?: number;
+    };
+    network?: {
+        mode: 'none' | 'egress_allowlist';
+        allow_hosts?: string[];
+    };
+}
+export interface CreateTemplateBuildParams {
+    /** Organization template slug (created by the first build; platform slugs are refused). */
+    templateSlug: string;
+    displayName?: string;
+    recipe: TemplateRecipe;
+    /** Publish the produced version as soon as it is registered (default true); false leaves it for the owner/admin publish route. */
+    autoPublish?: boolean;
+    /** Defaults to a random key so retries never create a second build. */
+    idempotencyKey?: string;
+}
+/** Short-lived download of the full build log (a bearer URL until expires_at: do not log or share it). */
+export interface TemplateBuildLogUrl {
+    url: string;
+    expires_at: string;
+    object_key: string;
+    bytes: number | null;
+    sha256: string | null;
+}
+export interface WaitForBuildOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    maxPollIntervalMs?: number;
+    signal?: AbortSignal;
+}
+/** Finished from the caller's point of view: failed/canceled/legacy succeeded, or published and its registration settled. */
+export declare function buildSettled(build: Pick<TemplateBuild, 'state' | 'registration'>): boolean;
+/** Thrown by waitForBuild when the build is still running (or awaiting registration) at the deadline (it keeps going). */
+export declare class TemplateBuildTimeoutError extends Error {
+    readonly build: TemplateBuild;
+    constructor(build: TemplateBuild, waitedMs: number);
+}
+export declare class TemplateBuildsApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    /** Queues a build (202). Poll with get()/waitForBuild(); `builder_availability` says whether a builder runs. */
+    create(organizationId: string, params: CreateTemplateBuildParams): Promise<TemplateBuild>;
+    get(organizationId: string, buildId: string): Promise<TemplateBuild>;
+    list(organizationId: string, params?: {
+        state?: TemplateBuildState;
+        template?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<TemplateBuild>>;
+    /**
+     * A presigned URL (<= 15 min) for the full build log `builds/<id>.log`. 404 with details.reason log_not_available
+     * (not recorded yet) or log_expired; 503 when the deployment has no build-log bucket.
+     */
+    logUrl(organizationId: string, buildId: string): Promise<TemplateBuildLogUrl>;
+    /** queued -> canceled; building/testing/publishing -> cancellation requested (honoured until publishing starts). API keys cancel only their own builds. */
+    cancel(organizationId: string, buildId: string): Promise<TemplateBuild>;
+    builderAvailability(organizationId: string): Promise<BuilderAvailability>;
+    /**
+     * Polls until the build is settled and returns it: failed | canceled, or published with its registration
+     * `registered` (the version exists; `template_version`) or `failed`. Legacy builds end `succeeded`.
+     * Throws TemplateBuildTimeoutError at the deadline (default 30 min); the build continues.
+     */
+    waitForBuild(organizationId: string, buildId: string, opts?: WaitForBuildOptions): Promise<TemplateBuild>;
+}
+export declare class TemplatesApi {
+    #private;
+    readonly builds: TemplateBuildsApi;
+    constructor(ctx: () => ClientContext);
+    /** Templates the API key's organization can use (platform + its own), with the version `open` picks. */
+    list(params?: {
+        organizationId?: string;
+        includeArchived?: boolean;
+        owner?: TemplateOwner;
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<TemplateSummary>>;
+    listAll(params?: {
+        organizationId?: string;
+        includeArchived?: boolean;
+        owner?: TemplateOwner;
+    }): AsyncGenerator<TemplateSummary>;
+    /** One template by slug: versions, compatibility, caps, installed tools, plan clamping and what `open` resolves to. */
+    get(slug: string, params?: {
+        organizationId?: string;
+        includeArchived?: boolean;
+        owner?: TemplateOwner;
+    }): Promise<TemplateDetail>;
+    /** Like get() but resolves to null on 404 (unknown slug or outside the organization). */
+    find(slug: string, params?: {
+        organizationId?: string;
+        includeArchived?: boolean;
+        owner?: TemplateOwner;
+    }): Promise<TemplateDetail | null>;
+}

package/dist/templates.js

@@ -0,0 +1,117 @@
+import { ShardfluxApiError } from "./errors.js";
+import { randomId } from "./http.js";
+const TERMINAL = new Set(['succeeded', 'failed', 'canceled']);
+/** Finished from the caller's point of view: failed/canceled/legacy succeeded, or published and its registration settled. */
+export function buildSettled(build) {
+    if (TERMINAL.has(build.state))
+        return true;
+    return build.state === 'published' && (build.registration.state === 'registered' || build.registration.state === 'failed');
+}
+/** Thrown by waitForBuild when the build is still running (or awaiting registration) at the deadline (it keeps going). */
+export class TemplateBuildTimeoutError extends Error {
+    build;
+    constructor(build, waitedMs) {
+        super(`Template build ${build.id} is still ${build.state} after ${waitedMs} ms${build.builder_availability.state === 'unavailable' ? ` (builder ${build.builder_availability.reason ?? 'unavailable'})` : ''}`);
+        this.name = 'TemplateBuildTimeoutError';
+        this.build = build;
+    }
+}
+const enc = encodeURIComponent;
+export class TemplateBuildsApi {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    /** Queues a build (202). Poll with get()/waitForBuild(); `builder_availability` says whether a builder runs. */
+    create(organizationId, params) {
+        const body = { template_slug: params.templateSlug, recipe: params.recipe };
+        if (params.displayName !== undefined)
+            body.display_name = params.displayName;
+        if (params.autoPublish !== undefined)
+            body.auto_publish = params.autoPublish;
+        return this.#ctx().http.json('POST', `/v1/organizations/${enc(organizationId)}/template-builds`, { json: body, idempotencyKey: params.idempotencyKey ?? randomId('template-build-') }, this.#ctx().authorization);
+    }
+    get(organizationId, buildId) {
+        return this.#ctx().http.json('GET', `/v1/organizations/${enc(organizationId)}/template-builds/${enc(buildId)}`, {}, this.#ctx().authorization);
+    }
+    async list(organizationId, params = {}) {
+        const page = await this.#ctx().http.json('GET', `/v1/organizations/${enc(organizationId)}/template-builds`, { query: { state: params.state, template: params.template, limit: params.limit, cursor: params.cursor } }, this.#ctx().authorization);
+        return { data: page.data, nextCursor: page.next_cursor };
+    }
+    /**
+     * A presigned URL (<= 15 min) for the full build log `builds/<id>.log`. 404 with details.reason log_not_available
+     * (not recorded yet) or log_expired; 503 when the deployment has no build-log bucket.
+     */
+    logUrl(organizationId, buildId) {
+        return this.#ctx().http.json('GET', `/v1/organizations/${enc(organizationId)}/template-builds/${enc(buildId)}/log-url`, {}, this.#ctx().authorization);
+    }
+    /** queued -> canceled; building/testing/publishing -> cancellation requested (honoured until publishing starts). API keys cancel only their own builds. */
+    cancel(organizationId, buildId) {
+        return this.#ctx().http.json('POST', `/v1/organizations/${enc(organizationId)}/template-builds/${enc(buildId)}/cancel`, {}, this.#ctx().authorization);
+    }
+    builderAvailability(organizationId) {
+        return this.#ctx().http.json('GET', `/v1/organizations/${enc(organizationId)}/template-builder-availability`, {}, this.#ctx().authorization);
+    }
+    /**
+     * Polls until the build is settled and returns it: failed | canceled, or published with its registration
+     * `registered` (the version exists; `template_version`) or `failed`. Legacy builds end `succeeded`.
+     * Throws TemplateBuildTimeoutError at the deadline (default 30 min); the build continues.
+     */
+    async waitForBuild(organizationId, buildId, opts = {}) {
+        const { sleep } = this.#ctx();
+        const timeoutMs = opts.timeoutMs ?? 1_800_000;
+        const maxInterval = opts.maxPollIntervalMs ?? 10_000;
+        let interval = opts.pollIntervalMs ?? 1_000;
+        const started = Date.now();
+        for (;;) {
+            const build = await this.get(organizationId, buildId);
+            if (buildSettled(build))
+                return build;
+            const waited = Date.now() - started;
+            if (waited >= timeoutMs)
+                throw new TemplateBuildTimeoutError(build, waited);
+            await sleep(Math.max(10, Math.min(interval, timeoutMs - waited)));
+            if (opts.signal?.aborted)
+                throw opts.signal.reason instanceof Error ? opts.signal.reason : new Error('aborted');
+            interval = Math.min(maxInterval, interval * 2);
+        }
+    }
+}
+export class TemplatesApi {
+    #ctx;
+    builds;
+    constructor(ctx) {
+        this.#ctx = ctx;
+        this.builds = new TemplateBuildsApi(ctx);
+    }
+    /** Templates the API key's organization can use (platform + its own), with the version `open` picks. */
+    async list(params = {}) {
+        const path = params.organizationId === undefined ? '/v1/templates' : `/v1/organizations/${enc(params.organizationId)}/templates`;
+        const page = await this.#ctx().http.json('GET', path, { query: { include_archived: params.includeArchived, owner: params.owner, 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);
+    }
+    /** One template by slug: versions, compatibility, caps, installed tools, plan clamping and what `open` resolves to. */
+    get(slug, params = {}) {
+        const path = params.organizationId === undefined ? `/v1/templates/${enc(slug)}` : `/v1/organizations/${enc(params.organizationId)}/templates/${enc(slug)}`;
+        return this.#ctx().http.json('GET', path, { query: { include_archived: params.includeArchived, owner: params.owner } }, this.#ctx().authorization);
+    }
+    /** Like get() but resolves to null on 404 (unknown slug or outside the organization). */
+    async find(slug, params = {}) {
+        try {
+            return await this.get(slug, params);
+        }
+        catch (err) {
+            if (err instanceof ShardfluxApiError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+}

package/dist/tokens.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Workspace tool-token lifecycle: one manager per (workspace, agent label,
+ * tools). Tokens are fetched lazily from POST /v1/workspaces/{id}/tool-tokens,
+ * reused until `refreshSkewMs` before expiry, refreshed with single-flight
+ * (concurrent callers share one request), and invalidated on the cell's
+ * `409 stale_epoch` or `401` so the next call gets a fresh token (and, after a
+ * move, a possibly different cell endpoint).
+ */
+import type { components } from './generated/app-api.js';
+import type { HttpClient } from './http.js';
+export type ToolToken = components['schemas']['ToolToken'];
+export type ToolName = ToolToken['tools'][number];
+export interface ToolTokenOptions {
+    agentLabel?: string | undefined;
+    tools?: readonly ToolName[] | undefined;
+    /** Refresh this long before expiry (default 60 s). */
+    refreshSkewMs?: number;
+    now?: () => number;
+}
+export declare class ToolTokenManager {
+    #private;
+    readonly workspaceId: string;
+    readonly agentLabel: string | undefined;
+    readonly tools: readonly ToolName[] | undefined;
+    /** Number of tokens fetched from the API (observability / tests). */
+    fetched: number;
+    constructor(http: HttpClient, authorization: string, workspaceId: string, opts?: ToolTokenOptions);
+    /** Accepts a token obtained elsewhere (e.g. the one returned by a 200 open). */
+    seed(token: ToolToken): void;
+    get current(): ToolToken | undefined;
+    get(): Promise<ToolToken>;
+    /** Forces a new token (single-flight). */
+    refresh(): Promise<ToolToken>;
+    invalidate(): void;
+}

package/dist/tokens.js

@@ -0,0 +1,61 @@
+export class ToolTokenManager {
+    workspaceId;
+    agentLabel;
+    tools;
+    #http;
+    #authorization;
+    #skew;
+    #now;
+    #current;
+    #inflight;
+    /** Number of tokens fetched from the API (observability / tests). */
+    fetched = 0;
+    constructor(http, authorization, workspaceId, opts = {}) {
+        this.#http = http;
+        this.#authorization = authorization;
+        this.workspaceId = workspaceId;
+        this.agentLabel = opts.agentLabel;
+        this.tools = opts.tools;
+        this.#skew = opts.refreshSkewMs ?? 60_000;
+        this.#now = opts.now ?? Date.now;
+    }
+    /** Accepts a token obtained elsewhere (e.g. the one returned by a 200 open). */
+    seed(token) {
+        if (token.workspace_id === this.workspaceId)
+            this.#current = token;
+    }
+    get current() {
+        return this.#current;
+    }
+    #fresh(t) {
+        return t !== undefined && Date.parse(t.expires_at) - this.#now() > this.#skew;
+    }
+    async get() {
+        if (this.#fresh(this.#current))
+            return this.#current;
+        return this.refresh();
+    }
+    /** Forces a new token (single-flight). */
+    refresh() {
+        this.#inflight ??= (async () => {
+            try {
+                const body = {};
+                if (this.agentLabel !== undefined)
+                    body.agent_label = this.agentLabel;
+                if (this.tools !== undefined)
+                    body.tools = [...this.tools];
+                const token = await this.#http.json('POST', `/v1/workspaces/${encodeURIComponent(this.workspaceId)}/tool-tokens`, { json: body }, this.#authorization);
+                this.fetched += 1;
+                this.#current = token;
+                return token;
+            }
+            finally {
+                this.#inflight = undefined;
+            }
+        })();
+        return this.#inflight;
+    }
+    invalidate() {
+        this.#current = undefined;
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,91 @@
+import type { ToolName } from './tokens.js';
+import type { Workspace } from './workspace.js';
+export interface JsonSchema {
+    type?: 'object' | 'string' | 'integer' | 'number' | 'boolean' | 'array';
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    items?: JsonSchema;
+    enum?: readonly (string | number)[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+    default?: unknown;
+}
+export interface WorkspaceTool<A extends Record<string, unknown> = Record<string, unknown>, R = unknown> {
+    name: string;
+    description: string;
+    parameters: JsonSchema & {
+        type: 'object';
+    };
+    /** Which workspace tool permission the call needs (exec, files, pty, process, git, browser). */
+    permission: ToolName;
+    execute(args: A, options?: {
+        signal?: AbortSignal;
+    }): Promise<R>;
+}
+export declare class ToolArgumentError extends Error {
+    readonly tool: string;
+    readonly issues: string[];
+    constructor(tool: string, issues: string[]);
+}
+/** Validates the JSON-Schema subset used by the tool definitions. Returns problems (empty = valid). */
+export declare function validateArgs(schema: JsonSchema, value: unknown, path?: string): string[];
+export interface WorkspaceToolsOptions {
+    /** Tool permissions to expose (default: the tools of the workspace's last token, else all). */
+    tools?: ToolName[];
+    /** Attribution label for the tokens these tools use (one agent session per label). */
+    agentLabel?: string;
+    /** Prefix for tool names, e.g. "workspace_" (default none). */
+    prefix?: string;
+    /** Bytes of command output / file content returned to the model (default 64 KiB). */
+    maxOutputBytes?: number;
+    /** Working directory for exec when the model gives none (default the guest user's home). */
+    defaultCwd?: string;
+}
+/** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
+export declare function workspaceTools(workspace: Workspace, opts?: WorkspaceToolsOptions): WorkspaceTool[];
+/** OpenAI tool definitions: Chat Completions (`{type:'function', function:{...}}`) or Responses API. */
+export declare function toOpenAITools(tools: readonly WorkspaceTool[], opts?: {
+    api?: 'chat' | 'responses';
+}): {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: JsonSchema & {
+        type: "object";
+    };
+    strict: boolean;
+}[] | {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: JsonSchema & {
+            type: "object";
+        };
+    };
+}[];
+/** Anthropic Messages API tool definitions (`{ name, description, input_schema }`). */
+export declare function toAnthropicTools(tools: readonly WorkspaceTool[]): {
+    name: string;
+    description: string;
+    input_schema: JsonSchema & {
+        type: "object";
+    };
+}[];
+/**
+ * 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 declare function executeToolCall(tools: readonly WorkspaceTool[], call: {
+    name: string;
+    arguments?: string | Record<string, unknown>;
+    input?: Record<string, unknown>;
+}, options?: {
+    signal?: AbortSignal;
+}): Promise<unknown>;