@pinecall/agents 0.9.20

package/dist/client/client.js

@@ -0,0 +1,284 @@
+// The client: one socket, the agents registered on it, and log reads for the key's org.
+import { createRequire } from "node:module";
+import { hostname } from "node:os";
+import { eventOf } from "../wire/codec.js";
+import {} from "../wire/envelope.js";
+import {} from "../wire/registry.js";
+import { Agent } from "./agent.js";
+import { Connection } from "./connection.js";
+import { lookupUrl } from "./endpoints.js";
+import { PinecallError, frame } from "./frames.js";
+import { Listeners, asError } from "./listeners.js";
+import { history, observe } from "./observe.js";
+import { signed } from "./signed.js";
+// Two levels up from both dist/client/ and src/client/.
+const { version } = createRequire(import.meta.url)("../../package.json");
+// `error` code sent when an org member stops this app (`POST /v1/apps/{app}/stop`). The client must
+// not reconnect afterwards, or the stop would have no effect.
+const STOPPED = "stopped";
+// Should fit inside the process manager's shutdown grace period.
+const DEFAULT_TOOLS_MS = 30_000;
+/**
+ * One app's connection to Pinecall.
+ *
+ * `url` and `apiKey` must be passed explicitly; nothing is read from the environment, so a stale
+ * `PINECALL_API_KEY` (also used by the v1 SDK) can never select the wrong org.
+ */
+export class Pinecall {
+    sdk;
+    /** This machine's hostname, shown by the gateway next to the app. */
+    host = hostname();
+    /** The gateway this client talks to. */
+    url;
+    /** The API key. Sent in a header, never in a URL. */
+    apiKey;
+    /** The requested world, or undefined to use the key's own. */
+    env;
+    #agents = new Map();
+    #listeners;
+    #errors = new Set();
+    #connects = new Set();
+    #stops = new Set();
+    #entries = 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.env = options.env;
+        this.sdk = options.sdk ?? `pinecall/${version}`;
+        this.#listeners = new Listeners((error) => this.onError(error));
+        const dial = { url, apiKey, ...(options.env === undefined ? {} : { env: options.env }) };
+        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 serves. 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, register every agent and send its declaration. */
+    async connect() {
+        await this.#connection.start();
+    }
+    /**
+     * Shut down without cutting calls: each agent drains (live calls move to another holder or are
+     * parked) and running tools get up to `toolsMs` to finish. Does not close the socket; call
+     * `close()` afterwards.
+     */
+    async drain({ answerMs, toolsMs = DEFAULT_TOOLS_MS } = {}) {
+        this.#connection.leaving();
+        const agents = [...this.#agents.values()];
+        const done = { handed: 0, parked: 0, tools: 0, finished: 0 };
+        if (!this.connected)
+            return done;
+        const answers = await Promise.allSettled(agents.map((agent) => agent.drain(answerMs)));
+        for (const answer of answers) {
+            if (answer.status === "fulfilled") {
+                done.handed += answer.value.handed;
+                done.parked += answer.value.parked;
+            }
+            else {
+                this.onError(asError(answer.reason));
+            }
+        }
+        done.tools = agents.reduce((sum, agent) => sum + agent.inFlight, 0);
+        let timer;
+        const cap = new Promise((resolve) => {
+            timer = setTimeout(resolve, toolsMs);
+        });
+        await Promise.race([Promise.all(agents.map((agent) => agent.settled())), cap]);
+        clearTimeout(timer);
+        done.finished = done.tools - agents.reduce((sum, agent) => sum + agent.inFlight, 0);
+        return done;
+    }
+    /** Close the socket without reconnecting. Every agent's slug is released. */
+    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);
+    }
+    /**
+     * Called after each (re)connect once every agent is declared. Use it to re-send state the
+     * gateway keeps only for a live socket.
+     */
+    onConnected(listener) {
+        this.#connects.add(listener);
+        return () => {
+            this.#connects.delete(listener);
+        };
+    }
+    /**
+     * Called when an org member stops this app. The socket is closed for good; the app decides what
+     * to do next (usually exit).
+     */
+    onStopped(listener) {
+        this.#stops.add(listener);
+        return () => {
+            this.#stops.delete(listener);
+        };
+    }
+    /**
+     * Every entry the socket receives, as the gateway wrote it (snake_case), before any agent takes
+     * it — other agents' entries and the client's own errors included.
+     */
+    onEntries(listener) {
+        this.#entries.add(listener);
+        return () => {
+            this.#entries.delete(listener);
+        };
+    }
+    /** Receive errors no caller awaits (bad frames, listener throws, socket loss). Defaults to `console.error`. */
+    onErrors(listener) {
+        this.#errors.add(listener);
+        return () => {
+            this.#errors.delete(listener);
+        };
+    }
+    /** Stream a log live, folded by the protocol's reducer. */
+    observe(target, options = {}) {
+        return observe(target, this.#reading(options));
+    }
+    /** Read one page of a log and its folded state. */
+    async history(target, options = {}) {
+        return history(target, this.#reading(options));
+    }
+    /**
+     * Search the agent's knowledge bases on behalf of a call this client serves. The gateway runs
+     * the search and logs it.
+     * @param k Number of chunks; defaults to the base's setting.
+     */
+    async search(call, query, k) {
+        const answered = await fetch(lookupUrl(this.url, call), {
+            method: "POST",
+            headers: { ...signed(this.apiKey, this.env), "content-type": "application/json" },
+            body: JSON.stringify({ tool: "search", input: k === undefined ? { query } : { query, k } }),
+        });
+        const text = await answered.text();
+        if (!answered.ok)
+            throw new PinecallError(`search: the gateway answered ${answered.status}: ${detailOf(text)}`);
+        return JSON.parse(text).output.chunks;
+    }
+    // ── what the agents send through ────────────────────────────────────────────
+    /** Send one command frame, validated against its schema. */
+    send(type, agent, call, data, id) {
+        this.#connection.send(frame(type, agent, call, data, id));
+    }
+    /** Emit an event an agent has handled to the client-wide listeners. */
+    seen(event, call) {
+        this.#listeners.emit(event, call);
+    }
+    /** Report an error no caller awaits. */
+    onError(error) {
+        if (this.#errors.size === 0) {
+            console.error(error);
+            return;
+        }
+        for (const listener of this.#errors) {
+            listener(error);
+        }
+    }
+    #take(entry) {
+        for (const listener of this.#entries) {
+            try {
+                listener(entry);
+            }
+            catch (failed) {
+                this.onError(asError(failed));
+            }
+        }
+        if (entry.type === "error" && entry.agent === "") {
+            const said = eventOf(entry);
+            if (said.type === "error" && said.data.code === STOPPED)
+                return this.#stopped(said.data.message);
+        }
+        const agent = this.#agents.get(entry.agent);
+        if (agent === undefined) {
+            // Not one of ours: the socket may carry other agents' entries.
+            return;
+        }
+        try {
+            agent.take(entry);
+        }
+        catch (failed) {
+            this.onError(asError(failed));
+        }
+    }
+    // With no stop listener, report the stop as an error so it is not silent.
+    #stopped(why) {
+        this.#connection.close();
+        if (this.#stops.size === 0) {
+            this.onError(new PinecallError(why));
+            return;
+        }
+        for (const listener of this.#stops) {
+            try {
+                listener(why);
+            }
+            catch (failed) {
+                this.onError(asError(failed));
+            }
+        }
+    }
+    async #declareAll() {
+        for (const agent of this.#agents.values()) {
+            await agent.open();
+        }
+        for (const listener of this.#connects) {
+            try {
+                listener();
+            }
+            catch (failed) {
+                this.onError(asError(failed));
+            }
+        }
+    }
+    #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, ...(this.env === undefined ? {} : { env: this.env }), ...options };
+    }
+}
+/** The `detail` of an error body, or the raw body. */
+function detailOf(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed.detail === "string" ? parsed.detail : text;
+    }
+    catch {
+        return text;
+    }
+}
+//# 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,52 @@
+import { type Command, type Entry } from "../wire/envelope.js";
+import { type World } from "./signed.js";
+/** Reconnect backoff: first delay, cap, and growth factor. */
+export interface Backoff {
+    firstMs: number;
+    capMs: number;
+    factor: number;
+}
+/** Options for a `Connection`. */
+export interface ConnectionOptions {
+    url: string;
+    apiKey: string;
+    /** The world to register agents in; omitted means sandbox. See `signed.ts`. */
+    env?: World;
+    pingMs?: number;
+    backoff?: Partial<Backoff>;
+}
+/** Callbacks a `Connection` drives. */
+export interface ConnectionHandlers {
+    /** The socket is up; re-send registrations before anything else. */
+    onOpen: () => Promise<void>;
+    /** One decoded log entry. */
+    onEntry: (entry: Entry) => void;
+    /** An unreadable frame, a throwing handler, or a socket failure. */
+    onError: (error: Error) => void;
+    /** Fired every `pingMs` while the socket is up. */
+    onHeartbeat: () => void;
+}
+/**
+ * One gateway connection across reconnects. The key is sent as `Authorization: Bearer` on the
+ * upgrade, never in the URL, which would end up in access logs.
+ */
+export declare class Connection {
+    #private;
+    private readonly options;
+    private readonly handlers;
+    constructor(options: ConnectionOptions, handlers: ConnectionHandlers);
+    /** True while the socket is open. */
+    get open(): boolean;
+    /** Open the socket and resolve once `onOpen` has run. Later drops reconnect automatically. */
+    start(): Promise<void>;
+    /** Send one command. Throws if the socket is down; nothing is queued. */
+    send(command: Command): void;
+    /**
+     * Keep the current socket but never reconnect. A reconnect mid-drain would re-register the
+     * agents and be handed the calls the drain just moved.
+     */
+    leaving(): void;
+    /** Close the socket without reconnecting. */
+    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":"AAGA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAK/D,OAAO,EAAU,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEjD,8DAA8D;AAC9D,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kCAAkC;AAClC,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,GAAG,CAAC,EAAE,KAAK,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,6BAA6B;IAC7B,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChC,oEAAoE;IACpE,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChC,mDAAmD;IACnD,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAQD;;;GAGG;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,qCAAqC;IACrC,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,8FAA8F;IACxF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAa3B;IAED,yEAAyE;IACzE,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAM3B;IAED;;;OAGG;IACH,OAAO,IAAI,IAAI,CAId;IAED,6CAA6C;IAC7C,KAAK,IAAI,IAAI,CAKZ;CAgFF"}

package/dist/client/connection.js

@@ -0,0 +1,157 @@
+// The gateway socket: authentication, reconnect with backoff, and heartbeat pings.
+import { decodeEntry } from "../wire/codec.js";
+import {} from "../wire/envelope.js";
+import WebSocket from "ws";
+import { appsUrl } from "./endpoints.js";
+import { PinecallError } from "./frames.js";
+import { asError } from "./listeners.js";
+import { signed } from "./signed.js";
+const DEFAULT_BACKOFF = { firstMs: 500, capMs: 30_000, factor: 2 };
+const DEFAULT_PING_MS = 30_000;
+// RFC 6455 policy violation: the gateway refused the key for this socket. Reported, not retried.
+const POLICY_VIOLATION = 1008;
+/**
+ * One gateway connection across reconnects. The key is sent as `Authorization: Bearer` on the
+ * upgrade, never in the URL, which would end up in access logs.
+ */
+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 while the socket is open. */
+    get open() {
+        return this.#socket?.readyState === WebSocket.OPEN;
+    }
+    /** Open the socket and resolve once `onOpen` has run. Later drops reconnect automatically. */
+    async start() {
+        this.#closed = false;
+        return new Promise((resolve, reject) => {
+            this.#opened = (error) => {
+                this.#opened = null;
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            };
+            this.#dial();
+        });
+    }
+    /** Send one command. Throws if the socket is down; nothing is 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));
+    }
+    /**
+     * Keep the current socket but never reconnect. A reconnect mid-drain would re-register the
+     * agents and be handed the calls the drain just moved.
+     */
+    leaving() {
+        this.#closed = true;
+        if (this.#reconnect !== null)
+            clearTimeout(this.#reconnect);
+        this.#reconnect = null;
+    }
+    /** Close the socket without reconnecting. */
+    close() {
+        this.#closed = true;
+        this.#stopTimers();
+        this.#socket?.close();
+        this.#socket = null;
+    }
+    #dial() {
+        const socket = new WebSocket(appsUrl(this.options.url), {
+            headers: signed(this.options.apiKey, this.options.env),
+        });
+        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, reason) => this.#onClose(code, reason.toString()));
+    }
+    async #onOpen() {
+        this.#attempt = 0;
+        this.#failed = null;
+        try {
+            await this.handlers.onOpen();
+        }
+        catch (failed) {
+            // Report once: as `start`'s rejection on first connect, otherwise through onError.
+            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, reason) {
+        this.#stopTimers();
+        this.#socket = null;
+        if (this.#closed) {
+            return;
+        }
+        // Prefer the close reason: the gateway explains refusals there. Fall back to the code.
+        const why = new PinecallError(`the gateway refused the socket: ${this.#failed?.message ?? (reason || `closed with ${code}`)}`);
+        // A failed first connect rejects `start`; later closes are retried.
+        if (this.#opened !== null) {
+            this.#opened(why);
+            return;
+        }
+        // Except a refusal: retrying a key that lacks the scope would loop silently forever.
+        if (code === POLICY_VIOLATION) {
+            this.#closed = true;
+            this.handlers.onError(why);
+            return;
+        }
+        this.#reconnect = setTimeout(() => this.#dial(), this.#waitMs());
+    }
+    // Full jitter, so clients that lost the same gateway don't reconnect in lockstep.
+    #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":"AAAA,mFAAmF;AAEnF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAA4B,MAAM,qBAAqB,CAAC;AAC/D,OAAO,SAAS,MAAM,IAAI,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,MAAM,EAAc,MAAM,aAAa,CAAC;AA+BjD,MAAM,eAAe,GAAY,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AAC5E,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B,iGAAiG;AACjG,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B;;;GAGG;AACH,MAAM,OAAO,UAAU;IAYF,OAAO;IACP,QAAQ;IAZ3B,OAAO,GAAqB,IAAI,CAAC;IACjC,UAAU,GAA0B,IAAI,CAAC;IACzC,KAAK,GAA0B,IAAI,CAAC;IACpC,QAAQ,GAAG,CAAC,CAAC;IACb,OAAO,GAAG,KAAK,CAAC;IAChB,OAAO,GAAiB,IAAI,CAAC;IAC7B,OAAO,GAAqC,IAAI,CAAC;IACxC,QAAQ,CAAU;IAClB,OAAO,CAAS;IAEzB,YACmB,OAA0B,EAC1B,QAA4B;uBAD5B,OAAO;wBACP,QAAQ;QAEzB,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,eAAe,CAAC;IACnD,CAAC;IAED,qCAAqC;IACrC,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI,CAAC;IACrD,CAAC;IAED,8FAA8F;IAC9F,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC3C,IAAI,CAAC,OAAO,GAAG,CAAC,KAAK,EAAE,EAAE;gBACvB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;gBACpB,IAAI,KAAK,EAAE,CAAC;oBACV,MAAM,CAAC,KAAK,CAAC,CAAC;gBAChB,CAAC;qBAAM,CAAC;oBACN,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC,CAAC;YACF,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IAED,yEAAyE;IACzE,IAAI,CAAC,OAAgB;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;YAC5D,MAAM,IAAI,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,gCAAgC,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI;YAAE,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5D,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;IAED,6CAA6C;IAC7C,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,KAAK;QACH,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;YACtD,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;SACvD,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7C,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5D,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,MAAa,EAAE,EAAE;YACnC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;YACtB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAY,EAAE,MAAc,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAC/F,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC/B,CAAC;QAAC,OAAO,MAAM,EAAE,CAAC;YAChB,mFAAmF;YACnF,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;gBAC1B,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACzC,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YAChC,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1E,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;IACnB,CAAC;IAED,UAAU,CAAC,GAAW;QACpB,IAAI,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAY,CAAC,CAAC,CAAC;QAC5E,CAAC;QAAC,OAAO,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,IAAY,EAAE,MAAc;QACnC,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,uFAAuF;QACvF,MAAM,GAAG,GAAG,IAAI,aAAa,CAAC,mCAAmC,IAAI,CAAC,OAAO,EAAE,OAAO,IAAI,CAAC,MAAM,IAAI,eAAe,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/H,oEAAoE;QACpE,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAClB,OAAO;QACT,CAAC;QACD,qFAAqF;QACrF,IAAI,IAAI,KAAK,gBAAgB,EAAE,CAAC;YAC9B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,kFAAkF;IAClF,OAAO;QACL,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5G,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC;IAChC,CAAC;IAED,WAAW;QACT,KAAK,MAAM,KAAK,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAClD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,YAAY,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;CACF"}

