pinecall 0.1.0

package/dist/client/client.d.ts

@@ -0,0 +1,58 @@
+import type { Camel, CommandData, CommandType, EventType } from "@pinecall/protocol";
+import { Agent, type AgentGateway, type AgentOptions } from "./agent.js";
+import type { Call } from "./calls.js";
+import { type Backoff } from "./connection.js";
+import { type AnyListener, type CamelEvent, type Listener } from "./listeners.js";
+import { type LogTarget, type Observation, type Page, type ReadOptions } from "./observe.js";
+/** Where the gateway is and who we are to it. Both default to the environment. */
+export interface PinecallOptions {
+    url?: string;
+    apiKey?: string;
+    pingMs?: number;
+    backoff?: Partial<Backoff>;
+}
+/**
+ * One app's connection to Pinecall.
+ *
+ * The gateway and the key are given, and this class reads NOTHING from the environment.
+ *
+ * It used to fall back to `PINECALL_URL` and `PINECALL_API_KEY`, and that second name was the
+ * problem: v1's SDK exports it too, so a shell that still had v1's key live handed this client
+ * another org's key and every call it made agreed — silently, because the name was the same.
+ * Where a program keeps its own secret is the program's business; guessing at one is not this
+ * class's, and a client pointed at a host nobody named fails later, where the app cannot read it.
+ */
+export declare class Pinecall implements AgentGateway {
+    #private;
+    readonly sdk: string;
+    /** The gateway this client talks to. */
+    readonly url: string;
+    /** The key it talks with. It travels in a header, never in a URL. */
+    readonly apiKey: string;
+    constructor(options?: PinecallOptions);
+    /** Declare an agent this app speaks for. Nothing is sent until `connect`. */
+    agent(slug: string, options?: AgentOptions): Agent;
+    /** Open the socket, claim every agent's slug and doors, and send every declaration. */
+    connect(): Promise<void>;
+    /** Close the socket and stay closed. Every agent's slug is free the moment it shuts. */
+    close(): void;
+    /** True while the socket is up. */
+    get connected(): boolean;
+    /** Listen for one event type across every agent on this client. */
+    on<K extends EventType>(type: K, listener: Listener<K, Call | null>): () => void;
+    /** Listen for every event across every agent. */
+    onAny(listener: AnyListener<Call | null>): () => void;
+    /** Hear what the client could not hand to anybody: a bad frame, a tool that threw, a lost socket. */
+    onErrors(listener: (error: Error) => void): () => void;
+    /** A log as it happens, folded by the protocol's reducer. */
+    observe(target: LogTarget, options?: Partial<ReadOptions>): AsyncGenerator<Observation>;
+    /** A log as it stands, as one page, and what it folds to. */
+    history(target: LogTarget, options?: Partial<ReadOptions>): Promise<Page>;
+    /** One command frame up the socket, checked against its schema before it leaves. */
+    send<K extends CommandType>(type: K, agent: string, call: string | null, data: Camel<CommandData<K>>, id: string): void;
+    /** One event an agent has finished with, for the listeners registered across every agent. */
+    seen(event: CamelEvent, call: Call | null): void;
+    /** Something failed where nobody was waiting. */
+    onError(error: Error): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAS,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5F,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAc,KAAK,OAAO,EAA0B,MAAM,iBAAiB,CAAC;AAEnF,OAAO,EAAsB,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACtG,OAAO,EAAoB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAK/G,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,YAAW,YAAY;;IAE3C,QAAQ,CAAC,GAAG,SAAyB;IACrC,wCAAwC;IACxC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAMxB,YAAY,OAAO,GAAE,eAAoB,EAqBxC;IAED,6EAA6E;IAC7E,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,KAAK,CAIrD;IAED,uFAAuF;IACjF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAE7B;IAED,wFAAwF;IACxF,KAAK,IAAI,IAAI,CAEZ;IAED,mCAAmC;IACnC,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,mEAAmE;IACnE,EAAE,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,GAAG,MAAM,IAAI,CAE/E;IAED,iDAAiD;IACjD,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,MAAM,IAAI,CAEpD;IAED,qGAAqG;IACrG,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAKrD;IAED,6DAA6D;IAC7D,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,cAAc,CAAC,WAAW,CAAC,CAE1F;IAED,6DAA6D;IACvD,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF;IAID,oFAAoF;IACpF,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAEtH;IAED,6FAA6F;IAC7F,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAE/C;IAED,iDAAiD;IACjD,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAQ1B;CAkCF"}

package/dist/client/client.js

@@ -0,0 +1,146 @@
+// The client: one socket, the agents on it, and a door to any log the key can read.
+import { createRequire } from "node:module";
+import { Agent } from "./agent.js";
+import { Connection } from "./connection.js";
+import { PinecallError, frame } from "./frames.js";
+import { Listeners, asError } from "./listeners.js";
+import { history, observe } from "./observe.js";
+// Two levels up from dist/client/, and from src/client/ under a loader: the package's own manifest.
+const { version } = createRequire(import.meta.url)("../../package.json");
+/**
+ * One app's connection to Pinecall.
+ *
+ * The gateway and the key are given, and this class reads NOTHING from the environment.
+ *
+ * It used to fall back to `PINECALL_URL` and `PINECALL_API_KEY`, and that second name was the
+ * problem: v1's SDK exports it too, so a shell that still had v1's key live handed this client
+ * another org's key and every call it made agreed — silently, because the name was the same.
+ * Where a program keeps its own secret is the program's business; guessing at one is not this
+ * class's, and a client pointed at a host nobody named fails later, where the app cannot read it.
+ */
+export class Pinecall {
+    // `sdk` is the wire's field name for who is registering, so it is this object's too.
+    sdk = `pinecall/${version}`;
+    /** The gateway this client talks to. */
+    url;
+    /** The key it talks with. It travels in a header, never in a URL. */
+    apiKey;
+    #agents = new Map();
+    #listeners;
+    #errors = new Set();
+    #connection;
+    constructor(options = {}) {
+        const { url, apiKey } = options;
+        if (url === undefined || apiKey === undefined) {
+            throw new PinecallError("new Pinecall({ url, apiKey }): one of the two was not given");
+        }
+        this.url = url;
+        this.apiKey = apiKey;
+        this.#listeners = new Listeners((error) => this.onError(error));
+        const dial = { url, apiKey };
+        if (options.pingMs !== undefined) {
+            dial.pingMs = options.pingMs;
+        }
+        if (options.backoff !== undefined) {
+            dial.backoff = options.backoff;
+        }
+        this.#connection = new Connection(dial, {
+            onOpen: () => this.#declareAll(),
+            onEntry: (entry) => this.#take(entry),
+            onError: (error) => this.onError(error),
+            onHeartbeat: () => this.#pingAll(),
+        });
+    }
+    /** Declare an agent this app speaks for. Nothing is sent until `connect`. */
+    agent(slug, options = {}) {
+        const agent = new Agent(slug, options, this);
+        this.#agents.set(slug, agent);
+        return agent;
+    }
+    /** Open the socket, claim every agent's slug and doors, and send every declaration. */
+    async connect() {
+        await this.#connection.start();
+    }
+    /** Close the socket and stay closed. Every agent's slug is free the moment it shuts. */
+    close() {
+        this.#connection.close();
+    }
+    /** True while the socket is up. */
+    get connected() {
+        return this.#connection.open;
+    }
+    /** Listen for one event type across every agent on this client. */
+    on(type, listener) {
+        return this.#listeners.on(type, listener);
+    }
+    /** Listen for every event across every agent. */
+    onAny(listener) {
+        return this.#listeners.onAny(listener);
+    }
+    /** Hear what the client could not hand to anybody: a bad frame, a tool that threw, a lost socket. */
+    onErrors(listener) {
+        this.#errors.add(listener);
+        return () => {
+            this.#errors.delete(listener);
+        };
+    }
+    /** A log as it happens, folded by the protocol's reducer. */
+    observe(target, options = {}) {
+        return observe(target, this.#reading(options));
+    }
+    /** A log as it stands, as one page, and what it folds to. */
+    async history(target, options = {}) {
+        return history(target, this.#reading(options));
+    }
+    // ── what the agents send through ────────────────────────────────────────────
+    /** One command frame up the socket, checked against its schema before it leaves. */
+    send(type, agent, call, data, id) {
+        this.#connection.send(frame(type, agent, call, data, id));
+    }
+    /** One event an agent has finished with, for the listeners registered across every agent. */
+    seen(event, call) {
+        this.#listeners.emit(event, call);
+    }
+    /** Something failed where nobody was waiting. */
+    onError(error) {
+        if (this.#errors.size === 0) {
+            console.error(error);
+            return;
+        }
+        for (const listener of this.#errors) {
+            listener(error);
+        }
+    }
+    #take(entry) {
+        const agent = this.#agents.get(entry.agent);
+        if (agent === undefined) {
+            // An entry for an agent this client never declared: the socket is shared, the app is not.
+            return;
+        }
+        try {
+            agent.take(entry);
+        }
+        catch (failed) {
+            this.onError(asError(failed));
+        }
+    }
+    async #declareAll() {
+        for (const agent of this.#agents.values()) {
+            await agent.open();
+        }
+    }
+    #pingAll() {
+        for (const agent of this.#agents.values()) {
+            try {
+                agent.ping();
+            }
+            catch (failed) {
+                this.onError(asError(failed));
+            }
+        }
+    }
+    #reading(options) {
+        return { url: this.url, apiKey: this.apiKey, ...options };
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}

