@coltonkirsten/a12s 0.3.0 → 0.4.1

package/dist/src/client.js

@@ -16,6 +16,16 @@ export class A12sError extends Error {
         this.details = body.details;
     }
 }
+/** A 404: the agent computer, Service, Message or token does not exist. */
+export class NotFound extends A12sError {
+    constructor(status, body) {
+        super(status, body);
+        this.name = "NotFound";
+    }
+}
+function apiError(status, body) {
+    return status === 404 ? new NotFound(status, body) : new A12sError(status, body);
+}
 /** Thrown by an event stream with `onGap: "throw"` when events were lost. */
 export class A12sGapError extends Error {
     after;
@@ -35,10 +45,15 @@ export class A12sStreamError extends Error {
     }
 }
 const enc = encodeURIComponent;
+/**
+ * @deprecated Use {@link Fleet}: `fleet.agentComputers.get(name)` returns an {@link AgentComputer} with these
+ * methods. Kept for one release.
+ */
 export class A12sClient {
     url;
     token;
     fetchImpl;
+    shared;
     constructor(opts = {}) {
         this.url = (opts.url ?? "").replace(/\/+$/, "");
         this.token = opts.token;
@@ -47,16 +62,17 @@ export class A12sClient {
     headers(extra = {}) {
         return this.token ? { authorization: `Bearer ${this.token}`, ...extra } : extra;
     }
-    async request(method, path, body, signal) {
+    /** @internal */
+    async request(method, path, body, opts = {}) {
         const res = await this.fetchImpl(this.url + path, {
             method,
-            headers: this.headers(body === undefined ? {} : { "content-type": "application/json" }),
+            headers: this.headers({ ...(body === undefined ? {} : { "content-type": "application/json" }), ...opts.headers }),
             body: body === undefined ? undefined : JSON.stringify(body),
-            signal,
+            signal: opts.signal,
         });
         const text = await res.text();
         if (!res.ok)
-            throw new A12sError(res.status, parseError(res.status, text));
+            throw apiError(res.status, parseError(res.status, text));
         return (text ? JSON.parse(text) : undefined);
     }
     /** Every Computer and Service: phase, session, active Turn, inbox, power. */
@@ -64,9 +80,9 @@ export class A12sClient {
         return this.request("GET", "/v1/status");
     }
     async computer(name) {
-        const c = (await this.status()).computers.find((x) => x.name === name);
+        const c = (await this.status()).agentComputers.find((x) => x.name === name);
         if (!c)
-            throw new A12sError(404, { code: "not_found", message: `no Computer ${name}` });
+            throw new NotFound(404, { code: "not_found", message: `no Computer ${name}` });
         return c;
     }
     /**
@@ -76,7 +92,7 @@ export class A12sClient {
     send(computer, msg) {
         const m = typeof msg === "string" ? { body: msg } : { ...msg };
         m.idempotencyKey ??= globalThis.crypto.randomUUID();
-        return this.request("POST", `/v1/computers/${enc(computer)}/inbox`, m);
+        return this.request("POST", `/v1/agent-computers/${enc(computer)}/inbox`, m);
     }
     /** Sends a Message, waits for the Turn that delivers it and resolves when that Turn ends: what `a12s prompt` does. */
     async prompt(computer, body, opts = {}) {
@@ -105,8 +121,21 @@ export class A12sClient {
         }
         return new EventStream((name, live, signal) => {
             const q = opts.turn ? `?turn=${enc(opts.turn)}` : "";
-            return this.stream(name, `/v1/computers/${enc(name)}/events${q}`, opts.after, { ...opts, signal, live });
-        }, names ?? (async () => (await this.status()).computers.map((c) => c.name)), opts.signal);
+            return this.stream(name, `/v1/agent-computers/${enc(name)}/events${q}`, opts.after, { ...opts, signal, live });
+        }, names ?? (async () => (await this.status()).agentComputers.map((c) => c.name)), opts.signal);
+    }
+    /**
+     * @internal Events of the named agent computers (all if none), and the Controller's own about them, read from this
+     * client's one GET /v1/events connection.
+     */
+    sharedEvents(names, opts = {}) {
+        this.shared ??= new SharedEvents((cursor, signal) => this.fetchImpl(this.url + "/v1/events", {
+            headers: this.headers({ accept: "text/event-stream", ...(cursor !== undefined ? { "last-event-id": cursor } : {}) }),
+            signal,
+        }));
+        const shared = this.shared;
+        const wanted = names && new Set(names);
+        return new EventStream((_name, live, signal) => shared.subscribe({ wanted, live, onGap: opts.onGap, reconnectMs: opts.reconnectMs }, signal), [""], opts.signal);
     }
     /**
      * Finished Turns of one Computer, several or all, as they end: who sent the work (`messages`), what the agent said
@@ -124,28 +153,28 @@ export class A12sClient {
         if (opts.after !== undefined)
             q.set("after", String(opts.after));
         const qs = q.toString();
-        return this.request("GET", `/v1/computers/${enc(computer)}/inbox${qs ? "?" + qs : ""}`);
+        return this.request("GET", `/v1/agent-computers/${enc(computer)}/inbox${qs ? "?" + qs : ""}`);
     }
     message(computer, id) {
-        return this.request("GET", `/v1/computers/${enc(computer)}/inbox/${enc(id)}`);
+        return this.request("GET", `/v1/agent-computers/${enc(computer)}/inbox/${enc(id)}`);
     }
     /** Withdraws a pending Message; a 409 A12sError names its state if it is too late. */
     withdraw(computer, id) {
-        return this.request("DELETE", `/v1/computers/${enc(computer)}/inbox/${enc(id)}`);
+        return this.request("DELETE", `/v1/agent-computers/${enc(computer)}/inbox/${enc(id)}`);
     }
     /** Interrupts a Turn (default: the active one). The Turn ends `interrupted`; nothing is replayed. */
     async stop(computer, turn) {
         const id = turn ?? (await this.computer(computer)).activeTurn;
         if (id)
-            await this.request("POST", `/v1/computers/${enc(computer)}/turns/${enc(id)}/stop`, {});
+            await this.request("POST", `/v1/agent-computers/${enc(computer)}/turns/${enc(id)}/stop`, {});
     }
     /** Stops the Computer's processes and keeps its disks, session and inbox. */
     async sleep(computer) {
-        await this.request("POST", `/v1/computers/${enc(computer)}/power`, { state: "asleep" });
+        await this.request("POST", `/v1/agent-computers/${enc(computer)}/power`, { state: "asleep" });
     }
     /** Starts a sleeping Computer; its session resumes on the next Turn. */
     async wake(computer) {
-        await this.request("POST", `/v1/computers/${enc(computer)}/power`, { state: "awake" });
+        await this.request("POST", `/v1/agent-computers/${enc(computer)}/power`, { state: "awake" });
     }
     async services() {
         return (await this.request("GET", "/v1/services")).services ?? [];
@@ -165,7 +194,7 @@ export class A12sClient {
     async deliveredIn(computer, id, signal) {
         // Every subscription starts with a snapshot, so resubscribing after a drop never misses the delivery.
         while (!signal?.aborted) {
-            for await (const ev of this.stream(computer, `/v1/computers/${enc(computer)}/inbox/${enc(id)}/events`, undefined, {
+            for await (const ev of this.stream(computer, `/v1/agent-computers/${enc(computer)}/inbox/${enc(id)}/events`, undefined, {
                 signal,
                 once: true,
             })) {
@@ -214,7 +243,7 @@ export class A12sClient {
                 continue;
             }
             if (!res.ok) {
-                const err = new A12sError(res.status, parseError(res.status, await res.text()));
+                const err = apiError(res.status, parseError(res.status, await res.text()));
                 // Asleep or starting: the journal comes back with the Computer.
                 if (res.status !== 503 && res.status !== 502)
                     throw err;
@@ -285,6 +314,188 @@ export class A12sClient {
         }
     }
 }
+/** One GET /v1/events connection, open while anything subscribes: watching fifty agent computers takes one. */
+class SharedEvents {
+    open;
+    subs = new Set();
+    conn;
+    live = false;
+    constructor(open) {
+        this.open = open;
+    }
+    async *subscribe(sub, signal) {
+        const queue = [];
+        let failure;
+        let wake;
+        const notify = () => {
+            const w = wake;
+            wake = undefined;
+            w?.();
+        };
+        const s = {
+            ...sub,
+            push: (ev) => {
+                queue.push(ev);
+                notify();
+            },
+            fail: (error) => {
+                failure ??= { error };
+                notify();
+            },
+        };
+        signal.addEventListener("abort", notify, { once: true });
+        this.add(s);
+        try {
+            for (;;) {
+                if (queue.length) {
+                    yield queue.shift();
+                    continue;
+                }
+                if (failure)
+                    throw failure.error;
+                if (signal.aborted)
+                    return;
+                await new Promise((r) => (wake = r));
+            }
+        }
+        finally {
+            signal.removeEventListener("abort", notify);
+            this.remove(s);
+        }
+    }
+    add(s) {
+        this.subs.add(s);
+        if (!this.conn) {
+            const conn = new AbortController();
+            this.conn = conn;
+            this.live = false;
+            void this.run(conn);
+        }
+        else if (this.live) {
+            s.live();
+        }
+    }
+    remove(s) {
+        this.subs.delete(s);
+        if (this.subs.size === 0)
+            this.stop();
+    }
+    stop() {
+        this.conn?.abort();
+        this.conn = undefined;
+        this.live = false;
+    }
+    async run(conn) {
+        const { signal } = conn;
+        let cursor;
+        try {
+            while (!signal.aborted) {
+                let res;
+                try {
+                    res = await this.open(cursor, signal);
+                }
+                catch (err) {
+                    if (signal.aborted)
+                        return;
+                    if (!isNetworkError(err))
+                        throw err;
+                }
+                if (res && !res.ok) {
+                    const err = apiError(res.status, parseError(res.status, await res.text()));
+                    if (res.status !== 502 && res.status !== 503)
+                        throw err;
+                    res = undefined;
+                }
+                if (res) {
+                    if (!res.body)
+                        throw new A12sStreamError("GET /v1/events: response has no body");
+                    const frames = readSSE(res.body);
+                    try {
+                        for (;;) {
+                            let r;
+                            try {
+                                r = await frames.next();
+                            }
+                            catch {
+                                break;
+                            }
+                            if (r.done)
+                                break;
+                            cursor = this.frame(r.value, cursor);
+                        }
+                    }
+                    finally {
+                        await frames.return(undefined);
+                        res.body.cancel().catch(() => { });
+                    }
+                }
+                await sleep(this.reconnectMs(), signal);
+            }
+        }
+        catch (err) {
+            if (signal.aborted)
+                return;
+            const subs = [...this.subs];
+            if (this.conn === conn)
+                this.stop();
+            for (const s of subs)
+                s.fail(err);
+        }
+    }
+    /** Delivers one frame and returns the cursor to resume after. */
+    frame(f, cursor) {
+        if (f.event === "head") {
+            const id = parseJSON(f.data)?.id;
+            this.live = true;
+            for (const s of this.subs)
+                s.live();
+            return typeof id === "string" && id ? id : cursor;
+        }
+        if (f.event === "gap") {
+            const data = cursor !== undefined ? { lastEventId: cursor } : {};
+            const gap = { v: 1, computer: "", session: "", turn: "", seq: 0, ts: new Date().toISOString(), type: "gap", data };
+            for (const s of this.subs) {
+                if (s.onGap === "throw")
+                    s.fail(new A12sGapError(data));
+                else
+                    s.push(gap);
+            }
+            return cursor;
+        }
+        if (f.event || !f.data)
+            return cursor;
+        let ev;
+        try {
+            ev = JSON.parse(f.data);
+        }
+        catch (err) {
+            throw new A12sStreamError(`malformed event after ${cursor ?? "(start)"}: ${f.data.slice(0, 120)}`, { cause: err });
+        }
+        for (const s of this.subs)
+            if (wanted(s.wanted, ev))
+                s.push(ev);
+        return f.id ?? cursor;
+    }
+    reconnectMs() {
+        let ms = 1000;
+        for (const s of this.subs)
+            if (s.reconnectMs !== undefined)
+                ms = Math.min(ms, s.reconnectMs);
+        return ms;
+    }
+}
+function agentComputerOf(ev) {
+    return ev.agentComputer || ev.computer;
+}
+function wanted(names, ev) {
+    if (!names)
+        return true;
+    if (ev.type === "fleet.changed")
+        return (ev.data?.names ?? []).some((n) => names.has(n));
+    if (ev.type === "service.phase")
+        return names.has(ev.data?.service);
+    return names.has(agentComputerOf(ev));
+}
 /** Events of one or more Computers, merged in arrival order. Iterate it with `for await`. */
 export class EventStream {
     source;
@@ -442,7 +653,8 @@ class TurnBuilder {
     add(ev) {
         if (!ev.turn)
             return undefined;
-        const key = `${ev.computer}\u0000${ev.turn}`;
+        const name = agentComputerOf(ev);
+        const key = `${name}\u0000${ev.turn}`;
         let t = this.open.get(key);
         if (!t)
             this.open.set(key, (t = { text: "", afterTool: false, messages: [], tools: new Map() }));
@@ -470,7 +682,8 @@ class TurnBuilder {
             case "turn.finished":
                 this.open.delete(key);
                 return {
-                    computer: ev.computer,
+                    agentComputer: name,
+                    computer: name,
                     id: ev.turn,
                     session: ev.session,
                     status: ev.data.status,
@@ -479,6 +692,7 @@ class TurnBuilder {
                     messages: t.messages,
                     tools: [...t.tools.values()],
                     usage: ev.data.usage,
+                    ...(ev.data.tokens ? { tokens: ev.data.tokens } : {}),
                     ...(t.startedAt ? { startedAt: t.startedAt } : {}),
                     finishedAt: ev.ts,
                 };

package/dist/src/fleet.d.ts

@@ -0,0 +1,160 @@
+import { A12sClient, type A12sClientOptions, type EventsOptions, TurnStream, type EventStream, type PromptOptions, type PromptResult, type SharedEventsOptions } from "./client.js";
+import type { AgentComputerData, AgentComputerSpec, Change, ComputerStatus, CredentialInfo, EnqueueRequest, EnqueueResponse, FleetSpec, InboxListOptions, InboxListResponse, MergePatch, Message, ServiceStatus, StatusResponse, Token, TokenAction, Turn } from "./types.js";
+/** The Fleet as written, and its version for a conditional write. */
+export interface FleetState {
+    version: number;
+    spec: FleetSpec;
+    /** What changed through the API since the last whole-Fleet write. */
+    drift: Change[];
+}
+export interface CreateOptions {
+    /** Overwrite an existing one instead of failing with A12sError code `exists`. */
+    replace?: boolean;
+}
+/**
+ * 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 declare class Fleet {
+    /** The lower-level client the handles use, for API calls that have no method here. */
+    readonly client: A12sClient;
+    readonly agentComputers: AgentComputers;
+    readonly services: Services;
+    readonly tokens: Tokens;
+    readonly credentials: Credentials;
+    /** No discovery: `url` and `token` as given, by default the page's own origin. */
+    constructor(opts?: A12sClientOptions);
+    /**
+     * 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 connect(opts?: A12sClientOptions): Promise<Fleet>;
+    get url(): string;
+    get(): Promise<FleetState>;
+    /**
+     * 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.
+     */
+    replace(fn: (spec: FleetSpec) => FleetSpec | void | Promise<FleetSpec | void>): Promise<FleetState>;
+    /**
+     * 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?: string | string[], opts?: EventsOptions): EventStream;
+    /** Finished Turns of the named agent computers, or all of them, as they end. */
+    turns(agentComputers?: string | string[], opts?: SharedEventsOptions): TurnStream;
+    /** Every agent computer and Service: phase, session, active Turn, inbox, power. */
+    status(): Promise<StatusResponse>;
+}
+export declare class AgentComputers {
+    private readonly client;
+    constructor(client: A12sClient);
+    /** Adds an agent computer to the Fleet and starts it. Fails with code `exists` if the name is taken. */
+    create(name: string, spec?: AgentComputerSpec & CreateOptions): Promise<AgentComputer>;
+    /** Throws {@link NotFound} if there is none. */
+    get(name: string): Promise<AgentComputer>;
+    list(): Promise<AgentComputer[]>;
+}
+/** A handle on one agent computer. `spec`, `effective` and `status` are as of the last create, get, reload or update. */
+export declare class AgentComputer {
+    private readonly client;
+    readonly name: string;
+    spec: AgentComputerSpec;
+    /** The spec with the Fleet's defaults merged in. */
+    effective: AgentComputerSpec;
+    status: ComputerStatus;
+    constructor(client: A12sClient, data: AgentComputerData);
+    private set;
+    private get path();
+    reload(): Promise<this>;
+    /** Changes the spec: a key set to null goes back to the Fleet's default. A busy one picks it up when idle. */
+    update(changes: MergePatch<AgentComputerSpec>): Promise<this>;
+    /** Removes it from the Fleet and stops it; its drives are kept. */
+    remove(): Promise<void>;
+    /** Sends a Message, waits for the Turn that delivers it and resolves when that Turn ends. */
+    prompt(text: string, opts?: PromptOptions): Promise<PromptResult>;
+    /** Puts a Message in the inbox and returns at once; it is delivered at the next idle moment. */
+    send(text: string, opts?: Omit<EnqueueRequest, "body">): Promise<EnqueueResponse>;
+    /** Its events, live, from the Fleet's shared connection; `turn` replays one Turn from its start instead. */
+    events(opts?: EventsOptions): EventStream;
+    /** Its last `limit` finished Turns, newest first. */
+    turns(opts: {
+        limit: number;
+    }): Promise<Turn[]>;
+    /** Its Turns as they end, from the Fleet's shared connection. */
+    turns(opts?: SharedEventsOptions & {
+        limit?: undefined;
+    }): TurnStream;
+    private pastTurns;
+    /** Stops its processes and keeps its disks, session and inbox. */
+    sleep(): Promise<void>;
+    wake(): Promise<void>;
+    /** Interrupts a Turn (default: the active one). */
+    stop(turn?: string): Promise<void>;
+    inbox(opts?: InboxListOptions): Promise<InboxListResponse>;
+    message(id: string): Promise<Message>;
+    /** Withdraws a pending Message; a 409 A12sError names its state if it is too late. */
+    withdraw(id: string): Promise<Message>;
+}
+export declare class Services {
+    private readonly client;
+    constructor(client: A12sClient);
+    /** Adds a Service to the Fleet. Fails with code `exists` if the name is taken. */
+    create(name: string, spec?: Record<string, unknown> & CreateOptions): Promise<Service>;
+    /** Throws {@link NotFound} if there is none. */
+    get(name: string): Promise<Service>;
+    list(): Promise<Service[]>;
+}
+/** A handle on one Service. `spec` and `status` are as of the last create, get, reload, update or power change. */
+export declare class Service {
+    private readonly client;
+    readonly name: string;
+    status: ServiceStatus;
+    constructor(client: A12sClient, status: ServiceStatus);
+    /** As written in the Fleet. */
+    get spec(): Record<string, unknown>;
+    private get path();
+    reload(): Promise<this>;
+    /** Changes the spec as a JSON merge patch: a key set to null is removed. */
+    update(changes: Record<string, unknown>): Promise<this>;
+    /** Removes it from the Fleet and stops it; its state drive is kept. */
+    remove(): Promise<void>;
+    sleep(): Promise<this>;
+    wake(): Promise<this>;
+    private power;
+}
+export declare class Tokens {
+    private readonly client;
+    constructor(client: A12sClient);
+    /**
+     * 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: string, opts: {
+        prefix: string;
+    } | {
+        actions: TokenAction[];
+        agentComputers?: string[];
+    }): Promise<Token>;
+    list(): Promise<Token[]>;
+    remove(name: string): Promise<void>;
+}
+/** Credentials by name: set once, then name them in a spec's `credentials`. Values are never read back. */
+export declare class Credentials {
+    private readonly client;
+    constructor(client: A12sClient);
+    /** Stores the value on the Controller; agent computers that use it get the new value at once. */
+    set(name: string, value: string): Promise<CredentialInfo>;
+    list(): Promise<CredentialInfo[]>;
+    /** Fails with A12sError code `in_use` while an agent computer or Service uses it. */
+    remove(name: string): Promise<void>;
+}