pinecall 0.1.0

package/dist/agent/tools.d.ts

@@ -0,0 +1,66 @@
+/** The tool registry: what a class declares, what the wire is sent, and what the state shows now. */
+import { z } from "zod";
+import type { ToolSpec } from "@pinecall/protocol";
+import { type ParamDoc } from "./docstrings.js";
+import type { StageOf } from "./stages.js";
+import { type Snapshot } from "./state.js";
+export type { ToolSpec };
+export type SideEffect = NonNullable<ToolSpec["side_effect"]>;
+/**
+ * Everything `@tool({...})` accepts, and nothing else. `T` is the class the decorator was written
+ * on — TypeScript infers it from the prototype the decorator is handed, so `when` gets the real
+ * state and `s.identified` is a boolean instead of `s["identified"]` being unknown.
+ */
+export interface ToolOptions<T = unknown> {
+    /** Visibility, and the only one there is: a question asked of the state, on every change. */
+    when?: (state: Snapshot<T>) => boolean;
+    /**
+     * Visible while the state is in one of these stages — sugar the decorator lowers to the `when`
+     * above. The names are typed against the class's own `stage` field, so a misspelling is a
+     * compile error; with a `when` beside it, the tool is there where both hold.
+     */
+    stage?: StageOf<T> | StageOf<T>[];
+    /** The read-back the agent says before running, `{{slot.when}}` filled from state and args. */
+    confirm?: string;
+    /** How many rows of a list result the model sees; the field itself keeps them all. */
+    preview?: number;
+    /** Parameter names that carry personal data, masked in the log by declaration. */
+    pii?: string[];
+    /** How long the platform waits for this method, in seconds. */
+    timeout?: number;
+    /** An explicit schema, when the signature's types are not enough. Optional, never required. */
+    params?: z.ZodObject;
+}
+export type ErasedToolOptions = ToolOptions<any>;
+/** One declared tool: the wire's half, the halves the wire never sees, and the method itself. */
+export interface ToolDeclaration {
+    name: string;
+    options: ErasedToolOptions;
+    method: (...args: unknown[]) => unknown;
+    owner: Function;
+    spec: ToolSpec;
+}
+/** A declaration the platform would refuse before the app's method ever ran. */
+export declare class DeclarationRefused extends Error {
+    constructor(message: string);
+}
+interface Declared {
+    name: string;
+    options: ErasedToolOptions;
+    method: (...args: unknown[]) => unknown;
+}
+/** Record one decorated method against the class that declared it. */
+export declare function register(prototype: object, declared: Declared): void;
+/** The JSON Schema a model must satisfy, from an explicit zod object or from the signature. */
+export declare function parametersOf(params: ParamDoc[], explicit?: z.ZodObject): Record<string, unknown>;
+/** Every tool this agent declares, its own class's first, then the ones it inherits. */
+export declare function toolsOf(agent: object): ToolDeclaration[];
+/** One declared tool by the name the model calls. */
+export declare function toolNamed(agent: object, name: string): ToolDeclaration | undefined;
+/** The tools the state shows right now: `when` is asked of a snapshot, never of a stage. */
+export declare function visibleToolsOf(agent: object): ToolDeclaration[];
+/** The specs a model may call right now — the list the runtime puts in the request. */
+export declare function visibleTools(agent: object): ToolSpec[];
+/** The docstring of the agent's own class, as the model reads it above everything else. */
+export declare function docOf(agent: object): string | undefined;
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/agent/tools.ts"],"names":[],"mappings":"AAAA,qGAAqG;AAErG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAkD,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIrD,YAAY,EAAE,QAAQ,EAAE,CAAC;AAIzB,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,6FAA6F;IAC7F,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC;IACvC;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;CACtB;AAID,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;AAEjD,iGAAiG;AACjG,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IACxC,KAAK,EAAE,QAAQ,CAAC;IAChB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,gFAAgF;AAChF,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,UAAU,QAAQ;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;CACzC;AASD,sEAAsE;AACtE,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAUpE;AAaD,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWhG;AAyDD,wFAAwF;AACxF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAuBxD;AAED,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAElF;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAG/D;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,CAEtD;AAED,2FAA2F;AAC3F,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvD"}

package/dist/agent/tools.js

