@dynamicagents/plugins 0.12.0 → 0.13.0

package/dist/computer/read.js

@@ -1,200 +0,0 @@
-/**
- * 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, and the
- * only ones that bound what crosses it. 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 on every read, to recover a bound the
- * marker already announces.
- *
- * ## 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 a skipped directory is
- * involved. Keeping each survivor's source index means the next page starts exactly
- * after the last one the model actually saw.
- *
- * Retries because a skipped directory can outnumber a whole page on its own — a
- * dependency tree runs to tens of thousands of files — so one fetch can come back
- * entirely excluded. `maxRounds` is the caller's: a retry re-reads and re-scans
- * every file the last one looked at. For a walk the store can prune instead, see
- * `sb_ls`, which passes exclusions to `find` and needs none of this.
- *
- * 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, skip, 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 (skip(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
- * skip 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) {
-    // Called as a method, never through `.call`: on an RPC stub `.call` is read as
-    // a remote method, and the stub it would pass as `this` cannot be serialised.
-    const remote = fs;
-    if (typeof remote.exists === "function")
-        return remote.exists(path);
-    return fs.stat(path).then(() => true, () => false);
-}

package/dist/computer/tools-find.js

@@ -1,216 +0,0 @@
-import { tool } from "ai";
-import { z } from "zod";
-import { guardPath, isSkipped, skipNames, WALK_SKIPS } from "./paths.js";
-import { humanBytes, packBlocks, renderGrepMatches } from "./render.js";
-import { collectVisible, listingNote, pathExists } from "./read.js";
-/** Finding things: what is in a directory, what a file contains, what exists. */
-/**
- * How many directory entries one `sb_ls` returns.
- *
- * A bound on the *listing*, not on the rendered text — `maxOutputChars` still
- * applies on top, and the order matters. Bounding only the text means `readdir`
- * returns every entry and the isolate holds all of them before the ceiling
- * discards the tail; a dependency tree is 22,470 files, and a misbehaving build
- * is exactly when someone lists one. `readdir` takes a `limit`, so the bound is
- * applied where the entries are read.
- */
-const DEFAULT_MAX_ENTRIES = 1000;
-/**
- * How many matches one `sb_grep` returns.
- *
- * Bounded at the source like {@link DEFAULT_MAX_ENTRIES}, and for a sharper reason
- * than a listing: without a `limit`, `fs.grep` reads *every* file under the path
- * looking for more. `.git` and the dependency tree are both in the workspace, so
- * an unbounded search of `/workspace` streams every loose object and every
- * vendored file through the isolate before answering. The limit is what stops
- * that walk early, and the skip list is what keeps the matches worth reading.
- */
-const DEFAULT_MAX_MATCHES = 200;
-export function findTools(ctx) {
-    const { cwd, maxChars, inWorkspace } = ctx;
-    return {
-        sb_ls: tool({
-            description: "List files in a workspace directory, or find files by name. Without `pattern` it lists one level: directories with a trailing slash, files with their size — check that before reading a large one, since sb_read truncates. " +
-                "`pattern` is a glob matched against paths relative to `path`, and searches the whole subtree: `*` stays within one path segment, `**/` crosses directories, `?` matches one character. So `*.ts` finds top-level TypeScript files and `**/*.ts` finds them at any depth. " +
-                "A cut listing reports the `offset` that continues it. Subtree listings leave out `.git` and `node_modules`.",
-            inputSchema: z.object({
-                path: z.string().describe("Absolute directory path"),
-                recursive: z
-                    .boolean()
-                    .optional()
-                    .describe("List the whole subtree rather than one level"),
-                pattern: z
-                    .string()
-                    .optional()
-                    .describe("Glob relative to path, e.g. '**/*.spec.ts'. Searches the subtree, so `recursive` is not needed with it."),
-                offset: z
-                    .number()
-                    .int()
-                    .min(0)
-                    .optional()
-                    .describe("Entries to skip — use the offset a cut listing reports")
-            }),
-            execute: async ({ path, recursive, pattern, offset }) => {
-                const refusal = guardPath(path, "sb_ls");
-                if (refusal)
-                    return refusal;
-                const from = offset ?? 0;
-                return inWorkspace("listing", path, async (fs) => {
-                    if (recursive || pattern) {
-                        // `find` rather than `ls`, which took no bound: a prefix scan
-                        // returned every path in the subtree and the ceiling then threw most
-                        // of them away — the same read-everything-then-discard shape the
-                        // `readdir` limit below exists to avoid. Two differences follow from
-                        // the swap, both improvements: directories appear (rendered like the
-                        // arm below renders them), and order is the walk's — pre-order, by
-                        // name — rather than one flat sort.
-                        //
-                        // `.git` and `node_modules` are pruned by the store, not filtered
-                        // here: at a repo root either one outnumbers a page on its own.
-                        const entries = await fs.find(path, pattern, {
-                            limit: DEFAULT_MAX_ENTRIES + 1,
-                            offset: from,
-                            exclude: WALK_SKIPS.map((segment) => `**/${segment}`)
-                        });
-                        if (entries.length === 0)
-                            return pattern
-                                ? `(nothing under ${path} matches ${pattern})`
-                                : `(${path} is empty)`;
-                        const blocks = entries
-                            .slice(0, DEFAULT_MAX_ENTRIES)
-                            .map((e) => [e.type === "dir" ? `${e.path}/` : e.path]);
-                        const { body, shown } = packBlocks(blocks, maxChars);
-                        const page = {
-                            rawIndex: entries.map((_, i) => from + i),
-                            rawEnd: from + entries.length,
-                            exhausted: entries.length <= DEFAULT_MAX_ENTRIES,
-                            crowded: false
-                        };
-                        return body + listingNote(page, shown, "entries", "`pattern`");
-                    }
-                    // One over the ceiling: enough to know the listing was cut without a
-                    // second round trip to find out, and the extra entry is not shown.
-                    // Unfiltered on purpose — one line naming a directory that is really
-                    // there is honest, and costs a line rather than a page. It is the
-                    // *subtree* walk above that cannot afford to descend into them.
-                    const entries = await fs.readdir(path, {
-                        limit: DEFAULT_MAX_ENTRIES + 1,
-                        offset: from
-                    });
-                    if (entries.length === 0)
-                        return from > 0
-                            ? `(no entries in ${path} past offset ${from})`
-                            : `(${path} is empty)`;
-                    const blocks = entries
-                        .slice(0, DEFAULT_MAX_ENTRIES)
-                        .map((e) => [
-                        e.isDirectory ? `${e.name}/` : `${e.name}\t${humanBytes(e.size)}`
-                    ]);
-                    const { body, shown } = packBlocks(blocks, maxChars);
-                    const more = entries.length > shown;
-                    return (body +
-                        (more
-                            ? `\n… showed ${shown} entries; there are more. Continue with \`offset: ${from + shown}\`, or narrow with \`pattern\`.`
-                            : ""));
-                });
-            }
-        }),
-        /**
-         * Search, without the container.
-         *
-         * The tool this replaces is `sb_exec("grep -rn …")`, and the case for a native
-         * one is not that shelling out fails — it is where the search runs. `fs.grep`
-         * reads the Durable Object's SQLite, so it answers while the container is
-         * being replaced or an install is still running, which is exactly the window
-         * the install gate leaves a subagent with nothing to do. It is also why this
-         * tool is not gated: see {@link file://./context.ts awaitAdvisories}.
-         *
-         * Two lesser reasons that still matter. The query arrives as a value rather
-         * than through `shellQuote` and a shell that would re-parse it. And the result
-         * is bounded by a `limit` at the source instead of being middle-truncated
-         * afterwards, which for a match list means losing whole files silently.
-         */
-        sb_grep: tool({
-            description: "Search file contents across the workspace. Returns matching lines grouped by file, each with its line number. " +
-                "The query is matched literally — set `regex` to interpret it as a regular expression. " +
-                "Pass `include` to limit which files are searched, e.g. '**/*.ts' — without it every file under `path` is read, which is slower and rarely what you meant. " +
-                "A cut result reports the `offset` that continues it. Use `context` to see the lines around a match. " +
-                "Results from `.git` and `node_modules` are left out — search node_modules with sb_exec.",
-            inputSchema: z.object({
-                query: z.string().describe("Text to find, e.g. 'buildComputerTools'"),
-                path: z
-                    .string()
-                    .optional()
-                    .describe(`Absolute file or directory to search (default: ${cwd})`),
-                include: z
-                    .string()
-                    .optional()
-                    .describe("Glob relative to path limiting which files are searched, e.g. '**/*.ts'"),
-                regex: z
-                    .boolean()
-                    .optional()
-                    .describe("Interpret query as a regular expression"),
-                ignoreCase: z.boolean().optional().describe("Ignore letter case"),
-                context: z
-                    .number()
-                    .int()
-                    .min(0)
-                    .max(3)
-                    .optional()
-                    .describe("Lines of surrounding context to include with each match"),
-                offset: z
-                    .number()
-                    .int()
-                    .min(0)
-                    .optional()
-                    .describe("Matches to skip — use the offset a cut result reports")
-            }),
-            execute: async ({ query, path, include, regex, ignoreCase, context, offset }) => {
-                const target = path ?? cwd;
-                const refusal = guardPath(target, "sb_grep");
-                if (refusal)
-                    return refusal;
-                const from = offset ?? 0;
-                return inWorkspace("searching", target, async (fs) => {
-                    // Two rounds, because a `grep` retry re-reads and re-scans every file
-                    // it already looked at. `.git` rarely floods a page here — its bulk is
-                    // compressed objects, which a text query does not match — where a
-                    // `node_modules` left in the workspace is source and matches.
-                    const skips = WALK_SKIPS;
-                    const page = await collectVisible((at, limit) => fs.grep(query, target, {
-                        include,
-                        regex,
-                        ignoreCase,
-                        context,
-                        limit,
-                        offset: at
-                    }), (m) => m.path, (p) => isSkipped(skips, p), DEFAULT_MAX_MATCHES, from, 2);
-                    if (page.items.length === 0)
-                        return page.crowded
-                            ? `every match for ${JSON.stringify(query)} from offset ${from} is inside ${skipNames(skips)}, which ${skips.length > 1 ? "are" : "is"} not searched. Add \`include\` (e.g. '**/*.ts') to search the working tree instead, or use sb_exec to search \`node_modules\`.`
-                            : `no matches for ${JSON.stringify(query)} in ${target}${include ? ` (${include})` : ""}${from > 0 ? ` past offset ${from}` : ""}`;
-                    const { body, shown, capped } = renderGrepMatches(page.items.slice(0, DEFAULT_MAX_MATCHES), maxChars);
-                    return (body +
-                        listingNote(page, shown, "matches", "`include`") +
-                        (capped
-                            ? `\n(Some lines were shortened. Read one in full with \`sb_read\` and an \`offset\`.)`
-                            : ""));
-                });
-            }
-        }),
-        sb_exists: tool({
-            description: "Check whether a path exists in the workspace.",
-            inputSchema: z.object({ path: z.string().describe("Absolute path") }),
-            execute: async ({ path }) => {
-                const refusal = guardPath(path, "sb_exists");
-                if (refusal)
-                    return refusal;
-                return inWorkspace("checking", path, async (fs) => {
-                    return (await pathExists(fs, path))
-                        ? `${path} exists`
-                        : `${path} does not exist`;
-                });
-            }
-        })
-    };
-}

package/dist/recall/index.d.ts

@@ -1,105 +0,0 @@
-import type { AgentPlugin } from "@dynamicagents/core";
-import type { SessionMessage } from "@dynamicagents/core/agent";
-/**
- * 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,
- *          agentName: host.agentName, ...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 fields by hand.
- */
-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;
-    /**
-     * The `agent` key on embedding calls' AI Gateway log rows. Pass the host's
-     * `PluginHost.agentName`, for the reason given on {@link aiGatewayId}.
-     */
-    agentName?: 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;