@coltonkirsten/a12s 0.3.0 → 0.4.0

package/dist/src/fleet.js

@@ -0,0 +1,306 @@
+// Runs in Node, Deno, Bun and browsers: no node: imports here (`npm run check:browser` enforces it).
+import { A12sClient, A12sError, TurnStream, } from "./client.js";
+const enc = encodeURIComponent;
+const maxReplaceTries = 5;
+/**
+ * A running Fleet. Its agent computers, Services and tokens are in {@link agentComputers}, {@link services} and
+ * {@link tokens}.
+ *
+ * ```ts
+ * const fleet = await Fleet.connect();
+ * const hello = await fleet.agentComputers.create("hello", { instructions: "Be helpful" });
+ * await hello.prompt("hi");
+ * await hello.remove();
+ * ```
+ */
+export class Fleet {
+    /** The lower-level client the handles use, for API calls that have no method here. */
+    client;
+    agentComputers;
+    services;
+    tokens;
+    credentials;
+    /** No discovery: `url` and `token` as given, by default the page's own origin. */
+    constructor(opts = {}) {
+        this.client = new A12sClient(opts);
+        this.agentComputers = new AgentComputers(this.client);
+        this.services = new Services(this.client);
+        this.tokens = new Tokens(this.client);
+        this.credentials = new Credentials(this.client);
+    }
+    /**
+     * In a browser: the Fleet behind the page's own origin, which is `a12s gateway` serving the page (no token
+     * needed). In Node: found like {@link connect} finds it. Pass `url` and `token` to reach anything else.
+     */
+    static async connect(opts = {}) {
+        return new Fleet(opts);
+    }
+    get url() {
+        return this.client.url;
+    }
+    async get() {
+        const r = await this.client.request("GET", "/v1/fleet");
+        return { version: r.version, spec: r.fleet ?? emptySpec(), drift: r.drift ?? [] };
+    }
+    /**
+     * Reads the Fleet, lets `fn` change it (in place, or by returning a new spec) and writes it back only if nobody
+     * wrote in between; otherwise it reads again and retries, up to 5 times. `spec.defaults` is always present.
+     */
+    async replace(fn) {
+        for (let attempt = 1;; attempt++) {
+            const cur = await this.get();
+            cur.spec.defaults ??= {};
+            const next = (await fn(cur.spec)) ?? cur.spec;
+            try {
+                await this.client.request("PUT", "/v1/fleet", { fleet: next }, {
+                    headers: { "if-match": `"${cur.version}"` },
+                });
+            }
+            catch (err) {
+                if (attempt < maxReplaceTries && err instanceof A12sError && err.code === "version_mismatch")
+                    continue;
+                throw err;
+            }
+            return this.get();
+        }
+    }
+    /**
+     * Live events of the named agent computers, or (no argument) all of them, and the Fleet's own (`fleet.changed`,
+     * `agent_computer.phase`). Every stream of this Fleet shares one connection, which reconnects without losing
+     * events. `await stream.ready()` before sending work you want to see from the start; `close()` (or `break`) ends it.
+     * `turn` or `after` (one agent computer) replays from its journal instead.
+     */
+    events(agentComputers, opts = {}) {
+        if (opts.turn !== undefined || opts.after !== undefined)
+            return this.client.events(agentComputers, opts);
+        return this.client.sharedEvents(namesOf(agentComputers), opts);
+    }
+    /** Finished Turns of the named agent computers, or all of them, as they end. */
+    turns(agentComputers, opts = {}) {
+        return new TurnStream(this.client.sharedEvents(namesOf(agentComputers), opts));
+    }
+    /** Every agent computer and Service: phase, session, active Turn, inbox, power. */
+    status() {
+        return this.client.status();
+    }
+}
+function namesOf(names) {
+    return typeof names === "string" ? [names] : names;
+}
+function emptySpec() {
+    return { apiVersion: "a12s.ai/v1alpha1", kind: "Fleet", metadata: { name: "" }, agent_computers: {} };
+}
+function writeHeaders(opts) {
+    return opts.replace ? {} : { "if-none-match": "*" };
+}
+export class AgentComputers {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Adds an agent computer to the Fleet and starts it. Fails with code `exists` if the name is taken. */
+    async create(name, spec = {}) {
+        const { replace, ...body } = spec;
+        const r = await this.client.request("PUT", `/v1/agent-computers/${enc(name)}`, body, {
+            headers: writeHeaders({ replace }),
+        });
+        return r.agentComputer ? new AgentComputer(this.client, r.agentComputer) : this.get(name);
+    }
+    /** Throws {@link NotFound} if there is none. */
+    async get(name) {
+        return new AgentComputer(this.client, await this.client.request("GET", `/v1/agent-computers/${enc(name)}`));
+    }
+    async list() {
+        const r = await this.client.request("GET", "/v1/agent-computers");
+        return (r.agentComputers ?? []).map((d) => new AgentComputer(this.client, d));
+    }
+}
+/** A handle on one agent computer. `spec`, `effective` and `status` are as of the last create, get, reload or update. */
+export class AgentComputer {
+    client;
+    name;
+    spec;
+    /** The spec with the Fleet's defaults merged in. */
+    effective;
+    status;
+    constructor(client, data) {
+        this.client = client;
+        this.name = data.name;
+        this.set(data);
+    }
+    set(d) {
+        this.spec = d.spec;
+        this.effective = d.effective;
+        this.status = d.status;
+        return this;
+    }
+    get path() {
+        return `/v1/agent-computers/${enc(this.name)}`;
+    }
+    async reload() {
+        return this.set(await this.client.request("GET", this.path));
+    }
+    /** Changes the spec: a key set to null goes back to the Fleet's default. A busy one picks it up when idle. */
+    async update(changes) {
+        const r = await this.client.request("PATCH", this.path, changes);
+        return r.agentComputer ? this.set(r.agentComputer) : this.reload();
+    }
+    /** Removes it from the Fleet and stops it; its drives are kept. */
+    async remove() {
+        await this.client.request("DELETE", this.path);
+    }
+    /** Sends a Message, waits for the Turn that delivers it and resolves when that Turn ends. */
+    prompt(text, opts = {}) {
+        return this.client.prompt(this.name, text, opts);
+    }
+    /** Puts a Message in the inbox and returns at once; it is delivered at the next idle moment. */
+    send(text, opts = {}) {
+        return this.client.send(this.name, { ...opts, body: text });
+    }
+    /** Its events, live, from the Fleet's shared connection; `turn` replays one Turn from its start instead. */
+    events(opts = {}) {
+        if (opts.turn !== undefined || opts.after !== undefined)
+            return this.client.events(this.name, opts);
+        return this.client.sharedEvents([this.name], opts);
+    }
+    turns(opts = {}) {
+        const { limit, ...rest } = opts;
+        if (limit !== undefined)
+            return this.pastTurns(limit);
+        return new TurnStream(this.client.sharedEvents([this.name], rest));
+    }
+    async pastTurns(limit) {
+        const r = await this.client.request("GET", `${this.path}/turns?limit=${limit}`);
+        return (r.turns ?? []).map((t) => ({
+            ...t,
+            computer: t.agentComputer,
+            tools: t.tools.map((tc) => ({ ...tc, isError: tc.isError ?? false })),
+        }));
+    }
+    /** Stops its processes and keeps its disks, session and inbox. */
+    sleep() {
+        return this.client.sleep(this.name);
+    }
+    wake() {
+        return this.client.wake(this.name);
+    }
+    /** Interrupts a Turn (default: the active one). */
+    stop(turn) {
+        return this.client.stop(this.name, turn);
+    }
+    inbox(opts = {}) {
+        return this.client.inbox(this.name, opts);
+    }
+    message(id) {
+        return this.client.message(this.name, id);
+    }
+    /** Withdraws a pending Message; a 409 A12sError names its state if it is too late. */
+    withdraw(id) {
+        return this.client.withdraw(this.name, id);
+    }
+}
+export class Services {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Adds a Service to the Fleet. Fails with code `exists` if the name is taken. */
+    async create(name, spec = {}) {
+        const { replace, ...body } = spec;
+        const r = await this.client.request("PUT", `/v1/services/${enc(name)}`, body, {
+            headers: writeHeaders({ replace }),
+        });
+        return r.service ? new Service(this.client, r.service) : this.get(name);
+    }
+    /** Throws {@link NotFound} if there is none. */
+    async get(name) {
+        return new Service(this.client, await this.client.service(name));
+    }
+    async list() {
+        return (await this.client.services()).map((s) => new Service(this.client, s));
+    }
+}
+/** A handle on one Service. `spec` and `status` are as of the last create, get, reload, update or power change. */
+export class Service {
+    client;
+    name;
+    status;
+    constructor(client, status) {
+        this.client = client;
+        this.name = status.name;
+        this.status = status;
+    }
+    /** As written in the Fleet. */
+    get spec() {
+        return this.status.spec ?? {};
+    }
+    get path() {
+        return `/v1/services/${enc(this.name)}`;
+    }
+    async reload() {
+        this.status = await this.client.service(this.name);
+        return this;
+    }
+    /** Changes the spec as a JSON merge patch: a key set to null is removed. */
+    async update(changes) {
+        const r = await this.client.request("PATCH", this.path, changes);
+        if (!r.service)
+            return this.reload();
+        this.status = r.service;
+        return this;
+    }
+    /** Removes it from the Fleet and stops it; its state drive is kept. */
+    async remove() {
+        await this.client.request("DELETE", this.path);
+    }
+    sleep() {
+        return this.power("asleep");
+    }
+    wake() {
+        return this.power("awake");
+    }
+    async power(state) {
+        this.status = await this.client.request("POST", `${this.path}/power`, { state });
+        return this;
+    }
+}
+export class Tokens {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * A token for another program; owner only. The secret is in the result once. With `prefix` it may do everything
+     * the owner can for names that start with it, and nothing outside; otherwise `actions` on `agentComputers`.
+     */
+    create(name, opts) {
+        if ("prefix" in opts) {
+            return this.client.createToken({ name, prefix: opts.prefix });
+        }
+        return this.client.createToken({ name, actions: opts.actions, computers: opts.agentComputers ?? ["*"] });
+    }
+    async list() {
+        return (await this.client.request("GET", "/v1/tokens")).tokens ?? [];
+    }
+    async remove(name) {
+        await this.client.request("DELETE", `/v1/tokens/${enc(name)}`);
+    }
+}
+/** Credentials by name: set once, then name them in a spec's `credentials`. Values are never read back. */
+export class Credentials {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Stores the value on the Controller; agent computers that use it get the new value at once. */
+    set(name, value) {
+        return this.client.request("PUT", `/v1/credentials/${enc(name)}`, { value });
+    }
+    async list() {
+        return (await this.client.request("GET", "/v1/credentials")).credentials ?? [];
+    }
+    /** Fails with A12sError code `in_use` while an agent computer or Service uses it. */
+    async remove(name) {
+        await this.client.request("DELETE", `/v1/credentials/${enc(name)}`);
+    }
+}

