@coltonkirsten/a12s 0.2.1 → 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");