pinecall 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export * from "./agent/agent.js";
+export * from "./agent/authors.js";
+export * from "./agent/state.js";
+export * from "./agent/tools.js";
+export * from "./agent/decorators.js";
+export type { Stages } from "./agent/stages.js";
+export * from "./agent/docstrings.js";
+export * from "./agent/lifecycle.js";
+export * from "./views/jsx-runtime.js";
+export * from "./views/components.js";
+export { PROMPT_BLOCKS, type Block, type Blocks } from "./views/layout.js";
+export * from "./views/render.js";
+export * from "./runtime/channels.js";
+export { ToolFailed, runTool } from "./runtime/run-tool.js";
+export * from "./runtime/connect.js";
+export * from "./agent/visibility.js";
+export * from "./agent/accepts.js";
+export * from "./call/room.js";
+export * from "./call/history.js";
+export * from "./call/call.js";
+export * from "./views/lang.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AAGtC,YAAY,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EAAE,aAAa,EAAE,KAAK,KAAK,EAAE,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3E,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AAItC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAC5D,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,35 @@
+// pinecall: the tenant's side — a class whose fields are the state and whose @tool methods are
+// the model's verbs. One export line per module.
+//
+// What a stranger who types `import { … } from "pinecall"` may reach: the agent, the JSX-to-text
+// runtime its `render()` is written in, the call, and the bridge that mounts one on a client. Never a CLI module, never a bridge internal —
+// test/index.test.ts pins the list, so adding an export means editing that test.
+//
+// The socket underneath is a door of its own, `pinecall/client`, because an app that has its own
+// way of deciding what to answer wants it without any of this.
+export * from "./agent/agent.js";
+export * from "./agent/authors.js";
+export * from "./agent/state.js";
+export * from "./agent/tools.js";
+export * from "./agent/decorators.js";
+export * from "./agent/docstrings.js";
+export * from "./agent/lifecycle.js";
+export * from "./views/jsx-runtime.js";
+export * from "./views/components.js";
+// Not `layout` itself: `promptOf(agent)` next door is that function under the name a tenant reads
+// it by, and one thing with two names is one name too many.
+export { PROMPT_BLOCKS } from "./views/layout.js";
+export * from "./views/render.js";
+export * from "./runtime/channels.js";
+// Not the whole module: `runTool` and its error are how a tenant runs one tool the way the bridge
+// would, which is what an agent's own ring-0 suite is written against. The rest of run-tool.ts —
+// the argument check, the preview cut — is the bridge's business and stays inside.
+export { ToolFailed, runTool } from "./runtime/run-tool.js";
+export * from "./runtime/connect.js";
+export * from "./agent/visibility.js";
+export * from "./agent/accepts.js";
+export * from "./call/room.js";
+export * from "./call/history.js";
+export * from "./call/call.js";
+export * from "./views/lang.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,iDAAiD;AACjD,EAAE;AACF,iGAAiG;AACjG,4IAA4I;AAC5I,iFAAiF;AACjF,EAAE;AACF,iGAAiG;AACjG,+DAA+D;AAE/D,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AAItC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,kGAAkG;AAClG,4DAA4D;AAC5D,OAAO,EAAE,aAAa,EAA2B,MAAM,mBAAmB,CAAC;AAC3E,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,kGAAkG;AAClG,iGAAiG;AACjG,mFAAmF;AACnF,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAC5D,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/dist/runtime/channels.d.ts

@@ -0,0 +1,16 @@
+/** The doors: the class's phone, whatsapp and web fields translated into the routes it registers. */
+import type { RouteInput } from "../client/index.js";
+/** The three config fields that are doors, in the order a console reads them. */
+export type ChannelField = "phone" | "whatsapp" | "web";
+/** The phone line, when the class declares one. */
+export declare function phoneRoute(value: unknown): RouteInput | null;
+/** The WhatsApp door, when the class declares one. */
+export declare function whatsappRoute(value: unknown): RouteInput | null;
+/** The web widget's door, which never carries a number. */
+export declare function webRoute(value: unknown): RouteInput | null;
+/**
+ * Every door this agent answers. The wire has no `channel.add` command — a route is part of
+ * agent.register — so this is where the three fields become the declaration, once, at register.
+ */
+export declare function routesOf(config: Record<string, unknown>): RouteInput[];
+//# sourceMappingURL=channels.d.ts.map

