@toshicloud/sdk 0.5.1 → 0.7.0

package/README.md

@@ -1,22 +1,34 @@
-# toshi-ts
+<p align="center">
+  <img src="docs/assets/toshi-logo.svg" alt="Toshi" width="120">
+</p>
 
-A TypeScript client for the Toshi Workspace API, `toshi.workspace.v1`,
-published as ES modules with type declarations.
+<h1 align="center">toshi-ts</h1>
 
-```sh
-npm install @toshicloud/sdk @bufbuild/protobuf @connectrpc/connect
-```
+<p align="center">The TypeScript SDK for the Toshi API.</p>
 
-The browser entry needs a transport such as `@connectrpc/connect-web`; the
-Node entry needs `@connectrpc/connect-node`. Both are peer dependencies, so
-install the ones your application uses.
+<p align="center">
+  <img alt="licence" src="https://img.shields.io/badge/licence-Apache--2.0-blue">
+  <img alt="node" src="https://img.shields.io/badge/node-22%2B-339933">
+  <img alt="status" src="https://img.shields.io/badge/status-early-orange">
+</p>
 
-Versions up to 0.1.2 were published as `@toshicloud/toshi-ts`.
+<p align="center">
+  <a href="docs/usage.md">Get started</a> ·
+  <a href="docs/usage.md">Docs</a> ·
+  <a href="https://github.com/toshicloud/toshi-ts/issues">Issues</a>
+</p>
 
-## Using the client
+A TypeScript client for the Toshi Workspace API, `toshi.workspace.v1`, published as ES modules with type declarations, for Node and browser programs that start jobs, sandboxes and services on Toshi and follow them. It retries safe calls, resumes watches and ships an in-memory fake Toshi for tests.
 
