@shardflux/sdk 0.5.0

package/dist/workspace.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A workspace handle: the latest view from the application API plus managed
+ * tool tokens and cell clients (one per agent label / tool set).
+ */
+import type { ClientContext, Caps, Operation, WaitOptions, WorkspaceView } from './client.js';
+import { CellClient } from './cell.js';
+import type { CellClientOptions } from './cell.js';
+import { ToolTokenManager } from './tokens.js';
+import type { ToolName, ToolToken } from './tokens.js';
+export declare class Workspace {
+    #private;
+    constructor(ctx: ClientContext, view: WorkspaceView, opts?: {
+        agentLabel?: string | undefined;
+        tools?: ToolName[] | undefined;
+        token?: ToolToken | null;
+    });
+    get id(): string;
+    get key(): string;
+    /** Observed lifecycle state reported by the cell. */
+    get state(): WorkspaceView['observed_state'];
+    get desiredState(): WorkspaceView['desired_state'];
+    /** True when observed and desired state are both `running`. */
+    get ready(): boolean;
+    get cellEndpoint(): string | null;
+    /** Actual grants reported by the cell for the running workspace (null until known). */
+    get grants(): WorkspaceView['grants'];
+    get ceilings(): WorkspaceView['ceilings'];
+    get template(): WorkspaceView['template'];
+    get pendingReason(): string | null;
+    get activeOperation(): WorkspaceView['active_operation'];
+    /** The raw view (GET /v1/workspaces/{id}). */
+    get data(): WorkspaceView;
+    refresh(): Promise<this>;
+    /** Waits for the active operation (if any) and refreshes. */
+    waitUntilReady(opts?: WaitOptions): Promise<this>;
+    delete(opts?: {
+        idempotencyKey?: string;
+    }): Promise<Operation>;
+    suspend(opts?: {
+        idempotencyKey?: string;
+    }): Promise<Operation>;
+    resume(opts?: {
+        idempotencyKey?: string;
+    }): Promise<Operation>;
+    snapshot(opts?: {
+        label?: string;
+        idempotencyKey?: string;
+    }): Promise<Operation>;
+    fork(target: {
+        key: string;
+        caps?: Caps;
+    }, opts?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        operation: Operation;
+        workspace: Workspace;
+    }>;
+    /** Token manager for an agent label / tool set (defaults: those given to open()). */
+    tokens(opts?: {
+        agentLabel?: string;
+        tools?: ToolName[];
+    }): ToolTokenManager;
+    /** Typed client for the cell gateway tools of this workspace. */
+    cell(opts?: {
+        agentLabel?: string;
+        tools?: ToolName[];
+    } & CellClientOptions): CellClient;
+    /** Tools granted by the most recent token (null before one was issued). */
+    get grantedTools(): ToolName[] | null;
+}

package/dist/workspace.js

