@coltonkirsten/a12s 0.4.0 → 0.4.2

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 ?? [];
@@ -469,8 +487,19 @@ function agentComputerOf(ev) {
 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));
 }
+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;
@@ -728,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;
@@ -776,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. */
@@ -813,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. */
@@ -845,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) {
@@ -877,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. */
@@ -909,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;
@@ -965,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 ?? [];
@@ -492,8 +510,23 @@ function wanted(names, ev) {
         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));
 }
+/** 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/dist/src/types.d.ts

@@ -92,6 +92,14 @@ export interface Change {
     when: "now" | "idle" | (string & {});
     /** The top-level spec fields that differ, for an update. */
     fields?: string[];
+    /** Every leaf that differs, for an update, with its value before and after (absent where the field is). */
+    diff?: FieldDiff[];
+}
+/** One leaf of a spec that differs: `path` is dotted field names ("grants.send"); lists and values are leaves. */
+export interface FieldDiff {
+    path: string;
+    before?: unknown;
+    after?: unknown;
 }
 export interface FleetResponse {
     version: number;
@@ -398,6 +406,15 @@ export interface PhaseData {
     phase: Phase;
     error?: Failure;
 }
+/** A Service's phase, health or restart count changed. */
+export interface ServicePhaseData {
+    service: string;
+    phase: Phase;
+    /** "ok", or why the last health check failed. */
+    health?: string;
+    restarts: number;
+    error?: Failure;
+}
 export interface ToolStartedData {
     id: string;
     /** MCP tools are named `mcp__<server>__<tool>`, e.g. `mcp__a12s__send`. */
@@ -468,10 +485,14 @@ export type EgressDeniedEvent = Ev<"egress.denied", EgressDeniedData>;
 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 Controller, on the fleet-wide stream only, after any change to the agent computer's inbox (a burst is one event). */
+export type InboxChangedEvent = Ev<"inbox.changed", InboxSummary>;
+/** Made by the Controller, on the fleet-wide stream only; `agentComputer` is empty, the Service is in `data`. */
+export type ServicePhaseEvent = Ev<"service.phase", ServicePhaseData>;
 /** 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 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 A12sEvent = TurnStartedEvent | TurnDispatchedEvent | TextDeltaEvent | ToolStartedEvent | ToolFinishedEvent | PermissionEvent | DiagnosticEvent | TurnFinishedEvent | SessionChangedEvent | ResumeFailedEvent | LifecycleEvent | HarnessRestartedEvent | ContinuationAbandonedEvent | TurnRefusedEvent | InboxDiscardedEvent | EgressDeniedEvent | FleetChangedEvent | PhaseEvent | InboxChangedEvent | ServicePhaseEvent | 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 {
@@ -530,6 +551,8 @@ export interface CredentialInfo {
     name: string;
     set: boolean;
     usedBy?: string[];
+    /** When the value last changed (RFC 3339); absent if unknown. */
+    updatedAt?: string;
 }
 export interface CredentialsResponse {
     credentials: CredentialInfo[];
@@ -540,6 +563,8 @@ export interface Token {
     computers: string[];
     prefix?: string;
     createdAt: string;
+    /** When it last authenticated (RFC 3339, recorded at most once a minute); absent if never. */
+    lastUsedAt?: string;
     secret?: string;
 }
 export {};

package/package.json

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