package/dist/runtime/channels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../../src/runtime/channels.ts"],"names":[],"mappings":"AAAA,qGAAqG;AAErG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,KAAK,CAAC;AAUxD,mDAAmD;AACnD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAE5D;AAED,sDAAsD;AACtD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAE/D;AAED,2DAA2D;AAC3D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAE1D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,EAAE,CAGtE"}

package/dist/runtime/channels.js

@@ -0,0 +1,30 @@
+/** The doors: the class's phone, whatsapp and web fields translated into the routes it registers. */
+// A door is declared by being truthy. `phone = "+34 910 000 000"` is a number; `web = true` is a
+// channel with no number at all, which is what the widget is. `false`, `""` and undefined are
+// "this agent does not answer there", not "answer with an empty number".
+function routeOf(channel, value) {
+    if (value === undefined || value === null || value === false || value === "")
+        return null;
+    return { channel, number: typeof value === "string" ? value : null };
+}
+/** The phone line, when the class declares one. */
+export function phoneRoute(value) {
+    return routeOf("phone", value);
+}
+/** The WhatsApp door, when the class declares one. */
+export function whatsappRoute(value) {
+    return routeOf("whatsapp", value);
+}
+/** The web widget's door, which never carries a number. */
+export function webRoute(value) {
+    return routeOf("web", value);
+}
+/**
+ * Every door this agent answers. The wire has no `channel.add` command — a route is part of
+ * agent.register — so this is where the three fields become the declaration, once, at register.
+ */
+export function routesOf(config) {
+    return [phoneRoute(config["phone"]), whatsappRoute(config["whatsapp"]), webRoute(config["web"])]
+        .filter((route) => route !== null);
+}
+//# sourceMappingURL=channels.js.map

package/dist/runtime/channels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.js","sourceRoot":"","sources":["../../src/runtime/channels.ts"],"names":[],"mappings":"AAAA,qGAAqG;AAOrG,iGAAiG;AACjG,8FAA8F;AAC9F,yEAAyE;AACzE,SAAS,OAAO,CAAC,OAAqB,EAAE,KAAc;IACpD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC1F,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACvE,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AACjC,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;AACpC,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,MAA+B;IACtD,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;SAC7F,MAAM,CAAC,CAAC,KAAK,EAAuB,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;AAC5D,CAAC"}

package/dist/runtime/connect.d.ts

@@ -0,0 +1,51 @@
+/** The bridge: an Agent class mounted on a Pinecall client, one live instance per call. */
+import type { Camel, ModelConfig } from "@pinecall/protocol";
+import type { Agent as SdkAgent, AgentOptions, Call as SdkCall, Pinecall, Tool } from "../client/index.js";
+import { Agent } from "../agent/agent.js";
+import { type LastCall, type Snapshot } from "../agent/state.js";
+/** What mount needs beyond the class: where to send, and the class's own source. */
+export interface MountOptions {
+    pc: Pinecall;
+    /** The class's own source, so docstrings and parameter types survive compilation. */
+    source?: string;
+    /** The agent file's own path: the dialect its source is parsed as, and where its knowledge file is read. */
+    file?: string;
+    /** Override the slug the class name would give. */
+    slug?: string;
+    /** Where every instance of this agent reads `this.last(contact)` from. Per mount, never global. */
+    last?: LastCall;
+    /** False for a console: it serves the call it opens itself and no call that named no app. */
+    takesUnclaimed?: boolean;
+    /**
+     * The state a case opens a call in. Applied after the class's own `onCall` and before the first
+     * render, which is the only moment it can be: earlier and `onCall` writes over it, later and the
+     * bridge re-renders once per field and shows the model states the call was never in.
+     */
+    opening?: (call: SdkCall) => Snapshot | undefined;
+}
+/** A mounted agent: the sdk agent it registered as, and the instances it is serving right now. */
+export interface Mounted {
+    slug: string;
+    agent: SdkAgent;
+    options: AgentOptions;
+    /** The instance serving one call, while the call lasts. */
+    instanceOf(callId: string): Agent | undefined;
+}
+type Ctor = new () => Agent;
+/** The slug an agent registers under: its `static slug`, or its class name in kebab-case. */
+export declare function slugOf(ctor: Function): string;
+/** The model a bare name means, so `llm = "haiku"` reaches the provider as an id it recognises. */
+export declare function modelOf(value: unknown): Camel<ModelConfig> | undefined;
+/**
+ * Everything the class says about itself, as the declaration the gateway is sent. The probe is one
+ * instance of the class, read and thrown away; mount builds it once and hands it in. `file` is
+ * where the class came from, so what it knows is read beside it.
+ */
+export declare function optionsFor(ctor: Ctor, tools: Tool[], instance?: Agent, file?: string): AgentOptions;
+/**
+ * Mount a class on a client: it registers once, and from then on every call gets its own instance,
+ * its own state and its own rendered prompt. Nothing is sent until `pc.connect()`.
+ */
+export declare function mount(ctor: Ctor, { pc, source, file, slug, last, opening, takesUnclaimed }: MountOptions): Mounted;
+export {};
+//# sourceMappingURL=connect.d.ts.map

