@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/computer/read.js

@@ -1,203 +0,0 @@
-import { isGitInternal } from "./paths.js";
-/**
- * Reading the workspace without pulling more of it across the boundary than the
- * model will be shown.
- *
- * The obvious version of each function here reads everything and throws most of
- * it away, which is the wrong shape against a Durable Object's 128 MB. So the
- * budget is applied at the source, and the offsets handed back are the *source's*
- * rather than the rendered subset's — which is what makes the next page exact
- * instead of a guess.
- */
-/**
- * Read a file without pulling more of it across the boundary than the model will
- * be shown.
- *
- * `readFile(path, "utf8")` materialises the whole file in the isolate before
- * `truncateOutput` throws most of it away. Harmless on a source file, and the
- * wrong shape against a Durable Object's 128 MB — `sb_read` is one model decision
- * away from a lockfile, a bundle or a captured build log. The read is
- * range-addressable, so the budget is enforced at the source.
- *
- * Two reads rather than one, because the budget is spent from both ends for the
- * reason {@link truncateOutput} documents — the first error is at the top of a
- * file and the summary is at the bottom.
- *
- * ## The one place the budget is spent in bytes
- *
- * `maxChars` is a character ceiling everywhere else — see
- * {@link ComputerConfig.maxOutputChars} — and here it is spent against
- * `byteOffset`/`byteLength`, which are the only units the transport has. That is
- * deliberate and it is safe in the direction that matters: a UTF-8 byte is never
- * more than one UTF-16 code unit, so *N* bytes decode to at most *N* characters.
- * Reading the character budget as bytes therefore always honours the ceiling,
- * and errs low on a file that is mostly non-ASCII — a CJK source file is cut at
- * about a third of the characters it could have shown. The alternative is a
- * second round trip to measure what the first one returned, on every read, to
- * recover a bound the marker already announces.
- *
- * The other reason it cannot be characters is the one this function exists for:
- * bounding the *transport*. A byte range is what stops a 4 MB lockfile being
- * materialised in a 128 MB isolate before anything is thrown away.
- *
- * ## Why `stat` first
- *
- * Sizing off the returned string instead would be wrong in a way that hides
- * itself. `byteLength` counts bytes and `String.length` counts UTF-16 code units,
- * so a file of two-byte characters comes back *under* a character budget while
- * still being over the byte budget — and the read would look complete with half
- * the file missing and no marker saying so. One extra round trip buys the
- * distinction.
- *
- * A slice boundary can land mid-codepoint, which the decoder resolves to a single
- * replacement character. That is one glyph of noise at a cut that already
- * announces itself as a cut.
- */
-export async function readBounded(fs, path, maxChars) {
-    const { size } = await fs.stat(path);
-    if (size <= maxChars)
-        return fs.readFile(path, "utf8");
-    // Names the way out, rather than only the size of the hole. Before `offset`
-    // existed the honest answer was "use sb_exec with sed", which needs a live
-    // container — the dependency these tools exist to remove.
-    const marker = (dropped, at) => `\n\n… [${dropped} bytes omitted from the middle — read them with ` +
-        `\`offset: ${at}\`] …\n\n`;
-    const half = Math.floor((maxChars - marker(size, size).length) / 2);
-    // No budget for two ends plus the marker: keep the head, where the first error
-    // is. The same fallback `truncateOutput` makes at the same ceiling.
-    if (half < 1)
-        return fs.readFile(path, {
-            encoding: "utf8",
-            byteLength: Math.max(0, maxChars)
-        });
-    const [head, tail] = await Promise.all([
-        fs.readFile(path, { encoding: "utf8", byteOffset: 0, byteLength: half }),
-        fs.readFile(path, {
-            encoding: "utf8",
-            byteOffset: size - half,
-            byteLength: half
-        })
-    ]);
-    return head + marker(size - half * 2, half) + tail;
-}
-/**
- * A byte window the model asked for, with its coordinates stated.
- *
- * No middle-out here, deliberately: {@link readBounded} guesses at what matters when
- * nobody said, but an explicit `offset` *is* the model saying. Trimming the middle
- * of a region it chose would defeat the request and, worse, make the next offset
- * unknowable.
- *
- * The window line is what makes paging work at all — the model needs to know where
- * it landed and how much is left to compute the next `offset`.
- */
-export async function readWindow(fs, path, offset, length, maxChars) {
-    const { size } = await fs.stat(path);
-    if (offset >= size)
-        return `(offset ${offset} is past the end of ${path}, which is ${size} bytes)`;
-    const byteLength = Math.min(length, maxChars, size - offset);
-    const body = await fs.readFile(path, {
-        encoding: "utf8",
-        byteOffset: offset,
-        byteLength
-    });
-    const end = offset + byteLength;
-    const rest = end < size ? `; ${size - end} bytes after this` : "";
-    return `${body}\n--- bytes ${offset}–${end} of ${size}${rest} ---`;
-}
-/**
- * Fetch a page, drop what is off-limits, and keep the source offsets that make the
- * *next* page exact.
- *
- * The subtle part is why `rawIndex` exists at all. `offset` counts items at the
- * source; the caller renders a filtered, budget-trimmed subset of them. So the
- * obvious `nextOffset = offset + shown` is wrong — it silently skips or repeats
- * whenever anything was dropped, which is precisely when `.git` is involved. Keeping
- * each survivor's source index means the next page starts exactly after the last one
- * the model actually saw.
- *
- * Retries because `.git` can outnumber a whole page on its own: at a repo root it is
- * walked *first* (`.` sorts before alphanumerics) and holds thousands of objects, so
- * one fetch can come back entirely excluded. `maxRounds` is the caller's, and the
- * asymmetry is deliberate — a `find` retry re-walks dirents, which is cheap SQLite
- * reads, while a `grep` retry re-reads and re-scans every file it already looked at.
- *
- * Deliberately no slicing to `want`: the caller needs the extra item to know a next
- * page exists, and its index to say where.
- */
-export async function collectVisible(fetch, pathOf, want, offset, maxRounds) {
-    const items = [];
-    const rawIndex = [];
-    let cursor = offset;
-    let exhausted = false;
-    let rounds = 0;
-    // One past `want`, so a next page is detected without a further round trip.
-    while (items.length <= want && rounds < maxRounds) {
-        rounds += 1;
-        const batch = await fetch(cursor, want + 1);
-        batch.forEach((item, i) => {
-            if (isGitInternal(pathOf(item)))
-                return;
-            items.push(item);
-            rawIndex.push(cursor + i);
-        });
-        cursor += batch.length;
-        if (batch.length <= want) {
-            exhausted = true;
-            break;
-        }
-    }
-    return {
-        items,
-        rawIndex,
-        rawEnd: cursor,
-        exhausted,
-        crowded: !exhausted && items.length <= want
-    };
-}
-/**
- * The "there is more, here is where" line, with an offset that is actually correct.
- *
- * `rawIndex[shown]` rather than `offset + shown`: the first item the model did *not*
- * see, at its source coordinate. Anything else drifts by however many entries the
- * `.git` filter removed, and drifts silently — the next page would repeat or skip
- * with nothing to indicate it had.
- *
- * Narrowing is still offered, and still first-class, because it is cheaper than
- * paging: `offset` does not skip the walk, it only discards its early results. It is
- * offered as the better option rather than the only one, which is the thing the
- * previous wording got wrong — "narrow it" is no answer at all when the model wants
- * the next page of a list it is working through.
- */
-export function listingNote(page, shown, noun, narrower) {
-    const next = shown < page.rawIndex.length
-        ? page.rawIndex[shown]
-        : page.exhausted
-            ? undefined
-            : page.rawEnd;
-    if (next === undefined)
-        return "";
-    return (`\n\n… showed ${shown} ${noun}; there are more. Continue with ` +
-        `\`offset: ${next}\`, or narrow with ${narrower} — narrowing is cheaper, ` +
-        `since an offset still walks everything it skips.`);
-}
-/**
- * Does this path exist?
- *
- * `getWorkspace()` types `fs` as the in-process `WorkspaceFilesystem`, but the
- * value on the far side of a Durable Object boundary is a
- * `WorkspaceFilesystemStub`, which carries a few methods the local class does
- * not — `exists` among them. So the fast path is asked for rather than cast to,
- * and `stat` is the fallback for a host that hands back a local workspace.
- *
- * The fallback treats *any* `stat` failure as absence, which is the honest
- * reading for a tool whose entire answer is a boolean: there is no error channel
- * to distinguish "missing" from "unreadable", and the caller's next move — look
- * somewhere else — is the same either way.
- */
-export async function pathExists(fs, path) {
-    const probe = fs.exists;
-    if (typeof probe === "function")
-        return probe.call(fs, path);
-    return fs.stat(path).then(() => true, () => false);
-}

