pinecall 0.1.0

package/dist/agent/agent.js

@@ -0,0 +1,262 @@
+/** The Agent base class: its fields are the state, and every assignment is a change with an author. */
+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";
+// The names an app uses to configure the agent rather than to remember something about the
+// caller. They live on the instance like any other field, but they are never state: they do not
+// change during a call, they are not diffed, and no snapshot carries them.
+export const CONFIG_FIELDS = [
+    "phone",
+    "whatsapp",
+    "web",
+    "voice",
+    "greeting",
+    "says",
+    "hears",
+    "llm",
+    "language",
+    "knowledge",
+    "docs",
+    "memory",
+    "hangup",
+];
+// The list is the array; the Set is how this module asks about it on every assignment. state.ts
+// derives `ConfigName` from the same array, so a name added here is a name the snapshot drops.
+const CONFIG = new Set(CONFIG_FIELDS);
+const internals = new WeakMap();
+/**
+ * The base every app agent extends. The constructor hands back a Proxy, so a plain
+ * `this.patient = row` inside a tool is the whole state API: one change, one author, one seq.
+ */
+export class Agent {
+    constructor() {
+        // Which fields this class said are its state, read once: every `@state` of a class has run by
+        // the time one of it exists. null means it decorated none, and then 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 is not state, and neither is a field a class that declares its state left out:
+                // that one is the tenant's own scratch space and nothing here records it, sends it or
+                // asks it for an author.
+                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();
+                // The declaration is written before the agent is sealed, so only a live write can be
+                // unauthored — and a live unauthored write is never an accident worth keeping.
+                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 docstring, when the app prefers to say it out loud instead of in a JSDoc. */
+    static doc;
+    /** The outside facts this class accepts, and from whom: `static events = {...}`. */
+    static events;
+    /** Who may see a field, for a class that would rather write a map than a `@state`. */
+    static visibility;
+    /** What this agent is, as the model reads it: the class's own docstring. */
+    doc() {
+        return docOf(this);
+    }
+    /**
+     * The prompt as a function of the state: what to do about THIS turn, in the class's own words.
+     * It is the whole dynamic region and the last thing the model reads. The base renders nothing,
+     * so a class that says nothing about the turn sends an empty block.
+     */
+    render() {
+        return null;
+    }
+    /**
+     * Whether memory has already told this call something about the caller under those words — the
+     * word a fact was filed under, or the fact itself. The runtime supplies the facts; before it has
+     * recalled anything this answers false, which is exactly what a caller nobody has met looks like.
+     */
+    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);
+    }
+    /** Drop the change log and keep one sentence in its place; the state itself stays. */
+    collapse(summary) {
+        collapse(this, summary);
+    }
+    /** Put the agent back to a snapshot — the move `onCall` makes when a caller comes back. */
+    restore(state) {
+        restore(this, state);
+    }
+    /**
+     * Start the agent in the state a case describes: the fields it names, written over the ones the
+     * agent already has — on a fresh instance, the ones the class gave itself. A goldens case names
+     * what it is about and nothing else, so `restore` is the wrong door for it: a snapshot is a
+     * WHOLE state, and restoring one clears every field it leaves out.
+     */
+    startIn(state) {
+        restore(this, { ...snapshot(this), ...state });
+    }
+    /** What this contact left behind last time. Wired per mount: `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);
+    }
+    /** Put a named fact in the call's log, for the console and for whatever reads it after. */
+    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 right now. It is a getter on the base class, not a field, so it never
+     * looks like state and never reaches a snapshot; a class that declares its own `call` field is
+     * refused at the first write, because there is only one thing that name can mean here.
+     */
+    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;
+    }
+    /** Say this, word for word, now. Resolves true when the turn it lands as arrived. */
+    say(text, options = {}) {
+        return this.call.say(text, options);
+    }
+    /** Make the model speak now, guided by words the caller never hears. 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);
+    }
+    /** An outside fact the class declared arrived. Override it; writes here are authored by it. */
+    onEvent(_name, _data, _meta) {
+        return undefined;
+    }
+    /** A call started. Override it; assigning state here is authored by the hook, not by nobody. */
+    onCall(_call) {
+        return undefined;
+    }
+    /** The call ended. Override it to write anything the call is worth writing. */
+    onEnd(_call) {
+        return undefined;
+    }
+    /** Memory was written. Override it to send the ops wherever the tenant keeps them. */
+    onMemory(_ops, _call) {
+        return undefined;
+    }
+}
+/** The framework's bookkeeping for one agent, or a clear error if this is not an agent. */
+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;
+}
+/**
+ * Close the declaration and start recording. Everything assigned before this — the field
+ * initializers that give the state its shape — is the baseline, not a change.
+ */
+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;
+}
+/** Hear every field assignment as it happens; the returned function stops listening. */
+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;
+}
+/** Hear every logged fact as it happens; the returned function stops listening. */
+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);
+}
+/** Hand this instance the store its `last(contact)` reads. The bridge does this at start(). */
+export function setLast(agent, source) {
+    internalsOf(agent).last = source;
+}
+/** Hand this instance the call it is serving. The bridge does this once, at start(). */
+export function setCall(agent, call) {
+    internalsOf(agent).call = call;
+}
+/**
+ * Hand this instance what memory has recalled about the caller: every fact, and the word it was
+ * filed under. The bridge does this from the call's own `memory.ops` entries, so `remembers(text)`
+ * answers with what the runtime actually found and never with a guess.
+ */
+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);
+    }
+}
+/** Tell the in-process observers about an event the hook has just been given. */
+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 @@
+/** Who is writing the state right now: the author every change carries, and the write that has none. */
+/** The name of whoever is writing state right now, or null when nobody claimed the write. */
+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;
+/** Like withAuthor, for a tool or a hook that returns a promise: the awaits inside keep the name. */
+export declare function withAuthorAsync<T>(name: string, body: () => Promise<T> | T): Promise<T>;
+/** A field assigned with no tool and no hook running: the framework refuses it by design. */
+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,wGAAwG;AAUxG,6FAA6F;AAC7F,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,qGAAqG;AACrG,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,6FAA6F;AAC7F,qBAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,KAAK,EAAE,MAAM,EAMxB;CACF"}