package/dist/client/connection.d.ts

@@ -0,0 +1,47 @@
+import { type Command, type Entry } from "@pinecall/protocol";
+/** How long the client waits before trying again, and how fast that grows. */
+export interface Backoff {
+    firstMs: number;
+    capMs: number;
+    factor: number;
+}
+/** Where the gateway is, who we are to it, and how patient to be. */
+export interface ConnectionOptions {
+    url: string;
+    apiKey: string;
+    pingMs?: number;
+    backoff?: Partial<Backoff>;
+}
+/** What the client does with what the socket brings. */
+export interface ConnectionHandlers {
+    /** The socket is up: send everything that must be true again before anything else is sent. */
+    onOpen: () => Promise<void>;
+    /** One log entry, exactly as the gateway wrote it. */
+    onEntry: (entry: Entry) => void;
+    /** A frame we could not read, a listener that threw, a socket that failed. */
+    onError: (error: Error) => void;
+    /** Time to prove the socket is alive. */
+    onHeartbeat: () => void;
+}
+/**
+ * One connection over its whole life, reconnects included.
+ *
+ * The key travels as `Authorization: Bearer` on the upgrade, never in the URL, because a URL ends
+ * up in an access log. A wrong key is closed with 1008 and no body, so a socket that never opens
+ * is retried like any other: the gateway will not say more the second time either.
+ */
+export declare class Connection {
+    #private;
+    private readonly options;
+    private readonly handlers;
+    constructor(options: ConnectionOptions, handlers: ConnectionHandlers);
+    /** True between the socket opening and it closing again. */
+    get open(): boolean;
+    /** Open the socket and resolve once `onOpen` has run. After that, staying up is our problem. */
+    start(): Promise<void>;
+    /** One frame up. A command sent while the socket is down is refused, not queued. */
+    send(command: Command): void;
+    /** Stop, and stay stopped: no reconnect follows a close the app asked for. */
+    close(): void;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/client/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/client/connection.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAM3E,8EAA8E;AAC9E,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B;AAED,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,sDAAsD;IACtD,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChC,8EAA8E;IAC9E,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChC,yCAAyC;IACzC,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAKD;;;;;;GAMG;AACH,qBAAa,UAAU;;IAYnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAF3B,YACmB,OAAO,EAAE,iBAAiB,EAC1B,QAAQ,EAAE,kBAAkB,EAI9C;IAED,4DAA4D;IAC5D,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,gGAAgG;IAC1F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAa3B;IAED,oFAAoF;IACpF,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAM3B;IAED,8EAA8E;IAC9E,KAAK,IAAI,IAAI,CAKZ;CA2EF"}

package/dist/client/connection.js

@@ -0,0 +1,141 @@
+// The socket to the gateway: the key at the door, backoff on the way back, a ping while it is up.
+import { decodeEntry } from "@pinecall/protocol";
+import WebSocket from "ws";
+import { appsUrl } from "./endpoints.js";
+import { PinecallError } from "./frames.js";
+import { asError } from "./listeners.js";
+const DEFAULT_BACKOFF = { firstMs: 500, capMs: 30_000, factor: 2 };
+const DEFAULT_PING_MS = 30_000;
+/**
+ * One connection over its whole life, reconnects included.
+ *
+ * The key travels as `Authorization: Bearer` on the upgrade, never in the URL, because a URL ends
+ * up in an access log. A wrong key is closed with 1008 and no body, so a socket that never opens
+ * is retried like any other: the gateway will not say more the second time either.
+ */
+export class Connection {
+    options;
+    handlers;
+    #socket = null;
+    #reconnect = null;
+    #ping = null;
+    #attempt = 0;
+    #closed = false;
+    #failed = null;
+    #opened = null;
+    #backoff;
+    #pingMs;
+    constructor(options, handlers) {
+        this.options = options;
+        this.handlers = handlers;
+        this.#backoff = { ...DEFAULT_BACKOFF, ...options.backoff };
+        this.#pingMs = options.pingMs ?? DEFAULT_PING_MS;
+    }
+    /** True between the socket opening and it closing again. */
+    get open() {
+        return this.#socket?.readyState === WebSocket.OPEN;
+    }
+    /** Open the socket and resolve once `onOpen` has run. After that, staying up is our problem. */
+    async start() {
+        this.#closed = false;
+        return new Promise((resolve, reject) => {
+            this.#opened = (error) => {
+                this.#opened = null;
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            };
+            this.#dial();
+        });
+    }
+    /** One frame up. A command sent while the socket is down is refused, not queued. */
+    send(command) {
+        const socket = this.#socket;
+        if (socket === null || socket.readyState !== WebSocket.OPEN) {
+            throw new PinecallError(`${command.type}: the gateway is not connected`);
+        }
+        socket.send(JSON.stringify(command));
+    }
+    /** Stop, and stay stopped: no reconnect follows a close the app asked for. */
+    close() {
+        this.#closed = true;
+        this.#stopTimers();
+        this.#socket?.close();
+        this.#socket = null;
+    }
+    #dial() {
+        const socket = new WebSocket(appsUrl(this.options.url), {
+            headers: { authorization: `Bearer ${this.options.apiKey}` },
+        });
+        this.#socket = socket;
+        socket.on("open", () => void this.#onOpen());
+        socket.on("message", (raw) => this.#onMessage(raw));
+        socket.on("error", (failed) => {
+            this.#failed = failed;
+            this.handlers.onError(failed);
+        });
+        socket.on("close", (code) => this.#onClose(code));
+    }
+    async #onOpen() {
+        this.#attempt = 0;
+        this.#failed = null;
+        try {
+            await this.handlers.onOpen();
+        }
+        catch (failed) {
+            // The socket is up and what must be true on it is not. Whoever called `start` hears it as a
+            // rejection and that is the whole report; on a reconnect nobody is waiting there, and then
+            // the app's error door is the only one. Both, and one failure is printed twice.
+            if (this.#opened === null) {
+                this.handlers.onError(asError(failed));
+            }
+            else {
+                this.#opened(asError(failed));
+            }
+            return;
+        }
+        this.#ping = setInterval(() => this.handlers.onHeartbeat(), this.#pingMs);
+        this.#opened?.();
+    }
+    #onMessage(raw) {
+        try {
+            this.handlers.onEntry(decodeEntry(JSON.parse(raw.toString())));
+        }
+        catch (failed) {
+            this.handlers.onError(asError(failed));
+        }
+    }
+    #onClose(code) {
+        this.#stopTimers();
+        this.#socket = null;
+        if (this.#closed) {
+            return;
+        }
+        // The first connection failing is the app's to hear: a wrong key, a host nobody is on. Every
+        // close after one that worked is a blip, and a blip is answered with a retry, not a rejection.
+        if (this.#opened !== null) {
+            this.#opened(new PinecallError(`the gateway refused the socket: ${this.#failed?.message ?? `closed with ${code}`}`));
+            return;
+        }
+        this.#reconnect = setTimeout(() => this.#dial(), this.#waitMs());
+    }
+    // Full jitter: every client that lost the same gateway comes back at a different moment.
+    #waitMs() {
+        const window = Math.min(this.#backoff.capMs, this.#backoff.firstMs * this.#backoff.factor ** this.#attempt);
+        this.#attempt += 1;
+        return Math.random() * window;
+    }
+    #stopTimers() {
+        for (const timer of [this.#reconnect, this.#ping]) {
+            if (timer !== null) {
+                clearTimeout(timer);
+            }
+        }
+        this.#reconnect = null;
+        this.#ping = null;
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/client/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/client/connection.ts"],"names":[],"mappings":"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"}

package/dist/client/endpoints.d.ts

@@ -0,0 +1,7 @@
+/** `WS /v1/apps`, from whatever base the app gave: http and https are the same host as ws and wss. */
+export declare function appsUrl(base: string): string;
+/** `GET /v1/calls/{id}/events`: one call's log, as a JSON page or as SSE. */
+export declare function callLogUrl(base: string, call: string): string;
+/** `GET /v1/agents/{slug}/calls`: the agent's own log — registrations, configurations, errors. */
+export declare function agentLogUrl(base: string, agent: string): string;
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/client/endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../../src/client/endpoints.ts"],"names":[],"mappings":"AAEA,sGAAsG;AACtG,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/dist/client/endpoints.js

@@ -0,0 +1,21 @@
+// One base URL, three doors. The app configures a host; nothing else writes a path.
+/** `WS /v1/apps`, from whatever base the app gave: http and https are the same host as ws and wss. */
+export function appsUrl(base) {
+    return doorAt(base, "/v1/apps", true);
+}
+/** `GET /v1/calls/{id}/events`: one call's log, as a JSON page or as SSE. */
+export function callLogUrl(base, call) {
+    return doorAt(base, `/v1/calls/${encodeURIComponent(call)}/events`, false);
+}
+/** `GET /v1/agents/{slug}/calls`: the agent's own log — registrations, configurations, errors. */
+export function agentLogUrl(base, agent) {
+    return doorAt(base, `/v1/agents/${encodeURIComponent(agent)}/calls`, false);
+}
+function doorAt(base, path, websocket) {
+    const url = new URL(base);
+    const secure = url.protocol === "https:" || url.protocol === "wss:";
+    url.protocol = websocket ? (secure ? "wss:" : "ws:") : secure ? "https:" : "http:";
+    url.pathname = `${url.pathname.replace(/\/$/, "")}${path}`;
+    return url.toString();
+}
+//# sourceMappingURL=endpoints.js.map

package/dist/client/endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.js","sourceRoot":"","sources":["../../src/client/endpoints.ts"],"names":[],"mappings":"AAAA,oFAAoF;AAEpF,sGAAsG;AACtG,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,IAAY;IACnD,OAAO,MAAM,CAAC,IAAI,EAAE,aAAa,kBAAkB,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,KAAa;IACrD,OAAO,MAAM,CAAC,IAAI,EAAE,cAAc,kBAAkB,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,MAAM,CAAC,IAAY,EAAE,IAAY,EAAE,SAAkB;IAC5D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,CAAC;IACpE,GAAG,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;IACnF,GAAG,CAAC,QAAQ,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC;IAC3D,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC"}

package/dist/client/frames.d.ts

@@ -0,0 +1,24 @@
+import { type Camel, type Command, type CommandData, type CommandType, type EventData } from "@pinecall/protocol";
+/** Anything the client refuses to do, and anything the gateway refused to do for it. */
+export declare class PinecallError extends Error {
+    readonly name = "PinecallError";
+}
+/** A refusal the gateway sent back as an `error` entry, with the code a program can match. */
+export declare class Refused extends PinecallError {
+    readonly refusal: Camel<EventData<"error">>;
+    constructor(refusal: Camel<EventData<"error">>);
+}
+/**
+ * What a dev verb's handler throws to refuse: the status the console's door answers with, and the
+ * sentence it shows verbatim. Anything else thrown is a 500 with the error's message.
+ */
+export declare class DevRefused extends PinecallError {
+    readonly status: number;
+    readonly detail: string;
+    constructor(status: number, detail: string);
+}
+/** The next command id, unique in this process: an `error` naming it is an answer to us. */
+export declare function nextId(): string;
+/** One command frame, its data camelCase in and snake_case on the wire. A bad shape throws here. */
+export declare function frame<K extends CommandType>(type: K, agent: string, call: string | null, data: Camel<CommandData<K>>, id?: string): Command;
+//# sourceMappingURL=frames.d.ts.map

package/dist/client/frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/client/frames.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,KAAK,EACV,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAE5B,wFAAwF;AACxF,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAkB,IAAI,mBAAmB;CAC1C;AAED,8FAA8F;AAC9F,qBAAa,OAAQ,SAAQ,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAAvD,YAAqB,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,EAEtD;CACF;AAED;;;GAGG;AACH,qBAAa,UAAW,SAAQ,aAAa;IAEzC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM;IAFzB,YACW,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EAGxB;CACF;AAID,4FAA4F;AAC5F,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAID,oGAAoG;AACpG,wBAAgB,KAAK,CAAC,CAAC,SAAS,WAAW,EACzC,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAC3B,EAAE,GAAE,MAAiB,GACpB,OAAO,CAWT"}

package/dist/client/frames.js

@@ -0,0 +1,49 @@
+// A command frame, built and checked against the schema its type names. Nothing here knows a socket.
+import { COMMAND_SCHEMAS, CommandSchema, toSnake, } from "@pinecall/protocol";
+/** Anything the client refuses to do, and anything the gateway refused to do for it. */
+export class PinecallError extends Error {
+    name = "PinecallError";
+}
+/** A refusal the gateway sent back as an `error` entry, with the code a program can match. */
+export class Refused extends PinecallError {
+    refusal;
+    constructor(refusal) {
+        super(`${refusal.code}: ${refusal.message}`);
+        this.refusal = refusal;
+    }
+}
+/**
+ * What a dev verb's handler throws to refuse: the status the console's door answers with, and the
+ * sentence it shows verbatim. Anything else thrown is a 500 with the error's message.
+ */
+export class DevRefused extends PinecallError {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(`${status}: ${detail}`);
+        this.status = status;
+        this.detail = detail;
+    }
+}
+let sent = 0;
+/** The next command id, unique in this process: an `error` naming it is an answer to us. */
+export function nextId() {
+    return `c${(sent += 1)}`;
+}
+// The app writes camelCase and the codec turns it into the wire's keys; the schema then says
+// whether the gateway would have accepted it, here, where the stack trace is still the app's.
+/** One command frame, its data camelCase in and snake_case on the wire. A bad shape throws here. */
+export function frame(type, agent, call, data, id = nextId()) {
+    // zod is @pinecall/protocol's dependency, not ours: the schema is used through the one method
+    // this file needs, so no version of zod is ever named on this side.
+    const schema = COMMAND_SCHEMAS[type];
+    let checked;
+    try {
+        checked = schema.parse(toSnake(data));
+    }
+    catch (bad) {
+        throw new PinecallError(`${type}: ${bad instanceof Error ? bad.message : String(bad)}`);
+    }
+    return CommandSchema.parse({ type, agent, call, id, data: checked });
+}
+//# sourceMappingURL=frames.js.map