@@ -0,0 +1,148 @@
+/** The tool registry: what a class declares, what the wire is sent, and what the state shows now. */
+import { z } from "zod";
+import { classDoc, docsVersion, methodDoc, methodParams } from "./docstrings.js";
+import { snapshot } from "./state.js";
+/** A declaration the platform would refuse before the app's method ever ran. */
+export class DeclarationRefused extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DeclarationRefused";
+    }
+}
+// Keyed by the prototype the decorator was handed, so a tool is declared once per class and not
+// once per instance. The chain is walked at read time, so a subclass inherits its parent's tools.
+const registries = new WeakMap();
+const specs = new WeakMap();
+const A_NAME_A_MODEL_CAN_CALL = /^[A-Za-z][A-Za-z0-9_]*$/;
+/** Record one decorated method against the class that declared it. */
+export function register(prototype, declared) {
+    if (!A_NAME_A_MODEL_CAN_CALL.test(declared.name)) {
+        throw new DeclarationRefused(`a tool name is one word a model can call, not ${declared.name}`);
+    }
+    let registry = registries.get(prototype);
+    if (!registry) {
+        registry = new Map();
+        registries.set(prototype, registry);
+    }
+    registry.set(declared.name, declared);
+}
+// string, number and boolean are the three a model fills directly. A shape the source could resolve
+// — a Slot, a Patient — arrives already expanded in `param.schema`; this maps what is left, the
+// types a scraped class body still gives as bare text, and an open object is the honest answer.
+function schemaOf(type) {
+    const name = (type ?? "").split(" ").join("");
+    if (name.includes("=>"))
+        return { description: "callback" };
+    if (name.endsWith("[]"))
+        return { type: "array", items: schemaOf(name.slice(0, -2)) };
+    if (name === "string" || name === "number" || name === "boolean")
+        return { type: name };
+    return { type: "object", additionalProperties: true };
+}
+/** The JSON Schema a model must satisfy, from an explicit zod object or from the signature. */
+export function parametersOf(params, explicit) {
+    if (explicit)
+        return z.toJSONSchema(explicit);
+    const properties = {};
+    const required = [];
+    for (const param of params) {
+        const schema = param.schema ?? schemaOf(param.type);
+        properties[param.name] = schema;
+        // A callback is the app's own plumbing: the model cannot write one, so it is never asked for.
+        if (!param.optional && schema["description"] !== "callback")
+            required.push(param.name);
+    }
+    return { type: "object", properties, required, additionalProperties: false };
+}
+/** Build the wire spec for one declared tool, refusing what the gateway would refuse. */
+function specFor(ctor, declared) {
+    const description = methodDoc(ctor, declared.name);
+    if (!description) {
+        throw new DeclarationRefused(`tool ${declared.name}: without a docstring no model can choose it; ` +
+            `write a /** one line */ above the method`);
+    }
+    const options = declared.options;
+    const parameters = parametersOf(methodParams(ctor, declared.name), options.params);
+    const properties = (parameters["properties"] ?? {});
+    const unknownPii = (options.pii ?? []).filter((field) => !(field in properties));
+    if (unknownPii.length > 0) {
+        throw new DeclarationRefused(`tool ${declared.name}: pii names parameters the tool has; unknown: ${unknownPii.join(", ")}`);
+    }
+    // A read-back is what makes a tool irreversible: the platform reads it, hears the yes, then runs.
+    const spec = {
+        name: declared.name,
+        description,
+        parameters,
+        side_effect: options.confirm ? "irreversible" : "read",
+    };
+    if (options.confirm !== undefined)
+        spec.confirm = options.confirm;
+    if (options.pii !== undefined)
+        spec.pii = [...options.pii];
+    if (options.timeout !== undefined)
+        spec.timeout_s = options.timeout;
+    return spec;
+}
+function cachedSpec(ctor, prototype, declared) {
+    let byName = specs.get(prototype);
+    if (!byName) {
+        byName = new Map();
+        specs.set(prototype, byName);
+    }
+    const known = byName.get(declared.name);
+    if (known && known.version === docsVersion())
+        return known.spec;
+    const spec = specFor(ctor, declared);
+    byName.set(declared.name, { spec, version: docsVersion() });
+    return spec;
+}
+// A `stage` is a question about the class's own `stage` field, so a class that declares none would
+// hide every staged tool for the whole call. The compiler says so first; this is the same sentence
+// for a class written in JavaScript, and it is read at mount, before a model ever sees the list.
+function refuseAStageWithNoField(agent, ctor, name) {
+    if ("stage" in agent)
+        return;
+    throw new DeclarationRefused(`tool ${name}: stage names a value of this agent's own stage field, and ${ctor.name} ` +
+        `declares none; add \`stage: Stages<"…"> = "…"\` to the class, or ask when(state) instead`);
+}
+/** Every tool this agent declares, its own class's first, then the ones it inherits. */
+export function toolsOf(agent) {
+    const ctor = agent.constructor;
+    const declarations = [];
+    const seen = new Set();
+    for (let prototype = Object.getPrototypeOf(agent); prototype && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)) {
+        for (const declared of registries.get(prototype)?.values() ?? []) {
+            if (seen.has(declared.name))
+                continue;
+            seen.add(declared.name);
+            if (declared.options.stage !== undefined)
+                refuseAStageWithNoField(agent, ctor, declared.name);
+            declarations.push({
+                name: declared.name,
+                options: declared.options,
+                method: declared.method,
+                owner: prototype.constructor,
+                spec: cachedSpec(ctor, prototype, declared),
+            });
+        }
+    }
+    return declarations;
+}
+/** One declared tool by the name the model calls. */
+export function toolNamed(agent, name) {
+    return toolsOf(agent).find((declared) => declared.name === name);
+}
+/** The tools the state shows right now: `when` is asked of a snapshot, never of a stage. */
+export function visibleToolsOf(agent) {
+    const state = snapshot(agent);
+    return toolsOf(agent).filter((declared) => declared.options.when?.(state) ?? true);
+}
+/** The specs a model may call right now — the list the runtime puts in the request. */
+export function visibleTools(agent) {
+    return visibleToolsOf(agent).map((declared) => declared.spec);
+}
+/** The docstring of the agent's own class, as the model reads it above everything else. */
+export function docOf(agent) {
+    return classDoc(agent.constructor);
+}
+//# sourceMappingURL=tools.js.map