package/dist/src/index.d.ts

@@ -1,8 +1,11 @@
 import { A12sClient, type A12sClientOptions } from "./client.js";
 export * from "./client.js";
+export * from "./fleet.js";
 export * from "./types.js";
 export type ConnectOptions = A12sClientOptions;
 /**
+ * @deprecated Use `Fleet.connect()`. Kept for one release.
+ *
  * In a browser: a client for the page's own origin, which is `a12s gateway` serving the page (no token needed).
  * Pass `url` and `token` to reach anything else.
  */

package/dist/src/index.js

@@ -1,9 +1,12 @@
 // The default entry (browsers, Deno, workers): no node: imports. Node resolves "@coltonkirsten/a12s" to ./node.ts instead, through
-// the "node" export condition, so `import { connect } from "@coltonkirsten/a12s"` works everywhere.
+// the "node" export condition, so `import { Fleet } from "@coltonkirsten/a12s"` works everywhere.
 import { A12sClient } from "./client.js";
 export * from "./client.js";
+export * from "./fleet.js";
 export * from "./types.js";
 /**
+ * @deprecated Use `Fleet.connect()`. Kept for one release.
+ *
  * In a browser: a client for the page's own origin, which is `a12s gateway` serving the page (no token needed).
  * Pass `url` and `token` to reach anything else.
  */

