@pinecall/agents 0.9.20

package/dist/agent/docstrings.js

@@ -0,0 +1,301 @@
+/** Read a class's JSDoc and parameter types from its source at runtime, with oxc's parser. */
+import { parseSync } from "oxc-parser";
+const registered = new WeakMap();
+const scraped = new WeakMap();
+/** Schema for a type whose shape is not visible in this file. */
+const ANY_OBJECT = { type: "object", additionalProperties: true };
+/** Flatten a JSDoc's description into one line, dropping tags. */
+function oneLine(value) {
+    const lines = [];
+    for (const raw of value.split("\n")) {
+        let line = raw.trim();
+        while (line.startsWith("*"))
+            line = line.slice(1).trim();
+        // The first tag line ends the description.
+        if (line.startsWith("@"))
+            break;
+        if (line.length > 0)
+            lines.push(line);
+    }
+    const flat = lines.join(" ");
+    return flat.length > 0 ? flat : undefined;
+}
+/**
+ * The JSDoc block ending right above `start`, separated only by whitespace. Method decorators are
+ * inside the node's span, so decorated methods still match.
+ */
+function docAt(start, source) {
+    let found;
+    for (const comment of source.jsdoc) {
+        if (comment.end > start)
+            break;
+        if (source.text.slice(comment.end, start).trim().length === 0)
+            found = comment;
+    }
+    return found ? oneLine(found.value) : undefined;
+}
+/** The type's source text. */
+function textOf(node, source) {
+    return source.text.slice(node.start, node.end);
+}
+/** The declaration inside an `export`, or the statement itself. */
+function declarationOf(statement) {
+    if (statement.type === "ExportNamedDeclaration" && statement.declaration)
+        return statement.declaration;
+    if (statement.type === "ExportDefaultDeclaration")
+        return statement.declaration;
+    return statement;
+}
+/** Top-level interfaces and type aliases. */
+function declaredTypes(body) {
+    const types = new Map();
+    for (const statement of body) {
+        const declared = declarationOf(statement);
+        if (declared.type === "TSInterfaceDeclaration" || declared.type === "TSTypeAliasDeclaration") {
+            types.set(declared.id.name, declared);
+        }
+    }
+    return types;
+}
+/** The default-exported class, else the first class, with the position its docstring must end at. */
+function theClass(body) {
+    let first;
+    for (const statement of body) {
+        const declared = declarationOf(statement);
+        if (declared.type !== "ClassDeclaration" && declared.type !== "ClassExpression")
+            continue;
+        const found = { node: declared, start: docstringEnd(declared, statement.start) };
+        if (statement.type === "ExportDefaultDeclaration")
+            return found;
+        first ??= found;
+    }
+    return first;
+}
+// A decorated class's docstring sits above its first decorator, which precedes the statement start.
+function docstringEnd(declared, start) {
+    const decorators = declared.decorators ?? [];
+    return decorators.reduce((earliest, decorator) => Math.min(earliest, decorator.start), start);
+}
+/** `undefined` or `null` in a union: makes the parameter optional. */
+function isNothing(node) {
+    return node.type === "TSUndefinedKeyword" || node.type === "TSNullKeyword";
+}
+/** JSON Schema for a type, following aliases declared in the same file. */
+function jsonOf(node, types, seen) {
+    if (node.type === "TSStringKeyword")
+        return { type: "string" };
+    if (node.type === "TSNumberKeyword")
+        return { type: "number" };
+    if (node.type === "TSBooleanKeyword")
+        return { type: "boolean" };
+    // The model never supplies a callback.
+    if (node.type === "TSFunctionType")
+        return { description: "callback" };
+    if (node.type === "TSArrayType")
+        return { type: "array", items: jsonOf(node.elementType, types, seen) };
+    if (node.type === "TSParenthesizedType")
+        return jsonOf(node.typeAnnotation, types, seen);
+    if (node.type === "TSTypeLiteral")
+        return objectOf(node.members, types, seen);
+    if (node.type === "TSUnionType")
+        return unionOf(node.types, types, seen);
+    if (node.type === "TSLiteralType")
+        return literalOf(node);
+    if (node.type === "TSTypeReference" && node.typeName.type === "Identifier") {
+        return referenceOf(node.typeName.name, types, seen);
+    }
+    return { ...ANY_OBJECT };
+}
+/** Expand a type name declared in this file; other names become a described object. */
+function referenceOf(name, types, seen) {
+    // Stop on recursive types.
+    const declared = seen.has(name) ? undefined : types.get(name);
+    if (!declared)
+        return { type: "object", description: name };
+    const deeper = new Set(seen).add(name);
+    if (declared.type === "TSInterfaceDeclaration")
+        return objectOf(declared.body.body, types, deeper);
+    return jsonOf(declared.typeAnnotation, types, deeper);
+}
+/** Object schema for interface or type-literal members. */
+function objectOf(members, types, seen) {
+    const properties = {};
+    const required = [];
+    for (const member of members) {
+        if (member.type !== "TSPropertySignature" || member.key.type !== "Identifier")
+            continue;
+        const type = member.typeAnnotation?.typeAnnotation;
+        properties[member.key.name] = type ? jsonOf(type, types, seen) : { ...ANY_OBJECT };
+        if (!member.optional)
+            required.push(member.key.name);
+    }
+    return { type: "object", properties, required, additionalProperties: false };
+}
+/** A literal type's value, or undefined for templates and expressions. */
+function valueOf(node) {
+    if (node.type !== "TSLiteralType")
+        return undefined;
+    return "value" in node.literal ? node.literal.value : undefined;
+}
+/** A union of string literals becomes an enum; anything else an open object. */
+function unionOf(members, types, seen) {
+    const real = members.filter((one) => !isNothing(one));
+    if (real.length === 1 && real[0])
+        return jsonOf(real[0], types, seen);
+    const values = real.map(valueOf).filter((value) => typeof value === "string");
+    if (values.length === real.length && real.length > 0)
+        return { type: "string", enum: values };
+    return { ...ANY_OBJECT };
+}
+/** Schema for a literal type. */
+function literalOf(node) {
+    const value = valueOf(node);
+    if (typeof value === "string")
+        return { type: "string", enum: [value] };
+    if (typeof value === "number")
+        return { type: "number" };
+    if (typeof value === "boolean")
+        return { type: "boolean" };
+    return { ...ANY_OBJECT };
+}
+/** Types the registry maps from text alone, so no schema is attached. */
+function plainType(node) {
+    if (node.type === "TSStringKeyword")
+        return true;
+    if (node.type === "TSNumberKeyword")
+        return true;
+    if (node.type === "TSBooleanKeyword")
+        return true;
+    if (node.type === "TSFunctionType")
+        return true;
+    return node.type === "TSArrayType" && plainType(node.elementType);
+}
+/** One parameter's name, type text and optionality. */
+function paramOf(node, source, types) {
+    const defaulted = node.type === "AssignmentPattern";
+    const binding = (defaulted ? node.left : node);
+    // Destructured parameters have no name to offer the model.
+    if (binding.type !== "Identifier")
+        return undefined;
+    let type = binding.typeAnnotation?.typeAnnotation;
+    let optional = defaulted || Boolean(binding.optional);
+    if (type?.type === "TSUnionType") {
+        const real = type.types.filter((one) => !isNothing(one));
+        if (real.length < type.types.length)
+            optional = true;
+        if (real.length === 1 && real[0])
+            type = real[0];
+    }
+    const param = { name: binding.name, optional };
+    if (type)
+        param.type = textOf(type, source);
+    if (type && !plainType(type))
+        param.schema = jsonOf(type, types, new Set());
+    return param;
+}
+/** Parameters of a method, or of a function-valued field. */
+function paramsOf(member, source, types) {
+    const holder = member.type === "MethodDefinition"
+        ? member.value
+        : member.type === "PropertyDefinition" &&
+            (member.value?.type === "ArrowFunctionExpression" || member.value?.type === "FunctionExpression")
+            ? member.value
+            : undefined;
+    if (!holder || holder.type === "TSEmptyBodyFunctionExpression")
+        return [];
+    return holder.params.map((param) => paramOf(param, source, types)).filter((param) => param !== undefined);
+}
+/**
+ * Read a class's JSDoc and method signatures from source text: a full file, or `Ctor.toString()`.
+ * `file`'s extension selects the dialect: JSX fails as .ts, and `<T>x` casts fail as .tsx.
+ */
+export function parseClassSource(text, file = "agent.tsx") {
+    const docs = { methods: new Map() };
+    const parsed = parseSync(file, text, { sourceType: "module" });
+    const source = {
+        text,
+        jsdoc: parsed.comments.filter((one) => one.type === "Block" && one.value.startsWith("*")),
+    };
+    const body = parsed.program.body;
+    const found = theClass(body);
+    if (!found)
+        return docs;
+    const doc = docAt(found.start, source);
+    if (doc)
+        docs.doc = doc;
+    const types = declaredTypes(body);
+    for (const member of found.node.body.body) {
+        const method = member.type === "MethodDefinition" && (member.kind === "method" || member.kind === "get");
+        if (!method && member.type !== "PropertyDefinition")
+            continue;
+        if (member.key.type !== "Identifier")
+            continue;
+        const name = member.key.name;
+        if (docs.methods.has(name))
+            continue;
+        const entry = { params: paramsOf(member, source, types) };
+        const memberDoc = docAt(member.start, source);
+        if (memberDoc)
+            entry.doc = memberDoc;
+        docs.methods.set(name, entry);
+    }
+    return docs;
+}
+// Bumped by describe() so caches built from scraped bodies know they are stale.
+let version = 0;
+/** Counter bumped by each describe(); used to invalidate caches. */
+export function docsVersion() {
+    return version;
+}
+/** Register a class's source so its docstrings and parameter types are available at runtime. */
+export function describe(ctor, source, file) {
+    const docs = parseClassSource(source, file);
+    registered.set(ctor, docs);
+    version++;
+    return docs;
+}
+/** The class's docs, from describe() if called, else parsed from `ctor.toString()`. */
+export function docsOf(ctor) {
+    const given = registered.get(ctor);
+    if (given)
+        return given;
+    let own = scraped.get(ctor);
+    if (!own) {
+        own = parseClassSource(ctor.toString());
+        scraped.set(ctor, own);
+    }
+    return own;
+}
+/** The class docstring, read from its source or from an explicit `static doc`. */
+export function classDoc(ctor) {
+    return docsOf(ctor).doc ?? ctor.doc;
+}
+/** The class and its ancestors, most derived first, excluding Function.prototype. */
+function chain(ctor) {
+    const classes = [];
+    for (let current = ctor; typeof current === "function"; current = Object.getPrototypeOf(current)) {
+        if (current === Function.prototype)
+            break;
+        classes.push(current);
+    }
+    return classes;
+}
+/** The docstring of one method, looked up along the prototype chain. */
+export function methodDoc(ctor, name) {
+    for (const current of chain(ctor)) {
+        const doc = docsOf(current).methods.get(name)?.doc;
+        if (doc)
+            return doc;
+    }
+    return undefined;
+}
+/** The parameters of one method, looked up along the prototype chain. */
+export function methodParams(ctor, name) {
+    for (const current of chain(ctor)) {
+        const found = docsOf(current).methods.get(name);
+        if (found)
+            return found.params;
+    }
+    return [];
+}
+//# sourceMappingURL=docstrings.js.map

