@pinecall/agents 0.9.20

package/dist/client/agent.js

@@ -0,0 +1,230 @@
+// One agent an app serves: its declaration, its tool handlers and its listeners.
+import {} from "../wire/agent-config.js";
+import { eventOf } from "../wire/codec.js";
+import {} from "../wire/defs.js";
+import {} from "../wire/envelope.js";
+import {} from "../wire/registry.js";
+import { Call, CallBook } from "./calls.js";
+import { DevRefused, PinecallError, Refused } from "./frames.js";
+import { Listeners, asError, camelEvent } from "./listeners.js";
+const ANSWER_MS = 10_000;
+const NO_DEV_HANDLER = "this process answers no dev verbs: it is not a `pinecall start` in the agent's directory";
+/**
+ * An agent, from the app's side.
+ *
+ * The gateway's registry is in memory, so the declaration is re-sent on every reconnect. Several
+ * sockets may hold one agent; unclaimed calls go to the newest one that takes them, so a rolling
+ * deploy serves as soon as the new process registers. Call `drain()` before exiting to hand live
+ * calls over instead of cutting them.
+ */
+export class Agent {
+    slug;
+    gateway;
+    calls;
+    #listeners;
+    #tools = new Map();
+    #waiters = [];
+    // Tool runs whose tool.result is not yet sent; a drain waits for these.
+    #running = new Set();
+    #config;
+    #takesUnclaimed;
+    #answersDev;
+    #app;
+    #dev;
+    constructor(slug, options, gateway) {
+        this.slug = slug;
+        this.gateway = gateway;
+        const { tools = [], takesUnclaimed = true, answersDev = false, ...config } = options;
+        this.#config = config;
+        this.#takesUnclaimed = takesUnclaimed;
+        this.#answersDev = answersDev;
+        this.declare(tools);
+        this.calls = new CallBook(this);
+        this.#listeners = new Listeners((error) => gateway.onError(error));
+    }
+    /** The agent's current declaration, in wire shape. */
+    get config() {
+        return this.#config;
+    }
+    /**
+     * This socket's app id as minted by the gateway, or undefined before the first register. A call
+     * that names it (`WS /v1/chat?app=<id>`, `app` in `POST /v1/calls`) is served by this process.
+     */
+    get app() {
+        return this.#app;
+    }
+    /** Listen for one event type across every call of this agent. `null` for the agent's own log. */
+    on(type, listener) {
+        return this.#listeners.on(type, listener);
+    }
+    /** Listen for every event of this agent. The returned function stops listening. */
+    onAny(listener) {
+        return this.#listeners.onAny(listener);
+    }
+    /**
+     * Handle `dev.request` asks relayed from a console. `pinecall start` registers one; without it
+     * every ask is refused with 501.
+     */
+    onDev(handler) {
+        this.#dev = handler;
+    }
+    /** Replace the tools. The next `configure` sends the new declaration. */
+    declare(tools) {
+        this.#tools.clear();
+        for (const tool of tools) {
+            this.#tools.set(tool.name, tool);
+        }
+        this.#config = { ...this.#config, tools: tools.map(({ run: _run, ...spec }) => spec) };
+    }
+    /** Update the declaration. Only the given fields change; live calls keep their session. */
+    async configure(changes = {}) {
+        this.#config = { ...this.#config, ...changes };
+        return this.#ask("agent.configure", "agent.configured", { config: this.#config });
+    }
+    /** Register the slug, then send the declaration. Runs again on every reconnect. */
+    async open() {
+        // Routes are org rows now; the empty field stays for older gateways.
+        const registered = await this.#ask("agent.register", "agent.registered", {
+            routes: [],
+            sdk: this.gateway.sdk,
+            host: this.gateway.host,
+            takesUnclaimed: this.#takesUnclaimed,
+            ...(this.#answersDev ? { answersDev: true } : {}),
+        });
+        // Each reconnect mints a new app id.
+        this.#app = registered.app;
+        // A registration inherits the newest holder's declaration; one sent from here would replace it.
+        if (!this.#answersDev)
+            await this.configure();
+    }
+    // ── the socket's side ───────────────────────────────────────────────────────
+    /** Fold one entry into its call and dispatch it to listeners. */
+    take(entry) {
+        const event = camelEvent(eventOf(entry));
+        const call = entry.call === null ? null : this.calls.of(entry.call, entry.ts);
+        this.#settle(event);
+        call?.take(event);
+        this.#listeners.emit(event, call);
+        this.gateway.seen(event, call);
+        if (event.type === "dev.request") {
+            this.#onDevRequest(event.data);
+            return;
+        }
+        if (call !== null) {
+            this.#onToolCall(event, call);
+            this.calls.forget(call);
+        }
+    }
+    /** Send one command on this agent's behalf. */
+    command(type, call, data) {
+        this.gateway.send(type, this.slug, call, data, `${this.slug}:${type}`);
+    }
+    /** Report an error no caller is waiting on. */
+    onError(error) {
+        this.gateway.onError(error);
+    }
+    /**
+     * Stop receiving new calls and hand live ones to another holder (or park them for the next).
+     * Running tools still answer. Resolves with where the calls went.
+     */
+    async drain(answerMs = ANSWER_MS) {
+        return this.#ask("agent.drain", "agent.draining", {}, answerMs);
+    }
+    /** Number of tool runs in progress. */
+    get inFlight() {
+        return this.#running.size;
+    }
+    /** Resolve once every running tool has sent its tool.result. */
+    async settled() {
+        await Promise.all([...this.#running]);
+    }
+    /** Send `ping`; the gateway answers with `pong`. */
+    ping() {
+        this.command("ping", null, {});
+    }
+    // ── tools ───────────────────────────────────────────────────────────────────
+    // Every outcome must produce exactly one tool.result: a turn without one waits forever.
+    #onToolCall(event, call) {
+        if (event.type !== "tool.call") {
+            return;
+        }
+        const { callId, name, arguments: args } = event.data;
+        const tool = this.#tools.get(name);
+        if (tool === undefined) {
+            call.toolResult({ callId, name, error: `this app declares no tool called ${name}` });
+            return;
+        }
+        const started = Date.now();
+        const running = (async () => {
+            try {
+                const output = await tool.run(args, call);
+                call.toolResult({ callId, name, output, durationS: (Date.now() - started) / 1000 });
+            }
+            catch (failed) {
+                // A rejection is the tool's answer (sent as `error`), not an app failure; don't report it.
+                const error = asError(failed);
+                try {
+                    call.toolResult({ callId, name, error: error.message, durationS: (Date.now() - started) / 1000 });
+                }
+                catch (unsent) {
+                    this.onError(asError(unsent));
+                }
+            }
+        })();
+        this.#running.add(running);
+        void running.finally(() => this.#running.delete(running));
+    }
+    // ── a console's ask ─────────────────────────────────────────────────────────
+    // Every outcome must produce one dev.answer, or the console's request hangs until timeout.
+    #onDevRequest(asked) {
+        const { id, verb, data } = asked;
+        void (async () => {
+            try {
+                if (this.#dev === undefined)
+                    throw new DevRefused(501, NO_DEV_HANDLER);
+                const result = await this.#dev(verb, data);
+                this.command("dev.answer", null, { id, result });
+            }
+            catch (failed) {
+                const refused = failed instanceof DevRefused
+                    ? { status: failed.status, detail: failed.detail }
+                    : { status: 500, detail: asError(failed).message };
+                this.command("dev.answer", null, { id, refused });
+            }
+        })();
+    }
+    // ── waiting for an answer ───────────────────────────────────────────────────
+    // Resolved by the event the command lands as, or rejected by an `error` carrying our id.
+    async #ask(type, lands, data, withinMs = ANSWER_MS) {
+        const id = `${this.slug}:${type}`;
+        const answer = new Promise((resolve, reject) => {
+            const waiter = { type: lands, id, settle: (payload) => resolve(payload), refuse: reject };
+            this.#waiters.push(waiter);
+            setTimeout(() => {
+                this.#drop(waiter);
+                reject(new PinecallError(`${type}: the gateway did not answer in ${withinMs}ms`));
+            }, withinMs).unref();
+        });
+        this.gateway.send(type, this.slug, null, data, id);
+        return answer;
+    }
+    #settle(event) {
+        for (const waiter of [...this.#waiters]) {
+            if (event.type === waiter.type) {
+                this.#drop(waiter);
+                waiter.settle(event.data);
+            }
+            else if (event.type === "error" && event.data.id === waiter.id) {
+                this.#drop(waiter);
+                waiter.refuse(new Refused(event.data));
+            }
+        }
+    }
+    #drop(waiter) {
+        const at = this.#waiters.indexOf(waiter);
+        if (at !== -1) {
+            this.#waiters.splice(at, 1);
+        }
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/client/agent.js.map

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

package/dist/client/calls.d.ts

@@ -0,0 +1,87 @@
+import { type Camel, type CommandData } from "../wire/codec.js";
+import { type Channel, type Contact, type Medium, type ToolResult, type ToolSpec } from "../wire/defs.js";
+import { type CommandType, type EventType } from "../wire/registry.js";
+import type { AnyListener, CamelEvent, Listener } from "./listeners.js";
+/** The agent a call sends its commands through. */
+export interface CallGateway {
+    readonly slug: string;
+    command<K extends CommandType>(type: K, call: string | null, data: Camel<CommandData<K>>): void;
+    onError(error: Error): void;
+}
+/** The call's lifecycle status, as reported by the log so far. */
+export type CallStatus = "ringing" | "dialing" | "active" | "ended";
+/**
+ * A call the app is serving.
+ *
+ * Fields come only from log entries. Each method sends one command without awaiting it; the result
+ * arrives later as log events.
+ */
+export declare class Call {
+    #private;
+    readonly id: string;
+    private readonly gateway;
+    status: CallStatus;
+    channel: Channel | null;
+    /** Spoken or written, as `call.started` says; null before it, and from a gateway that does not say. */
+    medium: Medium | null;
+    from: string | null;
+    to: string | null;
+    contact: Camel<Contact> | null;
+    /** The eval run that opened this call, or null for a real caller. */
+    run: string | null;
+    /** The page code this call claimed, or null. */
+    claimed: string | null;
+    /** The app state as last set here or reported by `state.changed`. */
+    state: Record<string, unknown>;
+    /**
+     * The day the call opened, `YYYY-MM-DD` in this process's timezone. On `call.attached` it is the
+     * original start day, not the handover day.
+     */
+    today: string;
+    constructor(id: string, gateway: CallGateway, openedAt: number);
+    /** The agent serving this call. */
+    get agent(): string;
+    /** Listen for one event type on this call. The returned function stops listening. */
+    on<K extends EventType>(type: K, listener: Listener<K, Call>): () => void;
+    /** Listen for every event on this call. The returned function stops listening. */
+    onAny(listener: AnyListener<Call>): () => void;
+    /** Say this, verbatim, now. Lands as `turn.agent`. */
+    say(text: string, options?: {
+        allowInterruptions?: boolean;
+    }): void;
+    /** Make the model speak now, following instructions the caller does not hear. Lands as `turn.agent`. */
+    reply(instructions: string, options?: {
+        allowInterruptions?: boolean;
+    }): void;
+    /** Replace one named prompt block: a built-in one or one the agent declared. */
+    setPrompt(name: string, text: string): void;
+    /** Set which declared tools the model may see now. */
+    setTools(tools: Camel<ToolSpec>[]): void;
+    /** Send the full app state. Lands as `state.changed`. */
+    setState(state: Record<string, unknown>, changed?: string[]): void;
+    /** Send a tool's result for the model's `call_id`. */
+    toolResult(result: Camel<ToolResult>): void;
+    /** Send an event from the tenant's backend. Refused unless the agent declared the name. */
+    event(name: string, data: Record<string, unknown>): void;
+    /** End the call from the app's side. `call.ended` follows with reason agent_hung_up. */
+    hangup(reason?: string): void;
+    /** Bind this call to a page code. Lands as `call.claimed`, or is refused with `no_code`. */
+    claim(code: string): void;
+    /** Write an app-defined entry to the call's log. Lands as `custom`. */
+    log(name: string, data?: Record<string, unknown>): void;
+    /** Apply one event to the call's fields, then emit it to this call's listeners. */
+    take(event: CamelEvent): void;
+}
+/** The calls an agent is serving, by id. A call is dropped once it ends. */
+export declare class CallBook {
+    #private;
+    private readonly gateway;
+    constructor(gateway: CallGateway);
+    /** The calls in progress, in the order they opened. */
+    get live(): Call[];
+    /** Return the call with this id, creating it on first sight. */
+    of(id: string, at: number): Call;
+    /** Drop the call if it has ended. Runs after `call.ended` listeners. */
+    forget(call: Call): void;
+}
+//# sourceMappingURL=calls.d.ts.map

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

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

package/dist/client/calls.js

@@ -0,0 +1,180 @@
+// A live call as the app holds it: its known fields and the commands it can send.
+import {} from "../wire/codec.js";
+import {} from "../wire/defs.js";
+import {} from "../wire/registry.js";
+import { Listeners } from "./listeners.js";
+/**
+ * A call the app is serving.
+ *
+ * Fields come only from log entries. Each method sends one command without awaiting it; the result
+ * arrives later as log events.
+ */
+export class Call {
+    id;
+    gateway;
+    status = "ringing";
+    channel = null;
+    /** Spoken or written, as `call.started` says; null before it, and from a gateway that does not say. */
+    medium = null;
+    from = null;
+    to = null;
+    contact = null;
+    /** The eval run that opened this call, or null for a real caller. */
+    run = null;
+    /** The page code this call claimed, or null. */
+    claimed = null;
+    /** The app state as last set here or reported by `state.changed`. */
+    state = {};
+    /**
+     * The day the call opened, `YYYY-MM-DD` in this process's timezone. On `call.attached` it is the
+     * original start day, not the handover day.
+     */
+    today;
+    #listeners;
+    constructor(id, gateway, openedAt) {
+        this.id = id;
+        this.gateway = gateway;
+        this.today = dayOf(openedAt);
+        this.#listeners = new Listeners((error) => gateway.onError(error));
+    }
+    /** The agent serving this call. */
+    get agent() {
+        return this.gateway.slug;
+    }
+    /** Listen for one event type on this call. The returned function stops listening. */
+    on(type, listener) {
+        return this.#listeners.on(type, listener);
+    }
+    /** Listen for every event on this call. The returned function stops listening. */
+    onAny(listener) {
+        return this.#listeners.onAny(listener);
+    }
+    // ── the commands ────────────────────────────────────────────────────────────
+    /** Say this, verbatim, now. Lands as `turn.agent`. */
+    say(text, options = {}) {
+        this.gateway.command("agent.say", this.id, { text, ...options });
+    }
+    /** Make the model speak now, following instructions the caller does not hear. Lands as `turn.agent`. */
+    reply(instructions, options = {}) {
+        this.gateway.command("agent.reply", this.id, { instructions, ...options });
+    }
+    /** Replace one named prompt block: a built-in one or one the agent declared. */
+    setPrompt(name, text) {
+        this.gateway.command("prompt.set", this.id, { name, text });
+    }
+    /** Set which declared tools the model may see now. */
+    setTools(tools) {
+        this.gateway.command("tools.set", this.id, { tools });
+    }
+    /** Send the full app state. Lands as `state.changed`. */
+    setState(state, changed) {
+        this.state = { ...state };
+        this.gateway.command("state.set", this.id, changed === undefined ? { state } : { state, changed });
+    }
+    /** Send a tool's result for the model's `call_id`. */
+    toolResult(result) {
+        this.gateway.command("tool.result", this.id, result);
+    }
+    /** Send an event from the tenant's backend. Refused unless the agent declared the name. */
+    event(name, data) {
+        this.gateway.command("call.event", this.id, { name, data });
+    }
+    /** End the call from the app's side. `call.ended` follows with reason agent_hung_up. */
+    hangup(reason) {
+        this.gateway.command("call.hangup", this.id, reason === undefined ? {} : { reason });
+    }
+    /** Bind this call to a page code. Lands as `call.claimed`, or is refused with `no_code`. */
+    claim(code) {
+        this.gateway.command("call.claim", this.id, { code });
+    }
+    /** Write an app-defined entry to the call's log. Lands as `custom`. */
+    log(name, data = {}) {
+        this.gateway.command("call.log", this.id, { name, data });
+    }
+    // ── what the log teaches it ─────────────────────────────────────────────────
+    /** Apply one event to the call's fields, then emit it to this call's listeners. */
+    take(event) {
+        this.#learn(event);
+        this.#listeners.emit(event, this);
+    }
+    #learn(event) {
+        switch (event.type) {
+            case "call.ringing":
+                this.status = "ringing";
+                this.#line(event.data);
+                return;
+            case "call.dialing":
+                this.status = "dialing";
+                this.#line(event.data);
+                return;
+            case "call.started":
+                this.status = "active";
+                this.#line(event.data);
+                this.medium = event.data.medium ?? null;
+                return;
+            case "call.ended":
+                this.status = "ended";
+                return;
+            // Handed over mid-conversation: carries the original start and current state.
+            case "call.attached":
+                this.status = "active";
+                this.#line(event.data.started);
+                this.medium = event.data.started.medium ?? null;
+                this.state = { ...event.data.state };
+                this.today = dayOf(event.data.started.startedAt);
+                // `claimed` is absent from gateways before protocol 0.6.11.
+                this.claimed = event.data.claimed ?? null;
+                return;
+            case "state.changed":
+                this.state = { ...event.data.state };
+                return;
+            case "call.claimed":
+                this.claimed = event.data.code;
+                return;
+            default:
+                return;
+        }
+    }
+    #line(line) {
+        this.channel = line.channel;
+        this.from = line.from;
+        this.to = line.to;
+        this.contact = line.caller;
+        this.run = line.run ?? null;
+    }
+}
+/** The calls an agent is serving, by id. A call is dropped once it ends. */
+export class CallBook {
+    gateway;
+    #live = new Map();
+    constructor(gateway) {
+        this.gateway = gateway;
+    }
+    /** The calls in progress, in the order they opened. */
+    get live() {
+        return [...this.#live.values()];
+    }
+    /** Return the call with this id, creating it on first sight. */
+    of(id, at) {
+        const known = this.#live.get(id);
+        if (known !== undefined) {
+            return known;
+        }
+        const call = new Call(id, this.gateway, at);
+        this.#live.set(id, call);
+        return call;
+    }
+    /** Drop the call if it has ended. Runs after `call.ended` listeners. */
+    forget(call) {
+        if (call.status === "ended") {
+            this.#live.delete(call.id);
+        }
+    }
+}
+/** `YYYY-MM-DD` of a unix timestamp, in local time. */
+function dayOf(ts) {
+    const at = new Date(ts * 1000);
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}`;
+}
+//# sourceMappingURL=calls.js.map

package/dist/client/calls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calls.js","sourceRoot":"","sources":["../../src/client/calls.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,OAAO,EAAgC,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAA2E,MAAM,iBAAiB,CAAC;AAC1G,OAAO,EAAoC,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAY3C;;;;;GAKG;AACH,MAAM,OAAO,IAAI;IAuBJ,EAAE;IACM,OAAO;IAvB1B,MAAM,GAAe,SAAS,CAAC;IAC/B,OAAO,GAAmB,IAAI,CAAC;IAC/B,uGAAuG;IACvG,MAAM,GAAkB,IAAI,CAAC;IAC7B,IAAI,GAAkB,IAAI,CAAC;IAC3B,EAAE,GAAkB,IAAI,CAAC;IACzB,OAAO,GAA0B,IAAI,CAAC;IACtC,qEAAqE;IACrE,GAAG,GAAkB,IAAI,CAAC;IAC1B,gDAAgD;IAChD,OAAO,GAAkB,IAAI,CAAC;IAC9B,qEAAqE;IACrE,KAAK,GAA4B,EAAE,CAAC;IACpC;;;OAGG;IACH,KAAK,CAAS;IAEL,UAAU,CAAkB;IAErC,YACW,EAAU,EACF,OAAoB,EACrC,QAAgB;kBAFP,EAAE;uBACM,OAAO;QAGxB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,IAAI,SAAS,CAAO,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED,mCAAmC;IACnC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,qFAAqF;IACrF,EAAE,CAAsB,IAAO,EAAE,QAA2B;QAC1D,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,QAA2B;QAC/B,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,+EAA+E;IAE/E,sDAAsD;IACtD,GAAG,CAAC,IAAY,EAAE,OAAO,GAAqC,EAAE;QAC9D,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,wGAAwG;IACxG,KAAK,CAAC,YAAoB,EAAE,OAAO,GAAqC,EAAE;QACxE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,gFAAgF;IAChF,SAAS,CAAC,IAAY,EAAE,IAAY;QAClC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,sDAAsD;IACtD,QAAQ,CAAC,KAAwB;QAC/B,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,yDAAyD;IACzD,QAAQ,CAAC,KAA8B,EAAE,OAAkB;QACzD,IAAI,CAAC,KAAK,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IACrG,CAAC;IAED,sDAAsD;IACtD,UAAU,CAAC,MAAyB;QAClC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAED,2FAA2F;IAC3F,KAAK,CAAC,IAAY,EAAE,IAA6B;QAC/C,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,wFAAwF;IACxF,MAAM,CAAC,MAAe;QACpB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,4FAA4F;IAC5F,KAAK,CAAC,IAAY;QAChB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,uEAAuE;IACvE,GAAG,CAAC,IAAY,EAAE,IAAI,GAA4B,EAAE;QAClD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,+EAA+E;IAE/E,mFAAmF;IACnF,IAAI,CAAC,KAAiB;QACpB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,CAAC,KAAiB;QACtB,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,cAAc;gBACjB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;gBACxB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACvB,OAAO;YACT,KAAK,cAAc;gBACjB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;gBACxB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACvB,OAAO;YACT,KAAK,cAAc;gBACjB,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;gBACvB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACvB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;gBACxC,OAAO;YACT,KAAK,YAAY;gBACf,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC;gBACtB,OAAO;YACT,8EAA8E;YAC9E,KAAK,eAAe;gBAClB,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;gBACvB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC/B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;gBAChD,IAAI,CAAC,KAAK,GAAG,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;gBACjD,4DAA4D;gBAC5D,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC;gBAC1C,OAAO;YACT,KAAK,eAAe;gBAClB,IAAI,CAAC,KAAK,GAAG,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACrC,OAAO;YACT,KAAK,cAAc;gBACjB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;gBAC/B,OAAO;YACT;gBACE,OAAO;QACX,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAML;QACC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QAClB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC;IAC9B,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,OAAO,QAAQ;IAGU,OAAO;IAF3B,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IAEzC,YAA6B,OAAoB;uBAApB,OAAO;IAAgB,CAAC;IAErD,uDAAuD;IACvD,IAAI,IAAI;QACN,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,gEAAgE;IAChE,EAAE,CAAC,EAAU,EAAE,EAAU;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wEAAwE;IACxE,MAAM,CAAC,IAAU;QACf,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;CACF;AAED,uDAAuD;AACvD,SAAS,KAAK,CAAC,EAAU;IACvB,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9D,OAAO,GAAG,EAAE,CAAC,WAAW,EAAE,IAAI,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;AAC9E,CAAC"}

package/dist/client/client.d.ts

@@ -0,0 +1,112 @@
+import { type Camel, type CommandData } from "../wire/codec.js";
+import { type Entry } from "../wire/envelope.js";
+import { type CommandType, type EventType } from "../wire/registry.js";
+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";
+import { type World } from "./signed.js";
+/** A search result chunk: its source path, heading and text. */
+export interface Found {
+    path: string;
+    heading: string | null;
+    text: string;
+}
+/** Timeouts for `drain()`: the gateway's answer per agent, and running tools. */
+export interface DrainOptions {
+    answerMs?: number;
+    toolsMs?: number;
+}
+/** Result of `drain()`: calls handed over, calls parked, tools running and tools that finished. */
+export interface Drained {
+    handed: number;
+    parked: number;
+    tools: number;
+    finished: number;
+}
+/** Options for `new Pinecall()`. `url` and `apiKey` are required. */
+export interface PinecallOptions {
+    url?: string;
+    apiKey?: string;
+    /**
+     * The world this client expects, sent on every request; a gateway of the other world refuses
+     * it. Required for a person's key on production; not needed for a server token.
+     */
+    env?: World;
+    /** How this app names itself in the org's list of processes; `pinecall/<version>` otherwise. */
+    sdk?: string;
+    pingMs?: number;
+    backoff?: Partial<Backoff>;
+}
+/**
+ * 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 declare class Pinecall implements AgentGateway {
+    #private;
+    readonly sdk: string;
+    /** This machine's hostname, shown by the gateway next to the app. */
+    readonly host: string;
+    /** The gateway this client talks to. */
+    readonly url: string;
+    /** The API key. Sent in a header, never in a URL. */
+    readonly apiKey: string;
+    /** The requested world, or undefined to use the key's own. */
+    readonly env: World | undefined;
+    constructor(options?: PinecallOptions);
+    /** Declare an agent this app serves. Nothing is sent until `connect`. */
+    agent(slug: string, options?: AgentOptions): Agent;
+    /** Open the socket, register every agent and send its declaration. */
+    connect(): Promise<void>;
+    /**
+     * 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.
+     */
+    drain({ answerMs, toolsMs }?: DrainOptions): Promise<Drained>;
+    /** Close the socket without reconnecting. Every agent's slug is released. */
+    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;
+    /**
+     * 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: () => void): () => void;
+    /**
+     * 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: (why: string) => void): () => void;
+    /**
+     * 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: (entry: Entry) => void): () => void;
+    /** Receive errors no caller awaits (bad frames, listener throws, socket loss). Defaults to `console.error`. */
+    onErrors(listener: (error: Error) => void): () => void;
+    /** Stream a log live, folded by the protocol's reducer. */
+    observe(target: LogTarget, options?: Partial<ReadOptions>): AsyncGenerator<Observation>;
+    /** Read one page of a log and its folded state. */
+    history(target: LogTarget, options?: Partial<ReadOptions>): Promise<Page>;
+    /**
+     * 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.
+     */
+    search(call: string, query: string, k?: number): Promise<Found[]>;
+    /** Send one command frame, validated against its schema. */
+    send<K extends CommandType>(type: K, agent: string, call: string | null, data: Camel<CommandData<K>>, id: string): void;
+    /** Emit an event an agent has handled to the client-wide listeners. */
+    seen(event: CamelEvent, call: Call | null): void;
+    /** Report an error no caller awaits. */
+    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":"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"}