@retinue/agentkit 0.1.0 → 0.3.0

package/dist/testing/pglite.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A shared PGlite instance with a fresh schema per caller.
+ *
+ * **Why.** Every test used to boot its own embedded Postgres, and boot is essentially the entire cost:
+ * measured on this machine, `new PGlite()` plus a first query is **432ms warm**, while running all
+ * eleven migrations is **20ms** — and creating a second schema and migrating into it inside an
+ * already-booted instance is also **20ms**. Boot dominates by more than twenty to one.
+ *
+ * The conformance entrypoints call their store factory once per test case, so between them they were
+ * booting roughly 250 embedded databases per run. That is the largest single cost in CI, and it grew
+ * with every port added — the `build` job roughly tripled over #98–#111.
+ *
+ * **Isolation is by schema, not by instance.** Each caller gets `CREATE SCHEMA` and an executor that
+ * sets `search_path` on every query, because the connection is shared and another caller's schema may
+ * be current by the time a query runs. Two in-process round trips instead of one is nothing next to a
+ * 432ms boot.
+ *
+ * **What this does not isolate**, and the reason some test files deliberately keep their own instance:
+ * connection-level state. Roles (`CREATE ROLE app_user`), `SET ROLE`, and session GUCs are properties
+ * of the connection, not the schema — so a file that creates a role per test would collide on the
+ * second one. The row-level-security tests are exactly that shape and are left alone on purpose.
+ *
+ * Also note: `information_schema` queries must filter on `table_schema = current_schema()` here. With
+ * one schema per instance an unqualified `WHERE table_name = 'runs'` matched one row; with many schemas
+ * in one instance it matches one per schema.
+ */
+import { PGlite } from "@electric-sql/pglite";
+import type { SqlExecutor } from "../adapters/postgres/sql.js";
+/**
+ * An executor pinned to `schema`.
+ *
+ * `search_path` is set per query rather than once, because the connection is shared: between two
+ * queries from this executor, another caller's executor may have pointed the path at its own schema.
+ * Setting it once at creation would make every test's isolation depend on execution order.
+ *
+ * `public` is deliberately **absent** from the path. With it present, `CREATE TABLE IF NOT EXISTS`
+ * would see a table of the same name in `public` and skip creating it here — so a stray table in
+ * `public` would silently make every later schema share it.
+ */
+export declare const schemaExecutor: (db: PGlite, schema: string) => SqlExecutor;
+export type PgliteSchema = {
+    readonly sql: SqlExecutor;
+    readonly db: PGlite;
+    readonly schema: string;
+};
+/** A migrated, isolated schema on the shared instance. Lazily boots the instance on first use. */
+export declare const freshPgliteSchema: () => Promise<PgliteSchema>;
+/**
+ * A migrated schema, created lazily on first query so a caller can build stores synchronously.
+ *
+ * The conformance harnesses call their factory inside each test and expect a usable executor back
+ * immediately, so the work has to be deferred to the first query rather than done up front.
+ */
+export declare const lazyPgliteSchema: () => SqlExecutor;
+//# sourceMappingURL=pglite.d.ts.map

package/dist/testing/pglite.js

