@agent-native/core 0.201.0-nightly-20261005153421 → 0.201.0

package/dist/agent-sql/lexer.js

@@ -0,0 +1,357 @@
+/**
+ * The lexer could not read the SQL the way the database would. Callers must
+ * refuse to run the statement: a guard that skipped what it could not read
+ * would be checking different text from what executes.
+ */
+export class AgentSqlSyntaxError extends Error {
+    code;
+    position;
+    constructor(code, message, position) {
+        super(message);
+        this.name = "AgentSqlSyntaxError";
+        this.code = code;
+        this.position = position;
+    }
+}
+// Postgres also allows a backtick in operator names; agent SQL rejects it
+// because it reads as identifier quoting in other dialects.
+const POSTGRES_OPERATOR_CHARS = new Set("+-*/<>=~!@#%^&|?");
+const BIGQUERY_OPERATOR_CHARS = new Set("+-*/<>=~!%^&|");
+const PUNCTUATION = new Set(["(", ")", "[", "]", ",", ";", ".", ":"]);
+function isIdentStart(ch, dialect) {
+    if (/[A-Za-z_]/.test(ch))
+        return true;
+    // Postgres accepts any non-ASCII letter in an unquoted identifier.
+    return dialect === "postgres" && ch.charCodeAt(0) >= 0x80;
+}
+function isIdentPart(ch, dialect) {
+    if (/[A-Za-z0-9_]/.test(ch))
+        return true;
+    if (dialect === "postgres")
+        return ch === "$" || ch.charCodeAt(0) >= 0x80;
+    return false;
+}
+// Exactly the whitespace Postgres skips. JavaScript's `\s` also matches
+// Unicode spaces, which Postgres reads as identifier characters; treating them
+// as separators would split one database identifier into several tokens.
+const WHITESPACE = new Set([" ", "\t", "\n", "\r", "\f", "\v"]);
+/** Postgres folds only the ASCII letters of unquoted identifiers. */
+function foldAscii(text) {
+    return text.replace(/[A-Z]/g, (ch) => ch.toLowerCase());
+}
+class Scanner {
+    sql;
+    dialect;
+    tokens = [];
+    pos = 0;
+    constructor(sql, dialect) {
+        this.sql = sql;
+        this.dialect = dialect;
+    }
+    peek(offset = 0) {
+        return this.sql[this.pos + offset] ?? "";
+    }
+    push(kind, start, value) {
+        const text = this.sql.slice(start, this.pos);
+        this.tokens.push({
+            kind,
+            text,
+            value: value ?? text,
+            start,
+            end: this.pos,
+        });
+    }
+    fail(code, message, at = this.pos) {
+        throw new AgentSqlSyntaxError(code, message, at);
+    }
+    /** A line comment ends at a line feed or a carriage return, as in Postgres. */
+    skipLineComment() {
+        while (this.pos < this.sql.length &&
+            this.sql[this.pos] !== "\n" &&
+            this.sql[this.pos] !== "\r") {
+            this.pos++;
+        }
+    }
+    skipBlockComment() {
+        const start = this.pos;
+        let depth = 0;
+        while (this.pos < this.sql.length) {
+            if (this.peek() === "/" && this.peek(1) === "*") {
+                // Postgres block comments nest; BigQuery's do not.
+                depth = this.dialect === "postgres" ? depth + 1 : 1;
+                this.pos += 2;
+                continue;
+            }
+            if (this.peek() === "*" && this.peek(1) === "/") {
+                depth--;
+                this.pos += 2;
+                if (depth === 0)
+                    return;
+                continue;
+            }
+            this.pos++;
+        }
+        this.fail("unterminated", "Unterminated block comment.", start);
+    }
+    /** Consumes a quoted run starting at `this.pos` and returns its body. */
+    readQuoted(quote, options, label) {
+        const start = this.pos;
+        this.pos += quote.length;
+        let body = "";
+        while (this.pos < this.sql.length) {
+            const ch = this.sql[this.pos];
+            if (options.backslashEscapes && ch === "\\") {
+                if (this.pos + 1 >= this.sql.length)
+                    break;
+                body += this.sql.slice(this.pos, this.pos + 2);
+                this.pos += 2;
+                continue;
+            }
+            if (this.sql.startsWith(quote, this.pos)) {
+                if (options.doubledQuoteEscapes &&
+                    this.sql.startsWith(quote, this.pos + quote.length)) {
+                    body += quote;
+                    this.pos += quote.length * 2;
+                    continue;
+                }
+                this.pos += quote.length;
+                return body;
+            }
+            body += ch;
+            this.pos++;
+        }
+        this.fail("unterminated", `Unterminated ${label}.`, start);
+    }
+    readWord(start) {
+        while (this.pos < this.sql.length &&
+            isIdentPart(this.peek(), this.dialect)) {
+            this.pos++;
+        }
+        this.push("word", start, foldAscii(this.sql.slice(start, this.pos)));
+    }
+    readNumber(start) {
+        const rest = this.sql.slice(this.pos);
+        const match = /^0[xXoObB][0-9A-Fa-f_]+/.exec(rest) ??
+            /^(?:\d[\d_]*(?:\.[\d_]*)?|\.\d[\d_]*)(?:[eE][+-]?\d[\d_]*)?/.exec(rest);
+        if (!match)
+            this.fail("unexpected_character", "Malformed number.");
+        this.pos += match[0].length;
+        // `1abc` is a lexing error on current Postgres and ambiguous elsewhere.
+        if (isIdentStart(this.peek(), this.dialect)) {
+            this.fail("unsupported_syntax", "A number must not run directly into an identifier.");
+        }
+        this.push("number", start);
+    }
+    readOperator(start, chars) {
+        while (this.pos < this.sql.length && chars.has(this.peek())) {
+            // An operator never contains the start of a comment.
+            const pair = this.peek() + this.peek(1);
+            if (this.pos > start && (pair === "--" || pair === "/*"))
+                break;
+            this.pos++;
+        }
+        if (this.dialect === "postgres") {
+            // Postgres drops a trailing + or - from a multi-character operator
+            // unless the operator contains one of these characters, so `a=-1`
+            // reads as `a = -1`.
+            const text = this.sql.slice(start, this.pos);
+            if (!/[~!@#%^&|`?]/.test(text)) {
+                while (this.pos - start > 1 && /[+-]/.test(this.sql[this.pos - 1])) {
+                    this.pos--;
+                }
+            }
+        }
+        this.push("operator", start);
+    }
+}
+function lexPostgres(s) {
+    while (s.pos < s.sql.length) {
+        const ch = s.peek();
+        const next = s.peek(1);
+        const start = s.pos;
+        if (WHITESPACE.has(ch)) {
+            s.pos++;
+            continue;
+        }
+        if (ch === "-" && next === "-") {
+            s.skipLineComment();
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            s.skipBlockComment();
+            continue;
+        }
+        // U&'...' and U&"..." spell characters as escape codes, so their text
+        // is not the name or value the database sees.
+        if ((ch === "u" || ch === "U") && next === "&") {
+            const quote = s.peek(2);
+            if (quote === "'" || quote === '"') {
+                s.fail("unsupported_syntax", "Unicode-escaped strings and identifiers (U&) are not supported in agent SQL.");
+            }
+        }
+        if ((ch === "e" || ch === "E") && next === "'") {
+            s.pos++;
+            s.readQuoted("'", { backslashEscapes: true, doubledQuoteEscapes: true }, "escape string");
+            s.push("string", start);
+            continue;
+        }
+        if (/[bBxXnN]/.test(ch) && next === "'") {
+            s.pos++;
+            s.readQuoted("'", { backslashEscapes: false, doubledQuoteEscapes: true }, "string");
+            s.push("string", start);
+            continue;
+        }
+        if (ch === "'") {
+            const previous = s.tokens.at(-1);
+            if (previous?.kind === "string" && /^[eE]'/.test(previous.text)) {
+                // PostgreSQL continuation inherits the E prefix across comments and
+                // newlines; reading this as an ordinary string would hide SQL tokens.
+                s.fail("unsupported_syntax", "Continuation after an escape string is not supported in agent SQL.");
+            }
+            s.readQuoted("'", { backslashEscapes: false, doubledQuoteEscapes: true }, "string");
+            s.push("string", start);
+            continue;
+        }
+        if (ch === '"') {
+            const name = s.readQuoted('"', { backslashEscapes: false, doubledQuoteEscapes: true }, "quoted identifier");
+            if (name.length === 0) {
+                s.fail("unsupported_syntax", "Empty quoted identifier.", start);
+            }
+            s.push("quoted-identifier", start, name);
+            continue;
+        }
+        if (ch === "$") {
+            if (/\d/.test(next)) {
+                s.pos++;
+                while (/\d/.test(s.peek()))
+                    s.pos++;
+                s.push("parameter", start);
+                continue;
+            }
+            const tag = /^\$(?:[A-Za-z_\u0080-￿][A-Za-z0-9_\u0080-￿]*)?\$/.exec(s.sql.slice(s.pos));
+            if (!tag) {
+                s.fail("unexpected_character", 'Unexpected "$".');
+            }
+            const end = s.sql.indexOf(tag[0], s.pos + tag[0].length);
+            if (end === -1) {
+                s.fail("unterminated", "Unterminated dollar-quoted string.", start);
+            }
+            s.pos = end + tag[0].length;
+            s.push("string", start);
+            continue;
+        }
+        if (isIdentStart(ch, "postgres")) {
+            s.readWord(start);
+            continue;
+        }
+        if (/\d/.test(ch) || (ch === "." && /\d/.test(next))) {
+            s.readNumber(start);
+            continue;
+        }
+        if (ch === ":" && next === ":") {
+            s.pos += 2;
+            s.push("punctuation", start);
+            continue;
+        }
+        if (PUNCTUATION.has(ch)) {
+            s.pos++;
+            s.push("punctuation", start);
+            continue;
+        }
+        if (ch === "?" && !POSTGRES_OPERATOR_CHARS.has(next)) {
+            s.pos++;
+            s.push("parameter", start);
+            continue;
+        }
+        if (POSTGRES_OPERATOR_CHARS.has(ch)) {
+            s.readOperator(start, POSTGRES_OPERATOR_CHARS);
+            continue;
+        }
+        s.fail("unexpected_character", `Unexpected character "${ch}".`);
+    }
+}
+function lexBigQuery(s) {
+    while (s.pos < s.sql.length) {
+        const ch = s.peek();
+        const next = s.peek(1);
+        const start = s.pos;
+        if (WHITESPACE.has(ch)) {
+            s.pos++;
+            continue;
+        }
+        if (ch === "#" || (ch === "-" && next === "-")) {
+            s.skipLineComment();
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            s.skipBlockComment();
+            continue;
+        }
+        const literal = /^([rRbB]{0,2})('''|"""|'|")/.exec(s.sql.slice(s.pos));
+        if (literal &&
+            /^(?:|[rR]|[bB]|[rR][bB]|[bB][rR])$/.test(literal[1]) &&
+            // A bare prefix letter is an identifier unless a quote follows it.
+            (literal[1].length > 0 || ch === "'" || ch === '"')) {
+            const raw = /[rR]/.test(literal[1]);
+            s.pos += literal[1].length;
+            s.readQuoted(literal[2], { backslashEscapes: !raw, doubledQuoteEscapes: false }, "string");
+            s.push("string", start);
+            continue;
+        }
+        if (ch === "`") {
+            const name = s.readQuoted("`", { backslashEscapes: true, doubledQuoteEscapes: false }, "quoted identifier");
+            if (name.length === 0 || name.includes("\\")) {
+                s.fail("unsupported_syntax", "Empty or escaped backtick identifiers are not supported in agent SQL.", start);
+            }
+            s.push("quoted-identifier", start, name);
+            continue;
+        }
+        if (ch === "@") {
+            s.pos += next === "@" ? 2 : 1;
+            if (!isIdentStart(s.peek(), "bigquery")) {
+                s.fail("unexpected_character", 'Expected a parameter name after "@".');
+            }
+            while (isIdentPart(s.peek(), "bigquery"))
+                s.pos++;
+            s.push("parameter", start);
+            continue;
+        }
+        if (ch === "?") {
+            s.pos++;
+            s.push("parameter", start);
+            continue;
+        }
+        if (isIdentStart(ch, "bigquery")) {
+            s.readWord(start);
+            continue;
+        }
+        if (/\d/.test(ch) || (ch === "." && /\d/.test(next))) {
+            s.readNumber(start);
+            continue;
+        }
+        if (PUNCTUATION.has(ch)) {
+            s.pos++;
+            s.push("punctuation", start);
+            continue;
+        }
+        if (BIGQUERY_OPERATOR_CHARS.has(ch)) {
+            s.readOperator(start, BIGQUERY_OPERATOR_CHARS);
+            continue;
+        }
+        s.fail("unexpected_character", `Unexpected character "${ch}".`);
+    }
+}
+/**
+ * Splits agent-authored SQL into the tokens the target database will see.
+ * Comments and whitespace are dropped; everything else is kept with its
+ * source offsets. Throws {@link AgentSqlSyntaxError} for anything the lexer
+ * cannot read the same way the database does.
+ */
+export function lexAgentSql(sql, options) {
+    const scanner = new Scanner(sql, options.dialect);
+    if (options.dialect === "postgres")
+        lexPostgres(scanner);
+    else
+        lexBigQuery(scanner);
+    return scanner.tokens;
+}

package/dist/agent-sql/postgres.d.ts

@@ -0,0 +1,51 @@
+import { type AgentSqlToken } from "./lexer.js";
+export type AgentSqlPolicyErrorCode = "unreadable" | "empty" | "multiple_statements" | "refused";
+/**
+ * Agent SQL was refused by policy. The message is written for the agent: it
+ * says what was refused and what to do instead. `code` lets a caller word the
+ * structural cases in its own terms.
+ */
+export declare class AgentSqlPolicyError extends Error {
+    readonly code: AgentSqlPolicyErrorCode;
+    constructor(message: string, code?: AgentSqlPolicyErrorCode);
+}
+export interface AgentPostgresStatement {
+    /**
+     * The statement text from its first token to its last, so a trailing
+     * semicolon or comment is gone and appended text cannot be swallowed.
+     */
+    sql: string;
+    tokens: AgentSqlToken[];
+    /** Lower-case leading keyword, ignoring leading parentheses. */
+    keyword: string | null;
+}
+/**
+ * Reads exactly one Postgres statement the way the database will. Throws
+ * {@link AgentSqlPolicyError} for text the lexer cannot read, an empty input,
+ * or more than one statement.
+ */
+export declare function readAgentPostgresStatement(sql: string): AgentPostgresStatement;
+/**
+ * Checks that need only the statement's tokens. Run them on every statement
+ * before it reaches the database, and again on the final executed text.
+ */
+export declare function assertAgentPostgresExpressionTokenPolicy(statement: AgentPostgresStatement): void;
+/** Includes the schema-qualification restrictions needed by raw DB tools. */
+export declare function assertAgentPostgresTokenPolicy(statement: AgentPostgresStatement): void;
+export interface AgentSqlQueryRunner {
+    unsafe(sql: string, args?: unknown[]): Promise<unknown[]>;
+}
+/**
+ * Checks expression resolution inside the executing transaction. Callers
+ * must separately scope relation reads; this check does not require temp
+ * views. Conversions can invoke a type's input routines or domain checks,
+ * including those nested inside a temporary view's composite row type.
+ */
+export declare function verifyAgentPostgresExpressions(db: AgentSqlQueryRunner, statement: AgentPostgresStatement): Promise<void>;
+/**
+ * Checks expression and relation resolution in the executing transaction,
+ * after the per-user temporary views exist. Every resolved relation must
+ * belong to this session's temp schema; qualifiers cannot name a schema or
+ * this database.
+ */
+export declare function verifyAgentPostgresResolution(db: AgentSqlQueryRunner, statement: AgentPostgresStatement): Promise<void>;

package/dist/agent-sql/postgres.js

@@ -0,0 +1,197 @@
+import { agentSqlIdentifierNames, agentSqlQualifiedReferences, agentSqlTypeNames, leadingAgentSqlKeyword, splitAgentSqlStatements, } from "./analysis.js";
+import { AgentSqlSyntaxError, lexAgentSql, } from "./lexer.js";
+/**
+ * Agent SQL was refused by policy. The message is written for the agent: it
+ * says what was refused and what to do instead. `code` lets a caller word the
+ * structural cases in its own terms.
+ */
+export class AgentSqlPolicyError extends Error {
+    code;
+    constructor(message, code = "refused") {
+        super(message);
+        this.name = "AgentSqlPolicyError";
+        this.code = code;
+    }
+}
+function refuse(message, code = "refused") {
+    throw new AgentSqlPolicyError(message, code);
+}
+/**
+ * Reads exactly one Postgres statement the way the database will. Throws
+ * {@link AgentSqlPolicyError} for text the lexer cannot read, an empty input,
+ * or more than one statement.
+ */
+export function readAgentPostgresStatement(sql) {
+    let tokens;
+    try {
+        tokens = lexAgentSql(sql, { dialect: "postgres" });
+    }
+    catch (error) {
+        if (error instanceof AgentSqlSyntaxError) {
+            refuse(`The SQL could not be read safely: ${error.message}`, "unreadable");
+        }
+        throw error;
+    }
+    const statements = splitAgentSqlStatements(tokens);
+    if (statements.length === 0)
+        refuse("The SQL is empty.", "empty");
+    if (statements.length > 1) {
+        refuse("The SQL contains more than one statement. Send one statement at a time.", "multiple_statements");
+    }
+    const [statementTokens] = statements;
+    return {
+        sql: sql.slice(statementTokens[0].start, statementTokens[statementTokens.length - 1].end),
+        tokens: statementTokens,
+        keyword: leadingAgentSqlKeyword(statementTokens),
+    };
+}
+// Postgres truncates longer identifiers to this many bytes, so a longer name
+// could resolve to an object whose name does not match it textually.
+const MAX_IDENTIFIER_BYTES = 63;
+// Schemas that hold base tables or catalogs. A name qualified with one of them
+// skips the per-user views, which only shadow unqualified names. The
+// in-transaction check below also catches every other schema in the database.
+// `main` is SQLite's schema name, kept so ported SQL gets the same answer.
+const KNOWN_SCHEMA_RE = /^(?:public|main|pg_catalog|information_schema|pg_toast|pg_temp|pg_temp_\d+|pg_toast_temp_\d+)$/i;
+// Built-in functions that run SQL text, read or change server or session
+// state, or reach outside the database. Matched against every identifier, not
+// only called names, because Postgres also resolves `row.fn` as `fn(row)`.
+const DENIED_IDENTIFIER_RES = [
+    // Catalog functions and relations. A short allowlist below keeps the
+    // harmless type and size helpers usable.
+    /^pg_/i,
+    // Large-object functions read and write server-side files and objects.
+    /^lo_/i,
+    // dblink opens a new connection that runs arbitrary SQL.
+    /^dblink/i,
+    // query_to_xml, table_to_xml, schema_to_xml, ... run or dump SQL by name.
+    /_to_xml/i,
+    /^(?:set_config|current_setting|nextval|currval|lastval|setval|ts_stat|ts_rewrite)$/i,
+    // These helpers convert fields using a supplied row type or type OID,
+    // which can invoke app-defined input routines and domain checks.
+    /^jsonb?_(?:populate_record(?:set|_valid)?|to_record(?:set)?)$/i,
+    /^(?:array|domain|record|range|multirange)_(?:in|recv)$/i,
+];
+const ALLOWED_PG_IDENTIFIERS = new Set([
+    "pg_typeof",
+    "pg_column_size",
+    "pg_size_pretty",
+]);
+/**
+ * Checks that need only the statement's tokens. Run them on every statement
+ * before it reaches the database, and again on the final executed text.
+ */
+export function assertAgentPostgresExpressionTokenPolicy(statement) {
+    for (const [index, token] of statement.tokens.entries()) {
+        if (token.kind !== "word" && token.kind !== "quoted-identifier")
+            continue;
+        if (Buffer.byteLength(token.value, "utf8") > MAX_IDENTIFIER_BYTES) {
+            refuse(`Identifier "${token.value.slice(0, 20)}…" is longer than ${MAX_IDENTIFIER_BYTES} bytes.`);
+        }
+        if (token.value === "pg_catalog" &&
+            statement.tokens[index + 1]?.text === ".") {
+            continue;
+        }
+        const value = token.value.toLowerCase();
+        if (ALLOWED_PG_IDENTIFIERS.has(value))
+            continue;
+        if (DENIED_IDENTIFIER_RES.some((re) => re.test(value))) {
+            refuse(`"${token.value}" is not available in agent SQL. Query the app's tables by their bare names.`);
+        }
+    }
+}
+/** Includes the schema-qualification restrictions needed by raw DB tools. */
+export function assertAgentPostgresTokenPolicy(statement) {
+    assertAgentPostgresExpressionTokenPolicy(statement);
+    for (const reference of agentSqlQualifiedReferences(statement.tokens)) {
+        if (reference.qualifiers.length > 1) {
+            refuse(`"${[...reference.qualifiers, reference.name].join(".")}" names a database or schema. Use bare table names; the current user's scoping is applied automatically.`);
+        }
+        if (KNOWN_SCHEMA_RE.test(reference.qualifiers[0])) {
+            refuse(`Schema-qualified names such as "${reference.qualifiers[0]}.${reference.name}" bypass the per-user data scoping. Use the bare table name; the current user's scoping is applied automatically.`);
+        }
+    }
+}
+/**
+ * Checks expression resolution inside the executing transaction. Callers
+ * must separately scope relation reads; this check does not require temp
+ * views. Conversions can invoke a type's input routines or domain checks,
+ * including those nested inside a temporary view's composite row type.
+ */
+export async function verifyAgentPostgresExpressions(db, statement) {
+    assertAgentPostgresExpressionTokenPolicy(statement);
+    const [setting] = (await db.unsafe("SELECT pg_catalog.current_setting('standard_conforming_strings') AS value"));
+    if (setting?.value !== "on") {
+        refuse("Agent SQL requires standard_conforming_strings to be on for this database connection.");
+    }
+    const names = [...agentSqlIdentifierNames(statement.tokens)];
+    const typeNames = [...agentSqlTypeNames(statement.tokens)];
+    if (typeNames.length > 0) {
+        const types = (await db.unsafe(`SELECT t.typname AS name
+       FROM pg_catalog.pg_type t
+       JOIN pg_catalog.pg_namespace ns ON ns.oid = t.typnamespace
+      WHERE t.typname = ANY($1::text[])
+        AND ns.nspname <> 'pg_catalog'
+      LIMIT 1`, [typeNames]));
+        if (types.length > 0) {
+            refuse(`"${types[0].name}" is not a built-in type, so agent SQL cannot convert values to it.`);
+        }
+    }
+    const routines = (await db.unsafe(`SELECT p.proname AS name
+       FROM pg_catalog.pg_proc p
+       JOIN pg_catalog.pg_namespace ns ON ns.oid = p.pronamespace
+      WHERE p.proname = ANY($1::text[])
+        AND ns.nspname <> 'pg_catalog'
+      LIMIT 1`, [names]));
+    if (routines.length > 0) {
+        refuse(`"${routines[0].name}" matches an app-defined database function, which agent SQL cannot call.`);
+    }
+    const operators = [
+        ...new Set(statement.tokens
+            .filter((token) => token.kind === "operator")
+            .map((token) => token.text)),
+    ];
+    if (operators.length > 0) {
+        const appOperators = (await db.unsafe(`SELECT o.oprname AS name
+         FROM pg_catalog.pg_operator o
+         JOIN pg_catalog.pg_namespace ns ON ns.oid = o.oprnamespace
+        WHERE o.oprname = ANY($1::text[])
+          AND ns.nspname <> 'pg_catalog'
+        LIMIT 1`, [operators]));
+        if (appOperators.length > 0) {
+            refuse(`Operator "${appOperators[0].name}" is backed by an app-defined database function, which agent SQL cannot call.`);
+        }
+    }
+}
+/**
+ * Checks expression and relation resolution in the executing transaction,
+ * after the per-user temporary views exist. Every resolved relation must
+ * belong to this session's temp schema; qualifiers cannot name a schema or
+ * this database.
+ */
+export async function verifyAgentPostgresResolution(db, statement) {
+    assertAgentPostgresTokenPolicy(statement);
+    await verifyAgentPostgresExpressions(db, statement);
+    const names = [...agentSqlIdentifierNames(statement.tokens)];
+    if (names.length === 0)
+        return;
+    const qualifiers = [
+        ...new Set(agentSqlQualifiedReferences(statement.tokens).flatMap((reference) => reference.qualifiers)),
+    ];
+    if (qualifiers.length > 0) {
+        const schemas = (await db.unsafe(`SELECT nspname AS name FROM pg_catalog.pg_namespace WHERE nspname = ANY($1::text[])
+       UNION ALL
+       SELECT pg_catalog.current_database() WHERE pg_catalog.current_database() = ANY($1::text[])`, [qualifiers]));
+        if (schemas.length > 0) {
+            refuse(`"${schemas[0].name}" names a schema or database. Use bare table names; the current user's scoping is applied automatically.`);
+        }
+    }
+    const relations = (await db.unsafe(`SELECT n.name
+       FROM pg_catalog.unnest($1::text[]) AS n(name)
+       JOIN pg_catalog.pg_class c
+         ON c.oid = pg_catalog.to_regclass(pg_catalog.quote_ident(n.name))
+      WHERE c.relnamespace IS DISTINCT FROM pg_catalog.pg_my_temp_schema()`, [names]));
+    if (relations.length > 0) {
+        refuse(`"${relations[0].name}" is not one of the app's tables scoped to the current user, so agent SQL cannot read or write it.`);
+    }
+}

package/dist/agent-sql/query.d.ts

@@ -0,0 +1,30 @@
+import { type AgentSqlDialect, type AgentSqlToken } from "./lexer.js";
+export interface AgentSqlQueryCte {
+    name: string;
+    quoted: boolean;
+    start: number;
+    end: number;
+}
+export interface AgentSqlQuerySource extends AgentSqlQueryCte {
+    qualifiers: string[];
+    cte: boolean;
+    commaSeparated: boolean;
+    modifiers: ("only" | "lateral")[];
+    alias?: {
+        name: string;
+        quoted: boolean;
+    };
+}
+export interface AgentSqlQuery {
+    sql: string;
+    dialect: AgentSqlDialect;
+    tokens: AgentSqlToken[];
+    sources: AgentSqlQuerySource[];
+    ctes: AgentSqlQueryCte[];
+}
+/** Reads sources in a bounded SELECT grammar; unsupported source syntax throws. */
+export declare function readAgentSqlQuery(sql: string, options: {
+    dialect: AgentSqlDialect;
+}): AgentSqlQuery;
+/** Replaces only analyzed source-name spans, preserving all other source text. */
+export declare function rewriteAgentSqlQuerySources(query: AgentSqlQuery, replacer: (source: AgentSqlQuerySource) => string): string;