nexus-ai-pro 2.2.0 → 2.3.0

package/dist-cjs/deep-agent/index.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeepAgent = createDeepAgent;
+const create_agent_js_1 = require("../agent/create-agent.js");
+const context_editor_js_1 = require("../agent/middleware/context-editor.js");
+const filesystem_js_1 = require("../agent/middleware/filesystem.js");
+const tool_selector_js_1 = require("../agent/middleware/tool-selector.js");
+const permissions_js_1 = require("../agent/permissions.js");
+const sandbox_js_1 = require("../agent/sandbox.js");
+const tool_js_1 = require("../agent/tool.js");
+const MOUNT = '/workspace';
+const CORE_TOOLS = [
+    'write_todos',
+    'delegate',
+    'load_skill',
+    'read_file',
+    'write_file',
+    'edit_file',
+    'list_files',
+    'run_command',
+];
+function createDeepAgent(options) {
+    const { instructions, sandbox, commands = [], planning = true, subagents = [], skills = [], include = ['AGENTS.md'], offload, contextEditing, toolSelection, permissions, middleware = [], tools: extraTools = [], ...agentOptions } = options;
+    const workspace = sandbox
+        ? [...(0, sandbox_js_1.sandboxTools)(sandbox, { shell: commands.length > 0, mount: MOUNT }), editFileTool(sandbox)]
+        : [];
+    const own = [
+        ...(planning ? [writeTodosTool()] : []),
+        ...(skills.length > 0 ? [loadSkillTool(skills, sandbox)] : []),
+        ...workspace,
+        ...extraTools,
+    ];
+    const helpers = new Map();
+    const approved = new Set(Object.keys(agentOptions.interruptOn ?? {}));
+    const { interruptOn: _approvals, ...helperOptions } = agentOptions;
+    for (const helper of subagents) {
+        const allowed = helper.tools ? new Set(helper.tools) : undefined;
+        helpers.set(helper.name, (0, create_agent_js_1.createAgent)({
+            ...helperOptions,
+            name: `${options.name ?? 'deep-agent'}.${helper.name}`,
+            ...(helper.model ? { model: helper.model } : {}),
+            maxIterations: helper.maxIterations ?? 20,
+            systemPrompt: `${helper.instructions}\n\n${WORKSPACE_NOTE}`,
+            tools: own.filter((candidate) => !approved.has(candidate.name) && (allowed ? allowed.has(candidate.name) : true)),
+            ...(permissions === false ? {} : { permissions: permissions ?? defaultPolicy(commands) }),
+            checkpointer: false,
+        }));
+    }
+    const tools = [...own, ...(helpers.size > 0 ? [delegateTool(subagents, helpers)] : [])];
+    const kit = [
+        ...(sandbox && (include.length > 0 || offload !== false)
+            ? [
+                (0, filesystem_js_1.filesystemContext)({
+                    source: sandbox,
+                    include,
+                    ...(offload === false ? {} : { offload: { overChars: 20_000, ...offload } }),
+                }),
+            ]
+            : []),
+        ...(contextEditing === false
+            ? []
+            : [
+                (0, context_editor_js_1.contextEditor)({
+                    triggerTokens: 60_000,
+                    ...contextEditing,
+                    exclude: ['write_todos', ...(contextEditing?.exclude ?? [])],
+                }),
+            ]),
+        ...(toolSelection
+            ? [(0, tool_selector_js_1.toolSelector)({ ...toolSelection, always: [...CORE_TOOLS, ...(toolSelection.always ?? [])] })]
+            : []),
+    ];
+    return (0, create_agent_js_1.createAgent)({
+        maxIterations: 40,
+        ...agentOptions,
+        systemPrompt: systemPrompt(instructions, { planning, sandbox: Boolean(sandbox), commands, subagents, skills }),
+        tools,
+        middleware: [...kit, ...middleware],
+        ...(permissions === false ? {} : { permissions: permissions ?? defaultPolicy(commands) }),
+    });
+}
+function defaultPolicy(commands) {
+    return (0, permissions_js_1.permissionPolicy)({
+        filesystem: { write: [`${MOUNT}/**`] },
+        shell: { allow: commands },
+        tools: { write_todos: 'allow', delegate: 'allow', load_skill: 'allow' },
+    });
+}
+const WORKSPACE_NOTE = `Files live in ${MOUNT}; paths are relative to it.`;
+function systemPrompt(instructions, parts) {
+    const lines = [];
+    if (instructions)
+        lines.push(instructions, '');
+    lines.push('Work through the task step by step, checking each step before the next.');
+    if (parts.planning) {
+        lines.push('For any task of more than two steps, first record a plan with write_todos, then keep it current: mark a step in_progress when you start it and completed when it is done.');
+    }
+    if (parts.sandbox) {
+        lines.push(`${WORKSPACE_NOTE} Read before you change a file; prefer edit_file to rewriting a whole file. A large result may be saved to a file and shown as a preview: read the file when you need the rest.`);
+        if (parts.commands.length > 0)
+            lines.push(`You may run these commands: ${parts.commands.join(', ')}.`);
+    }
+    if (parts.subagents.length > 0) {
+        lines.push('', 'Delegate a self-contained piece of work with delegate, to one of:');
+        for (const helper of parts.subagents)
+            lines.push(`- ${helper.name}: ${helper.description}`);
+    }
+    if (parts.skills.length > 0) {
+        lines.push('', 'Skills you can load with load_skill when a task calls for one:');
+        for (const skill of parts.skills)
+            lines.push(`- ${skill.name}: ${skill.description}`);
+    }
+    return lines.join('\n');
+}
+function writeTodosTool() {
+    return (0, tool_js_1.tool)({
+        name: 'write_todos',
+        description: 'Records the plan for this task as a list of steps, each pending, in_progress, or completed. Send the whole list each time.',
+        parameters: {
+            type: 'object',
+            properties: {
+                todos: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            content: { type: 'string' },
+                            status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] },
+                        },
+                        required: ['content', 'status'],
+                    },
+                },
+            },
+            required: ['todos'],
+        },
+        capabilities: [],
+        execute: ({ todos }) => {
+            const list = Array.isArray(todos) ? todos : [];
+            const mark = { pending: '[ ]', in_progress: '[~]', completed: '[x]' };
+            const done = list.filter((todo) => todo.status === 'completed').length;
+            return `Plan (${done}/${list.length} done):\n${list.map((todo) => `${mark[todo.status] ?? '[ ]'} ${todo.content}`).join('\n')}`;
+        },
+    });
+}
+function editFileTool(sandbox) {
+    const local = (file) => String(file ?? '')
+        .replace(/\\/g, '/')
+        .replace(new RegExp(`^${MOUNT}/`), '')
+        .replace(/^\/+/, '');
+    return (0, tool_js_1.tool)({
+        name: 'edit_file',
+        description: `Replaces one exact occurrence of old_text with new_text in a file. Paths are relative to ${MOUNT}.`,
+        parameters: {
+            type: 'object',
+            properties: { path: { type: 'string' }, old_text: { type: 'string' }, new_text: { type: 'string' } },
+            required: ['path', 'old_text', 'new_text'],
+        },
+        capabilities: (args) => [`filesystem:write:${MOUNT}/${local(args.path)}`],
+        execute: async ({ path, old_text: oldText, new_text: newText }) => {
+            const file = local(path);
+            const text = await sandbox.readFile(file);
+            const count = text.split(String(oldText)).length - 1;
+            if (count === 0)
+                throw new Error(`old_text was not found in ${file}`);
+            if (count > 1)
+                throw new Error(`old_text appears ${count} times in ${file}; include more context so it appears once`);
+            await sandbox.writeFile(file, text.replace(String(oldText), () => String(newText)));
+            return { edited: file };
+        },
+    });
+}
+function loadSkillTool(skills, sandbox) {
+    const byName = new Map(skills.map((skill) => [skill.name, skill]));
+    return (0, tool_js_1.tool)({
+        name: 'load_skill',
+        description: 'Loads the instructions of a skill by name.',
+        parameters: {
+            type: 'object',
+            properties: { name: { type: 'string', enum: skills.map((skill) => skill.name) } },
+            required: ['name'],
+        },
+        capabilities: [],
+        execute: async ({ name }) => {
+            const skill = byName.get(String(name));
+            if (!skill)
+                throw new Error(`No skill named "${String(name)}"`);
+            if (skill.instructions !== undefined)
+                return skill.instructions;
+            if (skill.file && sandbox)
+                return sandbox.readFile(skill.file);
+            throw new Error(`Skill "${skill.name}" has no instructions`);
+        },
+    });
+}
+function delegateTool(subagents, helpers) {
+    return (0, tool_js_1.tool)({
+        name: 'delegate',
+        description: 'Hands a self-contained task to a helper, which works in a fresh context and returns its answer.',
+        parameters: {
+            type: 'object',
+            properties: {
+                agent: { type: 'string', enum: subagents.map((helper) => helper.name) },
+                task: { type: 'string', description: 'Everything the helper needs to know: it sees nothing else.' },
+            },
+            required: ['agent', 'task'],
+        },
+        capabilities: [],
+        execute: async ({ agent, task }, context) => {
+            const helper = helpers.get(String(agent));
+            if (!helper)
+                throw new Error(`No helper named "${String(agent)}"`);
+            const result = await helper.invoke((0, create_agent_js_1.agentInput)(String(task)), {
+                ...(context.principal ? { principal: context.principal } : {}),
+                ...(context.signal ? { signal: context.signal } : {}),
+            });
+            return (result.state.answer || `The ${String(agent)} helper finished without an answer (${result.state.stopReason}).`);
+        },
+    });
+}

