TypeScript SDK

The SDK provides session, file, execution, SSH, and agent operations through one client. The packages have not been published to npm; install them from the supplied checkout or local archives.

Install from local packages

Inside this repository, npm install and npm run build make the SDK available through the npm workspace. To use it in another project, build and pack the local packages:

npm run build
mkdir -p artifacts
npm pack --workspace @assemble-workspace/contracts --pack-destination artifacts
npm pack --workspace @assemble-workspace/sdk --pack-destination artifacts
npm pack --workspace @assemble-workspace/cli --pack-destination artifacts

From your application's directory, install the resulting tarballs together. Replace /path/to/assemble-workspace with your checkout path:

npm install \
  /path/to/assemble-workspace/artifacts/assemble-workspace-contracts-0.1.0.tgz \
  /path/to/assemble-workspace/artifacts/assemble-workspace-sdk-0.1.0.tgz \
  /path/to/assemble-workspace/artifacts/assemble-workspace-cli-0.1.0.tgz

The CLI tarball is optional when you only need the SDK. Keep the contracts and SDK versions together.

Create the client

import { AssembleClient, ApiError } from "@assemble-workspace/sdk";

const client = new AssembleClient({
  apiKey: process.env.ASSEMBLE_API_KEY ?? "",
  baseUrl: process.env.ASSEMBLE_BASE_URL ?? "",
});

The client accepts an optional fetch implementation, maxResponseBytes, and maxStreamLineBytes. The default response bound is 10 MiB and the stream-line bound is 1 MiB. The client has no default base URL. Set ASSEMBLE_BASE_URL=https://assemble-vms-api.fly.dev for the hosted API and ASSEMBLE_API_KEY to your operator-issued product key, or use the URL for your local development service.

Remote service URLs must use HTTPS. HTTP is accepted only for localhost, 127.0.0.1, or [::1]. URLs containing credentials, a query, or a fragment are rejected, and requests do not follow redirects.

Sessions

Method	Returns
`client.sessions.open({name, image?})`	Ready `SessionHandle`
`client.sessions.get(id)`	`SessionHandle` with current metadata
`client.sessions.list({after?, limit?})`	`{items, nextCursor}`
`session.refresh()`	Updated session metadata
`session.pause()` / `session.resume()`	Updated session metadata
`session.delete()`	Completes permanent deletion

A handle exposes id, info, rootDirectory, and homeDirectory. info is the last response received; refresh it when you need current state.

rootDirectory is the persistent project directory mounted at /workspace. homeDirectory is the VM-local HOME used by managed commands. Raw SSH uses the image's login defaults; see Working directory and home.

Files and commands

Method	Returns
`session.files.read(path)`	`Uint8Array`
`session.files.write(path, stringOrBytes)`	Completes the write
`session.files.list(path?)`	Array of direct directory entries; defaults to `.`
`session.exec({command, cwd?, env?, timeoutSeconds?})`	`ExecutionHandle`
`session.execution(id)`	Handle for an existing execution
`execution.events({after?})`	Async iterator of ordered execution events
`execution.wait()` / `execution.refresh()`	Execution metadata
`execution.cancel()`	Metadata after requesting cancellation

wait() returns terminal state; it does not turn a nonzero exit code into an exception. Check state === 'completed' before treating the command as successful. Cancellation is a request; use wait() to observe the result.

SSH and the provided agent

Method	Returns
`session.ssh.create({expiresInMinutes?})`	`{id, command, expiresAt}`
`session.ssh.revoke(accessId)`	Completes the revocation request
`session.agent.run({message, provider?, model?})`	Async iterator of agent events

Agent requests use the operator's default provider and model. Supply both provider and model when overriding those defaults. Each request starts a fresh conversation. Inspect error events and process done as completion. An unexpectedly closed stream raises ApiError with code stream_interrupted.

Cancellation and errors

Request methods accept {signal}. Methods with an input body take it as a second argument, such as session.exec(input, {signal}). sessions.list and ssh.create include signal in their options object. File operations take options after their other arguments: files.read(path, {signal}), files.write(path, data, {signal}), and files.list(path, {signal}).

Aborting an execution stream disconnects the reader. Call execution.cancel() separately to stop the command. Aborting an agent stream requests cancellation of the agent and its active execution.

HTTP and protocol failures use ApiError with code, status, and optional requestId. Fetch/network errors and abort errors pass through. See Troubleshooting for recovery guidance.