@pinecall/agents 0.9.20

package/dist/agent/state.js.map

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

package/dist/agent/tools.d.ts

@@ -0,0 +1,61 @@
+/** The tool registry: declared tools, their wire specs, and which are visible in the current state. */
+import { z } from "zod";
+import { type ToolSpec } from "../wire/defs.js";
+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"]>;
+/** Options for `@tool({...})`. `T` is inferred from the decorated class, so `when` sees typed state. */
+export interface ToolOptions<T = unknown> {
+    /** Show the tool only while this returns true for the current state. */
+    when?: (state: Snapshot<T>) => boolean;
+    /**
+     * Show the tool only in these stages, typed against the class's `stage` field. Combined with
+     * `when`, both must hold.
+     */
+    stage?: StageOf<T> | StageOf<T>[];
+    /** Confirmation read back after the tool runs; `{{result.x}}` is filled from its return value. Marks the tool irreversible. */
+    confirm?: string;
+    /** Number of rows of a list result shown to the model; the full result is kept. */
+    preview?: number;
+    /** Parameter names holding personal data, masked in the log. */
+    pii?: string[];
+    /** Timeout for the method, in seconds. */
+    timeout?: number;
+    /** Explicit parameter schema, overriding the one inferred from the signature. */
+    params?: z.ZodObject;
+}
+export type ErasedToolOptions = ToolOptions<any>;
+/** A declared tool: its options, method, owning class and wire spec. */
+export interface ToolDeclaration {
+    name: string;
+    options: ErasedToolOptions;
+    method: (...args: unknown[]) => unknown;
+    owner: Function;
+    spec: ToolSpec;
+}
+/** Thrown at declaration time for a tool or class the platform would refuse. */
+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;
+/** JSON Schema for a tool's parameters, from an explicit zod object or from the signature. */
+export declare function parametersOf(params: ParamDoc[], explicit?: z.ZodObject): Record<string, unknown>;
+/** Every tool the agent declares, own class first, then inherited. */
+export declare function toolsOf(agent: object): ToolDeclaration[];
+/** A declared tool by name. */
+export declare function toolNamed(agent: object, name: string): ToolDeclaration | undefined;
+/** Tools whose `when` holds for the current state. */
+export declare function visibleToolsOf(agent: object): ToolDeclaration[];
+/** Wire specs of the currently visible tools. */
+export declare function visibleTools(agent: object): ToolSpec[];
+/** The agent class's docstring. */
+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,uGAAuG;AAEvG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,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;AAGrD,YAAY,EAAE,QAAQ,EAAE,CAAC;AAGzB,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D,wGAAwG;AACxG,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,wEAAwE;IACxE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC;IACvC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC,+HAA+H;IAC/H,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;CACtB;AAGD,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;AAEjD,wEAAwE;AACxE,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;AAQD,sEAAsE;AACtE,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAUpE;AAWD,8FAA8F;AAC9F,wBAAgB,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWhG;AAwDD,sEAAsE;AACtE,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAuBxD;AAED,+BAA+B;AAC/B,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAElF;AAED,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAG/D;AAED,iDAAiD;AACjD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,CAEtD;AAED,mCAAmC;AAEnC,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvD"}

package/dist/agent/tools.js

@@ -0,0 +1,145 @@
+/** The tool registry: declared tools, their wire specs, and which are visible in the current state. */
+import { z } from "zod";
+import {} from "../wire/defs.js";
+import { classDoc, docsVersion, methodDoc, methodParams } from "./docstrings.js";
+import { snapshot } from "./state.js";
+/** Thrown at declaration time for a tool or class the platform would refuse. */
+export class DeclarationRefused extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DeclarationRefused";
+    }
+}
+// Keyed by prototype; subclasses inherit by walking the chain at read time.
+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);
+}
+// Fallback for bare type text when `param.schema` is absent; unknown shapes become open objects.
+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 };
+}
+/** JSON Schema for a tool's parameters, 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;
+        // The model cannot supply a callback, so it is never required.
+        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(", ")}`);
+    }
+    // `confirm` makes a tool irreversible: the platform reads it back and waits for a yes.
+    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;
+}
+// Without a `stage` field every staged tool would stay hidden. The compiler catches this in TS;
+// this catches it for JavaScript classes, at mount.
+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 the agent declares, own class first, then inherited. */
+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;
+}
+/** A declared tool by name. */
+export function toolNamed(agent, name) {
+    return toolsOf(agent).find((declared) => declared.name === name);
+}
+/** Tools whose `when` holds for the current state. */
+export function visibleToolsOf(agent) {
+    const state = snapshot(agent);
+    return toolsOf(agent).filter((declared) => declared.options.when?.(state) ?? true);
+}
+/** Wire specs of the currently visible tools. */
+export function visibleTools(agent) {
+    return visibleToolsOf(agent).map((declared) => declared.spec);
+}
+/** The agent class's docstring. */
+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/view.d.ts

