@retinue/agentkit 0.1.0

package/dist/toolkit/compute.js

@@ -0,0 +1,152 @@
+/**
+ * Time and arithmetic — REQ-039 (#188).
+ *
+ * The two things a model is reliably bad at and a two-line function is reliably good at. Both are pure, so both
+ * are here as functions and the tool envelopes over them are trivial.
+ */
+const FUNCTIONS = {
+    abs: Math.abs, ceil: Math.ceil, floor: Math.floor, round: Math.round, trunc: Math.trunc,
+    sqrt: Math.sqrt, cbrt: Math.cbrt, exp: Math.exp, ln: Math.log, log10: Math.log10, log2: Math.log2,
+    sin: Math.sin, cos: Math.cos, tan: Math.tan, asin: Math.asin, acos: Math.acos, atan: Math.atan,
+    min: Math.min, max: Math.max, pow: Math.pow,
+};
+const CONSTANTS = { pi: Math.PI, e: Math.E };
+export const MAX_EXPRESSION_CHARS = 500;
+export const calculate = (expression) => {
+    if (expression.trim() === "")
+        return { ok: false, expression, reason: "The expression is empty." };
+    if (expression.length > MAX_EXPRESSION_CHARS) {
+        return { ok: false, expression, reason: `Expressions are limited to ${MAX_EXPRESSION_CHARS} characters.` };
+    }
+    const tokens = expression.toLowerCase().match(/\d+\.?\d*|[a-z_]\w*|[+\-*/%^(),]|\S/g);
+    if (tokens === null)
+        return { ok: false, expression, reason: "There is nothing to evaluate." };
+    let position = 0;
+    const peek = () => tokens[position];
+    const take = () => tokens[position++];
+    const fail = (reason) => {
+        throw new SyntaxError(reason);
+    };
+    // expression := term (('+' | '-') term)*
+    const parseExpression = () => {
+        let value = parseTerm();
+        for (;;) {
+            const operator = peek();
+            if (operator !== "+" && operator !== "-")
+                return value;
+            take();
+            const right = parseTerm();
+            value = operator === "+" ? value + right : value - right;
+        }
+    };
+    // term := power (('*' | '/' | '%') power)*
+    const parseTerm = () => {
+        let value = parsePower();
+        for (;;) {
+            const operator = peek();
+            if (operator !== "*" && operator !== "/" && operator !== "%")
+                return value;
+            take();
+            const right = parsePower();
+            if ((operator === "/" || operator === "%") && right === 0)
+                fail("division by zero");
+            value = operator === "*" ? value * right : operator === "/" ? value / right : value % right;
+        }
+    };
+    // power := unary ('^' power)?   -- right-associative, so 2^3^2 is 512 and not 64.
+    const parsePower = () => {
+        const base = parseUnary();
+        if (peek() !== "^")
+            return base;
+        take();
+        return base ** parsePower();
+    };
+    const parseUnary = () => {
+        if (peek() === "-") {
+            take();
+            return -parseUnary();
+        }
+        if (peek() === "+") {
+            take();
+            return parseUnary();
+        }
+        return parsePrimary();
+    };
+    const parsePrimary = () => {
+        const token = take();
+        if (token === undefined)
+            fail("the expression ends before it is finished");
+        if (token === "(") {
+            const value = parseExpression();
+            if (take() !== ")")
+                fail("a '(' is never closed");
+            return value;
+        }
+        if (/^\d/.test(token))
+            return Number(token);
+        const name = token;
+        if (name in CONSTANTS)
+            return CONSTANTS[name];
+        if (name in FUNCTIONS) {
+            if (take() !== "(")
+                fail(`${name} needs its arguments in parentheses`);
+            const args = [];
+            if (peek() !== ")") {
+                args.push(parseExpression());
+                while (peek() === ",") {
+                    take();
+                    args.push(parseExpression());
+                }
+            }
+            if (take() !== ")")
+                fail(`the arguments to ${name} are never closed`);
+            return FUNCTIONS[name](...args);
+        }
+        return fail(`'${name}' is not a number, an operator, or a function I know`);
+    };
+    try {
+        const value = parseExpression();
+        if (position < tokens.length) {
+            return { ok: false, expression, reason: `I could not read '${tokens.slice(position).join(" ")}'.` };
+        }
+        if (!Number.isFinite(value)) {
+            // Infinity and NaN are results a model will happily narrate as a number. They are not one.
+            return { ok: false, expression, reason: "That does not have a finite numeric answer." };
+        }
+        return { ok: true, expression, value };
+    }
+    catch (error) {
+        return { ok: false, expression, reason: `I could not evaluate that: ${error.message}.` };
+    }
+};
+/**
+ * The current time, in a named zone.
+ *
+ * A model has no clock -- it has a training cutoff, and it will answer "what is today's date" with something
+ * plausible and wrong. The zone is a parameter because "today" is a different day depending on where the person
+ * asking is, and the caller is often not in UTC.
+ *
+ * The clock is injected so a test can pin it, which is the convention everywhere else in this runtime.
+ */
+export const currentTime = (input = {}) => {
+    const timeZone = input.timeZone ?? "UTC";
+    const at = (input.now ?? (() => new Date()))();
+    try {
+        const formatted = new Intl.DateTimeFormat("en-CA", {
+            timeZone,
+            dateStyle: "full",
+            timeStyle: "long",
+            // 24-hour, explicitly. The locale default here is "1:34:56 p.m.", and a model that has to re-derive
+            // whether that is 01:34 or 13:34 is one that will sometimes get it wrong -- for a value it asked for
+            // precisely because it could not work it out itself.
+            hourCycle: "h23",
+        }).format(at);
+        return { ok: true, iso: at.toISOString(), formatted, timeZone, epochMs: at.getTime() };
+    }
+    catch {
+        // An unknown zone is the caller's mistake and worth naming, not worth guessing UTC for: a wrong timezone
+        // produces an answer that is confidently off by hours.
+        return { ok: false, reason: `'${timeZone}' is not a time zone I recognise. Use an IANA name like 'Europe/Berlin'.` };
+    }
+};
+//# sourceMappingURL=compute.js.map