@@ -0,0 +1,78 @@
+/**
+ * A shared PGlite instance with a fresh schema per caller.
+ *
+ * **Why.** Every test used to boot its own embedded Postgres, and boot is essentially the entire cost:
+ * measured on this machine, `new PGlite()` plus a first query is **432ms warm**, while running all
+ * eleven migrations is **20ms** — and creating a second schema and migrating into it inside an
+ * already-booted instance is also **20ms**. Boot dominates by more than twenty to one.
+ *
+ * The conformance entrypoints call their store factory once per test case, so between them they were
+ * booting roughly 250 embedded databases per run. That is the largest single cost in CI, and it grew
+ * with every port added — the `build` job roughly tripled over #98–#111.
+ *
+ * **Isolation is by schema, not by instance.** Each caller gets `CREATE SCHEMA` and an executor that
+ * sets `search_path` on every query, because the connection is shared and another caller's schema may
+ * be current by the time a query runs. Two in-process round trips instead of one is nothing next to a
+ * 432ms boot.
+ *
+ * **What this does not isolate**, and the reason some test files deliberately keep their own instance:
+ * connection-level state. Roles (`CREATE ROLE app_user`), `SET ROLE`, and session GUCs are properties
+ * of the connection, not the schema — so a file that creates a role per test would collide on the
+ * second one. The row-level-security tests are exactly that shape and are left alone on purpose.
+ *
+ * Also note: `information_schema` queries must filter on `table_schema = current_schema()` here. With
+ * one schema per instance an unqualified `WHERE table_name = 'runs'` matched one row; with many schemas
+ * in one instance it matches one per schema.
+ */
+import { PGlite } from "@electric-sql/pglite";
+import { migrate } from "../adapters/postgres/migrations.js";
+/**
+ * One instance per module, which under vitest means one per test file — files run in separate workers,
+ * so this is not shared across them.
+ */
+let shared = null;
+let schemas = 0;
+const instance = () => (shared ??= new PGlite());
+/**
+ * An executor pinned to `schema`.
+ *
+ * `search_path` is set per query rather than once, because the connection is shared: between two
+ * queries from this executor, another caller's executor may have pointed the path at its own schema.
+ * Setting it once at creation would make every test's isolation depend on execution order.
+ *
+ * `public` is deliberately **absent** from the path. With it present, `CREATE TABLE IF NOT EXISTS`
+ * would see a table of the same name in `public` and skip creating it here — so a stray table in
+ * `public` would silently make every later schema share it.
+ */
+export const schemaExecutor = (db, schema) => ({
+    async query(text, params) {
+        await db.exec(`SET search_path TO ${schema}`);
+        const result = await db.query(text, params ? [...params] : undefined);
+        return result.rows;
+    },
+});
+/** A migrated, isolated schema on the shared instance. Lazily boots the instance on first use. */
+export const freshPgliteSchema = async () => {
+    const db = instance();
+    const schema = `s${(schemas += 1)}`;
+    await db.exec(`CREATE SCHEMA ${schema}`);
+    const sql = schemaExecutor(db, schema);
+    await migrate(sql);
+    return { sql, db, schema };
+};
+/**
+ * A migrated schema, created lazily on first query so a caller can build stores synchronously.
+ *
+ * The conformance harnesses call their factory inside each test and expect a usable executor back
+ * immediately, so the work has to be deferred to the first query rather than done up front.
+ */
+export const lazyPgliteSchema = () => {
+    let ready = null;
+    const init = () => (ready ??= freshPgliteSchema().then((created) => created.sql));
+    return {
+        async query(text, params) {
+            return (await init()).query(text, params);
+        },
+    };
+};
+//# sourceMappingURL=pglite.js.map

package/dist/testing/stub-model.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A scripted model, for testing an agent without calling a provider — task #253 AC-4.
+ *
+ * Testing an agent currently means writing a `streamTurn` by hand, and every consumer writes the same one badly:
+ * a single `text-delta` and a `finish`, which exercises none of the paths that actually break. The interesting
+ * behaviour of this platform — retry, approval gates, tool errors, structured output, the catalogue budget — all
+ * live in what the model does *across steps*, and a one-chunk fake cannot express any of it.
+ *
+ * ## Scripted per turn, not per call
+ *
+ * A script is a list of **turns**, and each call consumes the next one. That is what lets a test say "the model
+ * calls the tool, sees the result, then answers" — three chunks in one turn — separately from "the first turn
+ * fails and the second succeeds", which is two turns and is how a retry test is written.
+ *
+ * Running past the end of the script is an **error**, not a silent empty turn. A test whose agent took one more
+ * turn than the author expected should fail loudly, because the alternative is an assertion passing against a
+ * turn that produced nothing.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import type { ModelTurnRequest, NeutralStreamChunk, NeutralUsage } from "../models/streaming.js";
+/** What the model does on one turn. */
+export type ScriptedTurn = 
+/** Answers with text. */
+{
+    readonly say: string;
+    readonly usage?: Partial<NeutralUsage>;
+}
+/** Calls tools, then answers — the shape almost every interesting test needs. */
+ | {
+    readonly call: readonly {
+        readonly tool: string;
+        readonly input?: unknown;
+        readonly id?: string;
+    }[];
+    readonly then?: string;
+    readonly usage?: Partial<NeutralUsage>;
+}
+/**
+ * Fails, as a provider would.
+ *
+ * `retryable` defaults to **true**, because the case worth testing is the retry path — a non-retryable failure
+ * is just a thrown error and needs no scripting to produce.
+ */
+ | {
+    readonly fail: string;
+    readonly code?: AgentPlatformError["code"];
+    readonly retryable?: boolean;
+};
+export type StubModel = {
+    /** Pass as `DefaultEngineDeps.streamTurn`. */
+    readonly streamTurn: (request: ModelTurnRequest) => AsyncIterable<NeutralStreamChunk>;
+    /** Every request the engine made, in order — so a test can assert what the model was *given*. */
+    readonly requests: readonly ModelTurnRequest[];
+    /** Turns consumed so far. */
+    readonly turns: () => number;
+};
+export declare const createStubModel: (script: readonly ScriptedTurn[]) => StubModel;
+//# sourceMappingURL=stub-model.d.ts.map