@@ -0,0 +1,29 @@
+/** `@view(Component)`: the console panel an agent draws beside a conversation. */
+import type { Child } from "../views/jsx-runtime.js";
+/**
+ * The conversation a panel is drawn for. It identifies a thread, not live call state: panels are
+ * shown for ended calls too, so a view fetches its data from the tenant's own systems.
+ */
+export interface Who {
+    /** The agent whose thread is open. */
+    agent: string;
+    /** The other party: phone number, contact id, or web visitor id. */
+    contact: string;
+    /** The thread's most recent call id. */
+    call: string;
+}
+/** Draws a panel for one conversation with `@pinecall/agents/panels` tags. May be async. */
+export type View = (who: Who) => Child | Promise<Child>;
+/** A class's declared panel: its title and draw function. */
+export interface DeclaredView {
+    name: string;
+    draw: View;
+}
+/**
+ * Declare the class's console panel. The title defaults to the function name spaced out
+ * (`CustomerCard` becomes "Customer Card"); pass `name` to set it.
+ */
+export declare function view(draw: View, name?: string): (ctor: new (...args: never[]) => object) => void;
+/** The class's declared panel, or undefined. */
+export declare function viewOf(ctor: object): DeclaredView | undefined;
+//# sourceMappingURL=view.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/agent/view.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAGrD;;;GAGG;AACH,MAAM,WAAW,GAAG;IAClB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4FAA4F;AAC5F,MAAM,MAAM,IAAI,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;AAExD,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;CACZ;AAKD;;;GAGG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,UACb,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,MAAM,KAAG,IAAI,CAOvE;AAED,gDAAgD;AAChD,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAE7D"}

package/dist/agent/view.js

@@ -0,0 +1,29 @@
+/** `@view(Component)`: the console panel an agent draws beside a conversation. */
+import { DeclarationRefused } from "./tools.js";
+// Stored outside the class: subclasses do not inherit it and nothing is added to the tenant's class.
+const VIEWS = new WeakMap();
+/**
+ * Declare the class's console panel. The title defaults to the function name spaced out
+ * (`CustomerCard` becomes "Customer Card"); pass `name` to set it.
+ */
+export function view(draw, name) {
+    return function decorate(ctor) {
+        const standing = VIEWS.get(ctor);
+        if (standing !== undefined) {
+            throw new DeclarationRefused(`${ctor.name} declares two views (${standing.name} and ${name ?? nameOf(draw)}); a class draws one panel`);
+        }
+        VIEWS.set(ctor, { name: name ?? nameOf(draw), draw });
+    };
+}
+/** The class's declared panel, or undefined. */
+export function viewOf(ctor) {
+    return VIEWS.get(ctor);
+}
+// `CustomerCard` -> `Customer Card`; acronyms are left intact.
+function nameOf(draw) {
+    const written = draw.name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").trim();
+    if (written === "")
+        return "View";
+    return written.charAt(0).toUpperCase() + written.slice(1);
+}
+//# sourceMappingURL=view.js.map

package/dist/agent/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../src/agent/view.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAGlF,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAwBhD,qGAAqG;AACrG,MAAM,KAAK,GAAG,IAAI,OAAO,EAAwB,CAAC;AAElD;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,IAAU,EAAE,IAAa;IAC5C,OAAO,SAAS,QAAQ,CAAC,IAAsC;QAC7D,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,kBAAkB,CAAC,GAAG,IAAI,CAAC,IAAI,wBAAwB,QAAQ,CAAC,IAAI,QAAQ,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;QAC1I,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC,CAAC;AACJ,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,+DAA+D;AAE/D,SAAS,MAAM,CAAC,IAAU;IACxB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IACxE,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,MAAM,CAAC;IAClC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/agent/visibility.d.ts