package/dist/src/node.d.ts

@@ -1,6 +1,12 @@
 import { A12sClient, type A12sClientOptions } from "./client.js";
+import { Fleet as PageFleet } from "./fleet.js";
 export * from "./client.js";
+export * from "./fleet.js";
 export * from "./types.js";
+export declare class Fleet extends PageFleet {
+    /** A running Fleet, as its owner, found like {@link connect} finds it. */
+    static connect(opts?: ConnectOptions): Promise<Fleet>;
+}
 export interface ConnectOptions extends A12sClientOptions {
     /** The Fleet's name (`metadata.name`). Default: found as described on {@link connect}. */
     fleet?: string;
@@ -10,6 +16,8 @@ export interface ConnectOptions extends A12sClientOptions {
     cwd?: string;
 }
 /**
+ * @deprecated Use `Fleet.connect()`, which finds the Fleet the same way. Kept for one release.
+ *
  * A client for a running Fleet, as its owner. It uses the first of:
  * 1. `url` (and `token`), or `$A12S_URL` (and `$A12S_TOKEN`);
  * 2. the Fleet named by `fleet`;

package/dist/src/node.js

@@ -3,9 +3,19 @@ import { readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { A12sClient } from "./client.js";
+import { Fleet as PageFleet } from "./fleet.js";
 export * from "./client.js";
+export * from "./fleet.js";
 export * from "./types.js";
+export class Fleet extends PageFleet {
+    /** A running Fleet, as its owner, found like {@link connect} finds it. */
+    static async connect(opts = {}) {
+        return new Fleet(await discover(opts));
+    }
+}
 /**
+ * @deprecated Use `Fleet.connect()`, which finds the Fleet the same way. Kept for one release.
+ *
  * A client for a running Fleet, as its owner. It uses the first of:
  * 1. `url` (and `token`), or `$A12S_URL` (and `$A12S_TOKEN`);
  * 2. the Fleet named by `fleet`;
@@ -14,9 +24,12 @@ export * from "./types.js";
  * For 2–4 it reads `~/.a12s/<fleet>/controller.json`, which `a12s up` writes.
  */
 export async function connect(opts = {}) {
+    return new A12sClient(await discover(opts));
+}
+async function discover(opts) {
     const url = opts.url ?? process.env.A12S_URL;
     if (url)
-        return new A12sClient({ url, token: opts.token ?? process.env.A12S_TOKEN, fetch: opts.fetch });
+        return { url, token: opts.token ?? process.env.A12S_TOKEN, fetch: opts.fetch };
     const home = join(opts.home ?? homedir(), ".a12s");
     const fleet = opts.fleet ?? (await fleetNameNearby(opts.cwd ?? process.cwd())) ?? (await onlyRunningFleet(home));
     const path = join(home, fleet, "controller.json");
@@ -27,7 +40,7 @@ export async function connect(opts = {}) {
     catch (err) {
         throw new Error(`Fleet ${fleet} isn't running (no ${path}): run a12s up in its directory first`, { cause: err });
     }
-    return new A12sClient({ url: `http://127.0.0.1:${cf.port}`, token: cf.token, fetch: opts.fetch });
+    return { url: `http://127.0.0.1:${cf.port}`, token: cf.token, fetch: opts.fetch };
 }
 async function fleetNameNearby(cwd) {
     const file = process.env.A12S_FLEET ? resolve(cwd, process.env.A12S_FLEET) : await findUp(cwd, "fleet.yaml");

package/dist/src/types.d.ts

@@ -8,12 +8,108 @@ export interface Harness {
     version: string;
     model?: string;
 }
-/** A parsed fleet.yaml. a12s validates it; the client passes it through. */
-export type Fleet = Record<string, unknown> & {
-    metadata: {
+export interface AgentComputerSpec {
+    harness?: {
+        kind: "claude-code" | "codex" | (string & {});
+        version?: string;
+        model?: string;
+    };
+    image?: string;
+    instructions?: string;
+    /** File contents by path, written into the agent computer's home. */
+    files?: Record<string, string>;
+    resources?: {
+        cpu?: string | number;
+        memory?: string | number;
+    };
+    home?: {
+        size?: string | number;
+        preset?: string;
+    };
+    autonomy?: "full" | "restricted";
+    /** Credential names; their values come from `a12s up` or the credentials API. */
+    credentials?: string[];
+    drives?: Array<{
+        name: string;
+        at: string;
+        readOnly?: boolean;
+    }>;
+    egress?: {
+        allow?: string[];
+    };
+    /** `seccomp` is the profile JSON itself. */
+    security?: {
+        seccomp?: Record<string, unknown>;
+    };
+    inbox?: {
+        maxMessages?: number;
+        maxBytes?: string;
+        intro?: string;
+    };
+    power?: {
+        sleepAfterIdle?: string;
+        wakeOnMessage?: {
+            from: string[];
+            maxWakesPerHour?: number;
+        };
+    };
+    uses?: Array<string | {
         name: string;
+        mcp?: boolean;
+    }>;
+    grants?: {
+        send?: string[];
     };
+}
+/** A JSON merge patch of T: a key set to null is deleted. */
+export type MergePatch<T> = {
+    [K in keyof T]?: T[K] | null;
 };
+/** A Fleet as written: the defaults and each agent computer before the defaults are merged in. */
+export interface FleetSpec {
+    apiVersion: string;
+    kind: string;
+    metadata: {
+        name: string;
+    };
+    egress?: {
+        enforcement?: string;
+        allowPrivate?: string[];
+    };
+    defaults?: AgentComputerSpec;
+    drives?: Record<string, {
+        size?: string | number;
+        access: string;
+    }>;
+    agent_computers: Record<string, AgentComputerSpec>;
+    services?: Record<string, Record<string, unknown>>;
+}
+export interface Change {
+    op: "create" | "update" | "remove" | (string & {});
+    kind: "agentComputer" | "service" | (string & {});
+    name: string;
+    /** "idle" for an update that waits for a busy agent computer's next idle boundary. */
+    when: "now" | "idle" | (string & {});
+    /** The top-level spec fields that differ, for an update. */
+    fields?: string[];
+}
+export interface FleetResponse {
+    version: number;
+    fleet: FleetSpec | null;
+    /** What changed through the API since the last whole-Fleet write: `a12s up` from the file undoes it. */
+    drift: Change[];
+}
+export interface AgentComputerData {
+    name: string;
+    /** As written. */
+    spec: AgentComputerSpec;
+    /** With the Fleet's defaults merged in. */
+    effective: AgentComputerSpec;
+    status: ComputerStatus;
+}
+export interface AgentComputersResponse {
+    agentComputers: AgentComputerData[];
+}
 export interface Lock {
     a12s?: string;
     images: Record<string, string>;
@@ -24,16 +120,12 @@ export interface Lock {
     seccomp?: Record<string, string>;
 }
 export interface PutFleetRequest {
-    fleet: Fleet;
+    fleet: FleetSpec;
     lock?: Lock;
     /** Credential values by name, base64-encoded (Go []byte). Kept in the Controller's memory only. */
     credentials?: Record<string, string>;
     asleep?: boolean;
     refresh?: string[];
-    /** Home presets as base64 tar streams, keyed by their path in the Fleet. */
-    presets?: Record<string, string>;
-    /** security.seccomp profiles (JSON text), keyed by their path in the Fleet. */
-    seccomp?: Record<string, string>;
 }
 export interface ServiceChanges {
     created: string[] | null;
@@ -41,6 +133,10 @@ export interface ServiceChanges {
     removed: string[] | null;
 }
 export interface PutFleetResponse {
+    /** The Fleet's version after the write; unchanged by a dry run or a write that changed nothing. */
+    version: number;
+    dryRun?: boolean;
+    changes: Change[];
     created: string[] | null;
     updated: string[] | null;
     staged: string[] | null;
@@ -49,6 +145,10 @@ export interface PutFleetResponse {
     errors?: Record<string, string>;
     warnings?: string[];
     services: ServiceChanges;
+    /** The written agent computer, after a PUT or PATCH of one. */
+    agentComputer?: AgentComputerData;
+    /** The written Service, after a PUT or PATCH of one. */
+    service?: ServiceStatus;
 }
 export interface LimitValue {
     value: number;
@@ -146,10 +246,14 @@ export interface ServiceStatus {
     stateDrive?: string;
     egressMode?: string;
     warnings?: string[];
+    /** The Service as written in the Fleet. */
+    spec?: Record<string, unknown>;
 }
 export interface StatusResponse {
     fleet: string;
     egressEnforcement: string;
+    agentComputers: ComputerStatus[];
+    /** @deprecated `agentComputers` under its old name. */
     computers: ComputerStatus[];
     orphanedDrives?: DriveRow[];
     credentialsLoaded: boolean;
@@ -213,10 +317,12 @@ export interface InboxListOptions {
     bodies?: boolean;
     after?: number;
 }
-/** The fields every journal event has. `seq` is the Computer's journal position and the SSE id. */
+/** The fields every event has. `seq` is the agent computer's journal position (0 for the Controller's own events). */
 export interface EventEnvelope {
     v: number;
-    /** The Computer that journaled it. */
+    /** The agent computer it is about; absent on `fleet.changed` and in journals older than the field. */
+    agentComputer?: string;
+    /** `agentComputer` under its old name, for one release. */
     computer: string;
     session: string;
     /** The Turn it belongs to; "" for events outside a Turn. */
@@ -264,8 +370,34 @@ export interface TurnFinishedData {
     status: "completed" | "failed" | "interrupted";
     /** The harness's own usage object (tokens, cost), or null. */
     usage: unknown;
+    /** The same usage, normalized across harnesses, when the harness reported it. */
+    tokens?: TokenUsage;
     error?: string;
 }
+/** A Turn's token usage, the same for every harness. `input` excludes cached input. */
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/** The egress proxy refused a connection. */
+export interface EgressDeniedData {
+    host: string;
+    port: number;
+    reason?: string;
+}
+/** The Fleet's version moved; `names` are the agent computers and Services the write changed. */
+export interface FleetChangedData {
+    version: number;
+    /** Who wrote it. */
+    by: string;
+    names: string[];
+}
+export interface PhaseData {
+    phase: Phase;
+    error?: Failure;
+}
 export interface ToolStartedData {
     id: string;
     /** MCP tools are named `mcp__<server>__<tool>`, e.g. `mcp__a12s__send`. */
@@ -331,10 +463,15 @@ export type TurnRefusedEvent = Ev<"turn.refused", {
 }>;
 /** A Message that ended without delivery (cleared, withdrawn, expired, replaced), body included. */
 export type InboxDiscardedEvent = Ev<"inbox.discarded", Record<string, unknown>>;
+export type EgressDeniedEvent = Ev<"egress.denied", EgressDeniedData>;
+/** Made by the Controller, on the fleet-wide stream only. */
+export type FleetChangedEvent = Ev<"fleet.changed", FleetChangedData>;
+/** Made by the Controller, on the fleet-wide stream only. */
+export type PhaseEvent = Ev<"agent_computer.phase", PhaseData>;
 /** Made by the SDK, never journaled: the stream could not resume from its cursor and events were lost. */
 export type GapEvent = Ev<"gap", GapData>;
-/** One event of a Computer's journal. Narrow on `type` to get typed `data`. */
-export type A12sEvent = TurnStartedEvent | TurnDispatchedEvent | TextDeltaEvent | ToolStartedEvent | ToolFinishedEvent | PermissionEvent | DiagnosticEvent | TurnFinishedEvent | SessionChangedEvent | ResumeFailedEvent | LifecycleEvent | HarnessRestartedEvent | ContinuationAbandonedEvent | TurnRefusedEvent | InboxDiscardedEvent | GapEvent;
+/** One event of an agent computer's journal, or the Controller's own on the fleet-wide stream. Narrow on `type` to get typed `data`. */
+export type A12sEvent = TurnStartedEvent | TurnDispatchedEvent | TextDeltaEvent | ToolStartedEvent | ToolFinishedEvent | PermissionEvent | DiagnosticEvent | TurnFinishedEvent | SessionChangedEvent | ResumeFailedEvent | LifecycleEvent | HarnessRestartedEvent | ContinuationAbandonedEvent | TurnRefusedEvent | InboxDiscardedEvent | EgressDeniedEvent | FleetChangedEvent | PhaseEvent | GapEvent;
 export type EventType = A12sEvent["type"];
 /** One tool call in a Turn. A `send` to another Computer is `mcp__a12s__send` with `input.body`. */
 export interface ToolCall {
@@ -346,6 +483,8 @@ export interface ToolCall {
 }
 /** A finished Turn: what `turns()` yields and `prompt()` returns. */
 export interface Turn {
+    agentComputer: string;
+    /** `agentComputer` under its old name, for one release. */
     computer: string;
     /** The Turn id. */
     id: string;
@@ -359,24 +498,47 @@ export interface Turn {
     /** The tools it called, in order, with their input and output: what it `send`s to other Computers is here. */
     tools: ToolCall[];
     usage: unknown;
+    tokens?: TokenUsage;
     startedAt?: string;
     finishedAt: string;
 }
+/** Past Turns, newest first, as GET /v1/agent-computers/{name}/turns sends them. */
+export interface TurnsResponse {
+    turns: Array<Omit<Turn, "computer" | "tools"> & {
+        tools: Array<Omit<ToolCall, "isError"> & {
+            isError?: boolean;
+        }>;
+    }>;
+}
 export interface ApiErrorBody {
     code: string;
     message: string;
     fix?: string;
     details?: Record<string, string>;
 }
+export type TokenAction = "send" | "inbox" | "status" | "events" | "power" | "stop";
+/** Either `prefix`, or `actions` on `computers` (agent computer names, or "*"). */
 export interface TokenRequest {
     name: string;
-    actions: Array<"send" | "inbox" | "status" | "events" | "power" | "stop">;
-    computers: string[];
+    actions?: TokenAction[];
+    computers?: string[];
+    /** Every power over agent computers, Services and credentials whose names start with it; none outside. */
+    prefix?: string;
+}
+/** A credential's name, whether it has a value, and who uses it. */
+export interface CredentialInfo {
+    name: string;
+    set: boolean;
+    usedBy?: string[];
+}
+export interface CredentialsResponse {
+    credentials: CredentialInfo[];
 }
 export interface Token {
     name: string;
     actions: string[];
     computers: string[];
+    prefix?: string;
     createdAt: string;
     secret?: string;
 }