pinecall 0.1.0

package/dist/agent/docstrings.js

@@ -0,0 +1,311 @@
+/** Docstrings at runtime: a class's own source, read by oxc's parser for its JSDoc and its parameters. */
+import { parseSync } from "oxc-parser";
+const registered = new WeakMap();
+const scraped = new WeakMap();
+/** An open object: the honest answer for a type this file cannot see the shape of. */
+const ANY_OBJECT = { type: "object", additionalProperties: true };
+/** Fold a JSDoc's lines into the one sentence a model should read, tags left out. */
+function oneLine(value) {
+    const lines = [];
+    for (const raw of value.split("\n")) {
+        let line = raw.trim();
+        while (line.startsWith("*"))
+            line = line.slice(1).trim();
+        // A tag line ends the description: `@param` and friends are not part of the sentence.
+        if (line.startsWith("@"))
+            break;
+        if (line.length > 0)
+            lines.push(line);
+    }
+    const flat = lines.join(" ");
+    return flat.length > 0 ? flat : undefined;
+}
+/**
+ * The docstring attached to a position: the last JSDoc block that closed above it with nothing but
+ * whitespace in between. That gap is the whole definition of "attached" — decorators live inside
+ * the node's own span, so a decorated method is still reached by its comment.
+ */
+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 as the source writes it: the span the parser gives, read back out of the text. */
+function textOf(node, source) {
+    return source.text.slice(node.start, node.end);
+}
+/** A statement as the file declares it, with `export` peeled off so both forms read the same. */
+function declarationOf(statement) {
+    if (statement.type === "ExportNamedDeclaration" && statement.declaration)
+        return statement.declaration;
+    if (statement.type === "ExportDefaultDeclaration")
+        return statement.declaration;
+    return statement;
+}
+/** Every interface and type alias the file declares at its top level. */
+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 class this source is about, and where its docstring may sit: the `export default` if there is one. */
+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;
+}
+// Where the class's own docstring has to stop. A decorator is written between the JSDoc and the
+// class — `@render(Prompt)` above `export default class` — and the parser puts the statement's
+// start after it, so a docstring read up to the statement would find the decorator in the way and
+// give up. The docstring of a decorated class is the comment above its FIRST decorator.
+function docstringEnd(declared, start) {
+    const decorators = declared.decorators ?? [];
+    return decorators.reduce((earliest, decorator) => Math.min(earliest, decorator.start), start);
+}
+/** `undefined` and `null` inside a union: what makes the parameter optional instead of a type. */
+function isNothing(node) {
+    return node.type === "TSUndefinedKeyword" || node.type === "TSNullKeyword";
+}
+/** The JSON Schema of a type the model must fill, 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" };
+    // A callback is the app's own plumbing — the tool takes it, the model never writes one.
+    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 };
+}
+/** A type name followed one level into the file that declares it; a name from elsewhere stays a name. */
+function referenceOf(name, types, seen) {
+    // A type that contains itself would expand forever; the name is what a model gets instead.
+    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);
+}
+/** The members of an interface or an object type, as properties and the ones that are required. */
+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 };
+}
+/** The value a literal type carries; a template or an expression carries none. */
+function valueOf(node) {
+    if (node.type !== "TSLiteralType")
+        return undefined;
+    return "value" in node.literal ? node.literal.value : undefined;
+}
+/** `'a' | 'b'` is a string a model must choose from; anything wider is just an 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 };
+}
+/** A literal type is its own value's type: `'a'` is a string, `1` a number, `true` a boolean. */
+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 };
+}
+/** A type the text alone already describes: the registry maps those, so no schema is carried. */
+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: its name, the type as the source writes it, and whether it may be left out. */
+function paramOf(node, source, types) {
+    const defaulted = node.type === "AssignmentPattern";
+    const binding = (defaulted ? node.left : node);
+    // A destructured parameter names no field a model could fill, so it is not offered as one.
+    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;
+}
+/** The parameters a class member declares — a method has its own, a field has a function's or none. */
+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 out of source text. Works on the real file (types and
+ * the class's own docstring included) and on `Ctor.toString()` (the class body alone).
+ *
+ * `file` is the name that source came from, and it is not decoration: the parser reads the dialect
+ * off the extension. A class with a `render()` lives in `agent.tsx` and its JSX is a syntax error
+ * as .ts, while a class that writes `<Slot>row` as a cast is a syntax error as .tsx — so the name
+ * of the file is the one thing that can tell the two apart, and it travels from whoever read it.
+ */
+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;
+}
+// Every describe() moves this on, so anything that cached a spec built from the scraped body knows
+// it is looking at an older answer than the one the source can now give.
+let version = 0;
+/** How many times a class has been handed its own source; a cache invalidator, nothing more. */
+export function docsVersion() {
+    return version;
+}
+/** Hand a class its own source, so its docstrings and parameter types are readable at runtime. */
+export function describe(ctor, source, file) {
+    const docs = parseClassSource(source, file);
+    registered.set(ctor, docs);
+    version++;
+    return docs;
+}
+/** What this class documents about itself: what describe() was given, or its own body. */
+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;
+}
+/** A class and the classes it extends, most derived first, stopping before Function itself. */
+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":"AAAA,0GAA0G;AAE1G,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA8CvC,MAAM,UAAU,GAAG,IAAI,OAAO,EAAuB,CAAC;AACtD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAuB,CAAC;AAKnD,sFAAsF;AACtF,MAAM,UAAU,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,oBAAoB,EAAE,IAAI,EAAW,CAAC;AAQ3E,qFAAqF;AACrF,SAAS,OAAO,CAAC,KAAa;IAC5B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACzD,sFAAsF;QACtF,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,MAAM;QAChC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,SAAS,KAAK,CAAC,KAAa,EAAE,MAAc;IAC1C,IAAI,KAA0B,CAAC;IAC/B,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACnC,IAAI,OAAO,CAAC,GAAG,GAAG,KAAK;YAAE,MAAM;QAC/B,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YAAE,KAAK,GAAG,OAAO,CAAC;IACjF,CAAC;IACD,OAAO,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED,8FAA8F;AAC9F,SAAS,MAAM,CAAC,IAAY,EAAE,MAAc;IAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;AACjD,CAAC;AAED,iGAAiG;AACjG,SAAS,aAAa,CAAC,SAAoB;IACzC,IAAI,SAAS,CAAC,IAAI,KAAK,wBAAwB,IAAI,SAAS,CAAC,WAAW;QAAE,OAAO,SAAS,CAAC,WAAW,CAAC;IACvG,IAAI,SAAS,CAAC,IAAI,KAAK,0BAA0B;QAAE,OAAO,SAAS,CAAC,WAAwB,CAAC;IAC7F,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,yEAAyE;AACzE,SAAS,aAAa,CAAC,IAAiB;IACtC,MAAM,KAAK,GAAa,IAAI,GAAG,EAAE,CAAC;IAClC,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,QAAQ,CAAC,IAAI,KAAK,wBAAwB,IAAI,QAAQ,CAAC,IAAI,KAAK,wBAAwB,EAAE,CAAC;YAC7F,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,6GAA6G;AAC7G,SAAS,QAAQ,CAAC,IAAiB;IACjC,IAAI,KAAiD,CAAC;IACtD,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,QAAQ,CAAC,IAAI,KAAK,kBAAkB,IAAI,QAAQ,CAAC,IAAI,KAAK,iBAAiB;YAAE,SAAS;QAC1F,MAAM,KAAK,GAAG,EAAE,IAAI,EAAE,QAAiB,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1F,IAAI,SAAS,CAAC,IAAI,KAAK,0BAA0B;YAAE,OAAO,KAAK,CAAC;QAChE,KAAK,KAAK,KAAK,CAAC;IAClB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gGAAgG;AAChG,+FAA+F;AAC/F,kGAAkG;AAClG,wFAAwF;AACxF,SAAS,YAAY,CAAC,QAA8C,EAAE,KAAa;IACjF,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,IAAI,EAAE,CAAC;IAC7C,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;AAChG,CAAC;AAED,kGAAkG;AAClG,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,IAAI,KAAK,oBAAoB,IAAI,IAAI,CAAC,IAAI,KAAK,eAAe,CAAC;AAC7E,CAAC;AAED,kGAAkG;AAClG,SAAS,MAAM,CAAC,IAAY,EAAE,KAAe,EAAE,IAAiB;IAC9D,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC/D,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC/D,IAAI,IAAI,CAAC,IAAI,KAAK,kBAAkB;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACjE,wFAAwF;IACxF,IAAI,IAAI,CAAC,IAAI,KAAK,gBAAgB;QAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;IACvE,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;IACxG,IAAI,IAAI,CAAC,IAAI,KAAK,qBAAqB;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACzF,IAAI,IAAI,CAAC,IAAI,KAAK,eAAe;QAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAC9E,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa;QAAE,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACzE,IAAI,IAAI,CAAC,IAAI,KAAK,eAAe;QAAE,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC3E,OAAO,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,EAAE,GAAG,UAAU,EAAE,CAAC;AAC3B,CAAC;AAED,yGAAyG;AACzG,SAAS,WAAW,CAAC,IAAY,EAAE,KAAe,EAAE,IAAiB;IACnE,2FAA2F;IAC3F,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9D,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC5D,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,QAAQ,CAAC,IAAI,KAAK,wBAAwB;QAAE,OAAO,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACnG,OAAO,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AACxD,CAAC;AAED,mGAAmG;AACnG,SAAS,QAAQ,CAAC,OAAsB,EAAE,KAAe,EAAE,IAAiB;IAC1E,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,IAAI,KAAK,qBAAqB,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,KAAK,YAAY;YAAE,SAAS;QACxF,MAAM,IAAI,GAAG,MAAM,CAAC,cAAc,EAAE,cAAc,CAAC;QACnD,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,CAAC;QACnF,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC;AAC/E,CAAC;AAED,kFAAkF;AAClF,SAAS,OAAO,CAAC,IAAY;IAC3B,IAAI,IAAI,CAAC,IAAI,KAAK,eAAe;QAAE,OAAO,SAAS,CAAC;IACpD,OAAO,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED,0FAA0F;AAC1F,SAAS,OAAO,CAAC,OAAiB,EAAE,KAAe,EAAE,IAAiB;IACpE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IACtD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACtE,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC;IAC9E,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC9F,OAAO,EAAE,GAAG,UAAU,EAAE,CAAC;AAC3B,CAAC;AAED,iGAAiG;AACjG,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;IACxE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACzD,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAC3D,OAAO,EAAE,GAAG,UAAU,EAAE,CAAC;AAC3B,CAAC;AAED,iGAAiG;AACjG,SAAS,SAAS,CAAC,IAAY;IAC7B,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,IAAI,CAAC,IAAI,KAAK,kBAAkB;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,IAAI,CAAC,IAAI,KAAK,gBAAgB;QAAE,OAAO,IAAI,CAAC;IAChD,OAAO,IAAI,CAAC,IAAI,KAAK,aAAa,IAAI,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AACpE,CAAC;AAED,iGAAiG;AACjG,SAAS,OAAO,CAAC,IAAkB,EAAE,MAAc,EAAE,KAAe;IAClE,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,KAAK,mBAAmB,CAAC;IACpD,MAAM,OAAO,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAoB,CAAC;IAClE,2FAA2F;IAC3F,IAAI,OAAO,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,SAAS,CAAC;IACpD,IAAI,IAAI,GAAG,OAAO,CAAC,cAAc,EAAE,cAAc,CAAC;IAClD,IAAI,QAAQ,GAAG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtD,IAAI,IAAI,EAAE,IAAI,KAAK,aAAa,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QACzD,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM;YAAE,QAAQ,GAAG,IAAI,CAAC;QACrD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;YAAE,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC;IACzD,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5C,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;QAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;IAC5E,OAAO,KAAK,CAAC;AACf,CAAC;AAED,uGAAuG;AACvG,SAAS,QAAQ,CAAC,MAAoB,EAAE,MAAc,EAAE,KAAe;IACrE,MAAM,MAAM,GACV,MAAM,CAAC,IAAI,KAAK,kBAAkB;QAChC,CAAC,CAAC,MAAM,CAAC,KAAK;QACd,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,oBAAoB;YAClC,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,KAAK,yBAAyB,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,KAAK,oBAAoB,CAAC;YACnG,CAAC,CAAC,MAAM,CAAC,KAAK;YACd,CAAC,CAAC,SAAS,CAAC;IAClB,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,+BAA+B;QAAE,OAAO,EAAE,CAAC;IAC1E,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;AAC5G,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,IAAI,GAAG,WAAW;IAC/D,MAAM,IAAI,GAAc,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IAC/C,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAW;QACrB,IAAI;QACJ,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;KAC1F,CAAC;IACF,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,IAAmB,CAAC;IAChD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACvC,IAAI,GAAG;QAAE,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACxB,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAClC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,KAAK,kBAAkB,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;QACzG,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,oBAAoB;YAAE,SAAS;QAC9D,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,KAAK,YAAY;YAAE,SAAS;QAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;QAC7B,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACrC,MAAM,KAAK,GAAyC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;QAChG,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC9C,IAAI,SAAS;YAAE,KAAK,CAAC,GAAG,GAAG,SAAS,CAAC;QACrC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mGAAmG;AACnG,yEAAyE;AACzE,IAAI,OAAO,GAAG,CAAC,CAAC;AAEhB,gGAAgG;AAChG,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,QAAQ,CAAC,IAAc,EAAE,MAAc,EAAE,IAAa;IACpE,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC5C,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3B,OAAO,EAAE,CAAC;IACV,OAAO,IAAI,CAAC;AACd,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,MAAM,CAAC,IAAc;IACnC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,IAAI,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,QAAQ,CAAC,IAAc;IACrC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,IAAK,IAAyB,CAAC,GAAG,CAAC;AAC5D,CAAC;AAED,+FAA+F;AAC/F,SAAS,KAAK,CAAC,IAAc;IAC3B,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,KAAK,IAAI,OAAO,GAAY,IAAI,EAAE,OAAO,OAAO,KAAK,UAAU,EAAE,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1G,IAAI,OAAO,KAAK,QAAQ,CAAC,SAAS;YAAE,MAAM;QAC1C,OAAO,CAAC,IAAI,CAAC,OAAmB,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,SAAS,CAAC,IAAc,EAAE,IAAY;IACpD,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC;QACnD,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;IACtB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAAC,IAAc,EAAE,IAAY;IACvD,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/agent/lifecycle.d.ts