package/dist/agent/tools.js.map

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

package/dist/agent/visibility.d.ts

@@ -0,0 +1,40 @@
+/** `@state`: which fields are the state, and who may see them. Declared once on the class. */
+/** Who may see a field of the state. The wire's three words, from protocol/schema/defs.json. */
+export type Visibility = "public" | "tenant" | "pii";
+/** Everything `@state({...})` accepts: who may see the field, or `pii: true`, which is the same answer. */
+export interface StateOptions {
+    visibility?: Visibility;
+    /** Sugar for `visibility: "pii"` — the one every app writes, spelled the way it is thought about. */
+    pii?: boolean;
+}
+/** One field's declaration, in the shape AgentConfig.state_fields carries it. */
+export interface StateFieldSpec {
+    name: string;
+    visibility: Visibility;
+}
+/**
+ * Declare a field as the agent's state, and optionally who may see it. Three spellings, one
+ * meaning: `@state`, `@state({ pii: true })`, `@state({ visibility: "public" })`.
+ *
+ * A field with no visibility is `tenant`, which is also the wire's default, so the framework never
+ * sends a declaration the tenant did not write.
+ */
+export declare function state(prototype: object, name: string): void;
+export declare function state(options?: StateOptions): (prototype: object, name: string) => void;
+/**
+ * Every field declaration this class carries, parents first: the `@state` decorators up the
+ * prototype chain, and then `static visibility = { field: "public" }` for a class that would
+ * rather write a map than a decorator. The map wins, because it is written last and closest.
+ */
+export declare function visibilityOf(ctor: Function): StateFieldSpec[];
+/**
+ * The fields this class said are its state, or null when it decorated none.
+ *
+ * One rule, and it is the whole feature: a class that decorates NO field has every own field as
+ * state, as it always did; a class that decorates ANY field means "these, and nothing else", so an
+ * undecorated field on it is the tenant's own scratch space — out of the snapshot, out of the
+ * prompt, out of `state.changed`. `static visibility` says who may see a field and never whether it
+ * is one: a map is an answer about visibility, not a declaration of the state.
+ */
+export declare function declaredStateOf(ctor: Function): ReadonlySet<string> | null;
+//# sourceMappingURL=visibility.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visibility.d.ts","sourceRoot":"","sources":["../../src/agent/visibility.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAI9F,gGAAgG;AAChG,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;AAErD,2GAA2G;AAC3G,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,qGAAqG;IACrG,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,UAAU,CAAC;CACxB;AAaD;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;AAC7D,wBAAgB,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAYzF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,cAAc,EAAE,CAU7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAU1E"}