package/dist/agent/docstrings.js.map

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

package/dist/agent/knowledge.d.ts

@@ -0,0 +1,9 @@
+/** The `this.knowledge` interface: search the knowledge bases attached to the agent. */
+import type { Found } from "../call/call.js";
+/** Search the attached knowledge bases and return the top `k` chunks for `query`. */
+export interface Knowledge {
+    search(query: string, options?: {
+        k?: number;
+    }): Promise<Found[]>;
+}
+//# sourceMappingURL=knowledge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/agent/knowledge.ts"],"names":[],"mappings":"AAAA,wFAAwF;AAExF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE7C,qFAAqF;AAErF,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;CACnE"}

package/dist/agent/knowledge.js

@@ -0,0 +1,3 @@
+/** The `this.knowledge` interface: search the knowledge bases attached to the agent. */
+export {};
+//# sourceMappingURL=knowledge.js.map

package/dist/agent/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../../src/agent/knowledge.ts"],"names":[],"mappings":"AAAA,wFAAwF"}

package/dist/agent/lifecycle.d.ts

@@ -0,0 +1,29 @@
+/** Lifecycle hooks: call start, call end, memory writes and external events. */
+import { type Medium } from "../wire/defs.js";
+import type { EventMeta } from "./accepts.js";
+/** The call passed to lifecycle hooks. */
+export interface Call {
+    id: string;
+    contact: string;
+    from?: string;
+    channel?: string;
+    /** Spoken or written, when the gateway says. */
+    medium?: Medium;
+}
+/** A memory write: remember or forget a key about the contact. */
+export interface MemoryOp {
+    op: "remember" | "forget";
+    key: string;
+    value?: unknown;
+}
+/** Hooks an agent may override; all default to no-ops. */
+export interface Lifecycle {
+    onCall(call: Call): unknown;
+    onEnd(call: Call): unknown;
+    onMemory(ops: MemoryOp[], call: Call): unknown;
+    onEvent(name: string, data: Record<string, unknown>, meta: EventMeta): unknown;
+}
+export type HookName = keyof Lifecycle;
+/** Run a hook with its state writes authored as `hook:<name>`; hooks and tools are the only writers. */
+export declare function runHook<K extends HookName>(agent: Lifecycle, hook: K, ...args: Parameters<Lifecycle[K]>): Promise<unknown>;
+//# sourceMappingURL=lifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/agent/lifecycle.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,0CAA0C;AAC1C,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IAC5B,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IAC/C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;CAChF;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC;AAEvC,wGAAwG;AAExG,wBAAgB,OAAO,CAAC,CAAC,SAAS,QAAQ,EACxC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,CAAC,EACP,GAAG,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/agent/lifecycle.js