package/dist/recall/index.d.ts

@@ -1,99 +0,0 @@
-import type { SessionMessage } from "agents/experimental/memory/session";
-import type { AgentPlugin } from "@dynamicagents/core";
-/**
- * The subset of the Vectorize binding recall drives — structurally satisfied by
- * `Vectorize`/`VectorizeIndex`, so nothing here names the binding type and a
- * test can pass a plain object.
- */
-export interface RecallIndex {
-    query(vector: number[], options?: VectorizeQueryOptions): Promise<VectorizeMatches>;
-    upsert(vectors: VectorizeVector[]): Promise<unknown>;
-}
-/** Embed a batch of texts. Output dimension must match the Vectorize index. */
-export type Embed = (texts: string[]) => Promise<number[][]>;
-/** A single archived message returned by a recall search. */
-export interface RecallResult {
-    score: number;
-    role: string;
-    /** The stored message snippet (truncated to `metadataTextMax`). */
-    text: string;
-    /** Display name of the human speaker, when the message carried a `<turn>` wrapper. */
-    author?: string;
-    /** Speaker's platform user id, when present. */
-    authorId?: string;
-    /** Channel the turn came from, when present. */
-    channel?: string;
-    /** ISO-8601 instant of the turn, when present. */
-    at?: string;
-}
-/**
- * Build the Vectorize vectors for a batch of archived messages. Pure:
- * `embeddings` are supplied 1:1 with `messages` (both already filtered to
- * non-empty text). The vector `id` is the message's own id, so re-archiving on a
- * compaction retry is an idempotent upsert; `<turn>` provenance is lifted into
- * metadata when present.
- */
-export declare function toRecallVectors(messages: SessionMessage[], namespace: string, embeddings: number[][], metadataTextMax?: number): VectorizeVector[];
-/**
- * Archive a range of displaced messages into Vectorize. Embeds the non-empty
- * texts in one batch and upserts them under `namespace`. No-op on empty input.
- */
-export declare function archiveMessages(index: RecallIndex, namespace: string, messages: SessionMessage[], embed: Embed, metadataTextMax?: number): Promise<void>;
-/**
- * Semantically search this instance's archive. Embeds the query and returns the
- * top matches within `namespace`, mapping each vector's metadata to a compact
- * {@link RecallResult}. Constrained to `namespace` — never a caller-supplied one.
- */
-export declare function recallSearch(index: RecallIndex, namespace: string, query: string, embed: Embed, topK?: number): Promise<RecallResult[]>;
-/**
- * The tuning half of {@link RecallConfig}: plain values, no bindings.
- *
- * Split out so a host can declare its settings in one place and spread them,
- * rather than re-typing each field at the call site:
- *
- * ```ts
- * // config.ts — the values, typed
- * export const RECALL: RecallTuning = { embeddingModelId: "@cf/baai/bge-m3", topK: 5 };
- *
- * // plugins.ts — the bindings, and the values spread
- * recall({ ai: host.env.AI, index: host.env.VECTORIZE,
- *          namespace: host.callerKey, aiGatewayId: host.aiGatewayId, ...RECALL })
- * ```
- *
- * Field-by-field re-typing is not just verbose — it silently drops any option
- * added later, so a new default lands everywhere except the deployments that
- * enumerated the old set.
- */
-export interface RecallTuning {
-    /**
-     * AI Gateway id. Pass the host's **resolved** value (`PluginHost.aiGatewayId`),
-     * so embedding calls stay correlated with chat calls in one gateway. Reading it
-     * off a config-overrides object instead yields `undefined` the moment that
-     * override is dropped in favour of core's default.
-     */
-    aiGatewayId?: string;
-    /** Workers-AI embedding model. Must match the index's dimension. */
-    embeddingModelId?: string;
-    /** Matches returned by a search. Defaults to 5. */
-    topK?: number;
-    /** Stored-snippet cap, guarding Vectorize's ~10 KiB/vector. Defaults to 2000. */
-    metadataTextMax?: number;
-}
-export interface RecallConfig extends RecallTuning {
-    /** The `AI` binding, for embeddings. Read lazily — see below. */
-    ai: Ai;
-    /** The `VECTORIZE` binding. Must be a 1024-dim, cosine index. */
-    index: RecallIndex;
-    /**
-     * The archive namespace for this agent instance — **a thunk, deliberately.**
-     *
-     * It derives from the verified caller's identity, which is not known when
-     * `plugins(host)` runs in `onStart`. The Durable Object is keyed 1:1 by that
-     * caller, so the value is constant once known; a thunk is what lets the host
-     * supply it late while both hooks here read the same one.
-     */
-    namespace: () => string;
-    /** Test override; skips the provider entirely. */
-    embed?: Embed;
-}
-export declare function recall(config: RecallConfig): AgentPlugin;