package/dist/agent/visibility.js

@@ -0,0 +1,89 @@
+/** `@state`: which fields are the state, and who may see them. Declared once on the class. */
+import { DeclarationRefused } from "./tools.js";
+// Keyed by prototype, like the tool registry: a legacy decorator runs once per class at
+// definition time, so a subclass inherits its parent's declarations by walking the chain. A field
+// declared with no visibility maps to undefined: it is state, and the wire is told nothing about
+// who may see it, which is the wire's own default.
+const declared = new WeakMap();
+// The merged declaration of a class, worked out once. Every `@state` of a class runs at definition
+// time, before any instance exists, so the answer cannot change after the first read — and the
+// Proxy asks this on every assignment.
+const merged = new WeakMap();
+export function state(first, name) {
+    // A legacy property decorator is called `(prototype, name)`, a factory with its options or with
+    // nothing at all: the second argument is what tells the two apart.
+    if (typeof name === "string")
+        return declare(first, name, {});
+    const options = (first ?? {});
+    return (prototype, field) => declare(prototype, field, options);
+}
+/**
+ * Every field declaration this class carries, parents first: the `@state` decorators up the
+ * prototype chain, and then `static visibility = { field: "public" }` for a class that would
+ * rather write a map than a decorator. The map wins, because it is written last and closest.
+ */
+export function visibilityOf(ctor) {
+    const fields = new Map();
+    for (const prototype of chainOf(ctor)) {
+        for (const [field, visibility] of declared.get(prototype) ?? [])
+            fields.set(field, visibility);
+    }
+    const map = ctor.visibility;
+    for (const [field, visibility] of Object.entries(map ?? {}))
+        fields.set(field, visibility);
+    return [...fields]
+        .filter((entry) => entry[1] !== undefined)
+        .map(([name, visibility]) => ({ name, visibility }));
+}
+/**
+ * The fields this class said are its state, or null when it decorated none.
+ *
+ * One rule, and it is the whole feature: a class that decorates NO field has every own field as
+ * state, as it always did; a class that decorates ANY field means "these, and nothing else", so an
+ * undecorated field on it is the tenant's own scratch space — out of the snapshot, out of the
+ * prompt, out of `state.changed`. `static visibility` says who may see a field and never whether it
+ * is one: a map is an answer about visibility, not a declaration of the state.
+ */
+export function declaredStateOf(ctor) {
+    const known = merged.get(ctor);
+    if (known !== undefined)
+        return known;
+    const fields = new Set();
+    for (const prototype of chainOf(ctor)) {
+        for (const field of (declared.get(prototype) ?? new Map()).keys())
+            fields.add(field);
+    }
+    const answer = fields.size === 0 ? null : fields;
+    merged.set(ctor, answer);
+    return answer;
+}
+// The prototypes of a class, parents first, so a subclass's own declaration is written last.
+function chainOf(ctor) {
+    const chain = [];
+    for (let prototype = ctor.prototype ?? null; prototype !== null && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)) {
+        chain.unshift(prototype);
+    }
+    return chain;
+}
+function declare(prototype, name, options) {
+    let own = declared.get(prototype);
+    if (own === undefined) {
+        own = new Map();
+        declared.set(prototype, own);
+    }
+    own.set(name, visibilityIn(options, prototype, name));
+}
+// `pii: true` is `visibility: "pii"` said the way an app thinks about it. Written together they
+// are either the same answer twice or two different ones, and the second is a field whose masking
+// depends on which line the reader believes.
+function visibilityIn(options, prototype, name) {
+    if (options.pii === true && options.visibility !== undefined && options.visibility !== "pii") {
+        throw new DeclarationRefused(`@state({ pii: true, visibility: ${JSON.stringify(options.visibility)} }) on ` +
+            `${prototype.constructor.name}.${name}: ` +
+            `two different answers to one question; write one`);
+    }
+    if (options.pii === true)
+        return "pii";
+    return options.visibility;
+}
+//# sourceMappingURL=visibility.js.map