package/dist/testing/stub-model.js

@@ -0,0 +1,71 @@
+/**
+ * A scripted model, for testing an agent without calling a provider — task #253 AC-4.
+ *
+ * Testing an agent currently means writing a `streamTurn` by hand, and every consumer writes the same one badly:
+ * a single `text-delta` and a `finish`, which exercises none of the paths that actually break. The interesting
+ * behaviour of this platform — retry, approval gates, tool errors, structured output, the catalogue budget — all
+ * live in what the model does *across steps*, and a one-chunk fake cannot express any of it.
+ *
+ * ## Scripted per turn, not per call
+ *
+ * A script is a list of **turns**, and each call consumes the next one. That is what lets a test say "the model
+ * calls the tool, sees the result, then answers" — three chunks in one turn — separately from "the first turn
+ * fails and the second succeeds", which is two turns and is how a retry test is written.
+ *
+ * Running past the end of the script is an **error**, not a silent empty turn. A test whose agent took one more
+ * turn than the author expected should fail loudly, because the alternative is an assertion passing against a
+ * turn that produced nothing.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+const usageOf = (partial) => ({
+    inputTokens: 10,
+    outputTokens: 5,
+    cachedInputTokens: 0,
+    ...partial,
+});
+export const createStubModel = (script) => {
+    const requests = [];
+    let index = 0;
+    async function* run(request) {
+        requests.push(request);
+        const turn = script[index];
+        index += 1;
+        if (turn === undefined) {
+            // Loud, not empty. An agent that took one more turn than the test expected is a finding, and an empty
+            // turn would let an assertion pass against a model that said nothing.
+            throw new AgentPlatformError({
+                code: "internal",
+                message: `the stub model's script has ${script.length} turn(s) and the agent asked for turn ${index}. ` +
+                    "Either the agent is looping, or the script is short — both are worth knowing.",
+                retryable: false,
+            });
+        }
+        if ("fail" in turn) {
+            throw new AgentPlatformError({
+                code: turn.code ?? "provider_error",
+                message: turn.fail,
+                retryable: turn.retryable ?? true,
+            });
+        }
+        if ("say" in turn) {
+            yield { type: "text-delta", id: `t${index}`, text: turn.say };
+            yield { type: "finish", usage: usageOf(turn.usage) };
+            return;
+        }
+        for (const [n, call] of turn.call.entries()) {
+            const id = call.id ?? `call-${index}-${n}`;
+            yield { type: "tool-call", toolCallId: id, toolName: call.tool, input: call.input ?? {} };
+            /**
+             * No `tool-result` is emitted here, deliberately.
+             *
+             * The engine runs the tool itself and produces the result — that is the path under test. A stub that
+             * emitted its own result would test nothing but the stub, and would hide an unwired tool entirely.
+             */
+        }
+        if (turn.then !== undefined)
+            yield { type: "text-delta", id: `t${index}`, text: turn.then };
+        yield { type: "finish", usage: usageOf(turn.usage) };
+    }
+    return { streamTurn: run, requests, turns: () => index };
+};
+//# sourceMappingURL=stub-model.js.map

