@coltonkirsten/a12s 0.4.2 → 0.5.0

package/dist/src/client.d.ts

@@ -49,13 +49,13 @@ export interface EventsOptions {
     onGap?: "yield" | "throw";
 }
 export type SharedEventsOptions = Omit<EventsOptions, "turn" | "after">;
-export interface PromptOptions extends Omit<EnqueueRequest, "body"> {
+export interface WaitOptions {
     signal?: AbortSignal;
     /** Every event of the Turn, as it streams. */
     onEvent?: (ev: A12sEvent) => void;
 }
-/** What `prompt()` resolves with: the finished Turn and the Message that started it. */
-export interface PromptResult extends Turn {
+/** What `send(...).wait()` resolves with: the finished Turn that delivered the Message, and the Message. */
+export interface Reply extends Turn {
     message: EnqueueResponse;
 }
 /**
@@ -82,8 +82,13 @@ export declare class A12sClient {
      * batched with anything else pending. Works while the Computer is busy or asleep.
      */
     send(computer: string, msg: EnqueueRequest | string): Promise<EnqueueResponse>;
-    /** Sends a Message, waits for the Turn that delivers it and resolves when that Turn ends: what `a12s prompt` does. */
-    prompt(computer: string, body: string, opts?: PromptOptions): Promise<PromptResult>;
+    /** Sends a Message, waits for the Turn that delivers it and resolves when that Turn ends. */
+    prompt(computer: string, body: string, opts?: Omit<EnqueueRequest, "body"> & WaitOptions): Promise<Reply>;
+    /**
+     * @internal Waits for the Turn that delivers the Message and resolves when it ends. Delivery is read from the
+     * Message's own snapshot and the Turn is replayed from its start, so it works however late it is called.
+     */
+    reply(computer: string, message: EnqueueResponse, opts?: WaitOptions): Promise<Reply>;
     /**
      * Live events of one Computer, several, or (no argument) every Computer in the Fleet, merged. Each event carries
      * its `computer`. Reconnects after a network drop without losing or repeating events. Call `await stream.ready()`
@@ -107,11 +112,11 @@ export declare class A12sClient {
     /** Interrupts a Turn (default: the active one). The Turn ends `interrupted`; nothing is replayed. */
     stop(computer: string, turn?: 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.
+     * Stops the agent computer's processes and keeps its disks, session and inbox. A Message from a sender its power
+     * policy lists (wakeOnMessage) wakes it; with `hold` it stays asleep until wake().
      */
     sleep(computer: string, opts?: {
-        allowWake?: boolean;
+        hold?: boolean;
     }): Promise<void>;
     /** Starts a sleeping agent computer; its session resumes on the next Turn. `clearInbox` discards pending Messages. */
     wake(computer: string, opts?: {

package/dist/src/client.js

@@ -1,4 +1,4 @@
-// Runs in Node, Deno, Bun and browsers: no node: imports here (`npm run check:browser` enforces it).
+// Runs in Node, Deno, Bun and browsers: no node: imports here (`npm run dashboard` bundles it for the browser).
 import { readSSE } from "./sse.js";
 /** A refused call: the HTTP status and the Controller's error, including its fix line. */
 export class A12sError extends Error {
@@ -94,10 +94,17 @@ export class A12sClient {
         m.idempotencyKey ??= globalThis.crypto.randomUUID();
         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. */
+    /** Sends a Message, waits for the Turn that delivers it and resolves when that Turn ends. */
     async prompt(computer, body, opts = {}) {
         const { signal, onEvent, ...msg } = opts;
-        const message = await this.send(computer, { ...msg, body });
+        return this.reply(computer, await this.send(computer, { ...msg, body }), { signal, onEvent });
+    }
+    /**
+     * @internal Waits for the Turn that delivers the Message and resolves when it ends. Delivery is read from the
+     * Message's own snapshot and the Turn is replayed from its start, so it works however late it is called.
+     */
+    async reply(computer, message, opts = {}) {
+        const { signal, onEvent } = opts;
         const turn = await this.deliveredIn(computer, message.id, signal);
         const builder = new TurnBuilder();
         // A gap mid-Turn would silently drop text: fail loudly instead.
@@ -170,13 +177,13 @@ export class A12sClient {
             await this.request("POST", `/v1/agent-computers/${enc(computer)}/turns/${enc(id)}/stop`, {});
     }
     /**
-     * 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.
+     * Stops the agent computer's processes and keeps its disks, session and inbox. A Message from a sender its power
+     * policy lists (wakeOnMessage) wakes it; with `hold` it stays asleep until wake().
      */
     async sleep(computer, opts = {}) {
         await this.request("POST", `/v1/agent-computers/${enc(computer)}/power`, {
             state: "asleep",
-            ...(opts.allowWake ? { allowWake: true } : {}),
+            ...(opts.hold ? { hold: true } : {}),
         });
     }
     /** Starts a sleeping agent computer; its session resumes on the next Turn. `clearInbox` discards pending Messages. */

package/dist/src/fleet.d.ts

@@ -1,4 +1,4 @@
-import { A12sClient, type A12sClientOptions, type EventsOptions, TurnStream, type EventStream, type PromptOptions, type PromptResult, type SharedEventsOptions } from "./client.js";
+import { A12sClient, type A12sClientOptions, type EventsOptions, TurnStream, type EventStream, type Reply, type SharedEventsOptions, type WaitOptions } 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 {
@@ -18,7 +18,7 @@ export interface CreateOptions {
  * ```ts
  * const fleet = await Fleet.connect();
  * const hello = await fleet.agentComputers.create("hello", { instructions: "Be helpful" });
- * await hello.prompt("hi");
+ * const reply = await hello.send("hi").wait();
  * await hello.remove();
  * ```
  */
@@ -58,7 +58,11 @@ export declare class Fleet {
 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. */
+    /**
+     * Adds an agent computer to the Fleet and starts it. One that names a credential with no value yet resolves at once,
+     * waiting in Provisioning (`status.waiting`, and a console warning); it starts when the value is set. 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>;
@@ -80,10 +84,11 @@ export declare class AgentComputer {
     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>;
+    /**
+     * Puts a Message in the inbox; it is delivered at the next idle moment. Await it for the queued Message, or call
+     * `wait()` on it (or on the awaited Message, at any time later) for the Turn that delivers it.
+     */
+    send(text: string, opts?: Omit<EnqueueRequest, "body">): Sending;
     /** 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. */
@@ -95,9 +100,9 @@ export declare class AgentComputer {
         limit?: undefined;
     }): TurnStream;
     private pastTurns;
-    /** Stops its processes and keeps its disks, session and inbox until wake(); `allowWake` lets wakeOnMessage wake it. */
+    /** Stops its processes and keeps its disks, session and inbox; a sender in wakeOnMessage wakes it, unless `hold`. */
     sleep(opts?: {
-        allowWake?: boolean;
+        hold?: boolean;
     }): Promise<void>;
     /** Wakes it; `clearInbox` discards the pending Messages first. */
     wake(opts?: {
@@ -116,6 +121,25 @@ export declare class AgentComputer {
     /** Withdraws a pending Message; a 409 A12sError names its state if it is too late. */
     withdraw(id: string): Promise<Message>;
 }
+/** A queued Message. */
+export interface SentMessage extends EnqueueResponse {
+    /**
+     * Waits for the Turn that delivers this Message and resolves with it once it ends, also if it already has. A failed
+     * Turn resolves with status "failed"; a Message that is withdrawn, expired, replaced or held throws A12sError.
+     */
+    wait(opts?: WaitOptions): Promise<Reply>;
+}
+/** What `send()` returns: a promise of the {@link SentMessage}, with its `wait()` one call away. */
+export declare class Sending implements Promise<SentMessage> {
+    private readonly sent;
+    readonly [Symbol.toStringTag] = "Sending";
+    constructor(sent: Promise<SentMessage>);
+    then<A = SentMessage, B = never>(onfulfilled?: ((m: SentMessage) => A | PromiseLike<A>) | null, onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+    catch<B = never>(onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<SentMessage | B>;
+    finally(onfinally?: (() => void) | null): Promise<SentMessage>;
+    /** See {@link SentMessage.wait}. */
+    wait(opts?: WaitOptions): Promise<Reply>;
+}
 export declare class Services {
     private readonly client;
     constructor(client: A12sClient);

package/dist/src/fleet.js

@@ -1,4 +1,4 @@
-// Runs in Node, Deno, Bun and browsers: no node: imports here (`npm run check:browser` enforces it).
+// Runs in Node, Deno, Bun and browsers: no node: imports here (`npm run dashboard` bundles it for the browser).
 import { A12sClient, A12sError, TurnStream, } from "./client.js";
 const enc = encodeURIComponent;
 const maxReplaceTries = 5;
@@ -9,7 +9,7 @@ const maxReplaceTries = 5;
  * ```ts
  * const fleet = await Fleet.connect();
  * const hello = await fleet.agentComputers.create("hello", { instructions: "Be helpful" });
- * await hello.prompt("hi");
+ * const reply = await hello.send("hi").wait();
  * await hello.remove();
  * ```
  */
@@ -98,7 +98,11 @@ export class AgentComputers {
     constructor(client) {
         this.client = client;
     }
-    /** Adds an agent computer to the Fleet and starts it. Fails with code `exists` if the name is taken. */
+    /**
+     * Adds an agent computer to the Fleet and starts it. One that names a credential with no value yet resolves at once,
+     * waiting in Provisioning (`status.waiting`, and a console warning); it starts when the value is set. 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, {
@@ -151,13 +155,15 @@ export class AgentComputer {
     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. */
+    /**
+     * Puts a Message in the inbox; it is delivered at the next idle moment. Await it for the queued Message, or call
+     * `wait()` on it (or on the awaited Message, at any time later) for the Turn that delivers it.
+     */
     send(text, opts = {}) {
-        return this.client.send(this.name, { ...opts, body: text });
+        return new Sending(this.client.send(this.name, { ...opts, body: text }).then((message) => ({
+            ...message,
+            wait: (w) => this.client.reply(this.name, message, w),
+        })));
     }
     /** Its events, live, from the Fleet's shared connection; `turn` replays one Turn from its start instead. */
     events(opts = {}) {
@@ -179,7 +185,7 @@ export class AgentComputer {
             tools: t.tools.map((tc) => ({ ...tc, isError: tc.isError ?? false })),
         }));
     }
-    /** Stops its processes and keeps its disks, session and inbox until wake(); `allowWake` lets wakeOnMessage wake it. */
+    /** Stops its processes and keeps its disks, session and inbox; a sender in wakeOnMessage wakes it, unless `hold`. */
     sleep(opts = {}) {
         return this.client.sleep(this.name, opts);
     }
@@ -210,6 +216,27 @@ export class AgentComputer {
         return this.client.withdraw(this.name, id);
     }
 }
+/** What `send()` returns: a promise of the {@link SentMessage}, with its `wait()` one call away. */
+export class Sending {
+    sent;
+    [Symbol.toStringTag] = "Sending";
+    constructor(sent) {
+        this.sent = sent;
+    }
+    then(onfulfilled, onrejected) {
+        return this.sent.then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.sent.catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.sent.finally(onfinally);
+    }
+    /** See {@link SentMessage.wait}. */
+    async wait(opts) {
+        return (await this.sent).wait(opts);
+    }
+}
 export class Services {
     client;
     constructor(client) {
@@ -317,8 +344,8 @@ 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. */
+/** A write's warnings (a grant to an agent computer that doesn't exist yet, a missing harness credential, a credential
+ * with no value yet) go to the console instead of being dropped. */
 function warnWrites(r) {
     for (const w of r?.warnings ?? [])
         console.warn(`a12s: ${w}`);

package/dist/src/types.d.ts

@@ -3,6 +3,12 @@ export interface Failure {
     reason: string;
     retryable: boolean;
 }
+/** Credentials an agent computer or Service waits for, in Provisioning; it starts by itself once they are set. */
+export interface Waiting {
+    credentials: string[];
+    /** The commands that set them, e.g. "a12s creds set dbname". */
+    fix: string;
+}
 export interface Harness {
     kind: string;
     version: string;
@@ -204,6 +210,7 @@ export interface ComputerStatus {
     name: string;
     phase: Phase;
     error?: Failure;
+    waiting?: Waiting;
     resumePending?: boolean;
     session?: string;
     activeTurn?: string;
@@ -240,6 +247,7 @@ export interface ServiceStatus {
     name: string;
     phase: Phase;
     error?: Failure;
+    waiting?: Waiting;
     image: string;
     pin?: string;
     generation: number;
@@ -405,6 +413,7 @@ export interface FleetChangedData {
 export interface PhaseData {
     phase: Phase;
     error?: Failure;
+    waiting?: Waiting;
 }
 /** A Service's phase, health or restart count changed. */
 export interface ServicePhaseData {
@@ -414,6 +423,7 @@ export interface ServicePhaseData {
     health?: string;
     restarts: number;
     error?: Failure;
+    waiting?: Waiting;
 }
 export interface ToolStartedData {
     id: string;
@@ -502,7 +512,7 @@ export interface ToolCall {
     output?: unknown;
     isError: boolean;
 }
-/** A finished Turn: what `turns()` yields and `prompt()` returns. */
+/** A finished Turn: what `turns()` yields and `wait()` returns. */
 export interface Turn {
     agentComputer: string;
     /** `agentComputer` under its old name, for one release. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coltonkirsten/a12s",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "TypeScript client for a12s: send work to agent Computers, stream their events and Turns, in Node or the browser",
   "license": "MIT",
   "type": "module",
@@ -16,12 +16,10 @@
         "types": "./dist/src/index.d.ts",
         "default": "./dist/src/index.js"
       }
-    },
-    "./browser.js": "./dist/a12s.js"
+    }
   },
   "files": [
-    "dist/src",
-    "dist/a12s.js"
+    "dist/src"
   ],
   "engines": {
     "node": ">=20"
@@ -37,10 +35,10 @@
     "provenance": true
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json && npm run check:browser",
+    "build": "rm -rf dist && tsc -p tsconfig.json && npm run dashboard",
     "lint": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test 'dist/test/*.test.js'",
-    "check:browser": "esbuild src/index.ts --bundle --platform=browser --format=esm --log-level=warning --outfile=dist/a12s.js"
+    "dashboard": "esbuild ../../internal/gateway/dashboard/main.js --bundle --platform=browser --format=esm --alias:@coltonkirsten/a12s=./src/index.ts --log-level=warning --outfile=dist/dashboard.js"
   },
   "devDependencies": {
     "@types/node": "^24.19.1",