package/dist/agent/visibility.js.map

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

package/dist/call/call.d.ts

@@ -0,0 +1,55 @@
+/** `this.call`: the one call this instance is serving — its line, its room, its turns, its verbs. */
+import type { Call as HookCall } from "../agent/lifecycle.js";
+import { History } from "./history.js";
+import { ParticipantHandle, Room, type Commander } from "./room.js";
+/** What the call world needs to know about the line, beyond what the room's entries tell it. */
+export interface CallLine extends HookCall {
+    today?: string;
+}
+/**
+ * One live call, as the class holds it. Everything on it was reduced from entries the runtime
+ * already receives, and every verb is one command on the wire — there is no LiveKit here and no
+ * escape hatch to it: a need the room cannot express is a new command with a name.
+ */
+export declare class CallWorld implements HookCall {
+    #private;
+    private readonly out;
+    private readonly ackMs;
+    readonly id: string;
+    readonly contact: string;
+    readonly from?: string;
+    readonly channel?: string;
+    /** The day this call opened, `YYYY-MM-DD`. What a prompt — and an agenda — means by today. */
+    readonly today?: string;
+    readonly room: Room;
+    readonly history: History;
+    /** The event being dispatched right now, so a write inside onEvent can name its cause. */
+    cause: {
+        name: string;
+        seq: number;
+    } | null;
+    constructor(line: CallLine, out: Commander, ackMs?: number);
+    /** The next outside fact's place in this call's own stream of them; the wire's seq is not on it. */
+    numbered(): number;
+    /** One participant, and what may be done to them: `call.participant(id).mute()`. */
+    participant(identity: string): ParticipantHandle;
+    /** Push a payload to a browser in the room. The log keeps its size, never the payload. */
+    send(topic: string, data: Record<string, unknown>, options?: {
+        to?: string;
+    }): void;
+    /** Say this, word for word. Resolves true when the turn it lands as arrived, false on the wait. */
+    say(text: string, options?: {
+        allowInterruptions?: boolean;
+    }): Promise<boolean>;
+    /** Make the model speak, guided by words the caller never hears. Resolves like `say`. */
+    reply(instructions: string, options?: {
+        allowInterruptions?: boolean;
+    }): Promise<boolean>;
+    /** Invite somebody into the room: the room's own verb, reachable from the call for symmetry. */
+    invite(to: string, options: {
+        kind: "sip" | "participant";
+    }): void;
+    /** One entry of this call's, folded into the room and the history. Unknown types are ignored. */
+    take(type: string, data: Record<string, unknown>, at: number): void;
+}
+//# sourceMappingURL=call.d.ts.map

package/dist/call/call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../../src/call/call.ts"],"names":[],"mappings":"AAAA,qGAAqG;AAErG,OAAO,KAAK,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,KAAK,SAAS,EAAwB,MAAM,WAAW,CAAC;AAK1F,gGAAgG;AAChG,MAAM,WAAW,QAAS,SAAQ,QAAQ;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,SAAU,YAAW,QAAQ;;IAoBtC,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK;IApBxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8FAA8F;IAC9F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,OAAO,UAAiB;IAMjC,0FAA0F;IAC1F,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAQ;IAGnD,YACE,IAAI,EAAE,QAAQ,EACG,GAAG,EAAE,SAAS,EACd,KAAK,SAAS,EAQhC;IAED,oGAAoG;IACpG,QAAQ,IAAI,MAAM,CAEjB;IAED,oFAAoF;IACpF,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAE/C;IAED,0FAA0F;IAC1F,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI,CAEtF;IAED,mGAAmG;IACnG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAGlF;IAED,yFAAyF;IACzF,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAG5F;IAED,gGAAgG;IAChG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,KAAK,GAAG,aAAa,CAAA;KAAE,GAAG,IAAI,CAEjE;IAED,iGAAiG;IACjG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAuBlE;CAmBF"}

package/dist/call/call.js