@@ -0,0 +1,29 @@
+/** The three hooks: what happens when a call starts, when it ends, and when memory is written. */
+import type { EventMeta } from "./accepts.js";
+/** The call an agent is answering, as much of it as this seam needs to name. */
+export interface Call {
+    id: string;
+    contact: string;
+    from?: string;
+    channel?: string;
+}
+/** One thing the agent decided to remember or to forget about this contact. */
+export interface MemoryOp {
+    op: "remember" | "forget";
+    key: string;
+    value?: unknown;
+}
+/** The hooks an app may override. All four are no-ops until the app says otherwise. */
+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 one hook with its writes authored by it. A hook is the one other place besides a tool where
+ * assigning state is legal — `onCall` restoring the last conversation is the reason it exists.
+ */
+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,kGAAkG;AAGlG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,gFAAgF;AAChF,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;CAClB;AAED,+EAA+E;AAC/E,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,uFAAuF;AACvF,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;;;GAGG;AACH,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,11 @@
+/** The three hooks: what happens when a call starts, when it ends, and when memory is written. */
+import { withAuthorAsync } from "./authors.js";
+/**
+ * Run one hook with its writes authored by it. A hook is the one other place besides a tool where
+ * assigning state is legal — `onCall` restoring the last conversation is the reason it exists.
+ */
+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,kGAAkG;AAElG,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AA4B/C;;;GAGG;AACH,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/stages.d.ts