@@ -0,0 +1,9 @@
+/** Lifecycle hooks: call start, call end, memory writes and external events. */
+import {} from "../wire/defs.js";
+import { withAuthorAsync } from "./authors.js";
+/** Run a hook with its state writes authored as `hook:<name>`; hooks and tools are the only writers. */
+export function runHook(agent, hook, ...args) {
+    const method = agent[hook];
+    return withAuthorAsync(`hook:${hook}`, () => method.apply(agent, args));
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/agent/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/agent/lifecycle.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAe,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AA8B/C,wGAAwG;AAExG,MAAM,UAAU,OAAO,CACrB,KAAgB,EAChB,IAAO,EACP,GAAG,IAA8B;IAEjC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAoC,CAAC;IAC9D,OAAO,eAAe,CAAC,QAAQ,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAC1E,CAAC"}

package/dist/agent/searching.d.ts

@@ -0,0 +1,7 @@
+/** Detect whether a class's source uses `this.knowledge`, with oxc's parser. */
+/**
+ * Whether the source reads `this.knowledge`. Sent at registration as `uses_knowledge`, so the
+ * gateway can refuse a world with no knowledge base attached at boot instead of mid-call.
+ */
+export declare function searchesKnowledge(source: string, file?: string): boolean;
+//# sourceMappingURL=searching.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"searching.d.ts","sourceRoot":"","sources":["../../src/agent/searching.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAchF;;;GAGG;AAEH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,SAAc,GAAG,OAAO,CAG7E"}

package/dist/agent/searching.js

@@ -0,0 +1,35 @@
+/** Detect whether a class's source uses `this.knowledge`, with oxc's parser. */
+import { parseSync } from "oxc-parser";
+// An AST walk, not a regex, so `this.knowledge` in strings or comments does not count. Any
+// method in the file counts, not only tools.
+const THE_WORD = "knowledge";
+/**
+ * Whether the source reads `this.knowledge`. Sent at registration as `uses_knowledge`, so the
+ * gateway can refuse a world with no knowledge base attached at boot instead of mid-call.
+ */
+export function searchesKnowledge(source, file = "agent.tsx") {
+    const parsed = parseSync(file, source, { sourceType: "module" });
+    return reaches(parsed.program);
+}
+function reaches(node) {
+    if (node.type === "MemberExpression") {
+        const object = node["object"];
+        const property = node["property"];
+        if (object.type === "ThisExpression" && property.type === "Identifier" && property["name"] === THE_WORD)
+            return true;
+    }
+    for (const child of Object.values(node)) {
+        if (Array.isArray(child)) {
+            if (child.some((one) => isNode(one) && reaches(one)))
+                return true;
+        }
+        else if (isNode(child) && reaches(child)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isNode(value) {
+    return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+//# sourceMappingURL=searching.js.map

package/dist/agent/searching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searching.js","sourceRoot":"","sources":["../../src/agent/searching.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,2FAA2F;AAC3F,6CAA6C;AAC7C,MAAM,QAAQ,GAAG,WAAW,CAAC;AAQ7B;;;GAGG;AAEH,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,IAAI,GAAG,WAAW;IAClE,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;IACjE,OAAO,OAAO,CAAC,MAAM,CAAC,OAA0B,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,OAAO,CAAC,IAAU;IACzB,IAAI,IAAI,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAS,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAS,CAAC;QAC1C,IAAI,MAAM,CAAC,IAAI,KAAK,gBAAgB,IAAI,QAAQ,CAAC,IAAI,KAAK,YAAY,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;IACvH,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;QACpE,CAAC;aAAM,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3C,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAQ,KAAc,CAAC,IAAI,KAAK,QAAQ,CAAC;AACjG,CAAC"}

package/dist/agent/stages.d.ts

@@ -0,0 +1,23 @@
+/** `stage`: shorthand for a tool visible only in certain stages of the agent. */
+import type { ToolOptions } from "./tools.js";
+/**
+ * Type for an agent's `stage` field: `stage: Stages<"identify" | "book"> = "identify"`.
+ * It is an ordinary state field; `@tool({ stage })` is typed against it.
+ */
+export type Stages<Named extends string> = Named;
+/**
+ * The union declared by a class's `stage` field, or `never` if it has none, so a misspelled or
+ * undeclared stage in `@tool({ stage })` is a compile error.
+ */
+export type StageOf<T> = T extends {
+    stage: infer Named extends string;
+} ? Named : never;
+/** A declaration's `stage` option normalized to a list. */
+export declare function stagesOf(options: {
+    stage?: unknown;
+}): string[] | undefined;
+/** The agent's current stage, or undefined if it has no string `stage` field. */
+export declare function stageOf(agent: object): string | undefined;
+/** Convert `stage` into a `when` predicate, AND-ed with any `when` already given. */
+export declare function lowerStage<T extends object>(options: ToolOptions<T>): ToolOptions<T>;
+//# sourceMappingURL=stages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stages.d.ts","sourceRoot":"","sources":["../../src/agent/stages.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAGjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,MAAM,CAAC,KAAK,SAAS,MAAM,IAAI,KAAK,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,KAAK,SAAS,MAAM,CAAA;CAAE,GAAG,KAAK,GAAG,KAAK,CAAC;AAEzF,2DAA2D;AAC3D,wBAAgB,QAAQ,CAAC,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,EAAE,GAAG,SAAS,CAI3E;AAED,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzD;AAED,qFAAqF;AAErF,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAYpF"}

package/dist/agent/stages.js

@@ -0,0 +1,29 @@
+/** `stage`: shorthand for a tool visible only in certain stages of the agent. */
+/** A declaration's `stage` option normalized to a list. */
+export function stagesOf(options) {
+    const declared = options.stage;
+    if (declared === undefined)
+        return undefined;
+    return Array.isArray(declared) ? declared.map(String) : [String(declared)];
+}
+/** The agent's current stage, or undefined if it has no string `stage` field. */
+export function stageOf(agent) {
+    const named = agent.stage;
+    return typeof named === "string" ? named : undefined;
+}
+/** Convert `stage` into a `when` predicate, AND-ed with any `when` already given. */
+export function lowerStage(options) {
+    const stages = stagesOf(options);
+    if (stages === undefined)
+        return options;
+    const also = options.when;
+    const inOneOfThem = (state) => {
+        const named = state.stage;
+        return typeof named === "string" && stages.includes(named);
+    };
+    return {
+        ...options,
+        when: also === undefined ? inOneOfThem : (state) => inOneOfThem(state) && also(state),
+    };
+}
+//# sourceMappingURL=stages.js.map

package/dist/agent/stages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stages.js","sourceRoot":"","sources":["../../src/agent/stages.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAiBjF,2DAA2D;AAC3D,MAAM,UAAU,QAAQ,CAAC,OAA4B;IACnD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC;IAC/B,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC7C,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,MAAM,KAAK,GAAI,KAA6B,CAAC,KAAK,CAAC;IACnD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,qFAAqF;AAErF,MAAM,UAAU,UAAU,CAAmB,OAAuB;IAClE,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IACzC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1B,MAAM,WAAW,GAAG,CAAC,KAAkB,EAAW,EAAE;QAClD,MAAM,KAAK,GAAI,KAA6B,CAAC,KAAK,CAAC;QACnD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC7D,CAAC,CAAC;IACF,OAAO;QACL,GAAG,OAAO;QACV,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC;KACtF,CAAC;AACJ,CAAC"}

package/dist/agent/state.d.ts

@@ -0,0 +1,36 @@
+/** Agent state as a plain object: snapshot, diff, restore and collapse. */
+import { CONFIG_FIELDS, changes } from "./agent.js";
+type ConfigName = (typeof CONFIG_FIELDS)[number];
+type StateOf<T> = {
+    [K in keyof T as T[K] extends Function ? never : K extends ConfigName ? never : K]: T[K];
+};
+/**
+ * The agent's state as a plain object: no methods, no config fields. `Snapshot<T>` is typed for
+ * class `T`; bare `Snapshot` is an untyped record.
+ */
+export type Snapshot<T = unknown> = unknown extends T ? Record<string, unknown> : StateOf<T>;
+/** One field that differs between two snapshots. */
+export interface FieldDiff {
+    field: string;
+    prev: unknown;
+    next: unknown;
+}
+/** A copy of the agent's current state, including getters. */
+export declare function snapshot(agent: object): Snapshot;
+/** Fields that differ between two snapshots. */
+export declare function diff(before: Snapshot, after: Snapshot): FieldDiff[];
+/** Replace the agent's state with a snapshot, authored by the current author or `restore`. */
+export declare function restore(agent: object, state: Snapshot): void;
+/** A change log collapsed into one summary entry. */
+export interface Collapsed {
+    summary: string;
+    seq: number;
+    at: number;
+}
+/** Replace the change log with a single summary entry; the state is unchanged. */
+export declare function collapse(agent: object, summary: string): Collapsed;
+/** Loads the snapshot a contact's last call left, if any. */
+export type LastCall = (contact: string) => Promise<Snapshot | null>;
+/** Re-exported for callers reading state and change log together. */
+export { changes };
+//# sourceMappingURL=state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/agent/state.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAE3E,OAAO,EAAS,aAAa,EAAE,OAAO,EAA8B,MAAM,YAAY,CAAC;AAIvF,KAAK,UAAU,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAGjD,KAAK,OAAO,CAAC,CAAC,IAAI;KACf,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,GAAG,KAAK,GAAG,CAAC,SAAS,UAAU,GAAG,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACzF,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,SAAS,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7F,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AA6BD,8DAA8D;AAC9D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAYhD;AAED,gDAAgD;AAChD,wBAAgB,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,SAAS,EAAE,CASnE;AAED,8FAA8F;AAC9F,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAiB5D;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAalE;AAED,6DAA6D;AAC7D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;AAErE,qEAAqE;AAErE,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/agent/state.js

@@ -0,0 +1,93 @@
+/** Agent state as a plain object: snapshot, diff, restore and collapse. */
+import { Agent, CONFIG_FIELDS, changes, internalsOf, isConfigField } from "./agent.js";
+import { currentAuthor, withAuthor } from "./authors.js";
+import { declaredStateOf } from "./visibility.js";
+// Own non-function, non-config fields; restricted to `@state` fields when the class declares any.
+function isStateField(key, value, declared) {
+    if (isConfigField(key) || typeof value === "function")
+        return false;
+    return declared === null || declared.has(key);
+}
+/** The class's `@state` fields, or null when it declares none. */
+function stateOf(agent) {
+    return declaredStateOf(internalsOf(agent).target.constructor);
+}
+// Getters are state too (`when` predicates read them). Stop at Agent so framework accessors are excluded.
+function gettersOf(agent) {
+    const names = [];
+    for (let prototype = Object.getPrototypeOf(agent); prototype && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)) {
+        if (prototype.constructor === Agent)
+            break;
+        for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(prototype))) {
+            if (typeof descriptor.get === "function" && !names.includes(name))
+                names.push(name);
+        }
+    }
+    return names;
+}
+/** A copy of the agent's current state, including getters. */
+export function snapshot(agent) {
+    const own = internalsOf(agent);
+    const readable = agent;
+    const declared = stateOf(agent);
+    const state = {};
+    for (const key of Object.keys(own.target)) {
+        const value = own.target[key];
+        if (isStateField(key, value, declared))
+            state[key] = value;
+    }
+    // Getters read through the proxy, since they are written against `this`.
+    for (const name of gettersOf(agent))
+        state[name] = readable[name];
+    return state;
+}
+/** Fields that differ between two snapshots. */
+export function diff(before, after) {
+    const fields = new Set([...Object.keys(before), ...Object.keys(after)]);
+    const changed = [];
+    for (const field of fields) {
+        if (!Object.is(before[field], after[field])) {
+            changed.push({ field, prev: before[field], next: after[field] });
+        }
+    }
+    return changed;
+}
+/** Replace the agent's state with a snapshot, authored by the current author or `restore`. */
+export function restore(agent, state) {
+    const author = currentAuthor() ?? "restore";
+    const derived = new Set(gettersOf(agent));
+    const declared = stateOf(agent);
+    const target = internalsOf(agent).target;
+    withAuthor(author, () => {
+        const writable = agent;
+        const fields = new Set(Object.keys(target));
+        // State fields missing from the snapshot are cleared; non-state fields are left alone.
+        for (const key of fields) {
+            if (isStateField(key, target[key], declared) && !(key in state))
+                writable[key] = undefined;
+        }
+        // Skip getters: they derive from the restored fields.
+        for (const [key, value] of Object.entries(state)) {
+            if (fields.has(key) || !derived.has(key))
+                writable[key] = value;
+        }
+    });
+}
+/** Replace the change log with a single summary entry; the state is unchanged. */
+export function collapse(agent, summary) {
+    const own = internalsOf(agent);
+    const collapsed = { summary, seq: ++own.seq, at: Date.now() };
+    own.changes.length = 0;
+    own.changes.push({
+        seq: collapsed.seq,
+        field: "@summary",
+        prev: undefined,
+        next: summary,
+        author: "collapse",
+        at: collapsed.at,
+    });
+    return collapsed;
+}
+/** Re-exported for callers reading state and change log together. */
+export { changes };
+//# sourceMappingURL=state.js.map