package/dist/client/frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.js","sourceRoot":"","sources":["../../src/client/frames.ts"],"names":[],"mappings":"AAAA,qGAAqG;AAErG,OAAO,EACL,eAAe,EACf,aAAa,EACb,OAAO,GAMR,MAAM,oBAAoB,CAAC;AAE5B,wFAAwF;AACxF,MAAM,OAAO,aAAc,SAAQ,KAAK;IACpB,IAAI,GAAG,eAAe,CAAC;CAC1C;AAED,8FAA8F;AAC9F,MAAM,OAAO,OAAQ,SAAQ,aAAa;IACnB,OAAO;IAA5B,YAAqB,OAAkC;QACrD,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;uBAD1B,OAAO;IAE5B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,UAAW,SAAQ,aAAa;IAEhC,MAAM;IACN,MAAM;IAFjB,YACW,MAAc,EACd,MAAc;QAEvB,KAAK,CAAC,GAAG,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;sBAHrB,MAAM;sBACN,MAAM;IAGjB,CAAC;CACF;AAED,IAAI,IAAI,GAAG,CAAC,CAAC;AAEb,4FAA4F;AAC5F,MAAM,UAAU,MAAM;IACpB,OAAO,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC;AAC3B,CAAC;AAED,6FAA6F;AAC7F,8FAA8F;AAC9F,oGAAoG;AACpG,MAAM,UAAU,KAAK,CACnB,IAAO,EACP,KAAa,EACb,IAAmB,EACnB,IAA2B,EAC3B,EAAE,GAAW,MAAM,EAAE;IAErB,8FAA8F;IAC9F,oEAAoE;IACpE,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAuC,CAAC;IAC3E,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,aAAa,CAAC,GAAG,IAAI,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AACvE,CAAC"}