package/dist/testing/supabase-storage-double.d.ts

@@ -0,0 +1,35 @@
+/**
+ * An in-process Supabase Storage, for the `FileContentStore` adapter (#129).
+ *
+ * Lives here rather than beside one test because two suites need it: `supabase-conformance.test.ts` is the
+ * single conformance entrypoint the matrix generator reads, and `supabase-storage.test.ts` holds the cases
+ * only an HTTP store has. A double copied into both would drift, and a drifting double is a suite that
+ * proves two different things while appearing to prove one.
+ *
+ * Deliberately strict about what the adapter must get right: it requires the bearer token, it refuses an
+ * upload to an existing path unless `x-upsert` says otherwise, and it 404s an unknown object rather than
+ * returning an empty body. A lenient double would let every one of those bugs through to production.
+ *
+ * It can only prove the adapter is self-consistent about the API it *believes* Supabase has. What it proves
+ * well is everything on this side of the wire — URL construction, status handling, tenant prefixing — which
+ * is where the tenant boundary lives.
+ */
+import type { FileContentStore } from "../persistence/index.js";
+export type RecordedCall = {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Record<string, string>;
+};
+export declare const STORAGE_BUCKET = "attachments";
+export declare const STORAGE_URL = "https://project.supabase.test";
+export declare const STORAGE_KEY = "service-role-key";
+/** The adapter over the double, plus the double's innards for the assertions that need them. */
+export declare const supabaseStorageDouble: () => {
+    readonly store: FileContentStore;
+    readonly objects: Map<string, {
+        bytes: Uint8Array;
+        mediaType: string;
+    }>;
+    readonly calls: RecordedCall[];
+};
+//# sourceMappingURL=supabase-storage-double.d.ts.map

package/dist/testing/supabase-storage-double.js