@@ -0,0 +1,108 @@
+/** `this.call`: the one call this instance is serving — its line, its room, its turns, its verbs. */
+import { History } from "./history.js";
+import { ParticipantHandle, Room } from "./room.js";
+/** How long a say or a reply waits for the turn it lands as before it gives up saying so. */
+const ACK_MS = 30_000;
+/**
+ * One live call, as the class holds it. Everything on it was reduced from entries the runtime
+ * already receives, and every verb is one command on the wire — there is no LiveKit here and no
+ * escape hatch to it: a need the room cannot express is a new command with a name.
+ */
+export class CallWorld {
+    out;
+    ackMs;
+    id;
+    contact;
+    from;
+    channel;
+    /** The day this call opened, `YYYY-MM-DD`. What a prompt — and an agenda — means by today. */
+    today;
+    room;
+    history = new History();
+    // Who is waiting for the agent's next turn. say and reply both settle on it, because turn.agent
+    // is the only acknowledgement the wire has for either: the command frame itself is fire and
+    // forget, and the gateway answers commands with the entries they land as.
+    #speaking = [];
+    /** The event being dispatched right now, so a write inside onEvent can name its cause. */
+    cause = null;
+    #events = 0;
+    constructor(line, out, ackMs = ACK_MS) {
+        this.out = out;
+        this.ackMs = ackMs;
+        this.id = line.id;
+        this.contact = line.contact;
+        if (line.from !== undefined)
+            this.from = line.from;
+        if (line.channel !== undefined)
+            this.channel = line.channel;
+        if (line.today !== undefined)
+            this.today = line.today;
+        this.room = new Room(out);
+    }
+    /** The next outside fact's place in this call's own stream of them; the wire's seq is not on it. */
+    numbered() {
+        return (this.#events += 1);
+    }
+    /** One participant, and what may be done to them: `call.participant(id).mute()`. */
+    participant(identity) {
+        return new ParticipantHandle(identity, this.out);
+    }
+    /** Push a payload to a browser in the room. The log keeps its size, never the payload. */
+    send(topic, data, options = {}) {
+        this.out("room.send", options.to === undefined ? { topic, data } : { topic, data, to: options.to });
+    }
+    /** Say this, word for word. Resolves true when the turn it lands as arrived, false on the wait. */
+    say(text, options = {}) {
+        this.out("agent.say", { text, ...options });
+        return this.#spoken();
+    }
+    /** Make the model speak, guided by words the caller never hears. Resolves like `say`. */
+    reply(instructions, options = {}) {
+        this.out("agent.reply", { instructions, ...options });
+        return this.#spoken();
+    }
+    /** Invite somebody into the room: the room's own verb, reachable from the call for symmetry. */
+    invite(to, options) {
+        this.room.invite(to, options);
+    }
+    /** One entry of this call's, folded into the room and the history. Unknown types are ignored. */
+    take(type, data, at) {
+        switch (type) {
+            case "participant.joined":
+                return this.room.joined({
+                    identity: String(data["identity"]),
+                    kind: data["kind"],
+                    ...(typeof data["name"] === "string" ? { name: data["name"] } : {}),
+                }, at);
+            case "participant.left":
+                return this.room.left(String(data["identity"]));
+            case "participant.speaking":
+                return this.room.speaking(String(data["identity"]), data["speaking"] === true);
+            case "turn.user":
+                return this.history.took({ who: "user", text: String(data["text"] ?? ""), speechId: String(data["speech_id"] ?? data["speechId"] ?? ""), interrupted: false, at });
+            case "turn.agent":
+                this.history.took({ who: "agent", text: String(data["text"] ?? ""), speechId: String(data["speech_id"] ?? data["speechId"] ?? ""), interrupted: data["interrupted"] === true, at });
+                return this.#settle(true);
+            default:
+                return;
+        }
+    }
+    #spoken() {
+        return new Promise((resolve) => {
+            this.#speaking.push(resolve);
+            // A line that hung up mid-sentence must not leave a tool awaiting forever, and a hang-up is
+            // not an error the tool can do anything about: the wait answers false and the call goes on.
+            setTimeout(() => {
+                this.#speaking = this.#speaking.filter((waiting) => waiting !== resolve);
+                resolve(false);
+            }, this.ackMs).unref?.();
+        });
+    }
+    #settle(spoken) {
+        const waiting = this.#speaking;
+        this.#speaking = [];
+        for (const resolve of waiting)
+            resolve(spoken);
+    }
+}
+//# sourceMappingURL=call.js.map

