@pinecall/agents 0.9.20

package/dist/agent/agent.js

@@ -0,0 +1,240 @@
+/** The Agent base class: its fields are the state, and every assignment is a change with an author. */
+// Circular with tools.ts; safe because both sides only call across at runtime (hoisted functions).
+import { currentAuthor, UnauthoredWrite } from "./authors.js";
+import { docOf, toolsOf, visibleToolsOf } from "./tools.js";
+import { declaredStateOf } from "./visibility.js";
+import { collapse, restore, snapshot } from "./state.js";
+// Fields that configure the agent instead of holding state: never diffed, never snapshotted.
+// Every other setting (voice, models, language, opening, memory) belongs to the world and is
+// refused at load.
+export const CONFIG_FIELDS = ["phone", "whatsapp", "web", "channelRules"];
+// state.ts derives `ConfigName` from CONFIG_FIELDS, so a name added here is dropped from snapshots.
+const CONFIG = new Set(CONFIG_FIELDS);
+const internals = new WeakMap();
+/**
+ * Base class for every agent. The constructor returns a Proxy, so `this.patient = row` records
+ * a change with its author and sequence number.
+ */
+export class Agent {
+    constructor() {
+        // null: no `@state` decorators, so every own field is state.
+        const stateFields = declaredStateOf(this.constructor);
+        const own = {
+            changes: [],
+            log: [],
+            logListeners: new Set(),
+            listeners: new Set(),
+            eventListeners: new Set(),
+            seq: 0,
+            sealed: false,
+            target: this,
+            call: null,
+            last: null,
+            recalled: [],
+        };
+        const proxy = new Proxy(this, {
+            set(target, key, next, receiver) {
+                // Config fields and undeclared fields (when the class uses `@state`) are not recorded.
+                if (typeof key !== "string" || CONFIG.has(key) || (stateFields !== null && !stateFields.has(key))) {
+                    return Reflect.set(target, key, next, target);
+                }
+                const prev = Reflect.get(target, key, target);
+                const ok = Reflect.set(target, key, next, target);
+                if (!ok || !own.sealed)
+                    return ok;
+                const author = currentAuthor();
+                // Field initializers run before seal(), so an unauthored write here is a live bug.
+                if (author === null)
+                    throw new UnauthoredWrite(key);
+                if (Object.is(prev, next))
+                    return true;
+                const change = { seq: ++own.seq, field: key, prev, next, author, at: Date.now() };
+                own.changes.push(change);
+                for (const listener of own.listeners)
+                    listener(change);
+                return true;
+            },
+        });
+        internals.set(this, own);
+        internals.set(proxy, own);
+        return proxy;
+    }
+    /** The class description, as an alternative to a JSDoc comment. */
+    static doc;
+    /**
+     * Knowledge bases attached to this agent (`pinecall docs attach`), searched from a tool:
+     * `await this.knowledge.search("horarios", { k: 3 })`. The gateway runs and logs the search.
+     */
+    get knowledge() {
+        // Async so that a missing call rejects the promise instead of throwing.
+        return { search: async (query, options) => await this.call.search(query, options) };
+    }
+    /** External events this class accepts, and from whom. */
+    static events;
+    /** Field visibility as a map, as an alternative to `@state`. */
+    static visibility;
+    /** The class docstring, as the model reads it. */
+    doc() {
+        return docOf(this);
+    }
+    /**
+     * The per-turn part of the prompt, rendered from the current state. It is the dynamic block and
+     * the last thing the model reads. Renders nothing by default.
+     */
+    render() {
+        return null;
+    }
+    /**
+     * Whether memory recalled a fact for this call containing `text` (the fact or its key word).
+     * Returns false until the runtime has recalled anything.
+     */
+    remembers(text) {
+        const wanted = text.trim().toLowerCase();
+        if (wanted === "")
+            return false;
+        return internalsOf(this).recalled.some((known) => known.includes(wanted));
+    }
+    /** Every tool this agent declares, whether or not the current state shows it. */
+    tools() {
+        return toolsOf(this).map((declared) => declared.spec);
+    }
+    /** The tools a model may call right now: the ones whose `when(state)` holds. */
+    visibleTools() {
+        return visibleToolsOf(this).map((declared) => declared.spec);
+    }
+    /** Replace the change log with a one-sentence summary; the state is kept. */
+    collapse(summary) {
+        collapse(this, summary);
+    }
+    /** Restore the whole state from a snapshot, e.g. in `onCall` for a returning caller. */
+    restore(state) {
+        restore(this, state);
+    }
+    /**
+     * Overwrite only the fields `state` names, keeping the rest. Unlike `restore`, which replaces the
+     * whole state and clears fields the snapshot omits.
+     */
+    startIn(state) {
+        restore(this, { ...snapshot(this), ...state });
+    }
+    /** The snapshot this contact's last call left. Requires `mount(Class, { pc, last })`. */
+    last(contact) {
+        const source = internalsOf(this).last;
+        if (source === null) {
+            return Promise.reject(new Error("last(contact) needs a store: mount the agent with { last } to give it one"));
+        }
+        return source(contact);
+    }
+    /** Append a named entry to the call's log. */
+    log(name, data) {
+        const own = internalsOf(this);
+        const entry = { seq: ++own.seq, name, at: Date.now() };
+        if (data !== undefined)
+            entry.data = data;
+        own.log.push(entry);
+        for (const listener of own.logListeners)
+            listener(entry);
+    }
+    /**
+     * The call being served. A getter, not a field, so it never enters a snapshot; a subclass field
+     * named `call` is refused at its first write. Throws when no call is being served.
+     */
+    get call() {
+        const serving = internalsOf(this).call;
+        if (serving === null) {
+            throw new Error("this.call is only there while a call is being served: the bridge sets it at start(), " +
+                "and a test that renders gives one with setCall(agent, new CallWorld(line, () => {}))");
+        }
+        return serving;
+    }
+    /** Speak `text` verbatim now. Resolves true once the turn is delivered. */
+    say(text, options = {}) {
+        return this.call.say(text, options);
+    }
+    /** Make the model speak now, guided by instructions the caller does not hear. Resolves like `say`. */
+    reply(instructions, options = {}) {
+        return this.call.reply(instructions, options);
+    }
+    on(type, listener) {
+        if (type === "state")
+            return onChange(this, listener);
+        const own = internalsOf(this);
+        own.eventListeners.add(listener);
+        return () => own.eventListeners.delete(listener);
+    }
+    /** Called when a declared external event arrives. State writes here are authored by the event. */
+    onEvent(_name, _data, _meta) {
+        return undefined;
+    }
+    /** Called when a call starts. State writes here are authored by the hook. */
+    onCall(_call) {
+        return undefined;
+    }
+    /** Called when the call ends. */
+    onEnd(_call) {
+        return undefined;
+    }
+    /** Called when memory is written; override to persist the ops. */
+    onMemory(_ops, _call) {
+        return undefined;
+    }
+}
+/** The framework's bookkeeping for an agent; throws if `agent` is not one. */
+export function internalsOf(agent) {
+    const own = internals.get(agent);
+    if (!own)
+        throw new TypeError("not a Pinecall agent: its constructor never ran through Agent");
+    return own;
+}
+/** Start recording changes. Assignments before this (field initializers) are the baseline. */
+export function seal(agent) {
+    internalsOf(agent).sealed = true;
+    return agent;
+}
+/** Every change this agent has recorded, oldest first. */
+export function changes(agent) {
+    return internalsOf(agent).changes;
+}
+/** Listen to field assignments. Returns an unsubscribe function. */
+export function onChange(agent, listener) {
+    const own = internalsOf(agent);
+    own.listeners.add(listener);
+    return () => own.listeners.delete(listener);
+}
+/** Everything this agent logged, oldest first. */
+export function logOf(agent) {
+    return internalsOf(agent).log;
+}
+/** Listen to log entries. Returns an unsubscribe function. */
+export function onLog(agent, listener) {
+    const own = internalsOf(agent);
+    own.logListeners.add(listener);
+    return () => own.logListeners.delete(listener);
+}
+/** Whether a name is one of CONFIG_FIELDS rather than a piece of state. */
+export function isConfigField(name) {
+    return CONFIG.has(name);
+}
+/** Set the store `last(contact)` reads. Called by the bridge at start(). */
+export function setLast(agent, source) {
+    internalsOf(agent).last = source;
+}
+/** Set the call being served. Called by the bridge at start(). */
+export function setCall(agent, call) {
+    internalsOf(agent).call = call;
+}
+/** Record recalled facts and their key words, from the call's `memory.ops` entries. */
+export function recalled(agent, words) {
+    const own = internalsOf(agent);
+    for (const word of words) {
+        const known = word.trim().toLowerCase();
+        if (known !== "" && !own.recalled.includes(known))
+            own.recalled.push(known);
+    }
+}
+/** Notify in-process observers of an event after its hook ran. */
+export function emitEvent(agent, heard) {
+    for (const listener of internalsOf(agent).eventListeners)
+        listener(heard);
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent/agent.js.map

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

package/dist/agent/authors.d.ts

@@ -0,0 +1,12 @@
+/** The author attached to each state write, tracked per async context. */
+/** The current writer's name, or null outside any tool or hook. */
+export declare function currentAuthor(): string | null;
+/** Run `body` with every state write inside it attributed to `author`. */
+export declare function withAuthor<T>(name: string, body: () => T): T;
+/** Async variant of `withAuthor`: the author holds across awaits inside `body`. */
+export declare function withAuthorAsync<T>(name: string, body: () => Promise<T> | T): Promise<T>;
+/** Thrown when state is assigned outside a tool or lifecycle hook. */
+export declare class UnauthoredWrite extends Error {
+    constructor(field: string);
+}
+//# sourceMappingURL=authors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authors.d.ts","sourceRoot":"","sources":["../../src/agent/authors.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAQ1E,mEAAmE;AACnE,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAE7C;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5D;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEvF;AAED,sEAAsE;AAEtE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,KAAK,EAAE,MAAM,EAMxB;CACF"}

package/dist/agent/authors.js

@@ -0,0 +1,26 @@
+/** The author attached to each state write, tracked per async context. */
+import { AsyncLocalStorage } from "node:async_hooks";
+// AsyncLocalStorage, not a shared stack: concurrent tools (and calls) interleave across awaits,
+// and each write must be attributed to its own tool.
+const author = new AsyncLocalStorage();
+/** The current writer's name, or null outside any tool or hook. */
+export function currentAuthor() {
+    return author.getStore() ?? null;
+}
+/** Run `body` with every state write inside it attributed to `author`. */
+export function withAuthor(name, body) {
+    return author.run(name, body);
+}
+/** Async variant of `withAuthor`: the author holds across awaits inside `body`. */
+export function withAuthorAsync(name, body) {
+    return author.run(name, async () => await body());
+}
+/** Thrown when state is assigned outside a tool or lifecycle hook. */
+export class UnauthoredWrite extends Error {
+    constructor(field) {
+        super(`state field ${field} was assigned outside a tool and outside a lifecycle hook; ` +
+            `tools are the only writers of state`);
+        this.name = "UnauthoredWrite";
+    }
+}
+//# sourceMappingURL=authors.js.map

package/dist/agent/authors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authors.js","sourceRoot":"","sources":["../../src/agent/authors.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,gGAAgG;AAChG,qDAAqD;AACrD,MAAM,MAAM,GAAG,IAAI,iBAAiB,EAAU,CAAC;AAE/C,mEAAmE;AACnE,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC,QAAQ,EAAE,IAAI,IAAI,CAAC;AACnC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,UAAU,CAAI,IAAY,EAAE,IAAa;IACvD,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,eAAe,CAAI,IAAY,EAAE,IAA0B;IACzE,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,sEAAsE;AAEtE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,KAAa;QACvB,KAAK,CACH,eAAe,KAAK,6DAA6D;YAC/E,qCAAqC,CACxC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}