package/dist/recall/index.js

@@ -1,171 +0,0 @@
-import { embedMany, tool } from "ai";
-import { z } from "zod";
-import { createWorkersAI } from "workers-ai-provider";
-import { definePlugin } from "@dynamicagents/core";
-import { parseTurn, sessionText } from "@dynamicagents/core/agent";
-/**
- * `@dynamicagents/plugins/recall` — episodic memory over Cloudflare Vectorize.
- *
- * When the Session compacts, the raw messages it folds into a summary would
- * otherwise be lost. Core announces that moment (`onMessagesDisplaced`) because
- * core is what performs the lossy operation; this plugin is what does something
- * about it — embedding the displaced range and upserting it, so a `recall` tool
- * can later semantically search history that has scrolled out of the live
- * context window.
- *
- * Core carries **no embedding code at all**: no `Embed` type, no
- * `embeddingModelId`, no recall config. It used to, without a single caller, and
- * that had fixed the shape of embedding for every future plugin — one model, one
- * dimension, `string[] → number[][]` — while `ModelConfig` could only say "the
- * agent has an embedding model" when the true statement is "*this plugin* uses
- * this embedding model". So the whole embedding path lives here.
- *
- * The namespace is always bound in code from the caller's verified identity,
- * never model input, so one caller can never read another's archive.
- */
-/** Workers-AI embedding model. 1024-dim/cosine, matching the Vectorize index. */
-const DEFAULT_EMBEDDING_MODEL_ID = "@cf/baai/bge-m3";
-/** Matches to return from a search. */
-const DEFAULT_TOP_K = 5;
-/**
- * Stored-snippet cap. Vectorize allows roughly 10 KiB of metadata per vector,
- * and the snippet is nearly all of it — a message longer than this is truncated
- * rather than costing the whole upsert.
- */
-const DEFAULT_METADATA_TEXT_MAX = 2000;
-/**
- * Build the Vectorize vectors for a batch of archived messages. Pure:
- * `embeddings` are supplied 1:1 with `messages` (both already filtered to
- * non-empty text). The vector `id` is the message's own id, so re-archiving on a
- * compaction retry is an idempotent upsert; `<turn>` provenance is lifted into
- * metadata when present.
- */
-export function toRecallVectors(messages, namespace, embeddings, metadataTextMax = DEFAULT_METADATA_TEXT_MAX) {
-    return messages.map((m, i) => {
-        const text = sessionText(m);
-        const metadata = {
-            role: m.role,
-            text: text.slice(0, metadataTextMax)
-        };
-        const turn = parseTurn(text);
-        if (turn) {
-            metadata.author = turn.from;
-            metadata.authorId = turn.id;
-            metadata.channel = turn.channel;
-            metadata.at = turn.at;
-        }
-        return { id: m.id, namespace, values: embeddings[i], metadata };
-    });
-}
-/**
- * Archive a range of displaced messages into Vectorize. Embeds the non-empty
- * texts in one batch and upserts them under `namespace`. No-op on empty input.
- */
-export async function archiveMessages(index, namespace, messages, embed, metadataTextMax = DEFAULT_METADATA_TEXT_MAX) {
-    const withText = messages.filter((m) => sessionText(m).trim().length > 0);
-    if (withText.length === 0)
-        return;
-    const embeddings = await embed(withText.map((m) => sessionText(m)));
-    await index.upsert(toRecallVectors(withText, namespace, embeddings, metadataTextMax));
-}
-/**
- * Semantically search this instance's archive. Embeds the query and returns the
- * top matches within `namespace`, mapping each vector's metadata to a compact
- * {@link RecallResult}. Constrained to `namespace` — never a caller-supplied one.
- */
-export async function recallSearch(index, namespace, query, embed, topK = DEFAULT_TOP_K) {
-    const [vector] = await embed([query]);
-    if (!vector)
-        return [];
-    const { matches } = await index.query(vector, {
-        namespace,
-        topK,
-        returnMetadata: "all"
-    });
-    return matches.map((match) => {
-        const md = (match.metadata ?? {});
-        const result = {
-            score: match.score,
-            role: md.role ?? "unknown",
-            text: md.text ?? ""
-        };
-        if (md.author)
-            result.author = md.author;
-        if (md.authorId)
-            result.authorId = md.authorId;
-        if (md.channel)
-            result.channel = md.channel;
-        if (md.at)
-            result.at = md.at;
-        return result;
-    });
-}
-export function recall(config) {
-    const { ai, index, namespace, aiGatewayId, embeddingModelId = DEFAULT_EMBEDDING_MODEL_ID, topK = DEFAULT_TOP_K, metadataTextMax = DEFAULT_METADATA_TEXT_MAX } = config;
-    /**
-     * Built on first use, never at module scope. Cloudflare evaluates module scope
-     * during `wrangler deploy` to validate the new version, and bindings are not
-     * populated at that point — constructing eagerly makes `createWorkersAI` throw
-     * "you must provide either a binding or credentials".
-     */
-    let provider;
-    const embed = config.embed ??
-        (async (texts) => {
-            if (texts.length === 0)
-                return [];
-            provider ??= createWorkersAI({
-                binding: ai,
-                ...(aiGatewayId ? { gateway: { id: aiGatewayId } } : {})
-            });
-            const { embeddings } = await embedMany({
-                model: provider.embedding(embeddingModelId),
-                values: texts
-            });
-            return embeddings;
-        });
-    return definePlugin({
-        key: "recall",
-        /**
-         * Offered only once this caller's history has actually been compacted.
-         *
-         * Before the first compaction the archive is empty by construction, and a
-         * tool whose only possible answer is "nothing here yet" costs the model a
-         * call to discover that — plus the tokens to describe it, every round.
-         */
-        mainAgentTools: async (ctx) => {
-            if ((await ctx.session.getCompactions()).length === 0)
-                return {};
-            return {
-                recall: tool({
-                    description: "Search your own older conversation history with this caller that has scrolled out of the live context window (it was summarized during compaction). Use this to recall specific past details — quotes, decisions, facts — that you no longer have verbatim. Returns the most semantically similar archived messages with their author/channel/timestamp when known.",
-                    inputSchema: z.object({
-                        query: z
-                            .string()
-                            .describe("What to look for in the archived history"),
-                        limit: z
-                            .number()
-                            .int()
-                            .min(1)
-                            .max(20)
-                            .optional()
-                            .describe(`Max number of matches to return (default ${topK})`)
-                    }),
-                    // The index, the namespace and the embedder all come from the closure.
-                    // The model can only ever supply a query string and a count.
-                    execute: async ({ query, limit }) => ({
-                        results: await recallSearch(index, namespace(), query, embed, limit ?? topK)
-                    })
-                })
-            };
-        },
-        capability: "You can search your own older history with this caller — everything that has scrolled out of your live context window and been summarized. Use `recall` when you need a specific past detail verbatim (a quote, a decision, a number) rather than the gist you already have in your summary. It searches by meaning, so describe what you are looking for rather than guessing exact words.",
-        /**
-         * Compaction is about to fold these into a summary; embed and store them
-         * first. Failures are the runtime's to swallow — it fans out with
-         * `allSettled` and never lets a listener abort compaction, because history
-         * must still shorten when a side store is briefly unavailable.
-         */
-        onMessagesDisplaced: (messages) => archiveMessages(index, namespace(), messages, embed, metadataTextMax),
-        requires: { bindings: ["VECTORIZE"] }
-    });
-}