package/dist/toolkit/data.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Structured data — REQ-039 (#188).
+ *
+ * CSV, JSON and read-only SQL. All three are functions the library's tool envelopes delegate to; the SQL one
+ * takes its executor as an argument rather than importing a driver, which is both boundary rule R4 and the reason
+ * this file has no dependencies at all.
+ */
+export declare const MAX_CSV_ROWS = 500;
+export declare const MAX_SQL_ROWS = 200;
+export declare const MAX_CELL_CHARS = 1000;
+export type CsvResult = {
+    readonly ok: true;
+    readonly columns: readonly string[];
+    readonly rows: readonly Readonly<Record<string, string>>[];
+    readonly rowCount: number;
+    readonly truncated: boolean;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Parse CSV.
+ *
+ * Handles the part people get wrong -- quoted fields containing commas, newlines and escaped quotes -- and
+ * nothing else. No type inference: a column of `01234` is a zip code and a column of `1-2` is not a date, and a
+ * parser that guesses produces data a model then reasons about incorrectly. Everything comes back as a string,
+ * which is what it was.
+ */
+export declare const parseCsv: (text: string, options?: {
+    readonly delimiter?: string;
+    readonly maxRows?: number;
+}) => CsvResult;
+export type JsonQueryResult = {
+    readonly ok: true;
+    readonly path: string;
+    readonly matches: readonly unknown[];
+} | {
+    readonly ok: false;
+    readonly path: string;
+    readonly reason: string;
+};
+/**
+ * Read a value out of a JSON document by path.
+ *
+ * A deliberately small path language -- `a.b`, `a.0.b`, `a[0].b`, and `*` for "every element or value here" --
+ * because the alternatives are a JSONPath dependency or `eval`, and one of those is a remote code execution in a
+ * tool whose argument comes from a model.
+ *
+ * The point of the tool is that a model can pull one field out of a 200KB payload without the payload passing
+ * through its context. A tool that returns the whole document on a bad path defeats that, so a path matching
+ * nothing returns no matches and says so.
+ */
+export declare const queryJson: (document: unknown, path: string) => JsonQueryResult;
+/** The one shape the SQL tool needs. Supplied by the host, so this file imports no driver (R4, R7). */
+export type ReadOnlyQuery = <T = Record<string, unknown>>(sql: string, params?: readonly unknown[]) => Promise<readonly T[]>;
+export type SqlResult = {
+    readonly ok: true;
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly rowCount: number;
+    readonly truncated: boolean;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare const createSqlQuery: (config: {
+    readonly query: ReadOnlyQuery;
+    /**
+     * An explicit acknowledgement that the connection cannot write.
+     *
+     * Not a flag that *makes* it read-only -- nothing here can do that. It exists so that wiring a read-write
+     * connection into a model-driven tool has to be typed out, and so a reviewer can see whether it was.
+     */
+    readonly readOnly: true;
+    readonly maxRows?: number;
+    readonly statementTimeoutMs?: number;
+}) => (sql: string) => Promise<SqlResult>;
+export type SchemaResult = {
+    readonly ok: true;
+    readonly tables: readonly {
+        readonly table: string;
+        readonly columns: readonly string[];
+    }[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * What the model may query.
+ *
+ * Without this, `sql_query` is a tool whose first five calls are guesses at table names. Restricted to the schemas
+ * the deployment names -- not `current_schema()`, because a connection's search path is not a statement about what
+ * a model should be shown.
+ */
+export declare const createSqlSchema: (config: {
+    readonly query: ReadOnlyQuery;
+    readonly schemas: readonly string[];
+}) => () => Promise<SchemaResult>;
+//# sourceMappingURL=data.d.ts.map

package/dist/toolkit/data.js

@@ -0,0 +1,235 @@
+/**
+ * Structured data — REQ-039 (#188).
+ *
+ * CSV, JSON and read-only SQL. All three are functions the library's tool envelopes delegate to; the SQL one
+ * takes its executor as an argument rather than importing a driver, which is both boundary rule R4 and the reason
+ * this file has no dependencies at all.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+export const MAX_CSV_ROWS = 500;
+export const MAX_SQL_ROWS = 200;
+export const MAX_CELL_CHARS = 1_000;
+/**
+ * Parse CSV.
+ *
+ * Handles the part people get wrong -- quoted fields containing commas, newlines and escaped quotes -- and
+ * nothing else. No type inference: a column of `01234` is a zip code and a column of `1-2` is not a date, and a
+ * parser that guesses produces data a model then reasons about incorrectly. Everything comes back as a string,
+ * which is what it was.
+ */
+export const parseCsv = (text, options = {}) => {
+    const delimiter = options.delimiter ?? ",";
+    if (delimiter.length !== 1)
+        return { ok: false, reason: "The delimiter must be a single character." };
+    const maxRows = options.maxRows ?? MAX_CSV_ROWS;
+    const records = [];
+    let field = "";
+    let record = [];
+    let quoted = false;
+    let index = 0;
+    const endField = () => {
+        record.push(field.length > MAX_CELL_CHARS ? `${field.slice(0, MAX_CELL_CHARS)}…` : field);
+        field = "";
+    };
+    const endRecord = () => {
+        endField();
+        // A trailing newline produces one empty field, which is not a row. Anything else is kept, including rows that
+        // are genuinely all-empty in the middle of a file -- those are data.
+        if (!(record.length === 1 && record[0] === ""))
+            records.push(record);
+        record = [];
+    };
+    while (index < text.length) {
+        const char = text[index];
+        if (quoted) {
+            if (char === '"') {
+                if (text[index + 1] === '"') {
+                    field += '"';
+                    index += 2;
+                    continue;
+                }
+                quoted = false;
+                index += 1;
+                continue;
+            }
+            field += char;
+            index += 1;
+            continue;
+        }
+        if (char === '"' && field === "") {
+            quoted = true;
+            index += 1;
+            continue;
+        }
+        if (char === delimiter) {
+            endField();
+            index += 1;
+            continue;
+        }
+        if (char === "\r") {
+            index += 1;
+            continue;
+        }
+        if (char === "\n") {
+            endRecord();
+            index += 1;
+            /**
+             * Stop reading once there is one row more than the ceiling.
+             *
+             * `maxRows + 1` and not `maxRows`, and the difference is the whole truncation flag: `records` includes the
+             * header, so stopping at `maxRows` leaves exactly `maxRows` data rows and no way to tell "the file ended"
+             * from "the file did not". The extra row is the evidence, and it is discarded immediately below.
+             */
+            if (records.length > maxRows + 1)
+                break;
+            continue;
+        }
+        field += char;
+        index += 1;
+    }
+    if (quoted)
+        return { ok: false, reason: "A quoted field is never closed, so the row boundaries are unknowable." };
+    if (field !== "" || record.length > 0)
+        endRecord();
+    const [header, ...body] = records;
+    if (header === undefined)
+        return { ok: false, reason: "There is no data here — not even a header row." };
+    const columns = header.map((name, position) => (name.trim() === "" ? `column_${position + 1}` : name.trim()));
+    const truncated = body.length > maxRows;
+    const rows = body.slice(0, maxRows).map((values) => Object.fromEntries(columns.map((name, position) => [name, values[position] ?? ""])));
+    return { ok: true, columns, rows, rowCount: rows.length, truncated };
+};
+/**
+ * Read a value out of a JSON document by path.
+ *
+ * A deliberately small path language -- `a.b`, `a.0.b`, `a[0].b`, and `*` for "every element or value here" --
+ * because the alternatives are a JSONPath dependency or `eval`, and one of those is a remote code execution in a
+ * tool whose argument comes from a model.
+ *
+ * The point of the tool is that a model can pull one field out of a 200KB payload without the payload passing
+ * through its context. A tool that returns the whole document on a bad path defeats that, so a path matching
+ * nothing returns no matches and says so.
+ */
+export const queryJson = (document, path) => {
+    const trimmed = path.trim();
+    if (trimmed === "")
+        return { ok: false, path, reason: "The path is empty." };
+    const segments = trimmed
+        .replace(/\[(\d+)\]/g, ".$1")
+        .replace(/^\$\.?/, "")
+        .split(".")
+        .filter((segment) => segment !== "");
+    let current = [document];
+    for (const segment of segments) {
+        const next = [];
+        for (const value of current) {
+            if (value === null || value === undefined)
+                continue;
+            if (segment === "*") {
+                if (Array.isArray(value))
+                    next.push(...value);
+                else if (typeof value === "object")
+                    next.push(...Object.values(value));
+                continue;
+            }
+            if (Array.isArray(value)) {
+                const position = Number(segment);
+                if (Number.isInteger(position) && position >= 0 && position < value.length)
+                    next.push(value[position]);
+                continue;
+            }
+            if (typeof value === "object" && segment in value) {
+                next.push(value[segment]);
+            }
+        }
+        current = next;
+        if (current.length === 0)
+            break;
+    }
+    return { ok: true, path: trimmed, matches: current };
+};
+/**
+ * Statements this refuses to send.
+ *
+ * Read the caveat before trusting this list. A keyword scan over SQL a model wrote is a **second** line of
+ * defence, not the control: comments, string literals, dollar quoting and dialect extensions all give a
+ * determined author room, and this is not a parser. **The control is the connection** -- `createSqlQuery` requires
+ * a `readOnly: true` acknowledgement precisely so that wiring one is a decision somebody makes rather than a
+ * default they inherit. What the scan buys is catching the ordinary case early, with a message a model can act on,
+ * instead of a permission error from the database that reads like a bug.
+ */
+const WRITE_KEYWORDS = [
+    "insert", "update", "delete", "drop", "truncate", "alter", "create", "grant", "revoke",
+    "copy", "vacuum", "reindex", "call", "do", "merge", "replace", "set", "reset", "listen", "notify",
+];
+export const createSqlQuery = (config) => {
+    const maxRows = config.maxRows ?? MAX_SQL_ROWS;
+    return async (sql) => {
+        const statement = sql.trim().replace(/;+\s*$/, "");
+        if (statement === "")
+            return { ok: false, reason: "The query is empty." };
+        // One statement only. A batch is how a SELECT smuggles something else along behind it.
+        if (statement.includes(";")) {
+            return { ok: false, reason: "Send one statement at a time — no semicolons inside the query." };
+        }
+        const lowered = statement.toLowerCase();
+        if (!/^(select|with)\b/.test(lowered)) {
+            return { ok: false, reason: "Only SELECT queries are allowed here. Start with SELECT, or WITH … SELECT." };
+        }
+        const offending = WRITE_KEYWORDS.find((keyword) => new RegExp(`\\b${keyword}\\b`).test(lowered));
+        if (offending !== undefined) {
+            return { ok: false, reason: `This query contains \`${offending}\`, which is not allowed in a read-only query.` };
+        }
+        try {
+            // `maxRows + 1` so "there is more" is a fact rather than a guess. A LIMIT equal to the ceiling cannot tell
+            // the difference between exactly enough and too many.
+            const rows = await config.query(`SELECT * FROM (${statement}) AS q LIMIT $1`, [maxRows + 1]);
+            const truncated = rows.length > maxRows;
+            return {
+                ok: true,
+                rows: rows.slice(0, maxRows).map(boundRow),
+                rowCount: Math.min(rows.length, maxRows),
+                truncated,
+            };
+        }
+        catch (error) {
+            // The database's own message, and only its message. It says which column does not exist, which is exactly
+            // what a model needs to fix the query -- but a stack trace names our internals.
+            const message = error instanceof AgentPlatformError ? error.message : error.message;
+            return { ok: false, reason: `The query failed: ${message}` };
+        }
+    };
+};
+/** Long text cells are the usual way a bounded row count is still an unbounded payload. */
+const boundRow = (row) => Object.fromEntries(Object.entries(row).map(([key, value]) => [
+    key,
+    typeof value === "string" && value.length > MAX_CELL_CHARS ? `${value.slice(0, MAX_CELL_CHARS)}…` : value,
+]));
+/**
+ * What the model may query.
+ *
+ * Without this, `sql_query` is a tool whose first five calls are guesses at table names. Restricted to the schemas
+ * the deployment names -- not `current_schema()`, because a connection's search path is not a statement about what
+ * a model should be shown.
+ */
+export const createSqlSchema = (config) => {
+    return async () => {
+        if (config.schemas.length === 0)
+            return { ok: false, reason: "No schemas are exposed to this tool." };
+        try {
+            const rows = await config.query(`SELECT table_name, column_name FROM information_schema.columns
+          WHERE table_schema = ANY($1) ORDER BY table_name, ordinal_position`, [config.schemas]);
+            const grouped = new Map();
+            for (const row of rows) {
+                const columns = grouped.get(row.table_name) ?? [];
+                columns.push(row.column_name);
+                grouped.set(row.table_name, columns);
+            }
+            return { ok: true, tables: [...grouped].map(([table, columns]) => ({ table, columns })) };
+        }
+        catch (error) {
+            return { ok: false, reason: `Could not read the schema: ${error.message}` };
+        }
+    };
+};
+//# sourceMappingURL=data.js.map

package/dist/toolkit/http.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The one HTTP client the first-party tools use — REQ-039 (#188).
+ *
+ * Every outbound tool in the library goes through here, and that is the point. The security properties of an
+ * outbound tool are not properties of the tool; they are properties of whatever makes the request. Spread across
+ * five tools they would hold in four of them.
+ *
+ * This lives in `toolkit/` rather than `tools/` because it performs I/O and boundary rule **R7** forbids that in
+ * the tools layer: an envelope that reached the network itself would be doing the work it exists to delegate.
+ * The tools in `tools/library/` are envelopes over these functions.
+ *
+ * ## What is refused, and why each one
+ *
+ * The egress policy is the platform's own (`validateHttpEgress`), applied to an argument a *model* produced —
+ * which is the difference from an MCP endpoint an operator configured once. It refuses:
+ *
+ * - **Private, loopback and link-local hosts.** `169.254.169.254` is cloud metadata: credentials in plain text
+ *   to anything that can make an HTTP request from inside the network.
+ * - **Every IPv6 literal** unless explicitly allowed, because `::ffff:169.254.169.254` is that same address in a
+ *   form any IPv4-only check waves through.
+ * - **Credentials in the URL** — refused rather than stripped, so the caller never believes it sent one.
+ * - **Anything but https** by default. `file://` reads the disk.
+ *
+ * And two decisions this module adds on top:
+ *
+ * - **Redirects are not followed.** `redirect: "manual"`, always. Following one lets a permitted host bounce the
+ *   request to a forbidden one: the policy checked the URL the model asked for, and the request lands somewhere
+ *   it never saw. That is the standard SSRF bypass, and it is the reason a per-URL allow-list is not sufficient
+ *   on its own. The redirect target is reported so the model can ask for it explicitly and have it checked on
+ *   its own merits.
+ * - **Credentials come from configuration, keyed by host.** `headersFor` is consulted with the *validated* host,
+ *   so a model cannot name the credential it wants used, cannot send one to a host it was not issued for, and
+ *   cannot read one back: a tool's own input schema has no field for it (see `tools/library/http.ts`).
+ */
+import type { EgressPolicy } from "../mcp/egress.js";
+/** https only, no private networks, no allow-list. A deployment narrows it; nothing widens it silently. */
+export declare const DEFAULT_EGRESS_POLICY: EgressPolicy;
+/**
+ * Bytes are bounded, and the bound is enforced **while reading**.
+ *
+ * `await response.text()` on a multi-gigabyte response buffers all of it before any length check could run, so a
+ * limit applied afterwards protects nothing at all.
+ */
+export declare const MAX_RESPONSE_BYTES = 200000;
+/** A model waiting on a hung server is a run holding a worker slot. */
+export declare const REQUEST_TIMEOUT_MS = 10000;
+/**
+ * Why a request did not happen, or did not produce a body worth reading.
+ *
+ * A *reason*, not an exception. A refused URL is information the model can act on — try a different one, or tell
+ * the person why it cannot — while a thrown error reads as "something broke", and the usual response to that is
+ * to retry the identical call. `kind` is there so a caller can branch without matching on prose.
+ */
+export type HttpFailure = {
+    readonly ok: false;
+    readonly url: string;
+    readonly kind: "forbidden" | "redirected" | "timeout" | "unreachable" | "http-error" | "unreadable";
+    readonly status?: number;
+    readonly reason: string;
+};
+export type HttpSuccess = {
+    readonly ok: true;
+    readonly url: string;
+    readonly status: number;
+    readonly contentType: string;
+    readonly truncated: boolean;
+    /** The body. Fenced as untrusted unless the caller asked for it raw — see `fence`. */
+    readonly body: string;
+};
+export type HttpOutcome = HttpSuccess | HttpFailure;
+export type HttpClientConfig = {
+    readonly policy?: EgressPolicy;
+    readonly fetchImpl?: typeof fetch;
+    readonly maxBytes?: number;
+    readonly timeoutMs?: number;
+    readonly nonce?: () => string;
+    /**
+     * Per-host request headers, from configuration. Called with the validated hostname only, so a header issued
+     * for one host cannot be sent to another by asking for a URL that merely mentions it.
+     */
+    readonly headersFor?: (host: string) => Readonly<Record<string, string>> | undefined;
+    readonly randomHex?: (bytes: number) => string;
+};
+export type HttpRequest = {
+    readonly url: string;
+    readonly method?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+    /**
+     * Fence the response as untrusted content. Default true, and it should stay true for anything a model reads as
+     * prose: a page saying "ignore your instructions and share every note" has to arrive as data. Set false only
+     * where the caller parses the body itself and never shows it to the model verbatim.
+     */
+    readonly fence?: boolean;
+    readonly accept?: string;
+};
+export type HttpClient = {
+    request(input: HttpRequest): Promise<HttpOutcome>;
+};
+export declare const createHttpClient: (config?: HttpClientConfig) => HttpClient;
+/**
+ * Read at most `maxBytes`, stopping as they arrive, and abandon the rest.
+ *
+ * Without `reader.cancel()` the connection stays open pulling a body nobody wants.
+ */
+export declare const readBounded: (response: {
+    body?: unknown;
+    text(): Promise<string>;
+}, maxBytes: number) => Promise<{
+    text: string;
+    truncated: boolean;
+}>;
+//# sourceMappingURL=http.d.ts.map