package/dist/agent/decorators.d.ts

@@ -0,0 +1,16 @@
+/** The `@tool({...})` method decorator and the `@render(Prompt)` class decorator. */
+import { type ToolOptions } from "./tools.js";
+import type { Child } from "../views/jsx-runtime.js";
+/**
+ * Declare a method as a tool. Its JSDoc is the description and its signature the schema;
+ * `when(state)` controls visibility (`stage` is shorthand for one). State writes are authored by it.
+ */
+export declare function tool<T extends object>(options?: ToolOptions<T>): (prototype: T, name: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/** A prompt component whose props are the agent instance itself. */
+export type Prompt<T> = (agent: T) => Child;
+/**
+ * Use `prompt` as the class's `render()`: `@render(SupportPrompt)` equals
+ * `render() { return SupportPrompt(this); }`. The instance is passed whole (a spread would drop getters).
+ */
+export declare function render<T extends object>(prompt: Prompt<T>): (ctor: new (...args: never[]) => T) => void;
+//# sourceMappingURL=decorators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/agent/decorators.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAIrF,OAAO,EAAgC,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAErD;;;GAGG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,GAAE,WAAW,CAAC,CAAC,CAAM,eAEpD,CAAC,QACN,MAAM,cACA,kBAAkB,KAC7B,kBAAkB,CAYtB;AAED,oEAAoE;AACpE,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,KAAK,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,UACzB,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAG,IAAI,CAiBlE"}

package/dist/agent/decorators.js

@@ -0,0 +1,43 @@
+/** The `@tool({...})` method decorator and the `@render(Prompt)` class decorator. */
+import { withAuthorAsync } from "./authors.js";
+import { lowerStage } from "./stages.js";
+import { DeclarationRefused, register } from "./tools.js";
+/**
+ * Declare a method as a tool. Its JSDoc is the description and its signature the schema;
+ * `when(state)` controls visibility (`stage` is shorthand for one). State writes are authored by it.
+ */
+export function tool(options = {}) {
+    return function decorate(prototype, name, descriptor) {
+        const method = descriptor.value;
+        if (typeof method !== "function") {
+            throw new TypeError(`@tool goes on a method; ${name} is not one`);
+        }
+        // Attribute every state write during the call, including after awaits, to this tool.
+        descriptor.value = function running(...args) {
+            return withAuthorAsync(name, () => method.apply(this, args));
+        };
+        register(prototype, { name, options: lowerStage(options), method });
+        return descriptor;
+    };
+}
+/**
+ * Use `prompt` as the class's `render()`: `@render(SupportPrompt)` equals
+ * `render() { return SupportPrompt(this); }`. The instance is passed whole (a spread would drop getters).
+ */
+export function render(prompt) {
+    return function decorate(ctor) {
+        // Refuse both spellings on one class: one of them would be silently dead.
+        if (Object.getOwnPropertyDescriptor(ctor.prototype, "render") !== undefined) {
+            throw new DeclarationRefused(`${ctor.name} declares both @render(${prompt.name || "a prompt"}) and a render() method; ` +
+                `two ways to answer one question — keep one`);
+        }
+        Object.defineProperty(ctor.prototype, "render", {
+            value: function render() {
+                return prompt(this);
+            },
+            writable: true,
+            configurable: true,
+        });
+    };
+}
+//# sourceMappingURL=decorators.js.map

package/dist/agent/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../src/agent/decorators.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAoB,MAAM,YAAY,CAAC;AAG5E;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAmB,OAAO,GAAmB,EAAE;IACjE,OAAO,SAAS,QAAQ,CACtB,SAAY,EACZ,IAAY,EACZ,UAA8B;QAE9B,MAAM,MAAM,GAAG,UAAU,CAAC,KAAwC,CAAC;QACnE,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CAAC,2BAA2B,IAAI,aAAa,CAAC,CAAC;QACpE,CAAC;QACD,qFAAqF;QACrF,UAAU,CAAC,KAAK,GAAG,SAAS,OAAO,CAAe,GAAG,IAAe;YAClE,OAAO,eAAe,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAY,CAAC,CAAC;QAC1E,CAAC,CAAC;QACF,QAAQ,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QACpE,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAKD;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAmB,MAAiB;IACxD,OAAO,SAAS,QAAQ,CAAC,IAAiC;QACxD,0EAA0E;QAE1E,IAAI,MAAM,CAAC,wBAAwB,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,KAAK,SAAS,EAAE,CAAC;YAC5E,MAAM,IAAI,kBAAkB,CAC1B,GAAG,IAAI,CAAC,IAAI,0BAA0B,MAAM,CAAC,IAAI,IAAI,UAAU,2BAA2B;gBACxF,4CAA4C,CAC/C,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE;YAC9C,KAAK,EAAE,SAAS,MAAM;gBACpB,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;YACtB,CAAC;YACD,QAAQ,EAAE,IAAI;YACd,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/agent/docstrings.d.ts

@@ -0,0 +1,35 @@
+/** Read a class's JSDoc and parameter types from its source at runtime, with oxc's parser. */
+/** One parameter of a tool method, as the source declares it. */
+export interface ParamDoc {
+    name: string;
+    type?: string;
+    optional: boolean;
+    /** JSON Schema for an interface or type literal; unset when `type` alone suffices (`string`, `number[]`). */
+    schema?: Record<string, unknown>;
+}
+/** A class's docstring and its methods' docstrings and parameters. */
+export interface ClassDocs {
+    doc?: string;
+    methods: Map<string, {
+        doc?: string;
+        params: ParamDoc[];
+    }>;
+}
+/**
+ * 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 declare function parseClassSource(text: string, file?: string): ClassDocs;
+/** Counter bumped by each describe(); used to invalidate caches. */
+export declare function docsVersion(): number;
+/** Register a class's source so its docstrings and parameter types are available at runtime. */
+export declare function describe(ctor: Function, source: string, file?: string): ClassDocs;
+/** The class's docs, from describe() if called, else parsed from `ctor.toString()`. */
+export declare function docsOf(ctor: Function): ClassDocs;
+/** The class docstring, read from its source or from an explicit `static doc`. */
+export declare function classDoc(ctor: Function): string | undefined;
+/** The docstring of one method, looked up along the prototype chain. */
+export declare function methodDoc(ctor: Function, name: string): string | undefined;
+/** The parameters of one method, looked up along the prototype chain. */
+export declare function methodParams(ctor: Function, name: string): ParamDoc[];
+//# sourceMappingURL=docstrings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docstrings.d.ts","sourceRoot":"","sources":["../../src/agent/docstrings.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAoB9F,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,6GAA6G;IAC7G,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC,CAAC;CAC5D;AAsMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAc,GAAG,SAAS,CAyB5E;AAKD,oEAAoE;AACpE,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAKjF;AAED,uFAAuF;AACvF,wBAAgB,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAShD;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAE3D;AAaD,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM1E;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CAMrE"}