package/dist/client/endpoints.d.ts

@@ -0,0 +1,9 @@
+/** `WS /v1/apps`. An http(s) base maps to ws(s). */
+export declare function appsUrl(base: string): string;
+/** `GET /v1/calls/{id}/events`: one call's log, as a JSON page or 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;
+/** `POST /v1/calls/{id}/lookup`: a knowledge-base search run by the gateway for this call. */
+export declare function lookupUrl(base: string, call: 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,oDAAoD;AACpD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,0EAA0E;AAC1E,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;AAED,8FAA8F;AAC9F,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/client/endpoints.js

@@ -0,0 +1,25 @@
+// Gateway endpoint URLs, built from the base URL the app configures.
+/** `WS /v1/apps`. An http(s) base maps to ws(s). */
+export function appsUrl(base) {
+    return doorAt(base, "/v1/apps", true);
+}
+/** `GET /v1/calls/{id}/events`: one call's log, as a JSON page or 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);
+}
+/** `POST /v1/calls/{id}/lookup`: a knowledge-base search run by the gateway for this call. */
+export function lookupUrl(base, call) {
+    return doorAt(base, `/v1/calls/${encodeURIComponent(call)}/lookup`, 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,qEAAqE;AAErE,oDAAoD;AACpD,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC;AAED,0EAA0E;AAC1E,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,8FAA8F;AAC9F,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,IAAY;IAClD,OAAO,MAAM,CAAC,IAAI,EAAE,aAAa,kBAAkB,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;AAC7E,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,29 @@
+import { type Camel, type CommandData, type EventData } from "../wire/codec.js";
+import { type Command } from "../wire/envelope.js";
+import { type CommandType } from "../wire/registry.js";
+/** Base error for client-side and gateway refusals. */
+export declare class PinecallError extends Error {
+    readonly name = "PinecallError";
+}
+/** A gateway refusal received as an `error` entry; match on `refusal.code`. */
+export declare class Refused extends PinecallError {
+    readonly refusal: Camel<EventData<"error">>;
+    constructor(refusal: Camel<EventData<"error">>);
+}
+/**
+ * Thrown by a dev verb handler to refuse with an HTTP status and a message shown verbatim. Any
+ * other error becomes a 500.
+ */
+export declare class DevRefused extends PinecallError {
+    readonly status: number;
+    readonly detail: string;
+    constructor(status: number, detail: string);
+}
+/** Return a command id unique within this process; an `error` carrying it answers that command. */
+export declare function nextId(): string;
+/**
+ * Build one command frame: camelCase data in, snake_case on the wire. Validates here so a bad
+ * shape throws with the app's stack trace.
+ */
+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,EAAE,KAAK,KAAK,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAW,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAExE,uDAAuD;AACvD,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAkB,IAAI,mBAAmB;CAC1C;AAED,+EAA+E;AAC/E,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,mGAAmG;AACnG,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAED;;;GAGG;AACH,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,CAUT"}

package/dist/client/frames.js

@@ -0,0 +1,51 @@
+// Command frames, validated against their schema, and the client's error types.
+import { toSnake } from "../wire/codec.js";
+import { CommandSchema } from "../wire/envelope.js";
+import { COMMAND_SCHEMAS } from "../wire/registry.js";
+/** Base error for client-side and gateway refusals. */
+export class PinecallError extends Error {
+    name = "PinecallError";
+}
+/** A gateway refusal received as an `error` entry; match on `refusal.code`. */
+export class Refused extends PinecallError {
+    refusal;
+    constructor(refusal) {
+        super(`${refusal.code}: ${refusal.message}`);
+        this.refusal = refusal;
+    }
+}
+/**
+ * Thrown by a dev verb handler to refuse with an HTTP status and a message shown verbatim. Any
+ * other error becomes a 500.
+ */
+export class DevRefused extends PinecallError {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(`${status}: ${detail}`);
+        this.status = status;
+        this.detail = detail;
+    }
+}
+let sent = 0;
+/** Return a command id unique within this process; an `error` carrying it answers that command. */
+export function nextId() {
+    return `c${(sent += 1)}`;
+}
+/**
+ * Build one command frame: camelCase data in, snake_case on the wire. Validates here so a bad
+ * shape throws with the app's stack trace.
+ */
+export function frame(type, agent, call, data, id = nextId()) {
+    // Typed structurally so this package never depends on a zod version.
+    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,gFAAgF;AAEhF,OAAO,EAAgD,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAgB,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAoB,MAAM,qBAAqB,CAAC;AAExE,uDAAuD;AACvD,MAAM,OAAO,aAAc,SAAQ,KAAK;IACpB,IAAI,GAAG,eAAe,CAAC;CAC1C;AAED,+EAA+E;AAC/E,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,mGAAmG;AACnG,MAAM,UAAU,MAAM;IACpB,OAAO,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,KAAK,CACnB,IAAO,EACP,KAAa,EACb,IAAmB,EACnB,IAA2B,EAC3B,EAAE,GAAW,MAAM,EAAE;IAErB,qEAAqE;IACrE,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"}