@coltonkirsten/a12s 0.4.1 → 0.4.3

package/dist/a12s.js

@@ -109,7 +109,7 @@ var A12sClient = class {
   }
   async computer(name) {
     const c = (await this.status()).agentComputers.find((x) => x.name === name);
-    if (!c) throw new NotFound(404, { code: "not_found", message: `no Computer ${name}` });
+    if (!c) throw new NotFound(404, { code: "not_found", message: `no agent computer ${name}` });
     return c;
   }
   /**
@@ -142,11 +142,12 @@ var A12sClient = class {
   events(computers, opts = {}) {
     const names = typeof computers === "string" ? [computers] : computers;
     if ((opts.turn !== void 0 || opts.after !== void 0) && names?.length !== 1) {
-      throw new TypeError("events: turn and after need exactly one Computer");
+      throw new TypeError("events: turn and after need exactly one agent computer");
     }
     return new EventStream((name, live, signal) => {
       const q = opts.turn ? `?turn=${enc(opts.turn)}` : "";
-      return this.stream(name, `/v1/agent-computers/${enc(name)}/events${q}`, opts.after, { ...opts, signal, live });
+      const events = this.stream(name, `/v1/agent-computers/${enc(name)}/events${q}`, opts.after, { ...opts, signal, live });
+      return opts.turn ? untilTurnFinished(events) : events;
     }, names ?? (async () => (await this.status()).agentComputers.map((c) => c.name)), opts.signal);
   }
   /**
@@ -195,13 +196,30 @@ var A12sClient = class {
     const id = turn ?? (await this.computer(computer)).activeTurn;
     if (id) 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/agent-computers/${enc(computer)}/power`, { state: "asleep" });
+  /**
+   * Stops the agent computer's processes and keeps its disks, session and inbox. It stays asleep until wake(); with
+   * `allowWake` its power policy (wakeOnMessage) may wake it instead.
+   */
+  async sleep(computer, opts = {}) {
+    await this.request("POST", `/v1/agent-computers/${enc(computer)}/power`, {
+      state: "asleep",
+      ...opts.allowWake ? { allowWake: true } : {}
+    });
+  }
+  /** Starts a sleeping agent computer; its session resumes on the next Turn. `clearInbox` discards pending Messages. */
+  async wake(computer, opts = {}) {
+    await this.request("POST", `/v1/agent-computers/${enc(computer)}/power`, {
+      state: "awake",
+      ...opts.clearInbox ? { clearInbox: true, requestId: crypto.randomUUID() } : {}
+    });
   }