package/dist/client/index.d.ts

@@ -0,0 +1,15 @@
+export { Agent } from "./agent.js";
+export type { AgentGateway, AgentOptions, DevHandler, RouteInput, Tool } from "./agent.js";
+export { Call, CallBook } from "./calls.js";
+export type { CallGateway, CallStatus } from "./calls.js";
+export { Pinecall } from "./client.js";
+export type { PinecallOptions } from "./client.js";
+export { Connection } from "./connection.js";
+export type { Backoff, ConnectionHandlers, ConnectionOptions } from "./connection.js";
+export { agentLogUrl, appsUrl, callLogUrl } from "./endpoints.js";
+export { DevRefused, PinecallError, Refused, frame, nextId } from "./frames.js";
+export { Listeners, camelEvent } from "./listeners.js";
+export type { AnyListener, CamelEvent, Listener, Payload } from "./listeners.js";
+export { history, observe } from "./observe.js";
+export type { LogTarget, Observation, Page, ReadOptions } from "./observe.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,14 @@
+// pinecall/client: an app registers its agents over the gateway's WS door, answers their tool
+// calls, and reads any log its key can reach. The wire's own shapes come from @pinecall/protocol.
+//
+// This is the socket, and nothing above it: no Agent class, no view, no CLI. An app that has
+// its own way of deciding what to answer imports this and never the framework.
+export { Agent } from "./agent.js";
+export { Call, CallBook } from "./calls.js";
+export { Pinecall } from "./client.js";
+export { Connection } from "./connection.js";
+export { agentLogUrl, appsUrl, callLogUrl } from "./endpoints.js";
+export { DevRefused, PinecallError, Refused, frame, nextId } from "./frames.js";
+export { Listeners, camelEvent } from "./listeners.js";
+export { history, observe } from "./observe.js";
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,kGAAkG;AAClG,EAAE;AACF,6FAA6F;AAC7F,+EAA+E;AAE/E,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/client/listeners.d.ts