package/dist/call/call.js.map

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

package/dist/call/history.d.ts

@@ -0,0 +1,34 @@
+/** The conversation so far: finished turns, and the one sentence a long call collapses them to. */
+/** One finished turn, from turn.user or turn.agent. Only what was said; the metrics stay in the log. */
+export interface Turn {
+    who: "user" | "agent";
+    text: string;
+    /** The id that joins a caller's turn to the reply it triggered. */
+    speechId: string;
+    /** True when the caller cut the agent off; always false for a caller's own turn. */
+    interrupted: boolean;
+    at: number;
+}
+/**
+ * The turns this call has finished, oldest first. A turn lands here when its entry does, so the
+ * words the model is still speaking are not in it — the log is the record, this is the reading.
+ */
+export declare class History {
+    #private;
+    /** Every finished turn, oldest first. */
+    get turns(): readonly Turn[];
+    /** How many turns are being kept. */
+    get length(): number;
+    /** The sentence a `collapse` left in place of the turns before it, or null while none was made. */
+    get summary(): string | null;
+    /** The last turn, whoever took it. */
+    get last(): Turn | undefined;
+    /** Add a finished turn. The bridge calls this from turn.user and turn.agent; nothing else does. */
+    took(turn: Turn): void;
+    /**
+     * Drop the turns and keep one sentence in their place. This is the view's memory, not the log's:
+     * the call log keeps every turn it ever had, and a summary here never rewrites one.
+     */
+    collapse(summary: string): void;
+}
+//# sourceMappingURL=history.d.ts.map

package/dist/call/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/call/history.ts"],"names":[],"mappings":"AAAA,mGAAmG;AAEnG,wGAAwG;AACxG,MAAM,WAAW,IAAI;IACnB,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,WAAW,EAAE,OAAO,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;GAGG;AACH,qBAAa,OAAO;;IAIlB,yCAAyC;IACzC,IAAI,KAAK,IAAI,SAAS,IAAI,EAAE,CAE3B;IAED,qCAAqC;IACrC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,mGAAmG;IACnG,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED,sCAAsC;IACtC,IAAI,IAAI,IAAI,IAAI,GAAG,SAAS,CAE3B;IAED,mGAAmG;IACnG,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAErB;IAED;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG9B;CACF"}

package/dist/call/history.js

@@ -0,0 +1,38 @@
+/** The conversation so far: finished turns, and the one sentence a long call collapses them to. */
+/**
+ * The turns this call has finished, oldest first. A turn lands here when its entry does, so the
+ * words the model is still speaking are not in it — the log is the record, this is the reading.
+ */
+export class History {
+    #turns = [];
+    #summary = null;
+    /** Every finished turn, oldest first. */
+    get turns() {
+        return this.#turns;
+    }
+    /** How many turns are being kept. */
+    get length() {
+        return this.#turns.length;
+    }
+    /** The sentence a `collapse` left in place of the turns before it, or null while none was made. */
+    get summary() {
+        return this.#summary;
+    }
+    /** The last turn, whoever took it. */
+    get last() {
+        return this.#turns[this.#turns.length - 1];
+    }
+    /** Add a finished turn. The bridge calls this from turn.user and turn.agent; nothing else does. */
+    took(turn) {
+        this.#turns.push(turn);
+    }
+    /**
+     * Drop the turns and keep one sentence in their place. This is the view's memory, not the log's:
+     * the call log keeps every turn it ever had, and a summary here never rewrites one.
+     */
+    collapse(summary) {
+        this.#turns.length = 0;
+        this.#summary = summary;
+    }
+}
+//# sourceMappingURL=history.js.map

package/dist/call/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../src/call/history.ts"],"names":[],"mappings":"AAAA,mGAAmG;AAanG;;;GAGG;AACH,MAAM,OAAO,OAAO;IACT,MAAM,GAAW,EAAE,CAAC;IAC7B,QAAQ,GAAkB,IAAI,CAAC;IAE/B,yCAAyC;IACzC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,qCAAqC;IACrC,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,mGAAmG;IACnG,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,sCAAsC;IACtC,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,mGAAmG;IACnG,IAAI,CAAC,IAAU;QACb,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,OAAe;QACtB,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;CACF"}