@adonis-agora/agent 0.31.0 → 0.33.1

package/dist/src/mcp-client/unsafe-regex.js.map

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

package/dist/src/memory.d.ts

@@ -0,0 +1,448 @@
+/**
+ * Memory: what the assistant has concluded about a person or an organisation, carried across turns
+ * and across threads.
+ *
+ * HOW A READER TELLS IT FROM RAG. Retrieval answers "what do the documents say"; memory answers
+ * "what did I decide about you". A passage is content a person authored and can correct at its
+ * source, and it is cited. A memory has no source to go and fix: it is the agent's own inference,
+ * which is why every record carries an {@link MemoryOrigin} (who wrote it, in which conversation),
+ * why the block tells the model to treat it as fallible, and why `forget` is a REQUIRED method on
+ * the provider rather than an optional one. A wrong document is a content problem. A wrong memory is
+ * the assistant being confidently wrong about someone with nobody aware it is there, so the whole
+ * design is arranged around making it visible and removable.
+ *
+ * WHAT IT COSTS THE PROMPT. One line per memory, capped by `maxMemories`, and each line capped by
+ * `maxFactChars` at WRITE time — so the block a turn can carry is the product of two numbers an
+ * operator sets, rather than however much the model felt like writing down. Unlike a skill, a memory
+ * has no body/catalog split: a fact that cannot be stated in a line is not a memory, it is a
+ * document, and documents are retrieval's job.
+ *
+ * WHAT IT IS NOT: recall over a TRANSCRIPT. Searching what was said earlier is retrieval, and this
+ * library already has `Retriever`/`Reranker` for that.
+ *
+ * RECALL OVER THE MEMORIES THEMSELVES IS A DIFFERENT QUESTION, and it is answered here. The prompt
+ * budget must be bounded; the store has no reason to be. A person accumulates preferences over
+ * months and an organisation publishes facts for everyone in it, so the applicable set outgrows
+ * `maxMemories` quickly — and once it does, WHICH of them the block carries is a decision somebody
+ * has to make. Making it by scope starves the widest scopes first, which is precisely backwards: the
+ * facts that apply to the most people are the ones nobody sees. So a provider MAY supply
+ * {@link MemoryProvider.search}, and where it does, the block is filled by relevance to the turn
+ * (see {@link resolveMemoryDigest}) with scope still a hard filter and never a ranking signal.
+ * `maxMemories` then means "how many matter right now" rather than "how many a person may have".
+ */
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { type ScopeContext, type ScopeResolver } from './skills.js';
+import type { Actor, ToolDefinition } from './types.js';
+/** Who wrote a memory, and out of what. Kept so a person reading it back can ask "says who?". */
+export interface MemoryOrigin {
+    /** `'agent'` — a turn concluded it. `'human'` — a person wrote it in the host's own console. */
+    author: 'agent' | 'human';
+    /**
+     * The conversation the conclusion was drawn in. MAY name a thread whose messages the history
+     * ceiling has since dropped: a memory deliberately outlives its source, so this is a pointer that
+     * is allowed to dangle, and a read-back that cannot resolve it says so rather than hiding the row.
+     */
+    threadId?: string;
+    runId?: string;
+    actorRef?: string;
+}
+/** One thing the assistant believes, at one scope. */
+export interface MemoryRecord {
+    /** The host's row id — what `forget` takes and what a read-back offers a delete button for. */
+    id: string;
+    /**
+     * What the fact is ABOUT. The handle that makes a conflict mechanically detectable: two memories
+     * sharing a key at different scopes are one question answered twice, and the narrower wins. A
+     * keyless store could only ever hope its facts did not contradict each other.
+     */
+    key: string;
+    /** The fact itself, as the model reads it. */
+    text: string;
+    /** The opaque scope token it is held at — see `ScopeResolver` in `skills.ts`. */
+    scope: string;
+    origin: MemoryOrigin;
+    /** ISO-8601, so the ceiling can keep the newest with a string comparison it can do purely. */
+    updatedAt: string;
+    /**
+     * Always-on: this fact is in the block whether or not the turn is about it. The difference between
+     * working memory and recall, drawn per record — "they report on the calendar year" must not depend
+     * on the turn mentioning dates, while "they prefer the shorter runway" can wait until it comes up.
+     *
+     * A PROPERTY OF THE ROW, NOT OF A WRITE. This library reads it and never sets it, the same way it
+     * never mints an `id`: an agent deciding its own conclusions are always-on is an agent deciding
+     * how much of every future prompt it gets, so pinning is an operator's act in the host's console.
+     * That is also why {@link StoreMemoryInput} carries no `pinned` — the `remember` tool has no
+     * parameter to refuse. A host whose upsert drops the flag has silently unpinned the row; preserve
+     * it across an upsert on (`scope`, `key`).
+     */
+    pinned?: boolean;
+}
+/** A same-key memory a narrower scope outranked, with the value it holds. */
+export interface OverriddenMemory {
+    scope: string;
+    text: string;
+    /**
+     * Who asserted the beaten value. Travels because precedence is blind to it: an agent's own
+     * inference at `actor:` outranks an administrator's published policy at `global`, and an agent
+     * that knew only that a wider value existed could not tell the two apart — one is a stale guess,
+     * the other is what the organisation decided.
+     */
+    author: MemoryOrigin['author'];
+}
+/** One memory as the model and a read-back both meet it. */
+export interface MemoryDigestEntry extends MemoryRecord {
+    /**
+     * Same-key memories this one outranks, widest last. Present ONLY where something was outranked.
+     *
+     * Carries the beaten TEXT, which is where memory departs from a skill's `shadows`. A skill only
+     * has to say which scope it beat — the agent follows one procedure either way. A memory is a
+     * VALUE, and an agent that knows only that a wider value existed cannot tell the user what the
+     * difference is; it can only choose, silently, which is the thing this is meant to prevent.
+     */
+    overrides?: OverriddenMemory[];
+}
+/** What a turn resolved — journaled whole, so its prompt is reconstructible from its journal alone. */
+export interface MemoryDigest {
+    /** The scope tokens this turn drew from, most specific first. */
+    scopes: string[];
+    /** The memories in the block, most specific first then by key. */
+    entries: MemoryDigestEntry[];
+    /**
+     * Applicable memories `maxMemories` left out. Non-zero means the block is not the whole truth —
+     * and under {@link recalled} it counts what the SEARCH offered and the ceiling dropped, not what
+     * the store holds, because nothing asked the store for a total.
+     */
+    omitted: number;
+    /**
+     * Of {@link omitted}, how many were ALWAYS-ON. Reported separately because it means something else
+     * entirely: ordinary omission is the budget doing its job, while an always-on memory the ceiling
+     * dropped is a deployment's own standing policies having silently stopped reaching any prompt.
+     * Non-zero is a misconfiguration — more was pinned than the block holds — and the fix is to unpin
+     * something or raise `maxMemories`, not to wait for it to come back.
+     */
+    pinnedOmitted: number;
+    /**
+     * Whether the entries were selected by relevance to this turn rather than read whole. The model is
+     * told (see {@link buildMemoryBlock}), because a partial set read as a whole one turns an absence
+     * into evidence: "you never told me that" about a fact it simply was not shown.
+     *
+     * Optional so a digest journaled before recall existed reads back as the plain scoped read it was.
+     */
+    recalled?: boolean;
+}
+/** What a write asks the host to store. `id` and `updatedAt` are the host's to mint. */
+export interface MemoryFact {
+    key: string;
+    text: string;
+    scope: string;
+    origin: MemoryOrigin;
+}
+/** Arguments to {@link MemoryProvider.list}. */
+export interface ListMemoriesInput {
+    /** The scope tokens that apply to this turn, most specific first. */
+    scopes: readonly string[];
+    ctx: ScopeContext;
+}
+/**
+ * Arguments to {@link MemoryProvider.search}.
+ *
+ * `scopes` GATES, AND IT GATES FIRST. A search that ranks before it filters is a cross-tenant leak
+ * wearing a relevance score: the nearest neighbour to "what is our rollback policy" is another
+ * base's rollback policy. Filter in the query, not after it. Records returned outside `scopes` are
+ * dropped rather than trusted, so a mistake here costs throughput rather than privacy — but the
+ * drop is a backstop, not the boundary.
+ */
+export interface SearchMemoriesInput {
+    /** The scope tokens that apply to this turn, most specific first. A HARD FILTER. */
+    scopes: readonly string[];
+    /** What this turn is about. Never blank — a blank query is served by `list` instead. */
+    query: string;
+    /**
+     * At most this many distinct KEYS may be ranked in, which is the block's own unit: precedence
+     * resolves a key to one line, so `limit` keys is `limit` lines. Pinned records are returned in
+     * addition and do not count against it.
+     */
+    limit: number;
+    ctx: ScopeContext;
+}
+/** Arguments to {@link MemoryProvider.forget}. */
+export interface ForgetMemoryInput {
+    id: string;
+    ctx: ScopeContext;
+}
+/**
+ * Arguments to {@link MemoryProvider.write}. An object rather than positional arguments because
+ * `key`, `text` and `scope` are all strings: transposed, a positional call compiles clean and writes
+ * a fact whose key is its value, at a scope nobody meant.
+ */
+export interface StoreMemoryInput extends MemoryFact {
+    ctx: ScopeContext;
+}
+/**
+ * Where memories live. The host owns the rows, for the same reason it owns skill rows: the axes a
+ * deployment scopes by, the console that edits them and the audit trail are all the host's, and a
+ * table this package created at boot would put a consumer's migrations in the path of the schema
+ * heal that manages the `agent_*` tables.
+ *
+ * `forget` is REQUIRED, unlike `write`. A deployment may reasonably populate memory from its own
+ * pipeline and offer the agent no write tool; no deployment may reasonably hold conclusions about a
+ * person that the person cannot have deleted. Making it optional would make forgetting a wiring
+ * choice, and it is not one.
+ */
+export interface MemoryProvider {
+    /**
+     * Every memory visible at `scopes`, in any order — this library resolves precedence and the
+     * ceiling. Asked on EVERY turn, so keep it cheap. A provider MAY return records outside `scopes`;
+     * they are dropped rather than trusted, so a filter bug in a host cannot widen what an actor sees.
+     */
+    list(input: ListMemoriesInput): MemoryRecord[] | Promise<MemoryRecord[]>;
+    /** Delete one record by id. `false` where there was nothing by that id to delete. */
+    forget(input: ForgetMemoryInput): boolean | Promise<boolean>;
+    /**
+     * Upsert on (`scope`, `key`) and return the stored record. Omit to serve memory read-only — the
+     * `remember` tool is then never offered, and a turn's tool list is the same on every pod.
+     */
+    write?(input: StoreMemoryInput): MemoryRecord | Promise<MemoryRecord>;
+    /**
+     * The memories worth putting in front of a turn about `query`, MOST RELEVANT FIRST. Omit and every
+     * turn is served by {@link list} — a deployment with twenty memories must not have to stand up an
+     * index to keep working, and one with two thousand uses whatever it already runs (pgvector, a
+     * full-text index, a hybrid service). The host owns the index for the same reason it owns the
+     * rows.
+     *
+     * THREE CLAUSES, and the third is the one that is easy to miss:
+     *
+     * 1. Filter to `scopes` before ranking — see {@link SearchMemoriesInput}.
+     * 2. Rank the KEYS visible at those scopes and take the best `limit` of them.
+     * 3. Return EVERY record sharing a returned key, plus every `pinned` record at those scopes.
+     *
+     * Clause three is what keeps precedence intact. Precedence resolves a conflict between two records
+     * at one key, narrower winning and the beaten value riding along; a search that returned the
+     * `global` half of a conflict and not the `actor:` half would render the org default as the answer
+     * — the exact failure memory exists to prevent, and one nothing downstream can detect. It is one
+     * query either way:
+     *
+     * ```sql
+     * SELECT * FROM agent_memory
+     *  WHERE scope IN (:scopes)
+     *    AND (pinned OR key IN (SELECT key FROM agent_memory
+     *                            WHERE scope IN (:scopes)
+     *                         ORDER BY embedding <=> :queryVector
+     *                            LIMIT :limit))
+     * ```
+     */
+    search?(input: SearchMemoriesInput): MemoryRecord[] | Promise<MemoryRecord[]>;
+}
+/**
+ * How many memories the block carries. The same ceiling shape as `maxSkills`, and for the same
+ * reason: a prompt that grows with how much the agent has written down is a prompt whose cost nobody
+ * set. A budget on the PROMPT and never on the store — with a provider that can
+ * {@link MemoryProvider.search}, it is how many matter right now rather than how many a person may
+ * have.
+ */
+export declare const DEFAULT_MAX_MEMORIES = 20;
+/**
+ * How long one memory may be, enforced when it is WRITTEN rather than when it is rendered. Enforcing
+ * it at render time would make the prompt disagree with the store; enforcing it at write time makes
+ * the block's whole ceiling a multiplication an operator can do — `maxMemories × maxFactChars` — and
+ * pushes back on the model at the moment it is writing an essay instead of a fact.
+ */
+export declare const DEFAULT_MAX_FACT_CHARS = 240;
+/** How a turn reaches its memory. See `AgentLoopDeps.memory`. */
+export interface MemoryConfig {
+    provider: MemoryProvider;
+    /** Undefined → `defaultScopeResolver`: the actor's own, their tenant's, the deployment's. */
+    scopes?: ScopeResolver;
+    /** Undefined → {@link DEFAULT_MAX_MEMORIES}. Always-on memories are taken from it first. */
+    maxMemories?: number;
+    /** Undefined → {@link DEFAULT_MAX_FACT_CHARS}. */
+    maxFactChars?: number;
+}
+/**
+ * Resolve a provider's records against an ordered scope list: most specific wins a key, and the
+ * losers' values are carried rather than discarded.
+ *
+ * Pure, and separately exported, because the loop and the read-back endpoint must reach the same
+ * answer — a person has to be shown what the model was shown, or "see what it believes about you"
+ * means nothing.
+ */
+/** Arguments to {@link resolveMemoryDigest}. */
+export interface ResolveMemoryDigestInput {
+    records: readonly MemoryRecord[];
+    /** The scope tokens that apply, most specific first — the precedence order. */
+    scopes: readonly string[];
+    /** Undefined → {@link DEFAULT_MAX_MEMORIES}. */
+    maxMemories?: number;
+    /**
+     * Whether `records` arrived most-relevant-first, from {@link MemoryProvider.search}. A key's rank
+     * is its best-placed record's. Undefined/false → the ceiling selects by scope and recency, which
+     * is the right order only while nothing is being starved.
+     */
+    ranked?: boolean;
+}
+export declare function resolveMemoryDigest({ records, scopes, maxMemories, ranked, }: ResolveMemoryDigestInput): Omit<MemoryDigest, 'scopes' | 'recalled'>;
+/** Arguments to {@link offerMemories}. */
+export interface OfferMemoriesInput {
+    config: MemoryConfig;
+    ctx: ScopeContext;
+    /**
+     * What this turn is about — the loop passes the user's own message, and nothing else. Given, and
+     * with a provider that has an index, the block is filled by relevance to it. Absent, the scope is
+     * read whole: that is what the read-back endpoint wants, since a person must be shown every belief
+     * held about them rather than the slice one turn happened to need.
+     */
+    query?: string;
+}
+/**
+ * Resolve the scopes and the digest for one turn. Called INSIDE the loop's `memory:digest` step, and
+ * that placement is the whole of its determinism: a search is the most re-derivable thing in this
+ * library — the index moves, a neighbour is written, embeddings are recomputed — so its result has
+ * to be part of the checkpoint every replay reads back, never something a replaying process asks
+ * again.
+ */
+export declare function offerMemories({ config, ctx, query, }: OfferMemoriesInput): Promise<MemoryDigest>;
+/**
+ * The block as the model reads it.
+ *
+ * THREE THINGS IT HAS TO DO THAT A SKILLS CATALOG DOES NOT.
+ *
+ * It must frame each note by WHO ASSERTED IT, which is why there are two sections rather than one
+ * sentence over the whole list. An unlabelled fact in a system prompt reads with the authority of an
+ * instruction, and the hazard of an agent's own inference is exactly that authority — so those are
+ * hedged. But a memory an administrator published for a whole organisation is not the agent's guess,
+ * and telling the model to "prefer what the user says now" about it hands any user an override of
+ * their organisation's policy by asserting the opposite. `MemoryOrigin.author` is the axis, and it
+ * is the only one that matters here: scope says who a fact applies to, not who decided it.
+ *
+ * Where a narrower scope won, it must print the value it beat, so the model can tell the user their
+ * setting differs from the org's instead of quietly applying one of them.
+ *
+ * And a block that is a SELECTION must say so. A model reading a partial set as a whole one turns an
+ * absence into evidence — "you never told me that" about a fact it simply was not shown.
+ */
+/** Arguments to {@link buildMemoryBlock}. */
+export interface BuildMemoryBlockInput {
+    entries: readonly MemoryDigestEntry[];
+    /** Whether this deployment offers `remember` — the block names the tool only where it exists. */
+    writable: boolean;
+    /** Whether applicable memories are missing from `entries` — the ceiling bit, or recall selected. */
+    partial: boolean;
+}
+export declare function buildMemoryBlock({ entries, writable, partial }: BuildMemoryBlockInput): string;
+/** The reserved name of the built-in memory-writing tool. */
+export declare const REMEMBER_TOOL_NAME = "remember";
+/** What the model passes to the `remember` tool. */
+export interface RememberToolInput {
+    key: string;
+    fact: string;
+}
+/**
+ * The `remember` tool's input schema. Hand-written for the same reason `askInputSchema` and
+ * `skillInputSchema` are: core depends on no validator and has to publish a JSON Schema a provider
+ * can constrain generation against.
+ *
+ * THERE IS NO SCOPE PARAMETER, and that is the enforcement rather than a simplification. An agent
+ * may only ever write the actor it is running for (see {@link memoryWriteVerdict}), so a scope
+ * argument could only ever be a request that gets refused — and a refusable request is one a model
+ * will keep making, and one a future reader will be tempted to make grantable.
+ */
+export declare const rememberInputSchema: StandardSchemaV1<unknown, RememberToolInput>;
+export declare const REMEMBER_TOOL_DESCRIPTION = "Record one durable fact about this user under a key, so later conversations start knowing it. For things that will still be true another day \u2014 how they work, what their organisation requires, a correction they made. Not for what this conversation is about, and not for anything you were not told or could not reasonably infer. The user can read and delete everything you record here.";
+/**
+ * The `remember` tool as the model sees it. NOT a `ToolSpec` and never registered, exactly like
+ * `ask` and `skill`: it has no handler, because the loop serves it against the digest the journal
+ * holds. Keeping it out of the `ToolRegistry` is also what keeps its kind off a process-local
+ * lookup — see `claimToolCall`.
+ */
+export declare function rememberToolDefinition(): ToolDefinition;
+/** Who is trying to write a memory. */
+export interface MemoryAuthor {
+    /**
+     * `'human'` is a person acting through a UI; `'agent'` is anything else — a turn, a tool, a batch
+     * job. The distinction is the whole of rule three below, so it is not inferable and has to be
+     * stated by the caller.
+     */
+    kind: 'human' | 'agent';
+    actorRef?: string;
+}
+/** A request to write a memory at a scope. */
+export interface MemoryWriteRequest {
+    scope: string;
+    actor: Actor;
+    /** The actor's resolved scopes, most specific first — the same list the turn drew its digest from. */
+    scopes: readonly string[];
+    author: MemoryAuthor;
+    /**
+     * The host's own answer to "may this person administer that scope". This library cannot know it,
+     * and inventing an answer would be a second, weaker authorization model next to the host's real
+     * one. Undefined/false → a wider scope is refused.
+     */
+    elevated?: boolean;
+}
+export type MemoryVerdict = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/**
+ * May this author write a memory at this scope?
+ *
+ * The same four rules as `skillWriteVerdict`, deliberately duplicated rather than shared: they are
+ * the same rules about two different things, and folding them into one function would mean a future
+ * change to how skills are authored silently changing who may edit what the assistant believes about
+ * a person. Rule three is the one that matters, and it bites harder here than it does for skills:
+ *
+ * 1. You may only write into a scope you are yourself in.
+ * 2. Your OWN scope is yours. A memory at `actor:<you>` affects exactly one prompt — your own.
+ * 3. NOTHING BUT A HUMAN MAY WRITE ABOVE ITS OWN SCOPE, whatever `elevated` says. A skill an agent
+ *    could publish at `tenant:` is a procedure anyone in the tenant can edit by talking to the
+ *    assistant; a MEMORY it could publish there is a fact everyone in the tenant is then answered
+ *    from, with no document to inspect and nobody aware it was written. An agent that has genuinely
+ *    learned something the organisation should know proposes it; a person publishes it.
+ * 4. A human writing above their own scope needs the host to say so (`elevated`).
+ */
+export declare function memoryWriteVerdict(request: MemoryWriteRequest): MemoryVerdict;
+/**
+ * May this actor delete this memory?
+ *
+ * Narrower than the write rule on purpose, and it takes no `elevated` flag. Deleting what the
+ * assistant believes about YOU needs no permission from anyone — that is the point of the read-back
+ * — so the endpoint that serves it must not be able to ask a host a question it might answer no to.
+ * Deleting what it believes about a tenant is an administrative act on shared state, which belongs
+ * in the host's console with the same elevation a write there needs.
+ */
+/** A request to delete one memory. */
+export interface MemoryForgetRequest {
+    record: Pick<MemoryRecord, 'scope'>;
+    actor: Actor;
+}
+export declare function memoryForgetVerdict({ record, actor }: MemoryForgetRequest): MemoryVerdict;
+/** What a `remember` call resolved to — the stored record, or why nothing was stored. */
+export type MemoryWriteOutcome = {
+    ok: true;
+    record: MemoryRecord;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Serve one `remember` call against the digest THIS TURN resolved.
+ *
+ * The digest's `scopes` are the authorization boundary, not the resolver: they came out of the
+ * `memory:digest` checkpoint, so a write is checked against the scopes the run recorded rather than
+ * the ones a replaying process's resolver would produce now. A membership table edited mid-run
+ * cannot retroactively widen — or narrow — what a turn already in flight is allowed to write.
+ */
+/** Arguments to {@link writeMemory}. */
+export interface WriteMemoryInput {
+    config: MemoryConfig;
+    /** The digest THIS TURN journaled — the authorization boundary, never a fresh resolution. */
+    digest: MemoryDigest;
+    /** The `remember` call as the model made it. */
+    call: RememberToolInput;
+    ctx: ScopeContext;
+    runId: string;
+}
+export declare function writeMemory({ config, digest, call, ctx, runId, }: WriteMemoryInput): Promise<MemoryWriteOutcome>;
+//# sourceMappingURL=memory.d.ts.map

package/dist/src/memory.d.ts.map

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