@toshicloud/sdk 0.2.0 → 0.3.1

package/README.md

@@ -37,7 +37,7 @@ const toshi = createToshiClient({
   project: "default",
 });
 
-const { projects } = await toshi.projects.listProjects({});
+const { projects } = await toshi.project.listProjects({});
 ```
 
 In a browser, with `@connectrpc/connect-web`:
@@ -70,6 +70,27 @@ server and any CA come from the caller.
   5, 200 ms and 10 s, with full jitter. `retry: false` turns off retries
   and watch reconnects.
 
+### The client's shape
+
+The client has one field per Workspace API service: `project`, `secret`,
+`webhook`, `display`, `channel`, `recording`, `volume`, `artifact`,
+`artifactUpload`, `workspace`, `hostJob`, `host`, `token`, `auditEvent`,
+`filler` and `storageProvider`, each holding that service's generated
+client.
+`workload` holds `WorkloadService`'s calls, grouped by the type they
+name: `workload.jobs`, `workload.sandboxes` and `workload.services`, one
+method for each call (`create`, `get`, `list`, `update`, `delete`,
+`wait`, `watch`, and `cancel` on a job, `execute` on a sandbox, `start`,
+`stop`, `setMode`, `listRuns`, `wake`, `hold` and `release` on a service). The calls that
+span the three types sit on `workload` itself: `listEvents`, `watchEvents`,
+`getOperation` and `waitOperation`. `run` sits at the top of the client, as
+`toshi run` sits at the top of the CLI.
+
+```ts
+const { jobs } = await toshi.workload.jobs.list({ pageSize: 10 });
+const job = await toshi.workload.jobs.get({ id: jobs[0].id });
+```
+
 ### Retries
 
 The client retries a read, and a write that carries a request key, when
@@ -85,22 +106,34 @@ from a server error.
 
 ### Waiting and watching
 
-- `waitWorkload(req)` and `waitOperation(req)` ask again until the
-  workload reaches the state or the operation is done.
-- `watchWorkloads(req)`, `watchEvents(req)` and `watchOutput(req)`
-  resolve to a watch you read with `for await`. A watch opens its stream
-  when you start reading and reconnects after a connection failure from
-  where it stopped: `cursor` for workloads and events, `offsets` (bytes,
-  as `bigint`) for output. With no cursor, `watchWorkloads` lists the
-  workloads first, and `snapshot` holds them once its promise resolves;
-  `watchEvents` yields the past events page by page before the live ones.
-  `close()` or leaving the loop ends the stream. The output watch ends at
-  the output's end.
+- `workload.jobs.wait(req)`, `workload.sandboxes.wait(req)` and
+  `workload.services.wait(req)` ask again until the workload reaches the
+  state; `workload.waitOperation(req)` asks until the operation is done.
+- `workload.getOperation(req)` returns one operation by id: a call that
+  takes long hands one back, and this asks for it again.
+- `workload.listEvents(req)` returns the events after a cursor, oldest
+  first, a page at a time, for a client that polls or catches up after
+  downtime; `workload.watchEvents(req)` is the live form.
+- `workload.jobs.watch(req)`, `workload.sandboxes.watch(req)`,
+  `workload.services.watch(req)`, `workload.watchEvents(req)` and
+  `workload.jobs.watchOutput(req)` resolve to a watch you read with
+  `for await`. A watch opens its stream when you start reading and
+  reconnects after a connection failure from where it stopped: `cursor`
+  for the typed watches and events, `offsets` (bytes, as `bigint`) for
+  output. With no cursor, a typed watch lists that type first, and
+  `snapshot` holds them once its promise resolves; `watchEvents`
+  yields the past events page by page before the live ones. `close()` or
+  leaving the loop ends the stream. The output watch ends at the output's
+  end.
+- Every watch yields the stream's responses: a job watch yields
+  `WatchJobsResponse` (`job`, `cursor`, `type`), an event watch yields
+  `WatchEventsResponse` (`event`), and the output watch yields
+  `WatchOutputResponse` (`stdout`, `stderr` or `end`).
 
 ```ts