@@ -0,0 +1,36 @@
+import { type Camel, type Event, type EventData, type EventType } from "@pinecall/protocol";
+/** One event's data as the app reads it: the wire's shape, camelCase. */
+export type Payload<K extends EventType> = Camel<EventData<K>>;
+/** One event, typed by its type, as the app reads it: switch on `type` and `data` narrows with it. */
+export type CamelEvent = {
+    [K in EventType]: {
+        type: K;
+        data: Payload<K>;
+    };
+}[EventType];
+/** What runs when an event of one type arrives. */
+export type Listener<K extends EventType, Context> = (data: Payload<K>, context: Context) => unknown;
+/** What runs for every event, whatever its type. */
+export type AnyListener<Context> = (event: CamelEvent, context: Context) => unknown;
+/** The decoded event with its keys as the app reads them. */
+export declare function camelEvent(event: Event): CamelEvent;
+/**
+ * Every listener registered against one thing — an agent, or a call — and the dispatch to them.
+ *
+ * A listener that throws is a bug in the app, not a reason to stop reading the socket: it is
+ * handed to `onError` and the next listener still runs.
+ */
+export declare class Listeners<Context> {
+    #private;
+    private readonly onError;
+    constructor(onError: (error: Error) => void);
+    /** Listen for one event type. The returned function stops listening. */
+    on<K extends EventType>(type: K, listener: Listener<K, Context>): () => void;
+    /** Listen for every event. The returned function stops listening. */
+    onAny(listener: AnyListener<Context>): () => void;
+    /** Hand one event to everybody waiting for it, then to everybody waiting for anything. */
+    emit(event: CamelEvent, context: Context): void;
+}
+/** Whatever was thrown, as an Error: `catch` gives `unknown` and a listener may throw a string. */
+export declare function asError(thrown: unknown): Error;
+//# sourceMappingURL=listeners.d.ts.map

package/dist/client/listeners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../src/client/listeners.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,KAAK,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAErG,yEAAyE;AACzE,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/D,sGAAsG;AACtG,MAAM,MAAM,UAAU,GAAG;KAAG,CAAC,IAAI,SAAS,GAAG;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE;CAAE,CAAC,SAAS,CAAC,CAAC;AAExF,mDAAmD;AACnD,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;AAErG,oDAAoD;AACpD,MAAM,MAAM,WAAW,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;AAIpF,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,UAAU,CAEnD;AAED;;;;;GAKG;AACH,qBAAa,SAAS,CAAC,OAAO;;IAIhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAApC,YAA6B,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAAI;IAEhE,wEAAwE;IACxE,EAAE,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,MAAM,IAAI,CAO3E;IAED,qEAAqE;IACrE,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI,CAKhD;IAED,0FAA0F;IAC1F,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAO9C;CAYF;AAED,mGAAmG;AACnG,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,KAAK,CAE9C"}