package/dist/runtime/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/runtime/connect.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAE3F,OAAO,KAAK,EACV,KAAK,EAGL,WAAW,EAIZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,KAAK,IAAI,QAAQ,EAAE,YAAY,EAAE,IAAI,IAAI,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE3G,OAAO,EAAE,KAAK,EAAuG,MAAM,mBAAmB,CAAC;AAM/I,OAAO,EAAY,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAU3E,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,QAAQ,CAAC;IACb,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4GAA4G;IAC5G,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mGAAmG;IACnG,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,6FAA6F;IAC7F,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,QAAQ,GAAG,SAAS,CAAC;CACnD;AAED,kGAAkG;AAClG,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,2DAA2D;IAC3D,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;CAC/C;AAED,KAAK,IAAI,GAAG,UAAU,KAAK,CAAC;AAoB5B,6FAA6F;AAC7F,wBAAgB,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAO7C;AAYD,mGAAmG;AACnG,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,SAAS,CAKtE;AAiED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,QAAQ,GAAE,KAAkB,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,CAyB/G;AAED;;;GAGG;AACH,wBAAgB,KAAK,CACnB,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAqB,EAAE,EAAE,YAAY,GAC7E,OAAO,CAuBT"}

package/dist/runtime/connect.js

@@ -0,0 +1,284 @@
+/** The bridge: an Agent class mounted on a Pinecall client, one live instance per call. */
+import { Agent, onChange, onLog, recalled, seal, setCall, setLast } from "../agent/agent.js";
+import { eventsOf } from "../agent/accepts.js";
+import { visibilityOf } from "../agent/visibility.js";
+import { CallWorld } from "../call/call.js";
+import { describe } from "../agent/docstrings.js";
+import { runHook } from "../agent/lifecycle.js";
+import { snapshot } from "../agent/state.js";
+import { toolNamed } from "../agent/tools.js";
+import { PROMPT_BLOCKS } from "../views/layout.js";
+import { promptOf } from "../views/render.js";
+import { routesOf } from "./channels.js";
+import { inOrder } from "./dispatch.js";
+import { groundingOf } from "./grounding.js";
+import { wordsRecalled } from "./recall.js";
+import { runTool, ToolFailed } from "./run-tool.js";
+/** The slug an agent registers under: its `static slug`, or its class name in kebab-case. */
+export function slugOf(ctor) {
+    const declared = ctor.slug;
+    if (typeof declared === "string")
+        return declared;
+    return ctor.name
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+        .toLowerCase();
+}
+// `llm = "haiku"` is how the design writes it, and the wire wants a provider and a real model id:
+// "haiku" on its own is a 404 from Anthropic. The three short names are the family's tiers as the
+// runtime prices them; anything else is passed through as written, with "provider/model" naming
+// both halves and a bare name defaulting to Anthropic. An object written out in full is untouched.
+const SHORT_NAMES = {
+    haiku: "claude-haiku-4-5-20251001",
+    sonnet: "claude-sonnet-5",
+    opus: "claude-opus-5",
+};
+/** The model a bare name means, so `llm = "haiku"` reaches the provider as an id it recognises. */
+export function modelOf(value) {
+    if (typeof value === "object" && value !== null)
+        return value;
+    if (typeof value !== "string" || value === "")
+        return undefined;
+    const [provider, name] = value.includes("/") ? value.split("/", 2) : ["anthropic", value];
+    return { provider: provider, model: SHORT_NAMES[name] ?? name };
+}
+// `voice = "carolina"` is a name, not an id: sending it as one is how a call spent twenty seconds
+// retrying 1008 voice_id_does_not_exist while the model apologised. The word the class wrote travels
+// as the word it is, and the platform resolves it to a vendor and an id when this declaration lands
+// — so a voice nobody curated is refused there, and never at the first utterance.
+function voiceOf(value) {
+    if (typeof value === "object" && value !== null)
+        return value;
+    if (typeof value !== "string" || value === "")
+        return undefined;
+    return { name: value };
+}
+// `says = { Vidal: "bidál" }` is how the class writes it, because a map is how anybody thinks
+// about it; the wire carries a list so the schema can name both halves. The voice is given the
+// spoken form on its way out and the log keeps what the model actually wrote.
+function saysOf(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const said = Object.entries(value)
+        .filter(([word, spoken]) => word !== "" && typeof spoken === "string" && spoken !== "")
+        .map(([word, spoken]) => ({ word, spoken: spoken }));
+    return said.length === 0 ? undefined : said;
+}
+/** `hears = ["Clínica Norte"]`: the words the ears must know, as the class wrote them. */
+function hearsOf(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const heard = value.filter((word) => typeof word === "string" && word !== "");
+    return heard.length === 0 ? undefined : heard;
+}
+// The same sentence the runtime refuses with, because it is the same rule: a greeting names one
+// of the two verbs the wire already has, and a class that named both has not decided which.
+const GREETING_IS_ONE_VERB = "a greeting is one of two things: `say` the words, or `reply` what the model reads before it finds its own.";
+/** `greeting = "Buenos días."` or `greeting = { reply: "saluda y preséntate" }`: the opening. */
+function greetingOf(value) {
+    if (typeof value === "string")
+        return value === "" ? undefined : { say: value };
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const declared = value;
+    const said = declared.say !== undefined;
+    const replied = declared.reply !== undefined;
+    if (said === replied) {
+        throw new Error(`${GREETING_IS_ONE_VERB} ${said ? "Both were declared" : "Neither was"} — pick one.`);
+    }
+    const greeting = said ? { say: declared.say } : { reply: declared.reply };
+    if (declared.allowInterruptions !== undefined)
+        greeting.allowInterruptions = declared.allowInterruptions;
+    return greeting;
+}
+// Only what the class declared: a field nobody wrote a visibility for is tenant by the wire's own
+// default, and saying so again would be the framework inventing a declaration.
+// `hangup = {}` is a declaration too: the empty object says the model may end the call and leaves
+// the wording to livekit's own description. Only a class that says nothing at all gets no tool.
+function hangupOf(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const declared = value;
+    return { when: declared.when ?? "" };
+}
+function stateFieldsOf(ctor) {
+    const declared = visibilityOf(ctor);
+    return declared.length === 0 ? undefined : declared;
+}
+/**
+ * Everything the class says about itself, as the declaration the gateway is sent. The probe is one
+ * instance of the class, read and thrown away; mount builds it once and hands it in. `file` is
+ * where the class came from, so what it knows is read beside it.
+ */
+export function optionsFor(ctor, tools, instance = new ctor(), file) {
+    const probe = instance;
+    const options = { routes: routesOf(probe), tools, ...groundingOf(probe, file) };
+    const language = probe["language"];
+    if (typeof language === "string")
+        options.language = language;
+    const llm = modelOf(probe["llm"]);
+    if (llm)
+        options.llm = llm;
+    const voice = voiceOf(probe["voice"]);
+    if (voice)
+        options.voice = voice;
+    const says = saysOf(probe["says"]);
+    if (says)
+        options.says = says;
+    const hears = hearsOf(probe["hears"]);
+    if (hears)
+        options.hears = hears;
+    const greeting = greetingOf(probe["greeting"]);
+    if (greeting)
+        options.greeting = greeting;
+    const hangup = hangupOf(probe["hangup"]);
+    if (hangup)
+        options.hangup = hangup;
+    // The layout is always sent whole: the send order is the framework's contract, and the wire
+    // carrying it is what lets the runtime and the console name every block the same way.
+    options.prompt = [...PROMPT_BLOCKS];
+    const stateFields = stateFieldsOf(ctor);
+    if (stateFields)
+        options.stateFields = stateFields;
+    const events = eventsOf(ctor);
+    if (events.length > 0)
+        options.events = events;
+    return options;
+}
+/**
+ * Mount a class on a client: it registers once, and from then on every call gets its own instance,
+ * its own state and its own rendered prompt. Nothing is sent until `pc.connect()`.
+ */
+export function mount(ctor, { pc, source, file, slug, last, opening, takesUnclaimed = true }) {
+    if (source !== undefined)
+        describe(ctor, source, file);
+    const name = slug ?? slugOf(ctor);
+    const live = new Map();
+    // One instance to read the class with: its tools and everything it declares about itself are
+    // read off the same probe, which is then thrown away. Every call gets an instance of its own.
+    const probe = new ctor();
+    const tools = probe.tools().map((spec) => ({
+        ...spec,
+        run: (args, call) => call_(live, call, spec.name, args),
+    }));
+    const options = { ...optionsFor(ctor, tools, probe, file), takesUnclaimed };
+    const agent = pc.agent(name, options);
+    agent.on("call.started", (_payload, call) => {
+        if (call !== null) {
+            void start(ctor, live, call, (type, id, data) => agent.command(type, id, data), last, opening);
+        }
+    });
+    agent.on("call.ended", (_payload, call) => {
+        if (call !== null)
+            void end(live, call);
+    });
+    return { slug: name, agent, options, instanceOf: (id) => live.get(id)?.agent };
+}
+// One tool call, routed to the instance that owns this call. A call the bridge is not serving is
+// the model talking to a hung-up line, and the model is told so instead of the process throwing.
+async function call_(live, call, name, args) {
+    const serving = live.get(call.id);
+    if (serving === undefined)
+        throw new ToolFailed(`${name}: this call is no longer being served`);
+    const declaration = toolNamed(serving.agent, name);
+    if (declaration === undefined)
+        throw new ToolFailed(`${name}: this agent declares no such tool`);
+    return runTool(serving.agent, declaration, args);
+}
+// A call started: build the instance, let onCall write into it, send the whole prompt once, and
+// only then start listening — so the opening send is one prompt and not one per field onCall set.
+async function start(ctor, live, call, send, last, opening) {
+    const agent = seal(new ctor());
+    if (last !== undefined)
+        setLast(agent, last);
+    const world = new CallWorld(hookCall(call), (type, data) => send(type, call.id, data));
+    setCall(agent, world);
+    const serving = { agent, ctor, call: world, warned: new Set(), queue: Promise.resolve() };
+    const link = { agent, sent: { blocks: new Map() }, stop: [], serving };
+    live.set(call.id, link);
+    await runHook(agent, "onCall", hookCall(call));
+    const wanted = opening?.(call);
+    if (wanted !== undefined)
+        agent.startIn(wanted);
+    call.setState(snapshot(agent));
+    sync(link, call);
+    link.stop.push(onChange(agent, (change) => {
+        call.setState(snapshot(agent), [change.field]);
+        // state.set carries no cause on the wire, so the reason a field moved goes in the log next
+        // to it: one line naming the event, the field and the event's place in this call's stream.
+        const cause = world.cause;
+        if (cause !== null)
+            call.log("state.cause", { field: change.field, kind: "event", ...cause });
+        sync(link, call);
+    }), onLog(agent, (entry) => call.log(entry.name, dataOf(entry.data))), call.onAny((event) => {
+        world.take(event.type, event.data, Date.now());
+        if (event.type === "event.received")
+            void received(serving, event.data);
+        // What memory found is not state and moves no field, so nothing else would re-render — and a
+        // `render()` that asks what the agent remembers is a different prompt once it has an answer.
+        if (event.type === "memory.ops") {
+            recalled(agent, wordsRecalled(event.data));
+            sync(link, call);
+        }
+    }));
+}
+// One outside fact, numbered by this call rather than by the wire: camelEvent hands listeners the
+// event without the entry's own seq, so the hook is told where the fact sits in this call's own
+// stream of them. See docs/decisions/agent-events.md.
+async function received(serving, data) {
+    const fact = data;
+    await inOrder(serving, {
+        name: fact.name,
+        data: fact.data,
+        source: fact.source,
+        seq: serving.call.numbered(),
+        ...(fact.identity === undefined ? {} : { identity: fact.identity }),
+    });
+}
+async function end(live, call) {
+    const link = live.get(call.id);
+    if (link === undefined)
+        return;
+    live.delete(call.id);
+    for (const stop of link.stop)
+        stop();
+    await runHook(link.agent, "onEnd", hookCall(call));
+    setCall(link.agent, null);
+}
+// The one rule this card exists for: render, then compare with what this call was last sent, and
+// send only the block whose text is different. Tools are compared as their whole declaration,
+// because a `when` flipping changes the list and nothing else about a spec ever changes mid-call.
+function sync(serving, call) {
+    const { blocks } = promptOf(serving.agent);
+    for (const block of blocks) {
+        if (block.text === (serving.sent.blocks.get(block.name) ?? ""))
+            continue;
+        serving.sent.blocks.set(block.name, block.text);
+        call.setPrompt(block.name, block.text);
+    }
+    const visible = serving.agent.visibleTools();
+    const key = JSON.stringify(visible);
+    if (key !== serving.sent.tools) {
+        serving.sent.tools = key;
+        call.setTools(visible);
+    }
+}
+function hookCall(call) {
+    const hook = { id: call.id, contact: call.contact?.id ?? call.from ?? "" };
+    if (call.from !== null)
+        hook.from = call.from;
+    if (call.channel !== null)
+        hook.channel = call.channel;
+    return hook;
+}
+// call.log carries an object; a tool that logged a number still deserves a line, so a value that
+// is not an object travels under `value` rather than being dropped at the door.
+function dataOf(data) {
+    if (data === undefined)
+        return {};
+    if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+        return data;
+    }
+    return { value: data };
+}
+//# sourceMappingURL=connect.js.map