-const watch = await toshi.watchEvents({ workloadId: id });
-for await (const event of watch) {
-  console.log(event.name);
+const watch = await toshi.workload.watchEvents({ workloadId: id });
+for await (const { event } of watch) {
+  console.log(event?.name);
 }
 // watch.cursor resumes a later watch after the last event read.
 ```
@@ -109,8 +142,8 @@ Every helper takes `{ signal }`, an `AbortSignal` that ends it.
 
 ### Running a command
 
-`execute(start)` runs a command and resolves once the server has started
-it. The process is one stream of output chunks, `{ stream: "stdout" |
+`workload.sandboxes.execute(start)` runs a command in a running sandbox
+and resolves once the server has started it. The process is one stream of output chunks, `{ stream: "stdout" |
 "stderr", data: Uint8Array }`. `write` sends standard input in frames of
 at most 64 KiB and resolves once the stream has taken the last one; await
 it before the next `write`, which is refused while one is pending, so the
@@ -119,7 +152,10 @@ after a pending write, and a later `write` is refused. `wait` settles when
 the command ends.
 
 ```ts
-const proc = await toshi.execute({ workloadId: id, command: { argv: ["cat"] } });
+const proc = await toshi.workload.sandboxes.execute({
+  sandboxId: id,
+  command: { argv: ["cat"] },
+});
 await proc.write("hello\n");
 await proc.closeStdin();
 for await (const chunk of proc) {
@@ -141,6 +177,26 @@ Execute needs a bidirectional stream: `@connectrpc/connect-node` with
 call. Over a transport without HTTP/2, the call fails with the
 transport's or the server's error.
 
+### Running a job
+
+`run(req)` creates a job with a `CreateJobRequest` and resolves to the
+job and its output, which is what `toshi run` does: `CreateJob`, then
+`WatchOutput`. It yields output chunks like an execution, and `wait()`
+resolves when the job exits 0 and rejects with `JobExitError` otherwise.
+
+```ts
+const run = await toshi.run({
+  spec: { command: { argv: ["./test.sh"] } },
+});
+for await (const chunk of run) {
+  process[chunk.stream].write(chunk.data);
+}
+await run.wait(); // rejects with JobExitError on a non-zero exit
+```
+
+Stopping the loop stops only the output stream: the job keeps running,
+and `workload.jobs.cancel` ends it.
+
 ## Generated code
 
 `src/gen/toshi/workspace/v1/` is generated by

package/dist/client.d.ts

@@ -1,11 +1,24 @@
 import type { MessageInitShape } from "@bufbuild/protobuf";
 import type { Client, Interceptor, Transport } from "@connectrpc/connect";
+import { ArtifactService, ArtifactUploadService } from "./gen/toshi/workspace/v1/artifacts_pb.js";
+import { AuditEventService } from "./gen/toshi/workspace/v1/audit_events_pb.js";
+import { ChannelService } from "./gen/toshi/workspace/v1/channels_pb.js";
 import { DisplayService } from "./gen/toshi/workspace/v1/display_pb.js";
-import { ExecuteStartSchema, WaitOperationRequestSchema, WaitWorkloadRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema, WatchWorkloadsRequestSchema, WorkspaceService } from "./gen/toshi/workspace/v1/workspace_pb.js";
-import type { Event, Operation, WaitWorkloadResponse, WatchOutputResponse, WatchWorkloadsResponse, Workload } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { FillerService } from "./gen/toshi/workspace/v1/fillers_pb.js";
+import { HostJobService } from "./gen/toshi/workspace/v1/hostjobs_pb.js";
+import { HostService } from "./gen/toshi/workspace/v1/hosts_pb.js";
 import { ProjectService } from "./gen/toshi/workspace/v1/projects_pb.js";
+import { RecordingService } from "./gen/toshi/workspace/v1/recordings_pb.js";
 import { SecretService } from "./gen/toshi/workspace/v1/secrets_pb.js";
+import { StorageProviderService } from "./gen/toshi/workspace/v1/storage_providers_pb.js";
+import { TokenService } from "./gen/toshi/workspace/v1/tokens_pb.js";
+import { VolumeService } from "./gen/toshi/workspace/v1/volumes_pb.js";
 import { WebhookService } from "./gen/toshi/workspace/v1/webhook_pb.js";
+import { WorkspaceService } from "./gen/toshi/workspace/v1/workspace_service_pb.js";
+import { CancelJobRequestSchema, CreateJobRequestSchema, CreateSandboxRequestSchema, CreateServiceRequestSchema, DeleteJobRequestSchema, DeleteSandboxRequestSchema, DeleteServiceRequestSchema, GetJobRequestSchema, GetSandboxRequestSchema, GetServiceRequestSchema, ListJobsRequestSchema, ListSandboxesRequestSchema, ListServicesRequestSchema, UpdateJobRequestSchema, UpdateSandboxRequestSchema, UpdateServiceRequestSchema, WaitJobRequestSchema, WaitSandboxRequestSchema, WaitServiceRequestSchema, WatchJobsRequestSchema, WatchSandboxesRequestSchema, WatchServicesRequestSchema } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import type { CancelJobResponse, CreateJobResponse, CreateSandboxResponse, CreateServiceResponse, DeleteJobResponse, DeleteSandboxResponse, DeleteServiceResponse, GetJobResponse, GetSandboxResponse, GetServiceResponse, ListJobsResponse, ListSandboxesResponse, ListServicesResponse, UpdateJobResponse, UpdateSandboxResponse, UpdateServiceResponse, WaitJobResponse, WaitSandboxResponse, WaitServiceResponse, WatchJobsResponse, WatchSandboxesResponse, WatchServicesResponse } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import { ExecuteStartSchema, GetOperationRequestSchema, HoldServiceRequestSchema, ListEventsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import type { GetOperationResponse, HoldServiceResponse, Job, ListEventsResponse, ListServiceRunsResponse, Operation, ReleaseServiceResponse, Sandbox, Service, SetServiceModeResponse, StartServiceResponse, StopServiceResponse, WakeServiceResponse, WatchEventsResponse, WatchOutputResponse } from "./gen/toshi/workspace/v1/workspace_pb.js";
 import type { RetryPolicy } from "./retry.js";
 /** How the client is configured; the caller builds the transport. */
 export interface ToshiOptions {
@@ -21,32 +34,103 @@ export interface ToshiOptions {
 export interface CallOptions {
     signal?: AbortSignal;
 }
-/** The five generated clients plus the helpers that live on top of them. */
+/** One client per Workspace API service, plus the helpers that live on top of them. */
 export interface ToshiClient {
+    readonly project: Client<typeof ProjectService>;
+    readonly secret: Client<typeof SecretService>;
+    readonly webhook: Client<typeof WebhookService>;
+    readonly display: Client<typeof DisplayService>;
+    readonly channel: Client<typeof ChannelService>;
+    readonly recording: Client<typeof RecordingService>;
+    readonly volume: Client<typeof VolumeService>;
+    readonly artifact: Client<typeof ArtifactService>;
+    readonly artifactUpload: Client<typeof ArtifactUploadService>;
+    readonly workload: WorkloadClient;
     readonly workspace: Client<typeof WorkspaceService>;
-    readonly projects: Client<typeof ProjectService>;
-    readonly secrets: Client<typeof SecretService>;
-    readonly webhooks: Client<typeof WebhookService>;
-    readonly displays: Client<typeof DisplayService>;
-    waitWorkload(req: MessageInitShape<typeof WaitWorkloadRequestSchema>, opts?: CallOptions): Promise<WaitWorkloadResponse>;
+    readonly hostJob: Client<typeof HostJobService>;
+    readonly host: Client<typeof HostService>;
+    readonly token: Client<typeof TokenService>;
+    readonly auditEvent: Client<typeof AuditEventService>;
+    readonly filler: Client<typeof FillerService>;
+    readonly storageProvider: Client<typeof StorageProviderService>;
+    run(req: MessageInitShape<typeof CreateJobRequestSchema>, opts?: CallOptions): Promise<JobRun>;
+}
+/** WorkloadService's calls, grouped by the type they name. */
+export interface WorkloadClient {
+    readonly jobs: JobsClient;
+    readonly sandboxes: SandboxesClient;
+    readonly services: ServicesClient;
     waitOperation(req: MessageInitShape<typeof WaitOperationRequestSchema>, opts?: CallOptions): Promise<Operation>;
-    watchWorkloads(req: MessageInitShape<typeof WatchWorkloadsRequestSchema>, opts?: CallOptions): Promise<WorkloadWatch>;
+    /** Lists the events after a cursor, a page at a time; `watchEvents` is the live form. */
+    listEvents(req: MessageInitShape<typeof ListEventsRequestSchema>, opts?: CallOptions): Promise<ListEventsResponse>;
     watchEvents(req: MessageInitShape<typeof WatchEventsRequestSchema>, opts?: CallOptions): Promise<EventWatch>;
+    /** Returns one operation: the id a long call hands back, asked for again. */
+    getOperation(req: MessageInitShape<typeof GetOperationRequestSchema>, opts?: CallOptions): Promise<GetOperationResponse>;
+}
+/** A job's calls: one method for each of WorkloadService's job calls. */
+export interface JobsClient {
+    create(req: MessageInitShape<typeof CreateJobRequestSchema>, opts?: CallOptions): Promise<CreateJobResponse>;
+    get(req: MessageInitShape<typeof GetJobRequestSchema>, opts?: CallOptions): Promise<GetJobResponse>;
+    list(req: MessageInitShape<typeof ListJobsRequestSchema>, opts?: CallOptions): Promise<ListJobsResponse>;
+    update(req: MessageInitShape<typeof UpdateJobRequestSchema>, opts?: CallOptions): Promise<UpdateJobResponse>;
+    delete(req: MessageInitShape<typeof DeleteJobRequestSchema>, opts?: CallOptions): Promise<DeleteJobResponse>;
+    cancel(req: MessageInitShape<typeof CancelJobRequestSchema>, opts?: CallOptions): Promise<CancelJobResponse>;
+    wait(req: MessageInitShape<typeof WaitJobRequestSchema>, opts?: CallOptions): Promise<WaitJobResponse>;
+    watch(req: MessageInitShape<typeof WatchJobsRequestSchema>, opts?: CallOptions): Promise<JobWatch>;
     watchOutput(req: MessageInitShape<typeof WatchOutputRequestSchema>, opts?: CallOptions): Promise<OutputWatch>;
+}
+/** A sandbox's calls: one method for each of WorkloadService's sandbox calls. */
+export interface SandboxesClient {
+    create(req: MessageInitShape<typeof CreateSandboxRequestSchema>, opts?: CallOptions): Promise<CreateSandboxResponse>;
+    get(req: MessageInitShape<typeof GetSandboxRequestSchema>, opts?: CallOptions): Promise<GetSandboxResponse>;
+    list(req: MessageInitShape<typeof ListSandboxesRequestSchema>, opts?: CallOptions): Promise<ListSandboxesResponse>;
+    update(req: MessageInitShape<typeof UpdateSandboxRequestSchema>, opts?: CallOptions): Promise<UpdateSandboxResponse>;
+    delete(req: MessageInitShape<typeof DeleteSandboxRequestSchema>, opts?: CallOptions): Promise<DeleteSandboxResponse>;
+    wait(req: MessageInitShape<typeof WaitSandboxRequestSchema>, opts?: CallOptions): Promise<WaitSandboxResponse>;
+    watch(req: MessageInitShape<typeof WatchSandboxesRequestSchema>, opts?: CallOptions): Promise<SandboxWatch>;
     execute(start: MessageInitShape<typeof ExecuteStartSchema>, opts?: CallOptions): Promise<Process>;
 }
-/** A live stream of workload changes (watch.go:40-60). */
-export interface WorkloadWatch extends AsyncIterable<WatchWorkloadsResponse> {
+/** A service's calls: one method for each of WorkloadService's service calls. */
+export interface ServicesClient {
+    create(req: MessageInitShape<typeof CreateServiceRequestSchema>, opts?: CallOptions): Promise<CreateServiceResponse>;
+    get(req: MessageInitShape<typeof GetServiceRequestSchema>, opts?: CallOptions): Promise<GetServiceResponse>;
+    list(req: MessageInitShape<typeof ListServicesRequestSchema>, opts?: CallOptions): Promise<ListServicesResponse>;
+    update(req: MessageInitShape<typeof UpdateServiceRequestSchema>, opts?: CallOptions): Promise<UpdateServiceResponse>;
+    delete(req: MessageInitShape<typeof DeleteServiceRequestSchema>, opts?: CallOptions): Promise<DeleteServiceResponse>;
+    wait(req: MessageInitShape<typeof WaitServiceRequestSchema>, opts?: CallOptions): Promise<WaitServiceResponse>;
+    watch(req: MessageInitShape<typeof WatchServicesRequestSchema>, opts?: CallOptions): Promise<ServiceWatch>;
+    start(req: MessageInitShape<typeof StartServiceRequestSchema>, opts?: CallOptions): Promise<StartServiceResponse>;
+    stop(req: MessageInitShape<typeof StopServiceRequestSchema>, opts?: CallOptions): Promise<StopServiceResponse>;
+    setMode(req: MessageInitShape<typeof SetServiceModeRequestSchema>, opts?: CallOptions): Promise<SetServiceModeResponse>;
+    release(req: MessageInitShape<typeof ReleaseServiceRequestSchema>, opts?: CallOptions): Promise<ReleaseServiceResponse>;
+    wake(req: MessageInitShape<typeof WakeServiceRequestSchema>, opts?: CallOptions): Promise<WakeServiceResponse>;
+    hold(req: MessageInitShape<typeof HoldServiceRequestSchema>, opts?: CallOptions): Promise<HoldServiceResponse>;
+    listRuns(req: MessageInitShape<typeof ListServiceRunsRequestSchema>, opts?: CallOptions): Promise<ListServiceRunsResponse>;
+}
+/** A live stream of a job's changes. */
+export interface JobWatch extends AsyncIterable<WatchJobsResponse> {
+    readonly cursor: string;
+    readonly snapshot: Job[] | undefined;
+    close(): void;
+}
+/** A live stream of a sandbox's changes. */
+export interface SandboxWatch extends AsyncIterable<WatchSandboxesResponse> {
+    readonly cursor: string;
+    readonly snapshot: Sandbox[] | undefined;
+    close(): void;
+}
+/** A live stream of a service's changes. */
+export interface ServiceWatch extends AsyncIterable<WatchServicesResponse> {
     readonly cursor: string;
-    readonly snapshot: Workload[] | undefined;
+    readonly snapshot: Service[] | undefined;
     close(): void;
 }
-/** A live stream of events (watch.go:261-460). */
-export interface EventWatch extends AsyncIterable<Event> {
+/** A live stream of events; every message is the stream's response. */
+export interface EventWatch extends AsyncIterable<WatchEventsResponse> {
     readonly cursor: string;
     close(): void;
 }
-/** A live stream of a job's output (output.go). */
+/** A live stream of a job's output. */
 export interface OutputWatch extends AsyncIterable<WatchOutputResponse> {
     readonly offsets: {
         readonly stdout: bigint;
@@ -54,7 +138,7 @@ export interface OutputWatch extends AsyncIterable<WatchOutputResponse> {
     };
     close(): void;
 }
-/** One chunk of an execution's output. */
+/** One chunk of output. */
 export type OutputChunk = {
     stream: "stdout";
     data: Uint8Array;
@@ -62,7 +146,7 @@ export type OutputChunk = {
     stream: "stderr";
     data: Uint8Array;
 };
-/** A running execution (execute.go). */
+/** A running execution. */
 export interface Process extends AsyncIterable<OutputChunk> {
     readonly executionId: string;
     readonly requestKey: string;
@@ -70,9 +154,18 @@ export interface Process extends AsyncIterable<OutputChunk> {
     closeStdin(): Promise<void>;
     wait(): Promise<void>;
 }
+/** A job started by `run`: its output as it comes, then its outcome. */
+export interface JobRun extends AsyncIterable<OutputChunk> {
+    readonly job: Job;
+    wait(): Promise<void>;
+}
 /**
  * Creates the client: one normalized retry setting, the auth, scope, key and
  * retry interceptors (auth outermost, retry innermost), one transport for every
- * client and helper (client.go:40-93).
+ * client and helper.
+ *
+ * Since 0.2.0 the workload calls are grouped by the type they name under
+ * `workload`; every other service, WorkspaceService's included, is handed out
+ * as one client.
  */
 export declare function createToshiClient(options: ToshiOptions): ToshiClient;

package/dist/client.js

@@ -1,20 +1,37 @@
 import { create } from "@bufbuild/protobuf";
 import { createClient } from "@connectrpc/connect";
 import { executeCommand } from "./execute.js";
+import { ArtifactService, ArtifactUploadService } from "./gen/toshi/workspace/v1/artifacts_pb.js";
+import { AuditEventService } from "./gen/toshi/workspace/v1/audit_events_pb.js";
+import { ChannelService } from "./gen/toshi/workspace/v1/channels_pb.js";
 import { DisplayService } from "./gen/toshi/workspace/v1/display_pb.js";
-import { ExecuteStartSchema, WaitOperationRequestSchema, WaitWorkloadRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema, WatchWorkloadsRequestSchema, WorkspaceService, } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { FillerService } from "./gen/toshi/workspace/v1/fillers_pb.js";
+import { HostJobService } from "./gen/toshi/workspace/v1/hostjobs_pb.js";
+import { HostService } from "./gen/toshi/workspace/v1/hosts_pb.js";
 import { ProjectService } from "./gen/toshi/workspace/v1/projects_pb.js";
+import { RecordingService } from "./gen/toshi/workspace/v1/recordings_pb.js";
 import { SecretService } from "./gen/toshi/workspace/v1/secrets_pb.js";
+import { StorageProviderService } from "./gen/toshi/workspace/v1/storage_providers_pb.js";
+import { TokenService } from "./gen/toshi/workspace/v1/tokens_pb.js";
+import { VolumeService } from "./gen/toshi/workspace/v1/volumes_pb.js";
 import { WebhookService } from "./gen/toshi/workspace/v1/webhook_pb.js";
+import { WorkspaceService } from "./gen/toshi/workspace/v1/workspace_service_pb.js";
+import { CancelJobRequestSchema, CreateJobRequestSchema, CreateSandboxRequestSchema, CreateServiceRequestSchema, DeleteJobRequestSchema, DeleteSandboxRequestSchema, DeleteServiceRequestSchema, GetJobRequestSchema, GetSandboxRequestSchema, GetServiceRequestSchema, ListJobsRequestSchema, ListSandboxesRequestSchema, ListServicesRequestSchema, UpdateJobRequestSchema, UpdateSandboxRequestSchema, UpdateServiceRequestSchema, WaitJobRequestSchema, WaitSandboxRequestSchema, WaitServiceRequestSchema, WatchJobsRequestSchema, WatchSandboxesRequestSchema, WatchServicesRequestSchema, WorkloadService, } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import { ExecuteStartSchema, GetOperationRequestSchema, HoldServiceRequestSchema, ListEventsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema, } from "./gen/toshi/workspace/v1/workspace_pb.js";
 import { openOutputWatch } from "./output.js";
 import { authInterceptor, keyInterceptor, retryInterceptor, scopeInterceptor } from "./interceptors.js";
 import { normalizeRetry } from "./retry.js";
-import { openEventWatch, openWorkloadWatch } from "./watch.js";
-import { waitOperation, waitWorkload } from "./wait.js";
+import { openEventWatch, openJobWatch, openSandboxWatch, openServiceWatch } from "./watch.js";
+import { runJob } from "./run.js";
+import { waitJob, waitOperation, waitSandbox, waitService } from "./wait.js";
 /**
  * Creates the client: one normalized retry setting, the auth, scope, key and
  * retry interceptors (auth outermost, retry innermost), one transport for every
- * client and helper (client.go:40-93).
+ * client and helper.
+ *
+ * Since 0.2.0 the workload calls are grouped by the type they name under
+ * `workload`; every other service, WorkspaceService's included, is handed out
+ * as one client.
  */
 export function createToshiClient(options) {
     const retry = normalizeRetry(options.retry);
@@ -25,18 +42,67 @@ export function createToshiClient(options) {
         retryInterceptor(retry),
     ];
     const transport = options.transport(interceptors);
-    const workspace = createClient(WorkspaceService, transport);
+    const workloadService = createClient(WorkloadService, transport);
     return {
-        workspace,
-        projects: createClient(ProjectService, transport),
-        secrets: createClient(SecretService, transport),
-        webhooks: createClient(WebhookService, transport),
-        displays: createClient(DisplayService, transport),
-        waitWorkload: (req, opts) => waitWorkload(workspace, create(WaitWorkloadRequestSchema, req), opts),
-        waitOperation: (req, opts) => waitOperation(workspace, create(WaitOperationRequestSchema, req), opts),
-        watchWorkloads: (req, opts) => openWorkloadWatch(workspace, retry, create(WatchWorkloadsRequestSchema, req), opts),
-        watchEvents: (req, opts) => openEventWatch(workspace, retry, create(WatchEventsRequestSchema, req), opts),
-        watchOutput: (req, opts) => openOutputWatch(workspace, retry, create(WatchOutputRequestSchema, req), opts),
-        execute: (start, opts) => executeCommand(workspace, start, opts),
+        project: createClient(ProjectService, transport),
+        secret: createClient(SecretService, transport),
+        webhook: createClient(WebhookService, transport),
+        display: createClient(DisplayService, transport),
+        channel: createClient(ChannelService, transport),
+        recording: createClient(RecordingService, transport),
+        volume: createClient(VolumeService, transport),
+        artifact: createClient(ArtifactService, transport),
+        artifactUpload: createClient(ArtifactUploadService, transport),
+        workload: {
+            jobs: {
+                create: (req, opts) => workloadService.createJob(req, opts),
+                get: (req, opts) => workloadService.getJob(req, opts),
+                list: (req, opts) => workloadService.listJobs(req, opts),
+                update: (req, opts) => workloadService.updateJob(req, opts),
+                delete: (req, opts) => workloadService.deleteJob(req, opts),
+                cancel: (req, opts) => workloadService.cancelJob(req, opts),
+                wait: (req, opts) => waitJob(workloadService, create(WaitJobRequestSchema, req), opts),
+                watch: (req, opts) => openJobWatch(workloadService, retry, create(WatchJobsRequestSchema, req), opts),
+                watchOutput: (req, opts) => openOutputWatch(workloadService, retry, create(WatchOutputRequestSchema, req), opts),
+            },
+            sandboxes: {
+                create: (req, opts) => workloadService.createSandbox(req, opts),
+                get: (req, opts) => workloadService.getSandbox(req, opts),
+                list: (req, opts) => workloadService.listSandboxes(req, opts),
+                update: (req, opts) => workloadService.updateSandbox(req, opts),
+                delete: (req, opts) => workloadService.deleteSandbox(req, opts),
+                wait: (req, opts) => waitSandbox(workloadService, create(WaitSandboxRequestSchema, req), opts),
+                watch: (req, opts) => openSandboxWatch(workloadService, retry, create(WatchSandboxesRequestSchema, req), opts),
+                execute: (start, opts) => executeCommand(workloadService, start, opts),
+            },
+            services: {
+                create: (req, opts) => workloadService.createService(req, opts),
+                get: (req, opts) => workloadService.getService(req, opts),
+                list: (req, opts) => workloadService.listServices(req, opts),
+                update: (req, opts) => workloadService.updateService(req, opts),
+                delete: (req, opts) => workloadService.deleteService(req, opts),
+                wait: (req, opts) => waitService(workloadService, create(WaitServiceRequestSchema, req), opts),
+                watch: (req, opts) => openServiceWatch(workloadService, retry, create(WatchServicesRequestSchema, req), opts),
+                start: (req, opts) => workloadService.startService(req, opts),
+                stop: (req, opts) => workloadService.stopService(req, opts),
+                setMode: (req, opts) => workloadService.setServiceMode(req, opts),
+                release: (req, opts) => workloadService.releaseService(req, opts),
+                wake: (req, opts) => workloadService.wakeService(req, opts),
+                hold: (req, opts) => workloadService.holdService(req, opts),
+                listRuns: (req, opts) => workloadService.listServiceRuns(req, opts),
+            },
+            waitOperation: (req, opts) => waitOperation(workloadService, create(WaitOperationRequestSchema, req), opts),
+            listEvents: (req, opts) => workloadService.listEvents(req, opts),
+            watchEvents: (req, opts) => openEventWatch(workloadService, retry, create(WatchEventsRequestSchema, req), opts),
+            getOperation: (req, opts) => workloadService.getOperation(req, opts),
+        },
+        run: (req, opts) => runJob(workloadService, retry, create(CreateJobRequestSchema, req), opts),
+        workspace: createClient(WorkspaceService, transport),
+        hostJob: createClient(HostJobService, transport),
+        host: createClient(HostService, transport),
+        token: createClient(TokenService, transport),
+        auditEvent: createClient(AuditEventService, transport),
+        filler: createClient(FillerService, transport),
+        storageProvider: createClient(StorageProviderService, transport),
     };
 }

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutionExit } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import type { ExecutionExit, OutputEnd } from "./gen/toshi/workspace/v1/workspace_pb.js";
 /** A command that ended non-zero, or was cancelled before it had a status (errors.go:9-26). */
 export declare class ExitError extends Error {
     /** The execution the exit belongs to. */
@@ -7,6 +7,14 @@ export declare class ExitError extends Error {
     readonly exit: ExecutionExit;
     constructor(executionId: string, exit: ExecutionExit);
 }
+/** A job `run` started that did not exit 0. */
+export declare class JobExitError extends Error {
+    /** The job's id. */
+    readonly jobId: string;
+    /** The job's end-of-output message. */
+    readonly end: OutputEnd;
+    constructor(jobId: string, end: OutputEnd);
+}
 /**
  * An Execute stream that ended before its exit message; stdin cannot be replayed
  * (errors.go:28-49). The cause is the error that ended the stream.

package/dist/errors.js

@@ -11,6 +11,28 @@ export class ExitError extends Error {
         this.exit = exit;
     }
 }
+/** A job `run` started that did not exit 0. */
+export class JobExitError extends Error {
+    /** The job's id. */
+    jobId;
+    /** The job's end-of-output message. */
+    end;
+    constructor(jobId, end) {
+        super(jobMessage(jobId, end));
+        this.name = "JobExitError";
+        this.jobId = jobId;
+        this.end = end;
+    }
+}
+function jobMessage(jobId, end) {
+    if (end.cancelled) {
+        return `toshi: job ${jobId} was cancelled`;
+    }
+    if (end.exitCode === undefined) {
+        return `toshi: job ${jobId} ended without an exit status`;
+    }
+    return `toshi: job ${jobId} exited with status ${end.exitCode}`;
+}
 function exitMessage(executionId, exit) {
     if (exit.cancelled) {
         return `toshi: execution ${executionId} was cancelled`;

package/dist/execute.d.ts

@@ -1,6 +1,7 @@
 import type { MessageInitShape } from "@bufbuild/protobuf";
 import type { Client } from "@connectrpc/connect";
 import type { CallOptions, Process } from "./client.js";
-import { ExecuteStartSchema, WorkspaceService } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { ExecuteStartSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import type { WorkloadService } from "./gen/toshi/workspace/v1/workloads_pb.js";
 /** Starts a command and returns its process; the only export of this module. */
-export declare function executeCommand(workspace: Client<typeof WorkspaceService>, start: MessageInitShape<typeof ExecuteStartSchema> | undefined, opts?: CallOptions): Promise<Process>;
+export declare function executeCommand(service: Client<typeof WorkloadService>, start: MessageInitShape<typeof ExecuteStartSchema> | undefined, opts?: CallOptions): Promise<Process>;

package/dist/execute.js

@@ -3,12 +3,12 @@ import { Code, ConnectError } from "@connectrpc/connect";
 import { createWritableIterable } from "@connectrpc/connect/protocol";
 import { ExitError, StreamLostError } from "./errors.js";
 import { isStreamLoss } from "./retry.js";
-import { ExecuteRequestSchema, ExecuteStartSchema, WorkspaceService, } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { ExecuteRequestSchema, ExecuteStartSchema, } from "./gen/toshi/workspace/v1/workspace_pb.js";
 // The largest standard-input frame Execute sends (execute.go:14-16).
 const STDIN_CHUNK = 64 << 10;
 const BROWSER_MESSAGE = 'toshi: Execute needs a Node transport over HTTP/2 (@connectrpc/connect-node with httpVersion "2"); a browser cannot open a bidirectional stream';
 /** Starts a command and returns its process; the only export of this module. */
-export async function executeCommand(workspace, start, opts) {
+export async function executeCommand(service, start, opts) {
     // G3: the browser check runs before any message or transport work, and reads
     // process only through globalThis so src/ needs no Node import.
     const nodeProcess = globalThis.process;
@@ -43,7 +43,7 @@ export async function executeCommand(workspace, start, opts) {
     const finishHandshake = () => {
         signal?.removeEventListener("abort", onAbort);
     };
-    const responses = workspace.execute(input, { signal: abort.signal });
+    const responses = service.execute(input, { signal: abort.signal });
     const responseIterator = responses[Symbol.asyncIterator]();
     // Send the start and read the answer together: the request stream only moves
     // while the call is running. The created message is the one the interceptors

package/dist/gen/toshi/workspace/v1/artifacts_pb.d.ts

@@ -649,9 +649,9 @@ export declare const GetArtifactResponseSchema: GenMessage<GetArtifactResponse,
     jsonType: GetArtifactResponseJson;
 }>;
 /**
- * @generated from message toshi.workspace.v1.GetDownloadURLRequest
+ * @generated from message toshi.workspace.v1.GetArtifactDownloadURLRequest
  */
-export type GetDownloadURLRequest = Message<"toshi.workspace.v1.GetDownloadURLRequest"> & {
+export type GetArtifactDownloadURLRequest = Message<"toshi.workspace.v1.GetArtifactDownloadURLRequest"> & {
     /**
      * @generated from field: string artifact_id = 1;
      */
@@ -671,9 +671,9 @@ export type GetDownloadURLRequest = Message<"toshi.workspace.v1.GetDownloadURLRe
     ttlSeconds: bigint;
 };
 /**
- * @generated from message toshi.workspace.v1.GetDownloadURLRequest
+ * @generated from message toshi.workspace.v1.GetArtifactDownloadURLRequest
  */
-export type GetDownloadURLRequestJson = {
+export type GetArtifactDownloadURLRequestJson = {
     /**
      * @generated from field: string artifact_id = 1;
      */
@@ -693,16 +693,16 @@ export type GetDownloadURLRequestJson = {
     ttlSeconds?: string;
 };
 /**
- * Describes the message toshi.workspace.v1.GetDownloadURLRequest.
- * Use `create(GetDownloadURLRequestSchema)` to create a new message.
+ * Describes the message toshi.workspace.v1.GetArtifactDownloadURLRequest.
+ * Use `create(GetArtifactDownloadURLRequestSchema)` to create a new message.
  */
-export declare const GetDownloadURLRequestSchema: GenMessage<GetDownloadURLRequest, {
-    jsonType: GetDownloadURLRequestJson;
+export declare const GetArtifactDownloadURLRequestSchema: GenMessage<GetArtifactDownloadURLRequest, {
+    jsonType: GetArtifactDownloadURLRequestJson;
 }>;
 /**
- * @generated from message toshi.workspace.v1.GetDownloadURLResponse
+ * @generated from message toshi.workspace.v1.GetArtifactDownloadURLResponse
  */
-export type GetDownloadURLResponse = Message<"toshi.workspace.v1.GetDownloadURLResponse"> & {
+export type GetArtifactDownloadURLResponse = Message<"toshi.workspace.v1.GetArtifactDownloadURLResponse"> & {
     /**
      * @generated from field: string url = 1;
      */
@@ -723,9 +723,9 @@ export type GetDownloadURLResponse = Message<"toshi.workspace.v1.GetDownloadURLR
     dataKey: Uint8Array;
 };
 /**
- * @generated from message toshi.workspace.v1.GetDownloadURLResponse
+ * @generated from message toshi.workspace.v1.GetArtifactDownloadURLResponse
  */
-export type GetDownloadURLResponseJson = {
+export type GetArtifactDownloadURLResponseJson = {
     /**
      * @generated from field: string url = 1;
      */
@@ -746,11 +746,11 @@ export type GetDownloadURLResponseJson = {
     dataKey?: string;
 };
 /**
- * Describes the message toshi.workspace.v1.GetDownloadURLResponse.
- * Use `create(GetDownloadURLResponseSchema)` to create a new message.
+ * Describes the message toshi.workspace.v1.GetArtifactDownloadURLResponse.
+ * Use `create(GetArtifactDownloadURLResponseSchema)` to create a new message.
  */
-export declare const GetDownloadURLResponseSchema: GenMessage<GetDownloadURLResponse, {
-    jsonType: GetDownloadURLResponseJson;
+export declare const GetArtifactDownloadURLResponseSchema: GenMessage<GetArtifactDownloadURLResponse, {
+    jsonType: GetArtifactDownloadURLResponseJson;
 }>;
 /**
  * ArtifactUploadService is how a job uploads what it recorded:
@@ -809,6 +809,8 @@ export declare const ArtifactService: GenService<{
      * ListArtifacts returns the workspace's artifacts, oldest first, by
      * project, environment, workload, execution and kind.
      *
+     * A page holds 50 artifacts when page_size is zero, and 200 at most.
+     *
      * @generated from rpc toshi.workspace.v1.ArtifactService.ListArtifacts
      */
     listArtifacts: {
@@ -827,15 +829,15 @@ export declare const ArtifactService: GenService<{
         output: typeof GetArtifactResponseSchema;
     };
     /**
-     * GetDownloadURL returns a signed URL that expires, and the artifact's
-     * data key when it is envelope encrypted. An artifact that is not
-     * complete fails with FAILED_PRECONDITION.
+     * GetArtifactDownloadURL returns a signed URL that expires, and the
+     * artifact's data key when it is envelope encrypted. An artifact that is
+     * not complete fails with FAILED_PRECONDITION.
      *
-     * @generated from rpc toshi.workspace.v1.ArtifactService.GetDownloadURL
+     * @generated from rpc toshi.workspace.v1.ArtifactService.GetArtifactDownloadURL
      */
-    getDownloadURL: {
+    getArtifactDownloadURL: {
         methodKind: "unary";
-        input: typeof GetDownloadURLRequestSchema;
-        output: typeof GetDownloadURLResponseSchema;
+        input: typeof GetArtifactDownloadURLRequestSchema;
+        output: typeof GetArtifactDownloadURLResponseSchema;
     };
 }>;