@@ -0,0 +1,113 @@
+import { CellClient } from "./cell.js";
+import { ToolTokenManager } from "./tokens.js";
+export class Workspace {
+    #view;
+    #ctx;
+    #defaults;
+    #managers = new Map();
+    #cells = new Map();
+    constructor(ctx, view, opts = {}) {
+        this.#ctx = ctx;
+        this.#view = view;
+        this.#defaults = { agentLabel: opts.agentLabel, tools: opts.tools };
+        if (opts.token)
+            this.tokens().seed(opts.token);
+    }
+    get id() {
+        return this.#view.id;
+    }
+    get key() {
+        return this.#view.workspace_key;
+    }
+    /** Observed lifecycle state reported by the cell. */
+    get state() {
+        return this.#view.observed_state;
+    }
+    get desiredState() {
+        return this.#view.desired_state;
+    }
+    /** True when observed and desired state are both `running`. */
+    get ready() {
+        return this.#view.observed_state === 'running' && this.#view.desired_state === 'running' && this.#view.deleted_at === null;
+    }
+    get cellEndpoint() {
+        return this.#view.cell_endpoint;
+    }
+    /** Actual grants reported by the cell for the running workspace (null until known). */
+    get grants() {
+        return this.#view.grants;
+    }
+    get ceilings() {
+        return this.#view.ceilings;
+    }
+    get template() {
+        return this.#view.template;
+    }
+    get pendingReason() {
+        return this.#view.pending_reason;
+    }
+    get activeOperation() {
+        return this.#view.active_operation;
+    }
+    /** The raw view (GET /v1/workspaces/{id}). */
+    get data() {
+        return this.#view;
+    }
+    async refresh() {
+        this.#view = await this.#ctx.http.json('GET', `/v1/workspaces/${encodeURIComponent(this.id)}`, {}, this.#ctx.authorization);
+        return this;
+    }
+    /** Waits for the active operation (if any) and refreshes. */
+    async waitUntilReady(opts = {}) {
+        const op = this.#view.active_operation;
+        if (op)
+            await this.#ctx.workspaces.waitForOperation(op.id, opts);
+        return this.refresh();
+    }
+    delete(opts = {}) {
+        return this.#ctx.workspaces.delete(this.id, opts);
+    }
+    suspend(opts = {}) {
+        return this.#ctx.workspaces.suspend(this.id, opts);
+    }
+    resume(opts = {}) {
+        return this.#ctx.workspaces.resume(this.id, opts);
+    }
+    snapshot(opts = {}) {
+        return this.#ctx.workspaces.snapshot(this.id, opts);
+    }
+    fork(target, opts = {}) {
+        return this.#ctx.workspaces.fork(this.id, target, opts);
+    }
+    /** Token manager for an agent label / tool set (defaults: those given to open()). */
+    tokens(opts = {}) {
+        const agentLabel = opts.agentLabel ?? this.#defaults.agentLabel;
+        const tools = opts.tools ?? this.#defaults.tools;
+        const k = JSON.stringify([agentLabel ?? null, tools ? [...tools].sort() : null]);
+        let m = this.#managers.get(k);
+        if (!m) {
+            m = new ToolTokenManager(this.#ctx.http, this.#ctx.authorization, this.id, { agentLabel, tools });
+            this.#managers.set(k, m);
+        }
+        return m;
+    }
+    /** Typed client for the cell gateway tools of this workspace. */
+    cell(opts = {}) {
+        const { agentLabel, tools, ...cellOpts } = opts;
+        const manager = this.tokens({ ...(agentLabel !== undefined ? { agentLabel } : {}), ...(tools !== undefined ? { tools } : {}) });
+        const k = `${JSON.stringify([agentLabel ?? null, tools ?? null])}`;
+        let c = this.#cells.get(k);
+        if (!c) {
+            c = new CellClient(this.id, manager, { fetch: this.#ctx.fetch, userAgent: this.#ctx.userAgent, sleep: this.#ctx.sleep, ...cellOpts });
+            this.#cells.set(k, c);
+        }
+        return c;
+    }
+    /** Tools granted by the most recent token (null before one was issued). */
+    get grantedTools() {
+        for (const m of this.#managers.values())
+            if (m.current)
+                return [...m.current.tools];
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@shardflux/sdk",
+  "version": "0.5.0",
+  "type": "module",
+  "description": "Shardflux TypeScript SDK: open persistent agent workspaces by key and give your agent workspace tools (exec, files, processes, PTY, git, browser).",
+  "license": "Apache-2.0",
+  "homepage": "https://shardflux.dev",
+  "keywords": [
+    "shardflux",
+    "sdk",
+    "agents",
+    "ai-agents",
+    "sandbox",
+    "workspace",
+    "microvm",
+    "code-execution",
+    "tools"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "24.13.6",
+    "eslint": "10.11.0",
+    "openapi-typescript": "7.13.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.70.1"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "generate": "openapi-typescript ../contracts/openapi/app-api.json -o src/generated/app-api.ts && openapi-typescript ../contracts/openapi/cell-api.yaml --default-non-nullable false -o src/generated/cell-api.ts",
+    "generate:check": "node scripts/check-generated.mjs",
+    "typecheck": "node scripts/check-generated.mjs && tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "node --test test/*.test.ts"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}