pinecall 0.1.0

package/dist/cli/world.js

@@ -0,0 +1,48 @@
+/** Which world a verb works in. The KEY decides it; `--env` is how a person says they know which. */
+import { refusal, whoIs } from "./whoami.js";
+/** The world a laptop is in: what is being written, held per person, nobody's customers calling. */
+export const SANDBOX = "sandbox";
+/** The world a deployment is in: the org's own, held by a key issued for a machine. */
+export const PRODUCTION = "production";
+const WORLDS = [PRODUCTION, SANDBOX];
+/**
+ * The `--env` every registering verb takes, declared once so the flag is spelled in one place.
+ *
+ * It selects NOTHING. A key opens one world and that is a property of the key, so a flag that
+ * chose would be a flag that lies: what this one does is say out loud which world you believe you
+ * are in, and refuse when the key disagrees. Sandbox is what a verb assumes when nothing is said,
+ * because a laptop is where things are written and a deployment is the deliberate act.
+ */
+export const ENV_FLAG = { env: { type: "string" } };
+/** What the gateway says this key is: asked once, and used for both the check and the line. */
+export async function standing(door) {
+    return await whoIs(door);
+}
+/**
+ * Why this verb will not run with the key in hand, or undefined when it will.
+ *
+ * The whole reason this exists: `pinecall run` used to register wherever the key it happened to
+ * find pointed, and the line it printed read the same either way — so an agent landed in
+ * production, in somebody else's org, and nothing said so until a customer called it.
+ */
+export function notThisWorld(verb, who, said) {
+    if (said !== undefined && !WORLDS.includes(said)) {
+        return `--env takes ${WORLDS.join(" or ")}, not ${JSON.stringify(said)}`;
+    }
+    const wanted = said ?? SANDBOX;
+    if (who.env === wanted)
+        return undefined;
+    if (said !== undefined) {
+        return (`--env ${said} asks for ${said}, and this key opens ${who.env}: a key opens one world and`
+            + " no flag changes that.\n"
+            + `  \`pinecall use <profile>\` for a key that opens ${said} — \`pinecall config\` lists them.`);
+    }
+    return (`this key opens ${who.env}, and \`pinecall ${verb}\` answers in the ${SANDBOX} unless you say so.\n`
+        + `  \`pinecall ${verb} --env ${who.env}\` if that is what you meant: it is what a deployment types.\n`
+        + "  `pinecall use <profile>` to work on a key of your own — `pinecall config` lists them.");
+}
+/** When the gateway will not say which world the key opens: guessing is the bug this replaces. */
+export function cannotTell(verb, failed) {
+    return `\`pinecall ${verb}\` will not guess which world this key opens: ${refusal(failed)}`;
+}
+//# sourceMappingURL=world.js.map

package/dist/cli/world.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.js","sourceRoot":"","sources":["../../src/cli/world.ts"],"names":[],"mappings":"AAAA,qGAAqG;AAGrG,OAAO,EAAE,OAAO,EAAE,KAAK,EAAY,MAAM,aAAa,CAAC;AAEvD,oGAAoG;AACpG,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AAEjC,uFAAuF;AACvF,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC;AAEvC,MAAM,MAAM,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,QAAiB,EAAE,EAAE,CAAC;AAE7D,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAU;IACvC,OAAO,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,GAAQ,EAAE,IAAwB;IAC3E,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,OAAO,eAAe,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;IAC3E,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,IAAI,OAAO,CAAC;IAC/B,IAAI,GAAG,CAAC,GAAG,KAAK,MAAM;QAAE,OAAO,SAAS,CAAC;IACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,CACL,SAAS,IAAI,aAAa,IAAI,wBAAwB,GAAG,CAAC,GAAG,6BAA6B;cACxF,0BAA0B;cAC1B,qDAAqD,IAAI,oCAAoC,CAChG,CAAC;IACJ,CAAC;IACD,OAAO,CACL,kBAAkB,GAAG,CAAC,GAAG,oBAAoB,IAAI,qBAAqB,OAAO,uBAAuB;UAClG,gBAAgB,IAAI,UAAU,GAAG,CAAC,GAAG,gEAAgE;UACrG,yFAAyF,CAC5F,CAAC;AACJ,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,MAAe;IACtD,OAAO,cAAc,IAAI,iDAAiD,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;AAC9F,CAAC"}

package/dist/client/agent.d.ts