-In Node, `@toshicloud/sdk/node` builds the transport and fills the server
-and the token from the environment:
+> **Early stage.** The package stays at 0.x until a Toshi release serves the API; the latest release is the one to use.
+> Interfaces may change before 1.0.
+> Read the [release notes](https://github.com/toshicloud/toshi-ts/releases) when upgrading.
+
+## Quick start
+
+```sh
+npm install @toshicloud/sdk @bufbuild/protobuf @connectrpc/connect @connectrpc/connect-node
+```
 
 <!-- examples/quick-start.ts -->
 
@@ -29,450 +41,22 @@ const { projects } = await toshi.project.listProjects({});
 console.log(projects.length);
 ```
 
-In a browser, with `@connectrpc/connect-web`:
-
-<!-- examples/browser.ts -->
-
-```ts
-import { createConnectTransport } from "@connectrpc/connect-web";
-import { createToshiClient } from "@toshicloud/sdk";
-
-// The token the browser app already holds.
-declare const token: string;
-
-export const toshi = createToshiClient({
-  transport: (interceptors) =>
-    createConnectTransport({ baseUrl: "https://toshi.example.com", interceptors }),
-  token,
-  project: "default",
-});
-```
-
-Interceptors of your own go before the client's. The Node entry takes
-`interceptors`; with a transport of your own, put them first:
-`interceptors: [...mine, ...interceptors]`. Each unary call enters them
-once, with its retries inside, and they never see the Authorization
-header: the client sets it on a copy of the request below them.
-
-The browser entry reads no environment variable and no file. The Node
-entry reads `TOSHI_SERVER`, `TOSHI_TOKEN`, `TOSHI_TOKEN_FILE` and
-`TOSHI_CA_FILE`; see Node options.
-
-### Options
-
-- `tokenSource`: a function that gives each request attempt its token, so a
-  refreshed token is used without a new client; it wins over `token`. See
-  Tokens that change.
-- `token`: sent as `Authorization: Bearer <token>` on every call.
-- `project`, `environment`: fill the request's `project` and
-  `environment` fields when they are empty. A value in the request wins.
-  `environment` is left empty on a request with `shared: true`.
-- `retry`: `{ maxAttempts, initialBackoffMs, maxBackoffMs }`, by default
-  5, 200 ms and 10 s, with full jitter. Reads, and the calls whose request
-  takes a `request_key`, are retried; a stream and every other call is not.
-  `retry: false` turns off retries and watch reconnects.
-- `defaultTimeoutMs`: bounds each unary call except the Wait calls,
-  which their request's timeout bounds; streams ignore it.
-
-A call may set `timeoutMs` instead: it bounds the whole call, retries
-included, and on a watch it bounds the open. It composes with `signal`.
-`ToshiOptions` is the object the client takes, and `CallOptions` the second
-argument of each call, which carries `signal` and `timeoutMs`.
-
-### Node options
-
-`@toshicloud/sdk/node` builds a connect-node transport over HTTP/2 and
-fills what is missing from the environment:
-
-- `server`, else `TOSHI_SERVER`: the control plane's URL. Without either,
-  the client refuses to start.
-- `tokenSource`, `token`, `tokenFile`, `TOSHI_TOKEN`, `TOSHI_TOKEN_FILE`, in
-  that order. A token file is trimmed, and an empty file is an error.
-- `caFile`, else `TOSHI_CA_FILE`: a PEM bundle trusted besides Node's
-  built-in roots.
-- `userAgent`: put in front of the User-Agent, for example "myapp/1.2".
-- `interceptors`: run before the client's own, in the order given.
-- `defaultTimeoutMs`: bounds each unary call except the Wait calls,
-  which their request's timeout bounds; streams ignore it.
-- `transport`: a transport of your own; then `server` and `caFile` are not
-  required.
-
-Every request carries `User-Agent: toshi-ts/<version> (node/<node
-version>)`, with `userAgent` and one space in front when it is set. The
-root entry sends no User-Agent: browsers own it.
-
-### Tokens that change
-
-`tokenSource` gives the client a function it calls for the token of every
-request attempt, so a token that is refreshed, for example from a secret
-manager, is used without a new client. It wins over every other token
-option. The client asks it once per attempt, a retry included, and may
-ask it concurrently, so it must be fast: keep the token somewhere and
-refresh it outside the call. A source that throws, or that answers an
-empty token, fails the call with `UNAUTHENTICATED`, with the error as the
-cause, and the call is not retried.
-
-<!-- examples/token-source.ts -->
-
-```ts
-// A token a refresh loop replaces; the client asks for it on every call.
-let token = "first-token";
-
-export const toshi = createToshiClient({
-  project: "default",
-  tokenSource: () => token,
-});
-
-export function rotate(next: string): void {
-  token = next;
-}
-```
-
-A token file, from `tokenFile` or `TOSHI_TOKEN_FILE`, is read again
-before a request when its modification time or size has changed, so a
-rotated token, such as a Kubernetes projected service account token, is
-picked up without a new client.
-
-### 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`, `grant`, `storageProvider`, `product`, `discovery`, `connection`,
-`role`, `trigger`, `account`, `image` and `domain`, 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`, `start` and `stop` on a sandbox,
-`start`, `stop`, `setMode`, `listRuns`, `wake`, `hold`, `release`,
-`listRevisions`, `getRevision`, `rollback` and `listActivations` 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.
-
-<!-- examples/client-shape.ts -->
-
-```ts
-const { jobs } = await toshi.workload.jobs.list({ pageSize: 10 });
-const { job } = await toshi.workload.jobs.get({ id: jobs[0].id });
-console.log(job?.id);
-```
-
-### Lists
-
-`workload.jobs.all`, `workload.sandboxes.all`,
-`workload.sandboxes.allPreviewShareLinks`, `workload.services.all`,
-`workload.services.allRuns` and `workload.allEvents` take the request their
-`list` method takes and yield every item, one page after another. Each
-response's `nextPageToken` becomes the next request's `pageToken`, and a
-`pageToken` in the request resumes from that page. A service with no
-`all` method is one `paginate` call away: it takes the list call and a
-function that picks a response's items.
-
-<!-- examples/lists.ts -->
-
-```ts
-import { paginate } from "@toshicloud/sdk";
+The Node entry reads `TOSHI_SERVER` and `TOSHI_TOKEN` from the environment; the [usage guide](docs/usage.md) continues from there, including the browser entry.
 
-import { toshi } from "./client.js";
+## Documentation
 
-// Every job that matches the request, one page after another.
-for await (const job of toshi.workload.jobs.all({ pageSize: 10 })) {
-  console.log(job.id);
-}
-
-// A service with no all() method: paginate takes its list call and items.
-for await (const project of paginate(
-  {},
-  (req, opts) => toshi.project.listProjects(req, opts),
-  (resp) => resp.projects,
-)) {
-  console.log(project.name);
-}
-```
-
-`paginate` sends a copy of the request, so the caller's request keeps its
-fields. Every page is a call of its own, so `opts` goes to each one, and
-`timeoutMs` bounds a page and not the whole iteration. An error throws once
-and ends the iteration; leaving the loop sends no further request.
-`PageRequest` is a list request, which may name the page to read first with
-`pageToken`, and `PageResponse` a list response, which names the page after
-it with `nextPageToken`.
-
-### Retries
-
-The client retries a read, and a write that carries a request key, when
-the connection fails: a `ConnectError` with code `Unavailable`, a
-connection reset or destroyed stream that `@connectrpc/connect-node`
-reports, or a stream the server refused before reading it
-(`REFUSED_STREAM`). A write that takes a request key gets a random one when the
-request has none, so the server applies a retried write once. Other
-writes are never retried.
-
-A `ResourceExhausted` refusal that names how long to wait, as the API's
-rate limit does, is retried the same way. The wait comes from its
-`google.rpc.RetryInfo` detail, else from its `Retry-After` header. So is an
-HTTP 429 with a `Retry-After`, which reaches the client as `Unavailable`.
-The client waits the longer of that wait and the backoff, never more than
-`maxBackoffMs`, and stops when the call's signal aborts. A
-`ResourceExhausted` that names no wait, such as a plan's limit, reaches the
-caller unchanged, as do every other error the server sends, including
-`Aborted` and `InvalidArgument`, and any connection failure the client
-cannot tell apart from a server error.
-
-`RetryPolicy` says how often and how long a call is retried, `maxAttempts`
-counting the first try; `defaultRetryPolicy` is the default — five
-attempts, a 200 ms initial backoff and a 10 s cap.
-
-### Waiting and watching
-
-- `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. A
-  call starts at least a second, and at most 1.2 seconds, after the start of
-  the one before, and a signal ends a pause with its own error.
-- `workload.getOperation(req)` returns one operation by id: a call that
-  takes long hands one back, and this asks for it again.
-- An event's payload says what happened: a trigger's `TriggerResult` names
-  the key's `reason` and its workload, and with `process_exited` or
-  `setup_failed` it carries the sandbox's `exitCode` and `message`.
-- `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`).
-
-<!-- examples/watch-events.ts -->
-
-```ts
-const id = "workload-id";
-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.
-```
-
-Every helper takes `{ signal }`, an `AbortSignal` that ends it.
-
-### Running a command
-
-`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
-client holds at most one buffer of input. `closeStdin` ends standard input
-after a pending write, and a later `write` is refused. `wait` settles when
-the command ends.
-
-<!-- examples/execute.ts -->
-
-```ts
-const id = "sandbox-id";
-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) {
-  process[chunk.stream].write(chunk.data);
-}
-await proc.wait(); // rejects with ExitError on a non-zero exit
-```
-
-Without a loop, `wait()` reads and drops the output itself. It rejects
-with `ExitError` when the command fails, is cancelled or ends without an
-exit status, and with `StreamLostError` when the stream ends first. The
-client never runs a command again by itself. Standard input cannot be
-replayed, so the caller decides whether to start again with the same
-`requestKey`. Leaving the loop early cancels the stream, and `wait()`
-then rejects with a `Canceled` error.
-
-Execute needs a bidirectional stream: `@connectrpc/connect-node` with
-`httpVersion: "2"`. In a browser, `execute` rejects at once and makes no
-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.
-
-<!-- examples/run-job.ts -->
-
-```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.
-
-## Products that are off
-
-A call for a product that is off for the workspace rejects with a
-`ProductError`, `wait`, the watches and `execute` included.
-`isProductError(err)` tells it apart. It is still a `ConnectError` with the
-same `code`, and it has the product's ID (`product`), the `reason`
-(`ProductReason.Unavailable`), the input that turned the product off
-(`productCause`: `build`, `operator`, `plan` or `workspace`) and, for a
-product the deployment turns off, how far it has wound down (`state`:
-`no_new_work`, `draining` or `stopped`).
-
-<!-- examples/product-error.ts -->
-
-```ts
-import { isProductError } from "@toshicloud/sdk";
-
-import { toshi } from "./client.js";
-
-// Turn a product on for the workspace.
-const enable = { id: "acme_ci", enabled: true };
-try {
-  await toshi.product.updateProduct(enable);
-} catch (err) {
-  if (!isProductError(err)) {
-    throw err;
-  }
-  // Off for the workspace: which product, the input that turns it off, and,
-  // for the deployment's config, how far it has wound down.
-  console.log(err.product, err.productCause, err.state);
-}
-```
-
-## Refusals with a reason
-
-A refusal that is not a product's rejects with a `RefusalError`;
-`isRefusalError(err)` tells it apart. It is still a `ConnectError` with the
-same `code`, and its `reason` is one of `RefusalReason`:
-`RefusalReason.ImageInUse` when an image a workload or a revision still uses
-cannot be deleted, `RefusalReason.ImageNotReady` when a job, a sandbox or a
-service revision names a workspace image with no ready version,
-`RefusalReason.PlanExcludesImages` when the plan has no images, `RefusalReason.LastIdentity` when the caller's last identity cannot
-be unlinked, and so on for images, volumes, roles and display sessions.
-
-`workload.services.rollback` asks the revision's registry whether it still
-serves the revision's image before it selects it, and refuses with
-`RefusalReason.ImageNotServed` when the registry answered that it does not
-serve the image, or `RefusalReason.ImageCheckFailed` when it could not say.
-A revision's `imageCheck` carries the last answer: its `outcome`, the
-registry's `status` and `message`, and when it was asked, `checkedAt`.
-Reading a revision asks no registry.
-
-## Testing with `@toshicloud/sdk/test`
-
-`createFake()` serves the whole Workspace API in memory: no server, no port,
-nothing to close, and no Node module, so it runs in the same runtimes as the
-client. `fake.client()` returns a `ToshiClient` wired to it, with the token
-`test-token` and the scope `default`/`production`, which is enough to drive
-`run`, the watchers and the generated clients from a test.
-
-<!-- examples/testing.ts -->
-
-```ts
-import { createFake } from "@toshicloud/sdk/test";
-
-const fake = createFake();
-fake.job("job-1").stdout("deployed\n").exitCode(0);
-
-const toshi = fake.client();
-const run = await toshi.run({ spec: { command: { argv: ["./deploy.sh"] } } });
-for await (const chunk of run) {
-  process[chunk.stream].write(chunk.data);
-}
-await run.wait();
-```
-
-`fake.on(method, impl)` replaces the state machine for one method with a hook
-typed by that method: one call for unary, server-stream and bidirectional
-methods alike. `fake.calls()` returns every call the fake received, oldest
-first, with the procedure, the request and the headers.
-
-## Generated code
-
-`src/gen/toshi/workspace/v1/` is generated by
-[`protoc-gen-es`](https://github.com/bufbuild/protobuf-es) from the protos
-in `proto/toshi/workspace/v1` of the
-[toshi-api](https://github.com/toshicloud/toshi-api) repository, one
-`*_pb.ts` file per proto, and `src/gen/toshi/permission_pb.ts` from
-`proto/toshi/permission.proto`, which they import. The generated code is committed and imports
-only `@bufbuild/protobuf`, so installing the package needs no generator.
-
-`pin.env` names the toshi-api commit the code is generated from:
-`2184ae8440834bb5b91991b3e4d62d14ce9dd15a` today, the commit of the
-release tag `v0.4.1`. `mise.toml` pins the versions of Node, pnpm and `buf`;
-`package.json` pins `protoc-gen-es` at the same version as the
-`@bufbuild/protobuf` development dependency.
-
-To regenerate:
-
-```sh
-mise install
-pnpm install --frozen-lockfile
-mise exec -- scripts/generate.sh
-```
-
-Moving to another commit or tag is one pull request that changes
-`pin.env` and `src/gen/` together. CI regenerates the code from `pin.env`
-and fails if the result differs from what is committed
-(`scripts/check-generated.sh`).
-
-## Versions
-
-The package's major version follows the API's: `1.x` will serve
-`toshi.workspace.v1`, and a `toshi.workspace.v2` gets a new major
-version. Until a Toshi release serves the API, the package stays at
-`0.x` and is generated from a pinned commit. `VERSION` is the package
-version, the one `package.json` carries.
-
-## Publishing
-
-Releases are published to npm by the publish workflow
-(`.github/workflows/publish.yml`) through npm trusted publishing: the
-workflow authenticates with its GitHub OIDC token, and no npm token
-exists. It runs on a `vX.Y.Z` tag that matches the version in
-`package.json`. A new version is a commit on `main` that sets the version
-in `package.json`, followed by its tag.
-
-## Integration test
-
-`test/integration/` runs the client against a real `toshi serve` over
-HTTPS with a test CA it mints itself. `TOSHI_INTEGRATION_BIN` names the
-`toshi` binary it runs; when `TOSHI_INTEGRATION_EXPECT_COMMIT` is set, the
-binary must report that commit:
-
-```sh
-TOSHI_INTEGRATION_BIN=/path/to/toshi mise exec -- pnpm vitest run test/integration
-```
+- [Usage](docs/usage.md): the client, options, retries, lists, watches, commands and jobs
+- [Errors](docs/errors.md): products that are off and refusals with a reason
+- [Testing with `@toshicloud/sdk/test`](docs/testing.md): the in-memory fake
+- [Development](docs/development.md): generated code, versions, publishing and the integration test
+- [The package on npm](https://www.npmjs.com/package/@toshicloud/sdk)
+- [The Toshi API](https://github.com/toshicloud/toshi-api) the client calls
+- [Releases](https://github.com/toshicloud/toshi-ts/releases)
+- [Security](SECURITY.md) · [Licence](LICENSE)
 
-The Toshi server's CI runs it against each server change. Without
-`TOSHI_INTEGRATION_BIN`, `pnpm test` skips the integration test and says
-why.
+## Status and support
 
-## Licence
+Issues and questions go to [GitHub issues](https://github.com/toshicloud/toshi-ts/issues).
+Security reports follow [SECURITY.md](SECURITY.md).
 
-Apache License 2.0, see LICENSE.
+Apache-2.0

package/dist/client.d.ts

@@ -3,7 +3,7 @@ import type { Client, Interceptor, Transport } from "@connectrpc/connect";
 import { AccountService } from "./gen/toshi/workspace/v1/account_pb.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 { EndpointService } from "./gen/toshi/workspace/v1/endpoints_pb.js";
 import { ConnectionService } from "./gen/toshi/workspace/v1/connections_pb.js";
 import { DiscoveryService } from "./gen/toshi/workspace/v1/discovery_pb.js";
 import { DisplayService } from "./gen/toshi/workspace/v1/display_pb.js";
@@ -13,6 +13,7 @@ import { GrantService } from "./gen/toshi/workspace/v1/grants_pb.js";
 import { ImageService } from "./gen/toshi/workspace/v1/images_pb.js";
 import { HostJobService } from "./gen/toshi/workspace/v1/hostjobs_pb.js";
 import { HostService } from "./gen/toshi/workspace/v1/hosts_pb.js";
+import { ModelCredentialService } from "./gen/toshi/workspace/v1/model_credentials_pb.js";
 import { ProductService } from "./gen/toshi/workspace/v1/products_pb.js";
 import { ProjectService } from "./gen/toshi/workspace/v1/projects_pb.js";
 import { RecordingService } from "./gen/toshi/workspace/v1/recordings_pb.js";
@@ -26,10 +27,10 @@ import { WebhookService } from "./gen/toshi/workspace/v1/webhook_pb.js";
 import { WorkspaceService } from "./gen/toshi/workspace/v1/workspace_service_pb.js";
 import { CreatePreviewShareLinkRequestSchema, ListPreviewShareLinksRequestSchema, RevokePreviewShareLinkRequestSchema, StartSandboxRequestSchema, StopSandboxRequestSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
 import type { CreatePreviewShareLinkResponse, ListPreviewShareLinksResponse, RevokePreviewShareLinkResponse, StartSandboxResponse, StopSandboxResponse } from "./gen/toshi/workspace/v1/workspace_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, GetServiceRevisionRequestSchema, HoldServiceRequestSchema, ListEventsRequestSchema, ListServiceActivationsRequestSchema, ListServiceRevisionsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, RollbackServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
-import type { Event, GetOperationResponse, GetServiceRevisionResponse, HoldServiceResponse, Job, ListEventsResponse, ListServiceActivationsResponse, ListServiceRevisionsResponse, ListServiceRunsResponse, Operation, PreviewShareLink, ReleaseServiceResponse, RollbackServiceResponse, Sandbox, Service, ServiceRun, SetServiceModeResponse, StartServiceResponse, StopServiceResponse, WakeServiceResponse, WatchEventsResponse, WatchOutputResponse } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { CancelJobRequestSchema, CreateJobRequestSchema, CreateSandboxRequestSchema, CreateServiceRequestSchema, DeleteJobRequestSchema, DeleteSandboxRequestSchema, DeleteServiceAlarmRequestSchema, DeleteServiceRequestSchema, EmitWorkloadEventRequestSchema, GetJobRequestSchema, GetSandboxRequestSchema, GetServiceAlarmRequestSchema, GetServiceRequestSchema, ListJobsRequestSchema, ListSandboxesRequestSchema, ListServiceAlarmsRequestSchema, ListServicesRequestSchema, PauseServiceAlarmRequestSchema, ResumeServiceAlarmRequestSchema, RunServiceAlarmNowRequestSchema, SetServiceAlarmRequestSchema, 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, DeleteServiceAlarmResponse, DeleteServiceResponse, EmitWorkloadEventResponse, GetJobResponse, GetSandboxResponse, GetServiceAlarmResponse, GetServiceResponse, ListJobsResponse, ListSandboxesResponse, ListServiceAlarmsResponse, ListServicesResponse, PauseServiceAlarmResponse, ResumeServiceAlarmResponse, RunServiceAlarmNowResponse, SetServiceAlarmResponse, UpdateJobResponse, UpdateSandboxResponse, UpdateServiceResponse, WaitJobResponse, WaitSandboxResponse, WaitServiceResponse, WatchJobsResponse, WatchSandboxesResponse, WatchServicesResponse } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import { AnswerServiceSignInRequestSchema, CancelServiceSignInRequestSchema, ExecuteStartSchema, GetOperationRequestSchema, GetServiceRevisionRequestSchema, GetServiceSignInStatusRequestSchema, HoldServiceRequestSchema, HoldWorkloadRequestSchema, ListEventsRequestSchema, ListServiceActivationsRequestSchema, ListServiceRevisionsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, ReleaseWorkloadRequestSchema, RollbackServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StartServiceSignInRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import type { AnswerServiceSignInResponse, CancelServiceSignInResponse, Event, GetOperationResponse, GetServiceRevisionResponse, GetServiceSignInStatusResponse, HoldServiceResponse, HoldWorkloadResponse, Job, ListEventsResponse, ListServiceActivationsResponse, ListServiceRevisionsResponse, ListServiceRunsResponse, Operation, PreviewShareLink, ReleaseServiceResponse, ReleaseWorkloadResponse, RollbackServiceResponse, Sandbox, Service, ServiceRun, SetServiceModeResponse, StartServiceResponse, StartServiceSignInResponse, 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 {
@@ -62,7 +63,7 @@ export interface ToshiClient {
     readonly secret: Client<typeof SecretService>;
     readonly webhook: Client<typeof WebhookService>;
     readonly display: Client<typeof DisplayService>;
-    readonly channel: Client<typeof ChannelService>;
+    readonly endpoint: Client<typeof EndpointService>;
     readonly recording: Client<typeof RecordingService>;
     readonly volume: Client<typeof VolumeService>;
     readonly artifact: Client<typeof ArtifactService>;
@@ -84,6 +85,7 @@ export interface ToshiClient {
     readonly account: Client<typeof AccountService>;
     readonly image: Client<typeof ImageService>;
     readonly domain: Client<typeof DomainService>;
+    readonly modelCredential: Client<typeof ModelCredentialService>;
     run(req: MessageInitShape<typeof CreateJobRequestSchema>, opts?: CallOptions): Promise<JobRun>;
 }
 /** WorkloadService's calls, grouped by the type they name. */
@@ -97,6 +99,22 @@ export interface WorkloadClient {
     /** Yields every event listEvents lists, following the page token from one page to the next. */
     allEvents(req: MessageInitShape<typeof ListEventsRequestSchema>, opts?: CallOptions): AsyncIterable<Event>;
     watchEvents(req: MessageInitShape<typeof WatchEventsRequestSchema>, opts?: CallOptions): Promise<EventWatch>;
+    /**
+     * Appends an event of type EMITTED, with the name and data given, to a job's, sandbox's or
+     * service's event log, as its guest emits one, and returns it; the workload need not be running.
+     */
+    emitEvent(req: MessageInitShape<typeof EmitWorkloadEventRequestSchema>, opts?: CallOptions): Promise<EmitWorkloadEventResponse>;
+    /**
+     * Places an operator's hold on a sandbox or service, stopping it if it runs. Only an
+     * operator may call it; the caller sets the operator's reason in the Toshi-Operator-Reason
+     * header with an interceptor, since the client sends none itself.
+     */
+    holdWorkload(req: MessageInitShape<typeof HoldWorkloadRequestSchema>, opts?: CallOptions): Promise<HoldWorkloadResponse>;
+    /**
+     * Lifts an operator's hold and starts nothing. Only an operator may call it; the caller
+     * sets the operator's reason in the Toshi-Operator-Reason header with an interceptor.
+     */
+    releaseWorkload(req: MessageInitShape<typeof ReleaseWorkloadRequestSchema>, opts?: CallOptions): Promise<ReleaseWorkloadResponse>;
     /** Returns one operation: the id a long call hands back, asked for again. */
     getOperation(req: MessageInitShape<typeof GetOperationRequestSchema>, opts?: CallOptions): Promise<GetOperationResponse>;
 }
@@ -162,6 +180,58 @@ export interface ServicesClient {
     rollback(req: MessageInitShape<typeof RollbackServiceRequestSchema>, opts?: CallOptions): Promise<RollbackServiceResponse>;
     /** Returns a service's activations, oldest first. */
     listActivations(req: MessageInitShape<typeof ListServiceActivationsRequestSchema>, opts?: CallOptions): Promise<ListServiceActivationsResponse>;
+    /**
+     * Creates or replaces the service's alarm with this name and returns it: at each instant of its
+     * schedule the alarm publishes its event, with its data, on one of the service's event endpoints.
+     */
+    setAlarm(req: MessageInitShape<typeof SetServiceAlarmRequestSchema>, opts?: CallOptions): Promise<SetServiceAlarmResponse>;
+    /** Returns one alarm and its most recent occurrences, newest first. */
+    getAlarm(req: MessageInitShape<typeof GetServiceAlarmRequestSchema>, opts?: CallOptions): Promise<GetServiceAlarmResponse>;
+    /**
+     * Returns all of a service's alarms, by name, in one answer: the call has no page token, so
+     * there is no `allAlarms`.
+     */
+    listAlarms(req: MessageInitShape<typeof ListServiceAlarmsRequestSchema>, opts?: CallOptions): Promise<ListServiceAlarmsResponse>;
+    /** Removes an alarm and its occurrences; messages it already published stay on the endpoint. */
+    deleteAlarm(req: MessageInitShape<typeof DeleteServiceAlarmRequestSchema>, opts?: CallOptions): Promise<DeleteServiceAlarmResponse>;
+    /** Stops an alarm publishing until it is resumed; pausing a paused alarm changes nothing. */
+    pauseAlarm(req: MessageInitShape<typeof PauseServiceAlarmRequestSchema>, opts?: CallOptions): Promise<PauseServiceAlarmResponse>;
+    /**
+     * Starts a paused alarm again from the next instant of its schedule; instants that passed while
+     * it was paused are not published.
+     */
+    resumeAlarm(req: MessageInitShape<typeof ResumeServiceAlarmRequestSchema>, opts?: CallOptions): Promise<ResumeServiceAlarmResponse>;
+    /**
+     * Publishes the alarm's event once, now, paused or not, and returns the occurrence; it does not
+     * move the alarm's next instant. It takes a request key, so a retried call is applied once.
+     */
+    runAlarmNow(req: MessageInitShape<typeof RunServiceAlarmNowRequestSchema>, opts?: CallOptions): Promise<RunServiceAlarmNowResponse>;
+    /**
+     * Runs one of the service's recipe's sign_in programs and hands back its stream as the server
+     * sends it. The caller reads the started message first, which names the sign-in; then the
+     * output messages, the program's standard output and standard error; answers the program with
+     * `answerSignIn` or ends it early with `cancelSignIn`; and reads the ended message last, which
+     * says how it ended. A sign-in may run for 15 minutes.
+     *
+     * The stream is not retried or resumed: a sign-in has no cursor. Its stream ending for another
+     * reason, as a client that leaves, also ends it, cancelled; the caller starts a new one.
+     */
+    startSignIn(req: MessageInitShape<typeof StartServiceSignInRequestSchema>, opts?: CallOptions): AsyncIterable<StartServiceSignInResponse>;
+    /**
+     * Writes one line, of at most 4 KiB and with no newline in it, to a running sign-in's standard
+     * input; the sign-in's program reads it.
+     */
+    answerSignIn(req: MessageInitShape<typeof AnswerServiceSignInRequestSchema>, opts?: CallOptions): Promise<AnswerServiceSignInResponse>;
+    /**
+     * Ends a running sign-in: its program is cancelled and its stream ends CANCELLED. It returns
+     * once the cancel is asked for, not once the sign-in has ended.
+     */
+    cancelSignIn(req: MessageInitShape<typeof CancelServiceSignInRequestSchema>, opts?: CallOptions): Promise<CancelServiceSignInResponse>;
+    /**
+     * Runs the status commands of the service's recipe and reports, for each sign_in program,
+     * whether it is signed in and what its status command wrote.
+     */
+    getSignInStatus(req: MessageInitShape<typeof GetServiceSignInStatusRequestSchema>, opts?: CallOptions): Promise<GetServiceSignInStatusResponse>;
 }
 /** A live stream of a job's changes. */
 export interface JobWatch extends AsyncIterable<WatchJobsResponse> {