@@ -0,0 +1,28 @@
+/** `stage`: the readable spelling of a tool that is only there while the state says so. */
+import type { ToolOptions } from "./tools.js";
+/**
+ * The stages an agent moves through, written once as the type of its own field:
+ * `stage: Stages<"identify" | "choose" | "book" | "done"> = "identify"`. It stays a plain state
+ * field — the alias is there so the class and every `@tool({ stage })` name the same four words.
+ */
+export type Stages<Named extends string> = Named;
+/**
+ * The stage names a tool of this class may name: the union its `stage` field declares. A class
+ * without one gives `never`, so `@tool({ stage: "book" })` on it is a compile error and
+ * `@tool({ stage: "bok" })` on the clinic is another.
+ */
+export type StageOf<T> = T extends {
+    stage: infer Named extends string;
+} ? Named : never;
+/** The stages one declaration names, always as a list: `"book"` and `["choose", "book"]` read alike. */
+export declare function stagesOf(options: {
+    stage?: unknown;
+}): string[] | undefined;
+/** The stage this agent is in right now, or undefined for a class that names no stages. */
+export declare function stageOf(agent: object): string | undefined;
+/**
+ * Lower `stage` to the one visibility there is, at declaration time. `when(state)` stays the only
+ * question ever asked of the state; a declaration that writes both is visible where both hold.
+ */
+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,2FAA2F;AAG3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,MAAM,MAAM,MAAM,CAAC,KAAK,SAAS,MAAM,IAAI,KAAK,CAAC;AAEjD;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,KAAK,SAAS,MAAM,CAAA;CAAE,GAAG,KAAK,GAAG,KAAK,CAAC;AAEzF,wGAAwG;AACxG,wBAAgB,QAAQ,CAAC,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,EAAE,GAAG,SAAS,CAI3E;AAED,2FAA2F;AAC3F,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzD;AAED;;;GAGG;AACH,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,32 @@
+/** `stage`: the readable spelling of a tool that is only there while the state says so. */
+/** The stages one declaration names, always as a list: `"book"` and `["choose", "book"]` read alike. */
+export function stagesOf(options) {
+    const declared = options.stage;
+    if (declared === undefined)
+        return undefined;
+    return Array.isArray(declared) ? declared.map(String) : [String(declared)];
+}
+/** The stage this agent is in right now, or undefined for a class that names no stages. */
+export function stageOf(agent) {
+    const named = agent.stage;
+    return typeof named === "string" ? named : undefined;
+}
+/**
+ * Lower `stage` to the one visibility there is, at declaration time. `when(state)` stays the only
+ * question ever asked of the state; a declaration that writes both is visible where both hold.
+ */
+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,2FAA2F;AAmB3F,wGAAwG;AACxG,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,2FAA2F;AAC3F,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;;;GAGG;AACH,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,43 @@
+/** The state: what the agent remembers, read as a plain object, diffed, restored and collapsed. */
+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, no framework keys. `Snapshot<T>`
+ * is that object for the class T, so `when: (s) => !s.identified` type-checks; bare `Snapshot` is
+ * the erased one the framework itself passes around.
+ */
+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;
+}
+/** Everything the agent remembers right now, copied out so a reader cannot write through it. */
+export declare function snapshot(agent: object): Snapshot;
+/** What changed between two snapshots, in the order the later one lists its fields. */
+export declare function diff(before: Snapshot, after: Snapshot): FieldDiff[];
+/**
+ * Put the agent back to a snapshot. This is a write like any other, so it needs an author: the
+ * caller's, when one is running, and `restore` when nothing is.
+ */
+export declare function restore(agent: object, state: Snapshot): void;
+/** A collapsed history: one sentence standing in for every change that came before it. */
+export interface Collapsed {
+    summary: string;
+    seq: number;
+    at: number;
+}
+/**
+ * Drop the change log and keep one sentence in its place. The state itself is untouched — what
+ * collapses is the memory of how it got here, which is what a long call runs out of room for.
+ */
+export declare function collapse(agent: object, summary: string): Collapsed;
+/** What the agent last knew about this contact, when a store is wired in. */
+export type LastCall = (contact: string) => Promise<Snapshot | null>;
+/** The change log, re-exported here because the log and the state are read 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,mGAAmG;AAEnG,OAAO,EAAS,aAAa,EAAE,OAAO,EAA8B,MAAM,YAAY,CAAC;AAMvF,KAAK,UAAU,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAKjD,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;;;;GAIG;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;AAiCD,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAYhD;AAED,uFAAuF;AACvF,wBAAgB,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,SAAS,EAAE,CASnE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAkB5D;AAED,0FAA0F;AAC1F,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAalE;AAED,6EAA6E;AAC7E,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;AAErE,wFAAwF;AACxF,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/agent/state.js

@@ -0,0 +1,104 @@
+/** The state: what the agent remembers, read as a plain object, diffed, restored and collapsed. */
+import { Agent, CONFIG_FIELDS, changes, internalsOf, isConfigField } from "./agent.js";
+import { currentAuthor, withAuthor } from "./authors.js";
+import { declaredStateOf } from "./visibility.js";
+// The state is whatever the app put on the instance: own, enumerable, not a method, not one of the
+// config names — and, when the class decorated any field with `@state`, one of the fields it named.
+// A class that decorated none declares nothing twice, as it always did.
+function isStateField(key, value, declared) {
+    if (isConfigField(key) || typeof value === "function")
+        return false;
+    return declared === null || declared.has(key);
+}
+/** The fields this instance's class said are its state, or null when it said nothing. */
+function stateOf(agent) {
+    return declaredStateOf(internalsOf(agent).target.constructor);
+}
+// A getter is state too — `get identified() { return !!this.patient }` is exactly what a `when`
+// asks about — so the snapshot reads the prototype chain as well as the instance, stopping at
+// Agent so the framework's own accessors never leak into the tenant's state.
+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;
+}
+/** Everything the agent remembers right now, copied out so a reader cannot write through it. */
+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;
+    }
+    // Read the getters through the agent itself: they are written against `this`, not against target.
+    for (const name of gettersOf(agent))
+        state[name] = readable[name];
+    return state;
+}
+/** What changed between two snapshots, in the order the later one lists its fields. */
+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;
+}
+/**
+ * Put the agent back to a snapshot. This is a write like any other, so it needs an author: the
+ * caller's, when one is running, and `restore` when nothing is.
+ */
+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));
+        // A whole state goes in, so a field the snapshot leaves out is emptied — but only if it is
+        // state at all: a scratch field is nobody's business here.
+        for (const key of fields) {
+            if (isStateField(key, target[key], declared) && !(key in state))
+                writable[key] = undefined;
+        }
+        // Getters are derived, so a snapshot restores the fields they are derived from and no more.
+        for (const [key, value] of Object.entries(state)) {
+            if (fields.has(key) || !derived.has(key))
+                writable[key] = value;
+        }
+    });
+}
+/**
+ * Drop the change log and keep one sentence in its place. The state itself is untouched — what
+ * collapses is the memory of how it got here, which is what a long call runs out of room for.
+ */
+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;
+}
+/** The change log, re-exported here because the log and the state are read together. */
+export { changes };
+//# sourceMappingURL=state.js.map

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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"}