package/dist/agent/authors.js

@@ -0,0 +1,28 @@
+/** Who is writing the state right now: the author every change carries, and the write that has none. */
+import { AsyncLocalStorage } from "node:async_hooks";
+// Who is writing right now, carried by the async context and not by a module-level stack: one
+// process runs many calls at once, and a tool that awaits its agenda while another tool runs would
+// otherwise read the other tool's name off the top of a shared stack. AsyncLocalStorage follows
+// each tool's own chain of awaits, so a write inside it is authored by it and by nothing else.
+const author = new AsyncLocalStorage();
+/** The name of whoever is writing state right now, or null when nobody claimed the write. */
+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);
+}
+/** Like withAuthor, for a tool or a hook that returns a promise: the awaits inside keep the name. */
+export function withAuthorAsync(name, body) {
+    return author.run(name, async () => await body());
+}
+/** A field assigned with no tool and no hook running: the framework refuses it by design. */
+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,wGAAwG;AAExG,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,8FAA8F;AAC9F,mGAAmG;AACnG,gGAAgG;AAChG,+FAA+F;AAC/F,MAAM,MAAM,GAAG,IAAI,iBAAiB,EAAU,CAAC;AAE/C,6FAA6F;AAC7F,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,qGAAqG;AACrG,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,6FAA6F;AAC7F,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,22 @@
+/** The two decorators a class wears: `@tool({...})` on a method, and `@render(Prompt)` on the class. */
+import { type ToolOptions } from "./tools.js";
+import type { Child } from "../views/jsx-runtime.js";
+/**
+ * Declare a method as a tool. The docstring above it is the prompt; the signature is the schema;
+ * `when(state)` is the only visibility there is, and `stage` is lowered to one here, at
+ * declaration time. Every write the method makes is authored by it.
+ */
+export declare function tool<T extends object>(options?: ToolOptions<T>): (prototype: T, name: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * The prompt as a function of the agent: the props ARE the instance, so a prompt written for
+ * `Support` destructures `{ stage, customer }` and stays typed with no generic machinery.
+ */
+export type Prompt<T> = (agent: T) => Child;
+/**
+ * The class's prompt, as a function beside it instead of a `render()` method — the spelling a
+ * prompt that has grown deserves. `@render(SupportPrompt)` is exactly
+ * `render() { return SupportPrompt(this); }`, byte for byte, and the instance is handed over
+ * whole: a spread would leave the getters and `remembers()` behind.
+ */
+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,wGAAwG;AAIxG,OAAO,EAAgC,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,GAAE,WAAW,CAAC,CAAC,CAAM,eAEpD,CAAC,QACN,MAAM,cACA,kBAAkB,KAC7B,kBAAkB,CAatB;AAED;;;GAGG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,KAAK,CAAC;AAE5C;;;;;GAKG;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,CAkBlE"}

package/dist/agent/decorators.js

@@ -0,0 +1,49 @@
+/** The two decorators a class wears: `@tool({...})` on a method, and `@render(Prompt)` on the class. */
+import { withAuthorAsync } from "./authors.js";
+import { lowerStage } from "./stages.js";
+import { DeclarationRefused, register } from "./tools.js";
+/**
+ * Declare a method as a tool. The docstring above it is the prompt; the signature is the schema;
+ * `when(state)` is the only visibility there is, and `stage` is lowered to one here, at
+ * declaration time. Every write the method makes is 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`);
+        }
+        // The wrapper is what makes `this.patient = row` inside the method carry an author: the tool's
+        // own name, for the whole time it runs, awaited included.
+        descriptor.value = function running(...args) {
+            return withAuthorAsync(name, () => method.apply(this, args));
+        };
+        register(prototype, { name, options: lowerStage(options), method });
+        return descriptor;
+    };
+}
+/**
+ * The class's prompt, as a function beside it instead of a `render()` method — the spelling a
+ * prompt that has grown deserves. `@render(SupportPrompt)` is exactly
+ * `render() { return SupportPrompt(this); }`, byte for byte, and the instance is handed over
+ * whole: a spread would leave the getters and `remembers()` behind.
+ */
+export function render(prompt) {
+    return function decorate(ctor) {
+        // The class's own `render()` is on its prototype by the time a class decorator runs, so this
+        // is the one moment both spellings are visible at once. Two ways to answer one question is
+        // the bug: whichever the reader trusts, the other one is dead and says something else.
+        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,wGAAwG;AAExG,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;;;;GAIG;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,+FAA+F;QAC/F,0DAA0D;QAC1D,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;AAQD;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAmB,MAAiB;IACxD,OAAO,SAAS,QAAQ,CAAC,IAAiC;QACxD,6FAA6F;QAC7F,2FAA2F;QAC3F,uFAAuF;QACvF,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,43 @@
+/** Docstrings at runtime: a class's own source, read by oxc's parser for its JSDoc and its parameters. */
+/** One parameter of a tool method, as the source declares it. */
+export interface ParamDoc {
+    name: string;
+    type?: string;
+    optional: boolean;
+    /**
+     * The JSON Schema only the file could give: an interface or a type literal expanded into its
+     * properties. Left unset when the type text says it all — `string`, `number[]`, a callback.
+     */
+    schema?: Record<string, unknown>;
+}
+/** What a class says about itself and its methods. */
+export interface ClassDocs {
+    doc?: string;
+    methods: Map<string, {
+        doc?: string;
+        params: ParamDoc[];
+    }>;
+}
+/**
+ * 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 declare function parseClassSource(text: string, file?: string): ClassDocs;
+/** How many times a class has been handed its own source; a cache invalidator, nothing more. */
+export declare function docsVersion(): number;
+/** Hand a class its own source, so its docstrings and parameter types are readable at runtime. */
+export declare function describe(ctor: Function, source: string, file?: string): ClassDocs;
+/** What this class documents about itself: what describe() was given, or its own body. */
+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,0GAA0G;AA8B1G,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,sDAAsD;AACtD,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;AA0MD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAc,GAAG,SAAS,CAyB5E;AAMD,gGAAgG;AAChG,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,kGAAkG;AAClG,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAKjF;AAED,0FAA0F;AAC1F,wBAAgB,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAShD;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAE3D;AAYD,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"}