package/dist/runtime/connect.js.map

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

package/dist/runtime/dispatch.d.ts

@@ -0,0 +1,37 @@
+/** An outside fact off the wire, dispatched to the instance serving that call — or dropped. */
+import { type EventSource } from "../agent/accepts.js";
+import type { CallWorld } from "../call/call.js";
+/** One event.received entry, in the shape the wire carries it. */
+export interface Received {
+    name: string;
+    data: Record<string, unknown>;
+    source: EventSource;
+    identity?: string;
+    seq: number;
+}
+/** What the dispatcher needs of the live instance: the class it is, and the call it is serving. */
+export interface Serving {
+    agent: object;
+    ctor: Function;
+    call: CallWorld;
+    /** The (call, name) pairs already warned about, so a chatty sender warns once and not once a second. */
+    warned: Set<string>;
+    /** The events of this call, one after another: the cause a write names is the event running. */
+    queue: Promise<unknown>;
+}
+/**
+ * Dispatch after every event before it has finished. The cause lives on the call while a hook runs,
+ * so two hooks awaiting at once would name each other's event; one at a time, in the order the wire
+ * delivered them, is also the only order a tenant can reason about.
+ */
+export declare function inOrder(serving: Serving, received: Received): Promise<boolean>;
+/**
+ * Hand the event to `onEvent`, or drop it. The gate is the pair, not the name: an event declared
+ * `from: ["app"]` that arrives from a participant's browser is somebody else's event with our
+ * name on it, and the hook never sees it.
+ *
+ * A write inside the hook is authored `event:<name>`, and the call carries the cause while the
+ * hook runs so the bridge can say in the log which event moved the field.
+ */
+export declare function dispatch(serving: Serving, received: Received): Promise<boolean>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/runtime/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/runtime/dispatch.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAI/F,OAAO,EAA2B,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,mGAAmG;AACnG,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,wGAAwG;IACxG,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,gGAAgG;IAChG,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAK9E;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAiBrF"}