@@ -0,0 +1,32 @@
+/** `@state`: declare which fields are state and who may see them. */
+/** Who may see a state field (wire values from the protocol). */
+export type Visibility = "public" | "tenant" | "pii";
+/** Options for `@state({...})`. */
+export interface StateOptions {
+    visibility?: Visibility;
+    /** Shorthand for `visibility: "pii"`. */
+    pii?: boolean;
+}
+/** One field's declaration as carried in `AgentConfig.state_fields`. */
+export interface StateFieldSpec {
+    name: string;
+    visibility: Visibility;
+}
+/**
+ * Declare a field as state, optionally with its visibility: `@state`, `@state({ pii: true })`,
+ * `@state({ visibility: "public" })`. The default visibility is `tenant`.
+ */
+export declare function state(prototype: object, name: string): void;
+export declare function state(options?: StateOptions): (prototype: object, name: string) => void;
+/**
+ * Field visibilities from `@state` decorators up the chain (parents first), then
+ * `static visibility`, which wins.
+ */
+export declare function visibilityOf(ctor: Function): StateFieldSpec[];
+/**
+ * The `@state` fields of a class, or null when it decorates none (then every own field is state).
+ * Once any field is decorated, undecorated fields are excluded from snapshots, prompt and
+ * `state.changed`. `static visibility` does not declare 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,qEAAqE;AAIrE,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;AAErD,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,yCAAyC;IACzC,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,UAAU,CAAC;CACxB;AASD;;;GAGG;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;AAWzF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,cAAc,EAAE,CAU7D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAU1E"}

package/dist/agent/visibility.js

@@ -0,0 +1,77 @@
+/** `@state`: declare which fields are state and who may see them. */
+import { DeclarationRefused } from "./tools.js";
+// Keyed by prototype; subclasses inherit by walking the chain. `undefined` visibility means the
+// field is state and the wire default applies.
+const declared = new WeakMap();
+// Cached: decorators all run at class definition, and the Proxy reads this on every assignment.
+const merged = new WeakMap();
+export function state(first, name) {
+    // Bare decorator `(prototype, name)` vs factory `(options?)`: told apart by the second argument.
+    if (typeof name === "string")
+        return declare(first, name, {});
+    const options = (first ?? {});
+    return (prototype, field) => declare(prototype, field, options);
+}
+/**
+ * Field visibilities from `@state` decorators up the chain (parents first), then
+ * `static visibility`, which wins.
+ */
+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 `@state` fields of a class, or null when it decorates none (then every own field is state).
+ * Once any field is decorated, undecorated fields are excluded from snapshots, prompt and
+ * `state.changed`. `static visibility` does not declare 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;
+}
+// Parents first, so a subclass's declarations override.
+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));
+}
+// Refuse `pii: true` combined with a different `visibility`.
+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":"AAAA,qEAAqE;AAErE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAkBhD,gGAAgG;AAChG,+CAA+C;AAC/C,MAAM,QAAQ,GAAG,IAAI,OAAO,EAA+C,CAAC;AAE5E,gGAAgG;AAChG,MAAM,MAAM,GAAG,IAAI,OAAO,EAAwC,CAAC;AAQnE,MAAM,UAAU,KAAK,CACnB,KAA6B,EAC7B,IAAa;IAEb,iGAAiG;IACjG,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC,KAAe,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE,CAAiB,CAAC;IAC9C,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAc;IACzC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkC,CAAC;IACzD,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,KAAK,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE;YAAE,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IACjG,CAAC;IACD,MAAM,GAAG,GAAI,IAAoD,CAAC,UAAU,CAAC;IAC7E,KAAK,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC;QAAE,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC3F,OAAO,CAAC,GAAG,MAAM,CAAC;SACf,MAAM,CAAC,CAAC,KAAK,EAAiC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;SACxE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAc;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,KAAK,MAAM,KAAK,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE;YAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IACjD,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,wDAAwD;AACxD,SAAS,OAAO,CAAC,IAAc;IAC7B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KACE,IAAI,SAAS,GAAmB,IAA+B,CAAC,SAAS,IAAI,IAAI,EACjF,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,EACpD,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,SAAS,CAAkB,EAC7D,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,OAAO,CAAC,SAAiB,EAAE,IAAY,EAAE,OAAqB;IACrE,IAAI,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,GAAG,GAAG,IAAI,GAAG,EAAkC,CAAC;QAChD,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC;IACD,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,6DAA6D;AAE7D,SAAS,YAAY,CAAC,OAAqB,EAAE,SAAiB,EAAE,IAAY;IAC1E,IAAI,OAAO,CAAC,GAAG,KAAK,IAAI,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,OAAO,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;QAC7F,MAAM,IAAI,kBAAkB,CAC1B,mCAAmC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS;YAC5E,GAAI,SAAuC,CAAC,WAAW,CAAC,IAAI,IAAI,IAAI,IAAI;YACxE,kDAAkD,CACrD,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACvC,OAAO,OAAO,CAAC,UAAU,CAAC;AAC5B,CAAC"}

package/dist/call/call.d.ts