-  /** Starts a sleeping Computer; its session resumes on the next Turn. */
-  async wake(computer) {
-    await this.request("POST", `/v1/agent-computers/${enc(computer)}/power`, { state: "awake" });
+  /** Holds the inbox: Messages still queue, none is delivered until resume(). */
+  hold(computer, opts = {}) {
+    return this.request("POST", `/v1/agent-computers/${enc(computer)}/inbox/hold`, opts.reason ? { reason: opts.reason } : {});
+  }
+  /** Releases a hold; pending Messages are delivered at the next idle moment. */
+  resume(computer) {
+    return this.request("POST", `/v1/agent-computers/${enc(computer)}/inbox/resume`, {});
   }
   async services() {
     return (await this.request("GET", "/v1/services")).services ?? [];
@@ -472,6 +490,16 @@ function wanted(names, ev) {
   if (ev.type === "service.phase") return names.has(ev.data?.service);
   return names.has(agentComputerOf(ev));
 }
+async function* untilTurnFinished(events) {
+  try {
+    for await (const ev of events) {
+      yield ev;
+      if (ev.type === "turn.finished") return;
+    }
+  } finally {
+    await events.return(void 0);
+  }
+}
 var EventStream = class {
   constructor(source, names, signal) {
     this.source = source;
@@ -729,9 +757,11 @@ var Fleet = class _Fleet {
       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}"` }
-        });
+        warnWrites(
+          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;
@@ -777,6 +807,7 @@ var AgentComputers = class {
     const r = await this.client.request("PUT", `/v1/agent-computers/${enc2(name)}`, body, {
       headers: writeHeaders({ replace })
     });
+    warnWrites(r);
     return r.agentComputer ? new AgentComputer(this.client, r.agentComputer) : this.get(name);
   }
   /** Throws {@link NotFound} if there is none. */
@@ -814,6 +845,7 @@ var AgentComputer = class {
   /** 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);
+    warnWrites(r);
     return r.agentComputer ? this.set(r.agentComputer) : this.reload();
   }
   /** Removes it from the Fleet and stops it; its drives are kept. */
@@ -846,12 +878,21 @@ var AgentComputer = class {
       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);
+  /** Stops its processes and keeps its disks, session and inbox until wake(); `allowWake` lets wakeOnMessage wake it. */
+  sleep(opts = {}) {
+    return this.client.sleep(this.name, opts);
   }
-  wake() {
-    return this.client.wake(this.name);
+  /** Wakes it; `clearInbox` discards the pending Messages first. */
+  wake(opts = {}) {
+    return this.client.wake(this.name, opts);
+  }
+  /** Holds its inbox: Messages still queue, none is delivered until resume(). */
+  hold(opts = {}) {
+    return this.client.hold(this.name, opts);
+  }
+  /** Releases a hold on its inbox. */
+  resume() {
+    return this.client.resume(this.name);
   }
   /** Interrupts a Turn (default: the active one). */
   stop(turn) {
@@ -878,6 +919,7 @@ var Services = class {
     const r = await this.client.request("PUT", `/v1/services/${enc2(name)}`, body, {
       headers: writeHeaders({ replace })
     });
+    warnWrites(r);
     return r.service ? new Service(this.client, r.service) : this.get(name);
   }
   /** Throws {@link NotFound} if there is none. */
@@ -910,6 +952,7 @@ var Service = class {
   /** 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);
+    warnWrites(r);
     if (!r.service) return this.reload();
     this.status = r.service;
     return this;
@@ -966,6 +1009,9 @@ var Credentials = class {
     await this.client.request("DELETE", `/v1/credentials/${enc2(name)}`);
   }
 };
+function warnWrites(r) {
+  for (const w of r?.warnings ?? []) console.warn(`a12s: ${w}`);
+}
 
 // src/index.ts
 async function connect(opts = {}) {

package/dist/src/client.d.ts

@@ -106,10 +106,23 @@ export declare class A12sClient {
     withdraw(computer: string, id: string): Promise<Message>;
     /** Interrupts a Turn (default: the active one). The Turn ends `interrupted`; nothing is replayed. */
     stop(computer: string, turn?: string): Promise<void>;
-    /** Stops the Computer's processes and keeps its disks, session and inbox. */
-    sleep(computer: string): Promise<void>;
-    /** Starts a sleeping Computer; its session resumes on the next Turn. */
-    wake(computer: string): Promise<void>;
+    /**
+     * Stops the agent computer's processes and keeps its disks, session and inbox. It stays asleep until wake(); with
+     * `allowWake` its power policy (wakeOnMessage) may wake it instead.
+     */
+    sleep(computer: string, opts?: {
+        allowWake?: boolean;
+    }): Promise<void>;
+    /** Starts a sleeping agent computer; its session resumes on the next Turn. `clearInbox` discards pending Messages. */
+    wake(computer: string, opts?: {
+        clearInbox?: boolean;
+    }): Promise<void>;
+    /** Holds the inbox: Messages still queue, none is delivered until resume(). */
+    hold(computer: string, opts?: {
+        reason?: string;
+    }): Promise<InboxListResponse>;
+    /** Releases a hold; pending Messages are delivered at the next idle moment. */
+    resume(computer: string): Promise<InboxListResponse>;
     services(): Promise<ServiceStatus[]>;
     service(name: string): Promise<ServiceStatus>;
     /** A scoped token for another program; owner only. The secret is in the response once. */

package/dist/src/client.js

@@ -82,7 +82,7 @@ export class A12sClient {
     async computer(name) {
         const c = (await this.status()).agentComputers.find((x) => x.name === name);
         if (!c)
-            throw new NotFound(404, { code: "not_found", message: `no Computer ${name}` });
+            throw new NotFound(404, { code: "not_found", message: `no agent computer ${name}` });
         return c;
     }
     /**
@@ -117,11 +117,12 @@ export class A12sClient {
     events(computers, opts = {}) {
         const names = typeof computers === "string" ? [computers] : computers;
         if ((opts.turn !== undefined || opts.after !== undefined) && names?.length !== 1) {
-            throw new TypeError("events: turn and after need exactly one Computer");
+            throw new TypeError("events: turn and after need exactly one agent computer");
         }
         return new EventStream((name, live, signal) => {
             const q = opts.turn ? `?turn=${enc(opts.turn)}` : "";
-            return this.stream(name, `/v1/agent-computers/${enc(name)}/events${q}`, opts.after, { ...opts, signal, live });
+            const events = this.stream(name, `/v1/agent-computers/${enc(name)}/events${q}`, opts.after, { ...opts, signal, live });
+            return opts.turn ? untilTurnFinished(events) : events;
         }, names ?? (async () => (await this.status()).agentComputers.map((c) => c.name)), opts.signal);
     }
     /**
@@ -168,13 +169,30 @@ export class A12sClient {
         if (id)
             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/agent-computers/${enc(computer)}/power`, { state: "asleep" });
+    /**
+     * Stops the agent computer's processes and keeps its disks, session and inbox. It stays asleep until wake(); with
+     * `allowWake` its power policy (wakeOnMessage) may wake it instead.
+     */
+    async sleep(computer, opts = {}) {
+        await this.request("POST", `/v1/agent-computers/${enc(computer)}/power`, {
+            state: "asleep",
+            ...(opts.allowWake ? { allowWake: true } : {}),
+        });
+    }
+    /** Starts a sleeping agent computer; its session resumes on the next Turn. `clearInbox` discards pending Messages. */
+    async wake(computer, opts = {}) {
+        await this.request("POST", `/v1/agent-computers/${enc(computer)}/power`, {
+            state: "awake",
+            ...(opts.clearInbox ? { clearInbox: true, requestId: crypto.randomUUID() } : {}),
+        });
+    }
+    /** Holds the inbox: Messages still queue, none is delivered until resume(). */
+    hold(computer, opts = {}) {
+        return this.request("POST", `/v1/agent-computers/${enc(computer)}/inbox/hold`, opts.reason ? { reason: opts.reason } : {});
     }
-    /** Starts a sleeping Computer; its session resumes on the next Turn. */
-    async wake(computer) {
-        await this.request("POST", `/v1/agent-computers/${enc(computer)}/power`, { state: "awake" });
+    /** Releases a hold; pending Messages are delivered at the next idle moment. */
+    resume(computer) {
+        return this.request("POST", `/v1/agent-computers/${enc(computer)}/inbox/resume`, {});
     }
     async services() {
         return (await this.request("GET", "/v1/services")).services ?? [];
@@ -496,6 +514,19 @@ function wanted(names, ev) {
         return names.has(ev.data?.service);
     return names.has(agentComputerOf(ev));
 }
+/** A Turn replay: its events up to and including its turn.finished. The server keeps the stream open after. */
+async function* untilTurnFinished(events) {
+    try {
+        for await (const ev of events) {
+            yield ev;
+            if (ev.type === "turn.finished")
+                return;
+        }
+    }
+    finally {
+        await events.return(undefined);
+    }
+}
 /** Events of one or more Computers, merged in arrival order. Iterate it with `for await`. */
 export class EventStream {
     source;

package/dist/src/fleet.d.ts

@@ -95,9 +95,20 @@ export declare class AgentComputer {
         limit?: undefined;
     }): TurnStream;
     private pastTurns;
-    /** Stops its processes and keeps its disks, session and inbox. */
-    sleep(): Promise<void>;
-    wake(): Promise<void>;
+    /** Stops its processes and keeps its disks, session and inbox until wake(); `allowWake` lets wakeOnMessage wake it. */
+    sleep(opts?: {
+        allowWake?: boolean;
+    }): Promise<void>;
+    /** Wakes it; `clearInbox` discards the pending Messages first. */
+    wake(opts?: {
+        clearInbox?: boolean;
+    }): Promise<void>;
+    /** Holds its inbox: Messages still queue, none is delivered until resume(). */
+    hold(opts?: {
+        reason?: string;
+    }): Promise<InboxListResponse>;
+    /** Releases a hold on its inbox. */
+    resume(): Promise<InboxListResponse>;
     /** Interrupts a Turn (default: the active one). */
     stop(turn?: string): Promise<void>;
     inbox(opts?: InboxListOptions): Promise<InboxListResponse>;

package/dist/src/fleet.js

@@ -52,9 +52,9 @@ export class Fleet {
             cur.spec.defaults ??= {};
             const next = (await fn(cur.spec)) ?? cur.spec;
             try {
-                await this.client.request("PUT", "/v1/fleet", { fleet: next }, {
+                warnWrites(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")
@@ -104,6 +104,7 @@ export class AgentComputers {
         const r = await this.client.request("PUT", `/v1/agent-computers/${enc(name)}`, body, {
             headers: writeHeaders({ replace }),
         });
+        warnWrites(r);
         return r.agentComputer ? new AgentComputer(this.client, r.agentComputer) : this.get(name);
     }
     /** Throws {@link NotFound} if there is none. */
@@ -143,6 +144,7 @@ export class AgentComputer {
     /** 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);
+        warnWrites(r);
         return r.agentComputer ? this.set(r.agentComputer) : this.reload();
     }
     /** Removes it from the Fleet and stops it; its drives are kept. */
@@ -177,12 +179,21 @@ export class 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);
+    /** Stops its processes and keeps its disks, session and inbox until wake(); `allowWake` lets wakeOnMessage wake it. */
+    sleep(opts = {}) {
+        return this.client.sleep(this.name, opts);
     }
-    wake() {
-        return this.client.wake(this.name);
+    /** Wakes it; `clearInbox` discards the pending Messages first. */
+    wake(opts = {}) {
+        return this.client.wake(this.name, opts);
+    }
+    /** Holds its inbox: Messages still queue, none is delivered until resume(). */
+    hold(opts = {}) {
+        return this.client.hold(this.name, opts);
+    }
+    /** Releases a hold on its inbox. */
+    resume() {
+        return this.client.resume(this.name);
     }
     /** Interrupts a Turn (default: the active one). */
     stop(turn) {
@@ -210,6 +221,7 @@ export class Services {
         const r = await this.client.request("PUT", `/v1/services/${enc(name)}`, body, {
             headers: writeHeaders({ replace }),
         });
+        warnWrites(r);
         return r.service ? new Service(this.client, r.service) : this.get(name);
     }
     /** Throws {@link NotFound} if there is none. */
@@ -244,6 +256,7 @@ export class Service {
     /** 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);
+        warnWrites(r);
         if (!r.service)
             return this.reload();
         this.status = r.service;
@@ -304,3 +317,9 @@ export class Credentials {
         await this.client.request("DELETE", `/v1/credentials/${enc(name)}`);
     }
 }
+/** A write's warnings (a grant to an agent computer that doesn't exist yet, a missing harness credential) go to the
+ * console instead of being dropped. */
+function warnWrites(r) {
+    for (const w of r?.warnings ?? [])
+        console.warn(`a12s: ${w}`);
+}

package/dist/src/node.d.ts

@@ -23,7 +23,8 @@ export interface ConnectOptions extends A12sClientOptions {
  * 2. the Fleet named by `fleet`;
  * 3. the Fleet file in `$A12S_FLEET`, else the nearest `fleet.yaml` in the current directory or a parent;
  * 4. the only Fleet with a running Controller on this machine.
- * For 2–4 it reads `~/.a12s/<fleet>/controller.json`, which `a12s up` writes.
+ * For 2–4 it reads `~/.a12s/<fleet>/controller.json`, which `a12s up` writes: its URL always, and its owner token
+ * unless `token` is given (a prefix or narrow token on this machine).
  */
 export declare function connect(opts?: ConnectOptions): Promise<A12sClient>;
 /** metadata.name from a Fleet file, in either `metadata: { name: x }` or block form. */

package/dist/src/node.js

@@ -21,7 +21,8 @@ export class Fleet extends PageFleet {
  * 2. the Fleet named by `fleet`;
  * 3. the Fleet file in `$A12S_FLEET`, else the nearest `fleet.yaml` in the current directory or a parent;
  * 4. the only Fleet with a running Controller on this machine.
- * For 2–4 it reads `~/.a12s/<fleet>/controller.json`, which `a12s up` writes.
+ * For 2–4 it reads `~/.a12s/<fleet>/controller.json`, which `a12s up` writes: its URL always, and its owner token
+ * unless `token` is given (a prefix or narrow token on this machine).
  */
 export async function connect(opts = {}) {
     return new A12sClient(await discover(opts));
@@ -40,7 +41,7 @@ async function discover(opts) {
     catch (err) {
         throw new Error(`Fleet ${fleet} isn't running (no ${path}): run a12s up in its directory first`, { cause: err });
     }
-    return { url: `http://127.0.0.1:${cf.port}`, token: cf.token, fetch: opts.fetch };
+    return { url: `http://127.0.0.1:${cf.port}`, token: opts.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coltonkirsten/a12s",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "TypeScript client for a12s: send work to agent Computers, stream their events and Turns, in Node or the browser",
   "license": "MIT",
   "type": "module",