package/dist-cjs/graph/functional.d.ts

@@ -1,4 +1,5 @@
 import type { OperationLifecycleLike } from '../types/lifecycle.js';
+import type { Principal } from '../types/principal.js';
 import { GraphError } from './errors.js';
 import type { GraphCheckpoint, GraphCheckpointer, GraphDescription, GraphEvent, GraphStatus, InterruptRequest, PendingInterrupt, RetryPolicy, RunControlLike } from '../types/graph.js';
 import type { Store } from '../types/store.js';
@@ -86,6 +87,8 @@ export interface WorkflowContext {
     readonly threadId: string;
     /** The tenant the run is for, when it has one. */
     readonly tenantId?: string;
+    /** Who the run is for, when it was started with a principal: the caller the server authenticated. */
+    readonly principal?: Readonly<Principal>;
     /** Aborted when the run is cancelled. */
     readonly signal: AbortSignal;
     /** Long-term memory, when the workflow was created with a store. In a tenant's run, the tenant's view of it. */
@@ -162,6 +165,12 @@ export interface WorkflowRunOptions {
      * without one carries on the thread's.
      */
     tenantId?: string;
+    /**
+     * Who the run is for, read as `context.principal`. Its `tenantId` is the run's tenant when
+     * `tenantId` is not given, and a run whose two tenants differ is refused; its `userId` is recorded
+     * on every checkpoint as `metadata.userId`.
+     */
+    principal?: Principal;
 }
 /** One event of a streamed workflow run. */
 export type WorkflowEvent<O = unknown> = {

package/dist-cjs/graph/functional.js

@@ -6,6 +6,7 @@ const checkpointer_js_1 = require("./checkpointer.js");
 const run_js_1 = require("../lifecycle/run.js");
 const checkpoint_migration_js_1 = require("./checkpoint-migration.js");
 const tenant_js_1 = require("../store/tenant.js");
+const tenant_js_2 = require("../utils/tenant.js");
 const errors_js_1 = require("./errors.js");
 class WorkflowStepTimeoutError extends errors_js_1.GraphError {
     stepName;
@@ -57,9 +58,10 @@ class Workflow {
         const threadId = runOptions.threadId ?? generatedId();
         return this.execute(threadId, runOptions, async () => {
             const latest = await this.latest(threadId);
-            if (latest && runOptions.tenantId !== undefined) {
+            const tenantId = runOptions.tenantId ?? runOptions.principal?.tenantId;
+            if (latest && tenantId !== undefined) {
                 const owner = latest.metadata?.tenantId;
-                if (typeof owner === 'string' && owner !== runOptions.tenantId) {
+                if (typeof owner === 'string' && owner !== tenantId) {
                     throw new errors_js_1.GraphError(`Thread "${threadId}" cannot be used by this tenant; choose another id`, 'GRAPH_VALIDATION_ERROR');
                 }
             }
@@ -153,7 +155,21 @@ class Workflow {
     }
     execute(threadId, runOptions, start) {
         const queue = new EventQueue();
-        void (0, run_js_1.withLifecycle)(this.options.lifecycle, { family: 'graph', operation: `workflow.${this.name}`, metadata: { threadId, graph: this.name } }, runOptions.signal ? { signal: runOptions.signal } : {}, () => this.run(threadId, runOptions, start, queue)).then(() => queue.close(), (error) => queue.fail(error));
+        let options;
+        try {
+            options = (0, tenant_js_2.withPrincipal)(runOptions);
+        }
+        catch (error) {
+            queue.fail(error);
+            return queue;
+        }
+        const metadata = {
+            threadId,
+            graph: this.name,
+            ...(options.tenantId !== undefined ? { tenantId: options.tenantId } : {}),
+            ...(options.principal?.userId !== undefined ? { userId: options.principal.userId } : {}),
+        };
+        void (0, run_js_1.withLifecycle)(this.options.lifecycle, { family: 'graph', operation: `workflow.${this.name}`, metadata }, options.signal ? { signal: options.signal } : {}, () => this.run(threadId, options, start, queue)).then(() => queue.close(), (error) => queue.fail(error));
         return queue;
     }
     async run(threadId, runOptions, start, queue) {
@@ -208,6 +224,7 @@ class Workflow {
         const context = {
             threadId,
             ...(tenantId === undefined ? {} : { tenantId }),
+            ...(runOptions.principal ? { principal: runOptions.principal } : {}),
             signal: controller.signal,
             ...(this.options.store
                 ? { store: tenantId === undefined ? this.options.store : (0, tenant_js_1.tenantStore)(this.options.store, tenantId) }

package/dist-cjs/graph/graph.js

@@ -38,6 +38,7 @@ exports.createGraph = createGraph;
 const node_crypto_1 = require("node:crypto");
 const graph_js_1 = require("../types/graph.js");
 const tenant_js_1 = require("../store/tenant.js");
+const tenant_js_2 = require("../utils/tenant.js");
 const signals_js_1 = require("../utils/signals.js");
 const checkpointer_js_1 = require("./checkpointer.js");
 const checkpoint_migration_js_1 = require("./checkpoint-migration.js");
@@ -190,9 +191,10 @@ class CompiledGraph {
         const threadId = resolveThreadId(runOptions.threadId);
         return this.run(threadId, runOptions, async () => {
             this.assertInput(input);
-            if (runOptions.tenantId !== undefined) {
+            const tenantId = runOptions.tenantId ?? runOptions.principal?.tenantId;
+            if (tenantId !== undefined) {
                 const existing = await this.checkpointer()?.get(threadId);
-                if (existing && !ownedBy(existing, runOptions.tenantId)) {
+                if (existing && !ownedBy(existing, tenantId)) {
                     throw new errors_js_1.GraphValidationError(`Thread "${threadId}" cannot be used by this tenant; choose another id`);
                 }
             }
@@ -304,6 +306,8 @@ class CompiledGraph {
             const runOptions = {
                 threadId: `${context.threadId}:${context.taskId}`,
                 signal: context.signal,
+                ...(context.tenantId !== undefined ? { tenantId: context.tenantId } : {}),
+                ...(context.principal ? { principal: context.principal } : {}),
                 ...(forward ? { onEvent: forward, subgraphEvents: true } : {}),
             };
             const paused = await this.state(runOptions.threadId);
@@ -347,7 +351,7 @@ class CompiledGraph {
     describe() {
         const nodes = [...this.nodes.entries()].map(([id, definition]) => {
             const subgraph = definition.fn[SUBGRAPH];
-            const { ends, defer, timeoutMs, cache, idempotent } = definition.options;
+            const { ends, defer, timeoutMs, cache, idempotent, effects, interrupts } = definition.options;
             const maxAttempts = this.retryPolicy(definition).maxAttempts;
             const timeout = this.timeoutOf(definition);
             return {
@@ -360,6 +364,8 @@ class CompiledGraph {
                 ...(this.errorHandler(definition) ? { onError: true } : {}),
                 ...(idempotent ? { idempotent: true } : {}),
                 ...(cache ? { cache: true } : {}),
+                ...(effects?.length ? { effects: [...effects] } : {}),
+                ...(interrupts ? { interrupts: true } : {}),
                 ...(subgraph ? { subgraph: subgraph.describe() } : {}),
             };
         });
@@ -396,6 +402,14 @@ class CompiledGraph {
             durability: this.options.durability ?? 'sync',
             checkpointer: this.options.checkpointer === false ? 'none' : this.options.checkpointer === undefined ? 'memory' : 'custom',
             maxConcurrency: this.options.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY,
+            ...(this.options.tools?.length
+                ? {
+                    tools: this.options.tools.map((tool) => ({
+                        ...tool,
+                        ...(tool.capabilities ? { capabilities: [...tool.capabilities] } : {}),
+                    })),
+                }
+                : {}),
         };
     }
     async updateState(threadId, update, options = {}) {
@@ -456,6 +470,7 @@ class CompiledGraph {
         return forkId;
     }
     async *run(threadId, runOptions, seed) {
+        runOptions = (0, tenant_js_2.withPrincipal)(runOptions);
         const lifecycle = this.options.lifecycle;
         if (!lifecycle) {
             yield* this.runSteps(threadId, runOptions, seed);
@@ -464,7 +479,12 @@ class CompiledGraph {
         const ticket = await lifecycle.start({
             family: this.options.lifecycleFamily ?? 'graph',
             operation: this.options.name ? `${this.options.lifecycleFamily ?? 'graph'}.${this.options.name}` : 'graph.run',
-            metadata: { threadId, ...(this.options.name ? { graph: this.options.name } : {}) },
+            metadata: {
+                threadId,
+                ...(this.options.name ? { graph: this.options.name } : {}),
+                ...(runOptions.tenantId !== undefined ? { tenantId: runOptions.tenantId } : {}),
+                ...(runOptions.principal?.userId !== undefined ? { userId: runOptions.principal.userId } : {}),
+            },
         }, runOptions.signal ? { signal: runOptions.signal } : {});
         let last;
         let settled = false;
@@ -888,6 +908,7 @@ class CompiledGraph {
             step,
             threadId,
             ...(runOptions.tenantId !== undefined ? { tenantId: runOptions.tenantId } : {}),
+            ...(runOptions.principal ? { principal: runOptions.principal } : {}),
             taskId: task.id,
             input: task.input,
             attempt,

package/dist-cjs/graph/lint.d.ts

@@ -2,7 +2,7 @@ import type { GraphDescription } from '../types/graph.js';
 /** How much a lint finding matters: `error` fails `nexus graph lint`, the others only report. */
 export type GraphLintSeverity = 'error' | 'warning' | 'info';
 /** The rules `lintGraph()` checks. */
-export type GraphLintCode = 'UNBOUNDED_CYCLE' | 'RETRY_WITHOUT_IDEMPOTENCY' | 'RETRY_WITHOUT_TIMEOUT' | 'DEFERRED_DURABILITY_WITH_SIDE_EFFECTS' | 'MEMORY_CHECKPOINTER' | 'NO_CHECKPOINTER' | 'UNBOUNDED_CONCURRENCY' | 'DYNAMIC_ROUTE';
+export type GraphLintCode = 'UNBOUNDED_CYCLE' | 'RETRY_WITHOUT_IDEMPOTENCY' | 'RETRY_WITHOUT_TIMEOUT' | 'DEFERRED_DURABILITY_WITH_SIDE_EFFECTS' | 'MEMORY_CHECKPOINTER' | 'NO_CHECKPOINTER' | 'UNBOUNDED_CONCURRENCY' | 'DYNAMIC_ROUTE' | 'SENSITIVE_TOOL_WITHOUT_APPROVAL' | 'UNDECLARED_TOOL_CAPABILITIES' | 'SIDE_EFFECT_BEFORE_INTERRUPT';
 /** One design problem `lintGraph()` found. */
 export interface GraphLintFinding {
     /** Which rule found it. */
@@ -43,6 +43,9 @@ export interface GraphLintOptions {
  * | `NO_CHECKPOINTER` | info | No checkpoints, so no interrupt, resume, or recovery |
  * | `UNBOUNDED_CONCURRENCY` | warning | A fan-out with no limit on tasks at once |
  * | `DYNAMIC_ROUTE` | info | A router with no mapping or `ends`, so routes cannot be checked |
+ * | `SENSITIVE_TOOL_WITHOUT_APPROVAL` | warning, or error when `deployed` | A tool that writes, runs commands or code, or reaches the network, with no approval and no permission policy |
+ * | `UNDECLARED_TOOL_CAPABILITIES` | info | A tool with no capabilities and no approval, whose effects cannot be judged |
+ * | `SIDE_EFFECT_BEFORE_INTERRUPT` | warning | A node that declares effects and interrupts, so its effects repeat when it runs again on the answer |
  *
  * @example
  * ```ts

package/dist-cjs/graph/lint.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.lintGraph = lintGraph;
+const capabilities_js_1 = require("../agent/capabilities.js");
 function lintGraph(graph, options = {}) {
     const description = 'describe' in graph && typeof graph.describe === 'function' ? graph.describe() : graph;
     const findings = [];
@@ -42,9 +43,43 @@ function lintDescription(description, prefix, options, findings, top) {
                 fix: 'Set `timeout: { runMs }`, or `idleMs` with `context.heartbeat()` for long work.',
             });
         }
+        if (node.effects?.length && node.interrupts && !node.idempotent) {
+            findings.push({
+                code: 'SIDE_EFFECT_BEFORE_INTERRUPT',
+                severity: 'warning',
+                node: at(node.id),
+                message: `"${at(node.id)}" declares effects (${node.effects.join(', ')}) and may interrupt, so when the answer comes the node runs again from the top and repeats whatever it did before asking.`,
+                fix: 'Ask in a node of its own before the effect, or give the effect an idempotency key and declare the node idempotent.',
+            });
+        }
         if (node.subgraph)
             lintDescription(node.subgraph, `${at(node.id)}/`, options, findings, false);
     }
+    for (const tool of description.tools ?? []) {
+        if (tool.approval !== 'none')
+            continue;
+        const sensitive = (tool.capabilities ?? []).filter((capability) => (0, capabilities_js_1.isSensitiveCapability)(capability));
+        if (sensitive.length > 0 || tool.dynamic) {
+            findings.push({
+                code: 'SENSITIVE_TOOL_WITHOUT_APPROVAL',
+                severity: options.deployed ? 'error' : 'warning',
+                node: `tool:${tool.name}`,
+                message: sensitive.length
+                    ? `Tool "${tool.name}" can ${sensitive.join(', ')}, and nothing approves or limits its calls.`
+                    : `Tool "${tool.name}" computes its capabilities per call, and nothing approves or limits its calls.`,
+                fix: 'Give the agent a permission policy that grants what the tool may do, or approve its calls with interruptOn.',
+            });
+        }
+        else if (tool.capabilities === undefined) {
+            findings.push({
+                code: 'UNDECLARED_TOOL_CAPABILITIES',
+                severity: 'info',
+                node: `tool:${tool.name}`,
+                message: `Tool "${tool.name}" declares no capabilities, so what it does cannot be judged.`,
+                fix: 'Declare its capabilities, or `capabilities: []` for a tool that changes nothing.',
+            });
+        }
+    }
     if (!top)
         return;
     if ((description.durability === 'async' || description.durability === 'exit') && sideEffecting.length > 0) {

package/dist-cjs/postgres/fulltext.d.ts

@@ -0,0 +1,67 @@
+import type { RagChunk } from '../hallucination/rag.js';
+import type { VectorSearchResult } from '../hallucination/retrieval.js';
+import type { RetrieveOptions, SparseRetriever } from '../rag/retrievers.js';
+import type { MigrationResult, SchemaMigration } from '../utils/schema-migrations.js';
+import { type PostgresLikeClient } from './client.js';
+import type { PostgresMigrateOptions } from './migrations.js';
+/** Options for `PostgresKeywordIndex`. */
+export interface PostgresKeywordIndexOptions {
+    /** Table name, optionally schema-qualified. Defaults to `nexus_keywords`. */
+    table?: string;
+    /**
+     * Searches the table of a `PostgresVectorStore` instead of keeping chunks of its own. `migrate()`
+     * adds a generated search column and its index to that table, the store's writes keep it current,
+     * and `add()` and `delete()` leave writing to the store. One copy of every chunk, and keyword and
+     * vector search can never disagree about what exists.
+     */
+    shared?: boolean;
+    /** The text search configuration: `english`, `simple`, `german`, and so on. Defaults to `english`. */
+    language?: string;
+    /**
+     * `any` (the default) finds chunks with any of the query's terms, ranked by how many and how close,
+     * as keyword search for retrieval should. `all` needs every term, read as a web search query, with
+     * quoted phrases and `-` for exclusion.
+     */
+    match?: 'any' | 'all';
+}
+/**
+ * The versioned schema, which `migrate()` applies. Version 1 creates the table with a generated
+ * `tsvector` column and a GIN index, or, `shared`, adds the column and the index to a vector table.
+ */
+export declare function keywordIndexMigrations(options?: PostgresKeywordIndexOptions): SchemaMigration[];
+/**
+ * Keyword search in Postgres, with its full-text search: stemmed terms, a GIN index, and
+ * `ts_rank_cd` ranking, so only the best matches leave the database however large the table.
+ *
+ * A `SparseRetriever`, so `hybridRetriever()` fuses it with `PostgresVectorStore`. With `shared`, it
+ * searches the vector store's own table, and the hybrid search runs over one copy of the data. A
+ * metadata filter runs in SQL, with the same meaning as the vector store's.
+ *
+ * ```ts
+ * const vectors = new PostgresVectorStore(client, { dimensions: 1536, embed });
+ * const keywords = new PostgresKeywordIndex(client, { table: 'nexus_vectors', shared: true });
+ * await vectors.migrate();
+ * await keywords.migrate();
+ * const retriever = hybridRetriever([vectorRetriever(vectors), keywords]);
+ * ```
+ */
+export declare class PostgresKeywordIndex implements SparseRetriever {
+    private readonly client;
+    private readonly options;
+    private readonly table;
+    private readonly language;
+    constructor(client: PostgresLikeClient, options?: PostgresKeywordIndexOptions);
+    /**
+     * Applies this index's pending migrations, recorded in `nexus_schema_migrations`, under a lock.
+     * Never runs implicitly. With `shared`, run the vector store's `migrate()` first.
+     */
+    migrate(options?: PostgresMigrateOptions): Promise<MigrationResult>;
+    /** Adds chunks, or replaces those whose id exists. With `shared`, does nothing: the vector store writes. */
+    add(chunks: readonly RagChunk[]): Promise<void>;
+    /** Removes chunks by id. With `shared`, does nothing: the vector store deletes. */
+    delete(ids: readonly string[]): Promise<void>;
+    /** The chunks that best match a query's terms, best first, scored from 0 to 1. */
+    retrieve(query: string, options?: RetrieveOptions): Promise<VectorSearchResult[]>;
+    /** Chunks held. */
+    size(): Promise<number>;
+}

package/dist-cjs/postgres/fulltext.js

@@ -0,0 +1,129 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresKeywordIndex = void 0;
+exports.keywordIndexMigrations = keywordIndexMigrations;
+const client_js_1 = require("./client.js");
+const sql_js_1 = require("./sql.js");
+const DEFAULT_TABLE = 'nexus_keywords';
+function languageOf(options) {
+    const language = options.language ?? 'english';
+    if (!/^[a-z_]{1,63}$/.test(language))
+        throw new RangeError(`"${language}" is not a text search configuration name`);
+    return language;
+}
+function keywordIndexMigrations(options = {}) {
+    const name = options.table ?? DEFAULT_TABLE;
+    const table = (0, client_js_1.quoteTable)(name);
+    const generated = `fts tsvector GENERATED ALWAYS AS (to_tsvector('${languageOf(options)}'::regconfig, content)) STORED`;
+    return [
+        {
+            component: `keywords:${name}`,
+            version: 1,
+            name: options.shared ? 'add full-text search to a vector table' : 'create the keyword table',
+            statements: [
+                options.shared
+                    ? `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS ${generated}`
+                    : `CREATE TABLE IF NOT EXISTS ${table} (
+  id text PRIMARY KEY,
+  content text NOT NULL,
+  source text,
+  metadata jsonb,
+  ${generated}
+)`,
+                `CREATE INDEX IF NOT EXISTS ${(0, client_js_1.quoteDerived)(name, 'fts')} ON ${table} USING gin (fts)`,
+            ],
+        },
+    ];
+}
+class PostgresKeywordIndex {
+    client;
+    options;
+    table;
+    language;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.options = options;
+        this.table = (0, client_js_1.quoteTable)(options.table ?? DEFAULT_TABLE);
+        this.language = languageOf(options);
+    }
+    async migrate(options = {}) {
+        const { applyPostgresMigrations } = await Promise.resolve().then(() => __importStar(require('./migrations.js')));
+        return applyPostgresMigrations(this.client, keywordIndexMigrations(this.options), options);
+    }
+    async add(chunks) {
+        if (this.options.shared || chunks.length === 0)
+            return;
+        const params = new sql_js_1.SqlParams();
+        const rows = chunks.map((chunk) => `(${params.add(chunk.id)}, ${params.add(chunk.content)}, ${params.add(chunk.source ?? null)}, ${params.add(chunk.metadata === undefined ? null : JSON.stringify(chunk.metadata))}::jsonb)`);
+        await this.client.query(`INSERT INTO ${this.table} (id, content, source, metadata) VALUES ${rows.join(', ')}
+       ON CONFLICT (id) DO UPDATE SET content = EXCLUDED.content, source = EXCLUDED.source, metadata = EXCLUDED.metadata`, params.values);
+    }
+    async delete(ids) {
+        if (this.options.shared || ids.length === 0)
+            return;
+        await this.client.query(`DELETE FROM ${this.table} WHERE id = ANY($1::text[])`, [(0, sql_js_1.textArray)(ids)]);
+    }
+    async retrieve(query, options = {}) {
+        options.signal?.throwIfAborted();
+        const params = new sql_js_1.SqlParams();
+        const text = params.add(query);
+        const language = `'${this.language}'::regconfig`;
+        const tsquery = this.options.match === 'all'
+            ? `websearch_to_tsquery(${language}, ${text})`
+            : `NULLIF(replace(plainto_tsquery(${language}, ${text})::text, ' & ', ' | '), '')::tsquery`;
+        const conditions = ['fts @@ q.query'];
+        if (options.filter && Object.keys(options.filter).length > 0) {
+            conditions.push(`metadata @> ${params.add(JSON.stringify(options.filter))}::jsonb`);
+        }
+        const limit = params.add(options.topK ?? 5);
+        const { rows } = await this.client.query(`SELECT id, content, source, metadata::text AS metadata, ts_rank_cd(fts, q.query, 32) AS score
+       FROM ${this.table}, (SELECT ${tsquery} AS query) AS q
+       WHERE ${conditions.join(' AND ')}
+       ORDER BY score DESC, id LIMIT ${limit}`, params.values);
+        return rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            ...(row.source === null ? {} : { source: row.source }),
+            ...(row.metadata === null ? {} : { metadata: (0, client_js_1.fromJson)(row.metadata) }),
+            score: Number(row.score),
+        }));
+    }
+    async size() {
+        const { rows } = await this.client.query(`SELECT count(*)::int AS count FROM ${this.table}`);
+        return Number(rows[0]?.count ?? 0);
+    }
+}
+exports.PostgresKeywordIndex = PostgresKeywordIndex;