@@ -0,0 +1,137 @@
+/** `this.call`: the live call an agent instance serves — its room, turns and verbs. */
+import { type Medium } from "../wire/defs.js";
+import type { Call as HookCall } from "../agent/lifecycle.js";
+import { History } from "./history.js";
+import { ParticipantHandle, Room, type Commander } from "./room.js";
+/** `cold`: the caller is sent on. `warm`: the far end is dialled into the call. */
+export type TransferMode = "cold" | "warm";
+/** The supervisor who took the line, as their token names them. */
+export interface Supervisor {
+    id: string;
+    name?: string;
+}
+/** Result of `transfer()`. `ok: false` means the caller is still on the line. */
+export interface Transferred {
+    to: string;
+    mode: TransferMode | null;
+    ok: boolean;
+    error?: string;
+}
+/** Result of `attention()`: who took the line, or why nobody did. */
+export interface Attended {
+    ok: boolean;
+    by: Supervisor | null;
+    error?: string;
+}
+/** One search hit: its source path, heading and text. */
+export interface Found {
+    path: string;
+    heading: string | null;
+    text: string;
+}
+/** Runs a search for this call through the gateway. */
+export type Searching = (query: string, k?: number) => Promise<Found[]>;
+/** Error for `search()` on a call with no gateway (an offline prompt, a test). */
+export declare const NO_GATEWAY_TO_SEARCH = "this call cannot search: no gateway is serving it";
+/** Line facts the call needs beyond what the room's entries carry. */
+export interface CallLine extends HookCall {
+    today?: string;
+    claimed?: string | null;
+}
+/**
+ * One live call. State is reduced from log entries; every verb sends one wire command.
+ * There is no direct LiveKit access.
+ */
+export declare class CallWorld implements HookCall {
+    #private;
+    private readonly out;
+    private readonly searching;
+    private readonly ackMs;
+    readonly id: string;
+    readonly contact: string;
+    readonly from?: string;
+    readonly channel?: string;
+    /** Spoken (`voice`) or written (`text`). A gateway that does not say gets it from the channel. */
+    readonly medium: Medium;
+    /** The day this call opened, `YYYY-MM-DD`. */
+    readonly today?: string;
+    /** The page code this call claimed, or null. */
+    claimed: string | null;
+    readonly room: Room;
+    readonly history: History;
+    /** The event being dispatched, so a write inside onEvent can name its cause. */
+    cause: {
+        name: string;
+        seq: number;
+    } | null;
+    constructor(line: CallLine, out: Commander, searching?: Searching | null, ackMs?: number);
+    /** Next sequence number for this call's events (independent of the wire's seq). */
+    numbered(): number;
+    /** A handle to one participant, e.g. `call.participant(id).mute()`. */
+    participant(identity: string): ParticipantHandle;
+    /** Send a payload to browsers in the room. The log records its size, not its content. */
+    send(topic: string, data: Record<string, unknown>, options?: {
+        to?: string;
+    }): void;
+    /** Speak this text verbatim. Resolves true once the turn lands, false on timeout. */
+    say(text: string, options?: {
+        allowInterruptions?: boolean;
+    }): Promise<boolean>;
+    /** Have the model speak, guided by instructions the caller never hears. Resolves like `say`. */
+    reply(instructions: string, options?: {
+        allowInterruptions?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Search the knowledge bases attached to this agent. The gateway runs the search and logs the
+     * results. `k` defaults to each base's own setting.
+     */
+    search(query: string, options?: {
+        k?: number;
+    }): Promise<Found[]>;
+    /** Invite someone into the room. Same as `room.invite`. */
+    invite(to: string, options: {
+        kind: "sip" | "participant";
+    }): void;
+    /**
+     * Transfer the caller to a number. On a phone call the line is sent on (cold); in a browser the
+     * number is dialled into the call (warm) and the agent goes silent once it answers. `mode`
+     * forces one. `ok: false` means the caller is still with the agent.
+     */
+    transfer(to: string, options?: {
+        mode?: TransferMode;
+    }): Promise<Transferred>;
+    /**
+     * Ask for a supervisor. The caller waits (on hold, or unanswered in a thread) until someone takes
+     * the line or `waitS` passes. `reason` is shown to the supervisor. The calling tool runs the
+     * whole time, so give it a `timeout` longer than `waitS`.
+     */
+    attention(reason: string, options: {
+        waitS: number;
+    }): Promise<Attended>;
+    /** Put the caller on hold: they hear hold music and the agent neither speaks nor listens. */
+    hold(): void;
+    /** Take the caller off hold. */
+    unhold(): void;
+    /** Send DTMF tones: `0-9`, `*`, `#`, and `,` for a pause. */
+    dtmf(digits: string): void;
+    /**
+     * Bind this call to the code shown on the caller's page, so the page follows the call. Sets
+     * `claimed` on `call.claimed`; an unknown, expired or taken code is refused with `no_code`.
+     */
+    claim(code: string): void;
+    /** Record a callback request in the call log for your backend to dial. */
+    callback(number: string, options?: {
+        when?: string;
+        note?: string;
+    }): void;
+    /**
+     * The caller asked never to be called again: their number joins the org's do-not-call list, and
+     * no call of the org reaches it until a consent is recorded. Tell them it is done.
+     */
+    optOut(note?: string): void;
+    /** End the call. Say goodbye before calling this; nothing after it is heard. */
+    hangup(reason?: string): void;
+    /** Fold one log entry into the room and 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":"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"}