package/dist/runtime/dispatch.js

@@ -0,0 +1,52 @@
+/** An outside fact off the wire, dispatched to the instance serving that call — or dropped. */
+import { emitEvent } from "../agent/agent.js";
+import { withAuthorAsync } from "../agent/authors.js";
+import { accepts } from "../agent/accepts.js";
+/**
+ * Dispatch after every event before it has finished. The cause lives on the call while a hook runs,
+ * so two hooks awaiting at once would name each other's event; one at a time, in the order the wire
+ * delivered them, is also the only order a tenant can reason about.
+ */
+export function inOrder(serving, received) {
+    const next = serving.queue.then(() => dispatch(serving, received));
+    // A hook that threw must not jam every later event behind it; the rejection is the caller's.
+    serving.queue = next.catch(() => undefined);
+    return next;
+}
+/**
+ * Hand the event to `onEvent`, or drop it. The gate is the pair, not the name: an event declared
+ * `from: ["app"]` that arrives from a participant's browser is somebody else's event with our
+ * name on it, and the hook never sees it.
+ *
+ * A write inside the hook is authored `event:<name>`, and the call carries the cause while the
+ * hook runs so the bridge can say in the log which event moved the field.
+ */
+export async function dispatch(serving, received) {
+    const { name, data, source, seq } = received;
+    if (!accepts(serving.ctor, name, source)) {
+        warn(serving, name, source);
+        return false;
+    }
+    const meta = { source, seq, ...(received.identity === undefined ? {} : { identity: received.identity }) };
+    const hook = serving.agent.onEvent;
+    serving.call.cause = { name, seq };
+    try {
+        await withAuthorAsync(`event:${name}`, () => hook.call(serving.agent, name, data, meta));
+    }
+    finally {
+        serving.call.cause = null;
+    }
+    const heard = { name, data, meta };
+    emitEvent(serving.agent, heard);
+    return true;
+}
+// One line per (call, name): a backend that sends an undeclared event sends it every time, and a
+// log that repeats itself is a log nobody reads.
+function warn(serving, name, source) {
+    const key = `${serving.call.id}:${name}`;
+    if (serving.warned.has(key))
+        return;
+    serving.warned.add(key);
+    console.warn(`pinecall: event ${name} from ${source} is not declared by this agent; dropped`);
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/runtime/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/runtime/dispatch.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAE/F,OAAO,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAoC,MAAM,qBAAqB,CAAC;AAuBhF;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,OAAgB,EAAE,QAAkB;IAC1D,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IACnE,6FAA6F;IAC7F,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAgB,EAAE,QAAkB;IACjE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,QAAQ,CAAC;IAC7C,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAc,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC;IACrH,MAAM,IAAI,GAAI,OAAO,CAAC,KAAuF,CAAC,OAAO,CAAC;IACtH,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,eAAe,CAAC,SAAS,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IAC3F,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IAC5B,CAAC;IACD,MAAM,KAAK,GAAe,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC/C,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAChC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iGAAiG;AACjG,iDAAiD;AACjD,SAAS,IAAI,CAAC,OAAgB,EAAE,IAAY,EAAE,MAAmB;IAC/D,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC;IACzC,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO;IACpC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,CAAC,IAAI,CAAC,mBAAmB,IAAI,SAAS,MAAM,yCAAyC,CAAC,CAAC;AAChG,CAAC"}

package/dist/runtime/grounding.d.ts

@@ -0,0 +1,15 @@
+/** `knowledge` / `docs` / `memory` fields → what the declaration carries: the file read, the base named, the policy. */
+import type { Camel, DocsConfig, KnowledgeFile, MemoryConfig } from "@pinecall/protocol";
+/** The three fields as the wire carries them. Absent when the class said nothing. */
+export interface Grounding {
+    knowledge?: Camel<KnowledgeFile>;
+    docs?: Camel<DocsConfig>;
+    memory?: Camel<MemoryConfig>;
+}
+/**
+ * What the class says it knows, reads and remembers, read off one probe instance. `file` is the
+ * agent's own path, so a knowledge file is found beside the class and not beside whoever ran the
+ * process; without one it is read from the working directory.
+ */
+export declare function groundingOf(probe: object, file?: string): Grounding;
+//# sourceMappingURL=grounding.d.ts.map

package/dist/runtime/grounding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding.d.ts","sourceRoot":"","sources":["../../src/runtime/grounding.ts"],"names":[],"mappings":"AAAA,wHAAwH;AAKxH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIzF,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACzB,MAAM,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;CAC9B;AAMD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAUnE"}