@@ -0,0 +1,87 @@
+import { type AgentConfig, type Camel, type CommandData, type CommandType, type DevVerb, type Entry, type EventType, type Route, type ToolSpec } from "@pinecall/protocol";
+import { Call, CallBook, type CallGateway } from "./calls.js";
+import { type AnyListener, type CamelEvent, type Listener, type Payload } from "./listeners.js";
+/** A door the agent answers. `number` is null for a channel that has none, which is what web is. */
+export interface RouteInput {
+    channel: Route["channel"];
+    number?: string | null;
+    label?: string;
+}
+/** One tool: the contract the model sees, and the function this process runs when it is called. */
+export interface Tool extends Camel<ToolSpec> {
+    run: (args: Record<string, unknown>, call: Call) => unknown;
+}
+/** Everything an app declares about an agent, plus the tools' own code. */
+export interface AgentOptions extends Omit<Camel<AgentConfig>, "tools"> {
+    routes?: RouteInput[];
+    tools?: Tool[];
+    /**
+     * Whether the gateway may hand this socket a call that named no app — every phone call, and every
+     * web call that did not ask for one. A console (`pinecall chat`) opens its own call and names
+     * this socket, so it passes false and a real caller is never answered here.
+     */
+    takesUnclaimed?: boolean;
+}
+/** What an agent sends its frames through: the client that holds the socket. */
+export interface AgentGateway {
+    send<K extends CommandType>(type: K, agent: string, call: string | null, data: Camel<CommandData<K>>, id: string): void;
+    seen(event: CamelEvent, call: Call | null): void;
+    onError(error: Error): void;
+    readonly sdk: string;
+}
+/**
+ * What answers a console's ask of this process: the verb, and the body the console sent as the
+ * verb's own shape. It resolves with the verb's answer, or throws a `DevRefused` to refuse with a
+ * status and a sentence; anything else thrown reaches the console as a 500 with its message.
+ */
+export type DevHandler = (verb: DevVerb, data: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/**
+ * An agent, from the app's side.
+ *
+ * The declaration is sent again on every reconnect, because the gateway's registry is memory: it
+ * knows which sockets are open right now and nothing else. Many sockets may hold one agent at
+ * once and a call nobody claimed takes the newest of those that take unclaimed calls, so a rolling
+ * deploy's new process serves from the moment it registers and never waits for the old one to let
+ * go — and a console holding the same agent is never handed a call it did not open.
+ */
+export declare class Agent implements CallGateway {
+    #private;
+    readonly slug: string;
+    private readonly gateway;
+    readonly calls: CallBook;
+    constructor(slug: string, options: AgentOptions, gateway: AgentGateway);
+    /** What this agent tells the gateway it is, as the wire's own shape. */
+    get config(): Camel<AgentConfig>;
+    /**
+     * The socket this app is holding the agent on, as the gateway minted it, or undefined before
+     * the first register. A caller that names it — `WS /v1/chat?app=<id>`, an `app` in a worker's
+     * `POST /v1/calls` — is served by THIS process, which is what makes `pinecall chat` a console:
+     * the tool runs where the person typed the command and not in whichever server registered last.
+     */
+    get app(): string | undefined;
+    /** Listen for one event type across every call of this agent. `null` for the agent's own log. */
+    on<K extends EventType>(type: K, listener: Listener<K, Call | null>): () => void;
+    /** Listen for every event of this agent. The returned function stops listening. */
+    onAny(listener: AnyListener<Call | null>): () => void;
+    /**
+     * Answer a console's asks of this process — `dev.request`, relayed by the gateway. Only the
+     * process standing in the agent's directory has one: `pinecall run` registers it, a plain app
+     * never does, and a console asking a plain app is told so.
+     */
+    onDev(handler: DevHandler): void;
+    /** Replace the tools and their code. The next `configure` carries the new declaration. */
+    declare(tools: Tool[]): void;
+    /** Change what the agent is. Only the fields sent change; live calls keep their session. */
+    configure(changes?: Partial<Camel<AgentConfig>>): Promise<Payload<"agent.configured">>;
+    /** Claim the slug and its doors, then send the declaration. Run again on every reconnect. */
+    open(): Promise<void>;
+    /** One entry of this agent's, folded into the call it belongs to and handed to the listeners. */
+    take(entry: Entry): void;
+    /** One command out, on this agent's behalf. */
+    command<K extends CommandType>(type: K, call: string | null, data: Camel<CommandData<K>>): void;
+    /** A listener of this agent's threw, where nobody was waiting for the answer. */
+    onError(error: Error): void;
+    /** Prove the socket is alive: `ping` is agent-scoped like every command, and lands as `pong`. */
+    ping(): void;
+}
+//# sourceMappingURL=agent.d.ts.map

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

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

package/dist/client/agent.js

@@ -0,0 +1,209 @@
+// One agent an app speaks for: what it declares, what it does with a tool call, who listens.
+import { eventOf } from "@pinecall/protocol";
+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;
+// A process that registered no handler is a plain app, and a console asking it is told so.
+const NO_DEV_HANDLER = "this process answers no dev verbs: it is not a `pinecall run` in the agent's directory";
+/**
+ * An agent, from the app's side.
+ *
+ * The declaration is sent again on every reconnect, because the gateway's registry is memory: it
+ * knows which sockets are open right now and nothing else. Many sockets may hold one agent at
+ * once and a call nobody claimed takes the newest of those that take unclaimed calls, so a rolling
+ * deploy's new process serves from the moment it registers and never waits for the old one to let
+ * go — and a console holding the same agent is never handed a call it did not open.
+ */
+export class Agent {
+    slug;
+    gateway;
+    calls;
+    #listeners;
+    #tools = new Map();
+    #waiters = [];
+    #routes;
+    #config;
+    #takesUnclaimed;
+    #app;
+    #dev;
+    constructor(slug, options, gateway) {
+        this.slug = slug;
+        this.gateway = gateway;
+        const { routes = [], tools = [], takesUnclaimed = true, ...config } = options;
+        this.#routes = routes;
+        this.#config = config;
+        this.#takesUnclaimed = takesUnclaimed;
+        this.declare(tools);
+        this.calls = new CallBook(this);
+        this.#listeners = new Listeners((error) => gateway.onError(error));
+    }
+    /** What this agent tells the gateway it is, as the wire's own shape. */
+    get config() {
+        return this.#config;
+    }
+    /**
+     * The socket this app is holding the agent on, as the gateway minted it, or undefined before
+     * the first register. A caller that names it — `WS /v1/chat?app=<id>`, an `app` in a worker's
+     * `POST /v1/calls` — is served by THIS process, which is what makes `pinecall chat` a console:
+     * the tool runs where the person typed the command and not in whichever server registered last.
+     */
+    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);
+    }
+    /**
+     * Answer a console's asks of this process — `dev.request`, relayed by the gateway. Only the
+     * process standing in the agent's directory has one: `pinecall run` registers it, a plain app
+     * never does, and a console asking a plain app is told so.
+     */
+    onDev(handler) {
+        this.#dev = handler;
+    }
+    /** Replace the tools and their code. The next `configure` carries 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) };
+    }
+    /** Change what the agent is. Only the fields sent change; live calls keep their session. */
+    async configure(changes = {}) {
+        this.#config = { ...this.#config, ...changes };
+        return this.#ask("agent.configure", "agent.configured", { config: this.#config });
+    }
+    /** Claim the slug and its doors, then send the declaration. Run again on every reconnect. */
+    async open() {
+        const registered = await this.#ask("agent.register", "agent.registered", {
+            routes: this.#routes.map((route) => ({ channel: route.channel, number: route.number ?? null, ...(route.label === undefined ? {} : { label: route.label }) })),
+            sdk: this.gateway.sdk,
+            takesUnclaimed: this.#takesUnclaimed,
+        });
+        // A reconnect mints a new socket and so a new id: the one kept is always this socket's own.
+        this.#app = registered.app;
+        await this.configure();
+    }
+    // ── the socket's side ───────────────────────────────────────────────────────
+    /** One entry of this agent's, folded into the call it belongs to and handed to the 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);
+        }
+    }
+    /** One command out, on this agent's behalf. */
+    command(type, call, data) {
+        this.gateway.send(type, this.slug, call, data, `${this.slug}:${type}`);
+    }
+    /** A listener of this agent's threw, where nobody was waiting for the answer. */
+    onError(error) {
+        this.gateway.onError(error);
+    }
+    /** Prove the socket is alive: `ping` is agent-scoped like every command, and lands as `pong`. */
+    ping() {
+        this.command("ping", null, {});
+    }
+    // ── tools ───────────────────────────────────────────────────────────────────
+    // The model called a tool; the code is here, not in the platform. Whatever it answers — a value,
+    // a rejection, nothing at all — becomes one tool.result against the model's own call_id, because
+    // a turn that never gets 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();
+        void (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, not an unhandled failure: the model is waiting for it
+                // and reads it as `error`, and the log keeps the same tool.result for a person to read
+                // afterwards. Printing it as well would report a refusal the app made on purpose twice.
+                const error = asError(failed);
+                call.toolResult({ callId, name, error: error.message, durationS: (Date.now() - started) / 1000 });
+            }
+        })();
+    }
+    // ── a console's ask ─────────────────────────────────────────────────────────
+    // The gateway relayed a console's ask down this socket. Whatever the handler does — an answer,
+    // a refusal, a throw — becomes one dev.answer against the gateway's own id, because a door
+    // that never gets one waits two minutes and says so to a person.
+    #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 ───────────────────────────────────────────────────
+    // A command is answered by the event it lands as, or by an `error` naming the id we sent. Only
+    // the two declarations are awaited: everything else on this wire is fire and read the log.
+    async #ask(type, lands, data) {
+        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 ${ANSWER_MS}ms`));
+            }, ANSWER_MS).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,77 @@
+import type { Camel, Channel, CommandData, CommandType, Contact, EventType, ToolResult, ToolSpec } from "@pinecall/protocol";
+import type { AnyListener, CamelEvent, Listener } from "./listeners.js";
+/** What a call sends its commands through: the agent that owns it. */
+export interface CallGateway {
+    readonly slug: string;
+    command<K extends CommandType>(type: K, call: string | null, data: Camel<CommandData<K>>): void;
+    onError(error: Error): void;
+}
+/** Where the call is in its life, as the log has said so far. */
+export type CallStatus = "ringing" | "dialing" | "active" | "ended";
+/**
+ * A call the app is serving.
+ *
+ * Everything on it was read off the log — the SDK never invents a field the wire does not carry —
+ * and every method is one command, sent and not awaited: the gateway answers with the events the
+ * command lands as, and those arrive as entries like everything else.
+ */
+export declare class Call {
+    #private;
+    readonly id: string;
+    private readonly gateway;
+    status: CallStatus;
+    channel: Channel | null;
+    from: string | null;
+    to: string | null;
+    contact: Camel<Contact> | null;
+    /** The eval run that opened this call, or null for a person: a run's call starts mid-conversation. */
+    run: string | null;
+    /** The app's state as this client last set it, and as `state.changed` last reported it. */
+    state: Record<string, unknown>;
+    /** The day the call opened, `YYYY-MM-DD` in this process's timezone: what a prompt means by today. */
+    readonly 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 alone. 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, guided by an instruction the caller never hears. Lands as `turn.agent`. */
+    reply(instructions: string, options?: {
+        allowInterruptions?: boolean;
+    }): void;
+    /** Rewrite one block of the prompt, whole, by name: one of the framework's four, or one the agent declared. */
+    setPrompt(name: string, text: string): void;
+    /** The tools the model may see now: the subset of the declaration this state allows. */
+    setTools(tools: Camel<ToolSpec>[]): void;
+    /** The app's state changed and this is all of it. Lands as `state.changed`. */
+    setState(state: Record<string, unknown>, changed?: string[]): void;
+    /** What came back from running a tool in this process, against the `call_id` the model gave. */
+    toolResult(result: Camel<ToolResult>): void;
+    /** A fact from the tenant's backend. The agent must have declared the name, or this is refused. */
+    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;
+    /** Write a line of the app's own into the call's log. Lands as `custom`, with a seq like anything. */
+    log(name: string, data?: Record<string, unknown>): void;
+    /** Fold one event into what the call knows, then hand it to this call's listeners. */
+    take(event: CamelEvent): void;
+}
+/** Every call this agent is serving right now, by id. A call is forgotten when its log ends. */
+export declare class CallBook {
+    #private;
+    private readonly gateway;
+    constructor(gateway: CallGateway);
+    /** The calls in progress, in the order they opened. */
+    get live(): Call[];
+    /** The call this entry belongs to, opened on the first entry that named it. */
+    of(id: string, at: number): Call;
+    /** Forget a call whose log has ended. Listeners for `call.ended` have already run. */
+    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":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7H,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAGxE,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAChG,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CAC7B;AAED,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpE;;;;;;GAMG;AACH,qBAAa,IAAI;;IAgBb,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhB1B,MAAM,EAAE,UAAU,CAAa;IAC/B,OAAO,EAAE,OAAO,GAAG,IAAI,CAAQ;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC3B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAQ;IACzB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,CAAQ;IACtC,sGAAsG;IACtG,GAAG,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC1B,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM;IACpC,sGAAsG;IACtG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAIvB,YACW,EAAE,EAAE,MAAM,EACF,OAAO,EAAE,WAAW,EACrC,QAAQ,EAAE,MAAM,EAIjB;IAED,mCAAmC;IACnC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,2FAA2F;IAC3F,EAAE,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,MAAM,IAAI,CAExE;IAED,kFAAkF;IAClF,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAE7C;IAID,sDAAsD;IACtD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI,CAEtE;IAED,wGAAwG;IACxG,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI,CAEhF;IAED,+GAA+G;IAC/G,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE1C;IAED,wFAAwF;IACxF,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI,CAEvC;IAED,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAGjE;IAED,gGAAgG;IAChG,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,CAE1C;IAED,mGAAmG;IACnG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEvD;IAED,wFAAwF;IACxF,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAE5B;IAED,sGAAsG;IACtG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI,CAE1D;IAID,sFAAsF;IACtF,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAG5B;CAwCF;AAED,gGAAgG;AAChG,qBAAa,QAAQ;;IAGP,OAAO,CAAC,QAAQ,CAAC,OAAO;IAApC,YAA6B,OAAO,EAAE,WAAW,EAAI;IAErD,uDAAuD;IACvD,IAAI,IAAI,IAAI,IAAI,EAAE,CAEjB;IAED,+EAA+E;IAC/E,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAQ/B;IAED,sFAAsF;IACtF,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAIvB;CACF"}

package/dist/client/calls.js

@@ -0,0 +1,153 @@
+// One live call, as the app holds it: what is known about the line, and every command it can send.
+import { Listeners } from "./listeners.js";
+/**
+ * A call the app is serving.
+ *
+ * Everything on it was read off the log — the SDK never invents a field the wire does not carry —
+ * and every method is one command, sent and not awaited: the gateway answers with the events the
+ * command lands as, and those arrive as entries like everything else.
+ */
+export class Call {
+    id;
+    gateway;
+    status = "ringing";
+    channel = null;
+    from = null;
+    to = null;
+    contact = null;
+    /** The eval run that opened this call, or null for a person: a run's call starts mid-conversation. */
+    run = null;
+    /** The app's state as this client last set it, and as `state.changed` last reported it. */
+    state = {};
+    /** The day the call opened, `YYYY-MM-DD` in this process's timezone: what a prompt means by today. */
+    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 alone. 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, guided by an instruction the caller never hears. Lands as `turn.agent`. */
+    reply(instructions, options = {}) {
+        this.gateway.command("agent.reply", this.id, { instructions, ...options });
+    }
+    /** Rewrite one block of the prompt, whole, by name: one of the framework's four, or one the agent declared. */
+    setPrompt(name, text) {
+        this.gateway.command("prompt.set", this.id, { name, text });
+    }
+    /** The tools the model may see now: the subset of the declaration this state allows. */
+    setTools(tools) {
+        this.gateway.command("tools.set", this.id, { tools });
+    }
+    /** The app's state changed and this is all of it. Lands as `state.changed`. */
+    setState(state, changed) {
+        this.state = { ...state };
+        this.gateway.command("state.set", this.id, changed === undefined ? { state } : { state, changed });
+    }
+    /** What came back from running a tool in this process, against the `call_id` the model gave. */
+    toolResult(result) {
+        this.gateway.command("tool.result", this.id, result);
+    }
+    /** A fact from the tenant's backend. The agent must have declared the name, or this is refused. */
+    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 });
+    }
+    /** Write a line of the app's own into the call's log. Lands as `custom`, with a seq like anything. */
+    log(name, data = {}) {
+        this.gateway.command("call.log", this.id, { name, data });
+    }
+    // ── what the log teaches it ─────────────────────────────────────────────────
+    /** Fold one event into what the call knows, then hand 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);
+                return;
+            case "call.ended":
+                this.status = "ended";
+                return;
+            case "state.changed":
+                this.state = { ...event.data.state };
+                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;
+    }
+}
+/** Every call this agent is serving right now, by id. A call is forgotten when its log 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()];
+    }
+    /** The call this entry belongs to, opened on the first entry that named it. */
+    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;
+    }
+    /** Forget a call whose log has ended. Listeners for `call.ended` have already run. */
+    forget(call) {
+        if (call.status === "ended") {
+            this.#live.delete(call.id);
+        }
+    }
+}
+/** The day of a unix timestamp, `YYYY-MM-DD`, in this process's timezone. */
+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":"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"}