@@ -0,0 +1,101 @@
+/**
+ * An in-process Supabase Storage, for the `FileContentStore` adapter (#129).
+ *
+ * Lives here rather than beside one test because two suites need it: `supabase-conformance.test.ts` is the
+ * single conformance entrypoint the matrix generator reads, and `supabase-storage.test.ts` holds the cases
+ * only an HTTP store has. A double copied into both would drift, and a drifting double is a suite that
+ * proves two different things while appearing to prove one.
+ *
+ * Deliberately strict about what the adapter must get right: it requires the bearer token, it refuses an
+ * upload to an existing path unless `x-upsert` says otherwise, and it 404s an unknown object rather than
+ * returning an empty body. A lenient double would let every one of those bugs through to production.
+ *
+ * It can only prove the adapter is self-consistent about the API it *believes* Supabase has. What it proves
+ * well is everything on this side of the wire — URL construction, status handling, tenant prefixing — which
+ * is where the tenant boundary lives.
+ */
+import { createSupabaseStorageFileContentStore } from "../adapters/supabase/storage.js";
+export const STORAGE_BUCKET = "attachments";
+export const STORAGE_URL = "https://project.supabase.test";
+export const STORAGE_KEY = "service-role-key";
+const fakeStorage = () => {
+    const objects = new Map();
+    const calls = [];
+    const reply = (status, body) => ({
+        status,
+        ok: status >= 200 && status < 300,
+        async text() {
+            return typeof body === "string" ? body : new TextDecoder().decode(body);
+        },
+        async arrayBuffer() {
+            return (typeof body === "string" ? new TextEncoder().encode(body) : body)
+                .slice()
+                .buffer;
+        },
+    });
+    const fetchImpl = async (url, init) => {
+        const method = init?.method ?? "GET";
+        const headers = init?.headers ?? {};
+        calls.push({ method, url, headers });
+        if (headers["Authorization"] !== `Bearer ${STORAGE_KEY}`)
+            return reply(401, "missing bearer token");
+        const rest = url.slice(`${STORAGE_URL}/storage/v1/`.length);
+        if (rest.startsWith(`object/list/${STORAGE_BUCKET}`) && method === "POST") {
+            const body = JSON.parse(String(init?.body ?? "{}"));
+            const matched = [...objects.entries()]
+                .filter(([path]) => path.startsWith(body.prefix))
+                .map(([path, value]) => ({
+                // The API returns names relative to the searched prefix, which is what the adapter relies on.
+                name: path.slice(body.prefix.length),
+                metadata: { size: value.bytes.byteLength },
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .slice(body.offset, body.offset + body.limit);
+            return reply(200, JSON.stringify(matched));
+        }
+        if (rest.startsWith(`object/sign/${STORAGE_BUCKET}/`) && method === "POST") {
+            const path = rest.slice(`object/sign/${STORAGE_BUCKET}/`.length);
+            if (!objects.has(path))
+                return reply(404, "Object not found");
+            const { expiresIn } = JSON.parse(String(init?.body ?? "{}"));
+            return reply(200, JSON.stringify({ signedURL: `/object/sign/${STORAGE_BUCKET}/${path}?token=t&exp=${expiresIn}` }));
+        }
+        if (rest.startsWith(`object/${STORAGE_BUCKET}/`)) {
+            const path = rest.slice(`object/${STORAGE_BUCKET}/`.length);
+            if (method === "POST") {
+                if (objects.has(path) && headers["x-upsert"] !== "true")
+                    return reply(409, "The resource already exists");
+                const body = init?.body;
+                if (!(body instanceof Uint8Array))
+                    return reply(400, "expected a byte body");
+                objects.set(path, { bytes: body, mediaType: headers["Content-Type"] ?? "application/octet-stream" });
+                return reply(200, JSON.stringify({ Key: `${STORAGE_BUCKET}/${path}` }));
+            }
+            if (method === "DELETE") {
+                if (!objects.has(path))
+                    return reply(404, "Object not found");
+                objects.delete(path);
+                return reply(200, JSON.stringify({ message: "Successfully deleted" }));
+            }
+            const stored = objects.get(path);
+            return stored === undefined ? reply(404, "Object not found") : reply(200, stored.bytes);
+        }
+        return reply(404, `unrouted ${method} ${rest}`);
+    };
+    return { fetchImpl, objects, calls };
+};
+/** The adapter over the double, plus the double's innards for the assertions that need them. */
+export const supabaseStorageDouble = () => {
+    const storage = fakeStorage();
+    return {
+        store: createSupabaseStorageFileContentStore({
+            url: STORAGE_URL,
+            serviceKey: STORAGE_KEY,
+            bucket: STORAGE_BUCKET,
+            fetch: storage.fetchImpl,
+        }),
+        objects: storage.objects,
+        calls: storage.calls,
+    };
+};
+//# sourceMappingURL=supabase-storage-double.js.map

package/dist/toolkit/files.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Reading and writing files, path-scoped — REQ-047 (#206), task #215.
+ *
+ * In `toolkit/` rather than `tools/` because it performs I/O and boundary rule **R7** forbids that in the tools
+ * layer, the same arrangement `http.ts` has with the web tools. The tools in `tools/library/fs.ts` are envelopes
+ * over these functions, and every security property lives here — not in the envelope, and not in the schema.
+ *
+ * ## The one property that matters
+ *
+ * **A path a model produced must not be able to name a file outside the configured root**, and there are three
+ * ways it tries:
+ *
+ * - `../../etc/passwd` — normalised away by resolving against the root first.
+ * - `/etc/passwd` — an absolute path is **refused outright** rather than silently re-rooted. Re-rooting would
+ *   answer a different question than the one asked, and the model would not know.
+ * - A **symlink** inside the root pointing out of it. This is the one that gets missed, because the path is
+ *   inside the root right up until the filesystem resolves it. So the check is against the *real* path, after
+ *   symlink resolution, on every call — not against the string.
+ *
+ * The root itself is resolved once at construction, also through `realpath`: a root that is itself a symlink
+ * would otherwise make every real path look like an escape.
+ *
+ * ## Bytes are bounded while reading
+ *
+ * A cap applied after `readFile` has already buffered a two-gigabyte file protects nothing. These read into a
+ * fixed buffer and report `truncated`, which is the same decision `http.ts` made for the same reason. Truncation
+ * rather than refusal, because "the first 200 KB of the log" is usually the answer, and a refusal leaves the
+ * model with nothing.
+ */
+/** Bytes returned from one read. Matches the HTTP client's ceiling, for the same reason. */
+export declare const MAX_FILE_BYTES = 200000;
+/** Entries returned from one listing. A directory of ten thousand files is not an answer. */
+export declare const MAX_ENTRIES = 200;
+/** Files examined by one search. Bounded work, so a search cannot become a filesystem crawl. */
+export declare const MAX_SEARCHED_FILES = 2000;
+/** Matches returned from one search. */
+export declare const MAX_MATCHES = 100;
+export type FileScope = {
+    /** Everything readable, and the only thing readable. Resolved through `realpath` at construction. */
+    readonly root: string;
+    /**
+     * Where writes may land, when writes are wanted at all.
+     *
+     * Separate from `root`, and absent by default. A deployment that pointed both at the same directory would let
+     * a model edit the material it also reads — which is how a corpus a model cites becomes a corpus a model wrote.
+     */
+    readonly writableRoot?: string;
+    readonly maxBytes?: number;
+    readonly maxEntries?: number;
+    readonly maxMatches?: number;
+    readonly maxSearchedFiles?: number;
+};
+/**
+ * Why a file operation did not happen.
+ *
+ * A *reason*, not an exception, for the reason `HttpFailure` gives: a refused path is information the model can
+ * act on, and a thrown error reads as "something broke", which invites an identical retry.
+ */
+export type FileFailure = {
+    readonly ok: false;
+    readonly path: string;
+    readonly kind: "forbidden" | "not-found" | "not-a-file" | "not-a-directory" | "unreadable" | "too-many";
+    readonly reason: string;
+};
+export type FileRead = {
+    readonly ok: true;
+    readonly path: string;
+    readonly bytes: number;
+    readonly truncated: boolean;
+    readonly content: string;
+};
+export type FileEntry = {
+    readonly name: string;
+    readonly path: string;
+    readonly kind: "file" | "directory" | "other";
+    readonly bytes?: number;
+};
+export type FileList = {
+    readonly ok: true;
+    readonly path: string;
+    readonly entries: readonly FileEntry[];
+    readonly truncated: boolean;
+};
+export type FileMatch = {
+    readonly path: string;
+    readonly line: number;
+    /** The matching line, trimmed and capped. Untrusted content, like everything else read from disk. */
+    readonly text: string;
+};
+export type FileSearch = {
+    readonly ok: true;
+    readonly query: string;
+    readonly matches: readonly FileMatch[];
+    readonly filesSearched: number;
+    /** True when the file or match ceiling stopped the search early. */
+    readonly truncated: boolean;
+};
+export type FileWrite = {
+    readonly ok: true;
+    readonly path: string;
+    readonly bytes: number;
+    readonly created: boolean;
+};
+/**
+ * Is `candidate` inside `root`, both already real paths?
+ *
+ * `relative` rather than `startsWith`: `/srv/data-secrets` starts with `/srv/data`, and a prefix comparison would
+ * accept it. A relative path that begins with `..` or is absolute is outside.
+ */
+export declare const contains: (root: string, candidate: string) => boolean;
+export type FileReader = {
+    read(path: string): FileRead | FileFailure;
+    list(path?: string): FileList | FileFailure;
+    search(input: {
+        readonly query: string;
+        readonly path?: string;
+        readonly namePattern?: string;
+    }): FileSearch | FileFailure;
+    write(input: {
+        readonly path: string;
+        readonly content: string;
+    }): FileWrite | FileFailure;
+};
+export declare const createFileReader: (scope: FileScope) => FileReader;
+//# sourceMappingURL=files.d.ts.map