@adonis-agora/agent 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @adonis-agora/agent
 
+## 0.9.0
+
+### Minor Changes
+
+- [#25](https://github.com/DavideCarvalho/adonis-agent/pull/25) [`e726f1f`](https://github.com/DavideCarvalho/adonis-agent/commit/e726f1fdcc13e479ffc10c150dc4148bc18efdfb) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Novo `BaseTool` (classe base opcional para a forma de classe de um tool) — o análogo do `BaseWorkflow` do durable. Declarar `static tool = { … }` numa subclasse de `BaseTool` é type-checado pela estática herdada (`static tool?: AiToolOptions`), sem precisar de `satisfies AiToolOptions`. `ToolHandler<I, O = unknown>` e `defineTool<I, O>` passam a tipar o retorno do `execute` (antes `Promise<unknown>`), então o compilador confere o corpo contra o que o tool promete. Ambos non-breaking (defaults preservam o comportamento anterior).
+
 ## 0.8.0
 
 ### Minor Changes

package/dist/src/ai-sdk/ai-sdk-model.d.ts

@@ -1,11 +1,22 @@
-import { type CallSettings, type LanguageModel } from 'ai';
+import { type CallSettings, type Experimental_DownloadFunction, type LanguageModel } from 'ai';
 import type { ModelProvider } from '../index.js';
 /**
  * Pass-through settings forwarded to the AI SDK `streamText` call (headers, temperature,
  * `maxOutputTokens`, `providerOptions`, …). `model`, `instructions`, `messages`, `tools`, and
  * `abortSignal` are owned by the adapter and always win over anything set here.
  */
-export type AiSdkModelOptions = CallSettings;
+export type AiSdkModelOptions = CallSettings & {
+    /**
+     * Override the AI SDK's file/attachment downloader (`experimental_download` on `streamText`).
+     * The SDK's DEFAULT downloader refuses localhost/private hostnames (SSRF guard), which breaks
+     * attachment parts whose staging presigns against a local object store (e.g. MinIO in dev) —
+     * the model call dies with `AI_DownloadError: URL with hostname localhost is not allowed`.
+     * Attachment URLs come from the host's own staging SPI — never from user input — so relaxing
+     * the guard with a plain fetch is the host's legitimate call. Pair with the ready-made
+     * {@link import('./attachment-fetch-downloader.js').attachmentFetchDownloader}.
+     */
+    experimental_download?: Experimental_DownloadFunction;
+};
 /**
  * Adapt a Vercel AI SDK v7 `LanguageModel` to the core `ModelProvider` SPI so a host app writes
  * zero provider code. Streams text deltas to `args.sink`, returns the assembled text, requested

package/dist/src/ai-sdk/ai-sdk-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk-model.d.ts","sourceRoot":"","sources":["../../../src/ai-sdk/ai-sdk-model.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,YAAY,EAKjB,KAAK,aAAa,EAYnB,MAAM,IAAI,CAAC;AAEZ,OAAO,KAAK,EAIV,aAAa,EAMd,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,aAAa,CA0CxF"}
+{"version":3,"file":"ai-sdk-model.d.ts","sourceRoot":"","sources":["../../../src/ai-sdk/ai-sdk-model.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,6BAA6B,EAKlC,KAAK,aAAa,EAYnB,MAAM,IAAI,CAAC;AAEZ,OAAO,KAAK,EAIV,aAAa,EAMd,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG;IAC7C;;;;;;;;OAQG;IACH,qBAAqB,CAAC,EAAE,6BAA6B,CAAC;CACvD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,aAAa,CA0CxF"}

package/dist/src/ai-sdk/ai-sdk-model.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk-model.js","sourceRoot":"","sources":["../../../src/ai-sdk/ai-sdk-model.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ai-sdk-model.js","sourceRoot":"","sources":["../../../src/ai-sdk/ai-sdk-model.ts"],"names":[],"mappings":"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"}

package/dist/src/ai-sdk/attachment-fetch-downloader.d.ts

@@ -0,0 +1,15 @@
+import type { Experimental_DownloadFunction } from 'ai';
+/**
+ * A ready-made `experimental_download` for {@link import('./ai-sdk-model.js').AiSdkModelOptions}:
+ * plain-fetches every URL the model can't consume natively, with NO hostname policy — unlike the
+ * AI SDK's default downloader, which refuses localhost/private hostnames (SSRF guard) and kills
+ * attachment parts staged against a non-public object store (local MinIO in dev, VPC-only S3).
+ *
+ * Only safe because agent attachment URLs come exclusively from the host's own attachment-staging
+ * SPI presigner — never from user input. Do NOT reuse this for URLs a user can influence.
+ *
+ * Mirrors the default's routing otherwise: URLs the model supports natively are left to the
+ * provider (`null`), everything else is fetched and inlined as bytes.
+ */
+export declare function attachmentFetchDownloader(fetchImpl?: typeof fetch): Experimental_DownloadFunction;
+//# sourceMappingURL=attachment-fetch-downloader.d.ts.map

package/dist/src/ai-sdk/attachment-fetch-downloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-fetch-downloader.d.ts","sourceRoot":"","sources":["../../../src/ai-sdk/attachment-fetch-downloader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,IAAI,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,OAAO,KAAa,GAC9B,6BAA6B,CAmB/B"}

package/dist/src/ai-sdk/attachment-fetch-downloader.js

@@ -0,0 +1,28 @@
+/**
+ * A ready-made `experimental_download` for {@link import('./ai-sdk-model.js').AiSdkModelOptions}:
+ * plain-fetches every URL the model can't consume natively, with NO hostname policy — unlike the
+ * AI SDK's default downloader, which refuses localhost/private hostnames (SSRF guard) and kills
+ * attachment parts staged against a non-public object store (local MinIO in dev, VPC-only S3).
+ *
+ * Only safe because agent attachment URLs come exclusively from the host's own attachment-staging
+ * SPI presigner — never from user input. Do NOT reuse this for URLs a user can influence.
+ *
+ * Mirrors the default's routing otherwise: URLs the model supports natively are left to the
+ * provider (`null`), everything else is fetched and inlined as bytes.
+ */
+export function attachmentFetchDownloader(fetchImpl = fetch) {
+    return (requests) => Promise.all(requests.map(async ({ url, isUrlSupportedByModel }) => {
+        if (isUrlSupportedByModel) {
+            return null;
+        }
+        const response = await fetchImpl(url);
+        if (!response.ok) {
+            throw new Error(`attachmentFetchDownloader: ${response.status} fetching attachment from ${url.hostname}`);
+        }
+        return {
+            data: new Uint8Array(await response.arrayBuffer()),
+            mediaType: response.headers.get('content-type') ?? undefined,
+        };
+    }));
+}
+//# sourceMappingURL=attachment-fetch-downloader.js.map

package/dist/src/ai-sdk/attachment-fetch-downloader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-fetch-downloader.js","sourceRoot":"","sources":["../../../src/ai-sdk/attachment-fetch-downloader.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CACvC,YAA0B,KAAK;IAE/B,OAAO,CAAC,QAAQ,EAAE,EAAE,CAClB,OAAO,CAAC,GAAG,CACT,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,qBAAqB,EAAE,EAAE,EAAE;QACpD,IAAI,qBAAqB,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACb,8BAA8B,QAAQ,CAAC,MAAM,6BAA6B,GAAG,CAAC,QAAQ,EAAE,CACzF,CAAC;QACJ,CAAC;QACD,OAAO;YACL,IAAI,EAAE,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC;YAClD,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,SAAS;SAC7D,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;AACN,CAAC"}

package/dist/src/ai-sdk/index.d.ts

@@ -1,2 +1,3 @@
 export { aiSdkModel, type AiSdkModelOptions } from './ai-sdk-model.js';
+export { attachmentFetchDownloader } from './attachment-fetch-downloader.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/ai-sdk/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/src/ai-sdk/index.js

@@ -1,2 +1,3 @@
 export { aiSdkModel } from './ai-sdk-model.js';
+export { attachmentFetchDownloader } from './attachment-fetch-downloader.js';
 //# sourceMappingURL=index.js.map

package/dist/src/ai-sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA0B,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA0B,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/src/ai-tool-ref.d.ts

@@ -85,5 +85,5 @@ export declare function isBrandedFunctionalTool(value: unknown): value is Brande
  * )
  * ```
  */
-export declare function defineTool<I = unknown>(options: AiToolOptions, execute: (input: I, ctx: AiToolCtx) => Promise<unknown> | unknown): BrandedFunctionalTool;
+export declare function defineTool<I = unknown, O = unknown>(options: AiToolOptions, execute: (input: I, ctx: AiToolCtx) => Promise<O> | O): BrandedFunctionalTool;
 //# sourceMappingURL=ai-tool-ref.d.ts.map

package/dist/src/ai-tool-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-tool-ref.d.ts","sourceRoot":"","sources":["../../src/ai-tool-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAgD,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAmD,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,EAAE,gBAAgB,CAAC;IACxB,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wGAAwG;AACxG,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC,2FAA2F;AAC3F,MAAM,MAAM,SAAS,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,WAAW,CAAC;AAEvE;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,IACnC,CAAC,SAAS,SAAS,EAAE,QAAQ,CAAC,KAAG,CAAC,CAQ3C;AAyBD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAMtE;AAED,4FAA4F;AAC5F,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,oGAAoG;AACpG,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAC;CACnC;AAED,kGAAkG;AAClG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAQtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EACpC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,GAChE,qBAAqB,CAcvB"}
+{"version":3,"file":"ai-tool-ref.d.ts","sourceRoot":"","sources":["../../src/ai-tool-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAgD,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAmD,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,EAAE,gBAAgB,CAAC;IACxB,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wGAAwG;AACxG,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC,2FAA2F;AAC3F,MAAM,MAAM,SAAS,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,WAAW,CAAC;AAEvE;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,IACnC,CAAC,SAAS,SAAS,EAAE,QAAQ,CAAC,KAAG,CAAC,CAQ3C;AAyBD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAMtE;AAED,4FAA4F;AAC5F,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,oGAAoG;AACpG,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAC;CACnC;AAED,kGAAkG;AAClG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAQtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EACjD,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACpD,qBAAqB,CAcvB"}

package/dist/src/ai-tool-ref.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai-tool-ref.js","sourceRoot":"","sources":["../../src/ai-tool-ref.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ai-tool-ref.js","sourceRoot":"","sources":["../../src/ai-tool-ref.ts"],"names":[],"mappings":"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"}

package/dist/src/base-tool.d.ts

@@ -0,0 +1,31 @@
+import type { AiToolOptions } from './ai-tool-ref.js';
+import type { AiToolCtx, ToolHandler } from './spi/tool.js';
+/**
+ * Optional base class for the class-authoring form of a tool — the counterpart of durable's
+ * `BaseWorkflow`. Declaring `static tool?: AiToolOptions` here means a subclass writes
+ * `static tool = { name, kind, description, input, … }` and gets it type-checked by the inherited
+ * static declaration — no `satisfies AiToolOptions` needed. Implement `execute(input, ctx)`; the
+ * discovery scan reads the static `tool` off the subclass and registers it (the abstract base
+ * carries no `static tool`, so it is never registered itself).
+ *
+ * `I` is the parsed (Zod) input; `O` is the return — both flow into `execute`'s signature, so the
+ * compiler checks the body against what the tool promises.
+ *
+ * ```ts
+ * export default class FilaDeAlocacao extends BaseTool<Input, Row[]> {
+ *   static tool = {
+ *     name: 'fila_de_alocacao',
+ *     kind: 'read',
+ *     description: '…',
+ *     input: z.object({}),
+ *     ability: 'agent.coordenador.fila.ler',
+ *   }
+ *   async execute(_input: Input, ctx: AiToolCtx): Promise<Row[]> { … }
+ * }
+ * ```
+ */
+export declare abstract class BaseTool<I = unknown, O = unknown> implements ToolHandler<I, O> {
+    static tool?: AiToolOptions;
+    abstract execute(input: I, ctx: AiToolCtx): Promise<O> | O;
+}
+//# sourceMappingURL=base-tool.d.ts.map

package/dist/src/base-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-tool.d.ts","sourceRoot":"","sources":["../../src/base-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,CAAE,YAAW,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC;IACnF,MAAM,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;CAC3D"}

package/dist/src/base-tool.js

@@ -0,0 +1,28 @@
+/**
+ * Optional base class for the class-authoring form of a tool — the counterpart of durable's
+ * `BaseWorkflow`. Declaring `static tool?: AiToolOptions` here means a subclass writes
+ * `static tool = { name, kind, description, input, … }` and gets it type-checked by the inherited
+ * static declaration — no `satisfies AiToolOptions` needed. Implement `execute(input, ctx)`; the
+ * discovery scan reads the static `tool` off the subclass and registers it (the abstract base
+ * carries no `static tool`, so it is never registered itself).
+ *
+ * `I` is the parsed (Zod) input; `O` is the return — both flow into `execute`'s signature, so the
+ * compiler checks the body against what the tool promises.
+ *
+ * ```ts
+ * export default class FilaDeAlocacao extends BaseTool<Input, Row[]> {
+ *   static tool = {
+ *     name: 'fila_de_alocacao',
+ *     kind: 'read',
+ *     description: '…',
+ *     input: z.object({}),
+ *     ability: 'agent.coordenador.fila.ler',
+ *   }
+ *   async execute(_input: Input, ctx: AiToolCtx): Promise<Row[]> { … }
+ * }
+ * ```
+ */
+export class BaseTool {
+    static tool;
+}
+//# sourceMappingURL=base-tool.js.map

package/dist/src/base-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-tool.js","sourceRoot":"","sources":["../../src/base-tool.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAgB,QAAQ;IAC5B,MAAM,CAAC,IAAI,CAAiB;CAE7B"}

package/dist/src/index.d.ts

@@ -1,6 +1,7 @@
-export declare const VERSION = "0.8.0";
+export declare const VERSION = "0.9.0";
 export * from './types.js';
 export * from './spi/tool.js';
+export * from './base-tool.js';
 export * from './spi/model-provider.js';
 export * from './spi/token-stream-sink.js';
 export * from './spi/agent-store.js';

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/index.js

@@ -1,6 +1,7 @@
-export const VERSION = '0.8.0';
+export const VERSION = '0.9.0';
 export * from './types.js';
 export * from './spi/tool.js';
+export * from './base-tool.js';
 export * from './spi/model-provider.js';
 export * from './spi/token-stream-sink.js';
 export * from './spi/agent-store.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/rag/filter.d.ts

@@ -1,6 +1,15 @@
 /**
- * Exact-match metadata filter (every key in `filter` must equal the record's). Used by the in-memory
- * {@link import('./memory-vector-store.js').MemoryVectorStore}. Pure and dependency-free.
+ * Metadata filter, shared by the in-memory {@link import('./memory-vector-store.js').MemoryVectorStore}
+ * (and any lexical retriever). Every key must match:
+ *
+ * - a **scalar** filter value keeps exact-match — the record's value must equal it;
+ * - an **array** filter value means **match-any** (OR / set membership) — the record matches when its
+ *   value for that key is one of them, or (for a multi-valued record) shares at least one element.
+ *   An empty array matches nothing (no value is a member of the empty set) — the deny primitive.
+ *
+ * Array-valued filters are how a caller expresses capability-style access control over a shared store
+ * (e.g. `{ audience: ['public', 'role:ADMIN', 'base:…'] }`) without the store knowing what a token means.
+ * Pure and dependency-free; backward compatible (scalar filters behave exactly as before).
  */
 export declare function matchesFilter(metadata: Record<string, unknown> | undefined, filter: Record<string, unknown>): boolean;
 //# sourceMappingURL=filter.d.ts.map

package/dist/src/rag/filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/rag/filter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAKT"}
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/rag/filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAcT"}

package/dist/src/rag/filter.js

@@ -1,11 +1,29 @@
 /**
- * Exact-match metadata filter (every key in `filter` must equal the record's). Used by the in-memory
- * {@link import('./memory-vector-store.js').MemoryVectorStore}. Pure and dependency-free.
+ * Metadata filter, shared by the in-memory {@link import('./memory-vector-store.js').MemoryVectorStore}
+ * (and any lexical retriever). Every key must match:
+ *
+ * - a **scalar** filter value keeps exact-match — the record's value must equal it;
+ * - an **array** filter value means **match-any** (OR / set membership) — the record matches when its
+ *   value for that key is one of them, or (for a multi-valued record) shares at least one element.
+ *   An empty array matches nothing (no value is a member of the empty set) — the deny primitive.
+ *
+ * Array-valued filters are how a caller expresses capability-style access control over a shared store
+ * (e.g. `{ audience: ['public', 'role:ADMIN', 'base:…'] }`) without the store knowing what a token means.
+ * Pure and dependency-free; backward compatible (scalar filters behave exactly as before).
  */
 export function matchesFilter(metadata, filter) {
+    const entries = Object.entries(filter);
     if (metadata === undefined) {
-        return Object.keys(filter).length === 0;
+        return entries.length === 0;
     }
-    return Object.entries(filter).every(([key, value]) => metadata[key] === value);
+    return entries.every(([key, expected]) => {
+        if (Array.isArray(expected)) {
+            const actual = metadata[key];
+            return Array.isArray(actual)
+                ? actual.some((value) => expected.includes(value))
+                : expected.includes(actual);
+        }
+        return metadata[key] === expected;
+    });
 }
 //# sourceMappingURL=filter.js.map

package/dist/src/rag/filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../../src/rag/filter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,QAA6C,EAC7C,MAA+B;IAE/B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,CAAC;AACjF,CAAC"}
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../../src/rag/filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,QAA6C,EAC7C,MAA+B;IAE/B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,EAAE;QACvC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC7B,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBAC1B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAClD,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;QACD,OAAO,QAAQ,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/rag/hybrid-retriever.d.ts

@@ -0,0 +1,23 @@
+import type { Passage, RetrieveOptions, Retriever } from '../spi/retriever.js';
+export interface HybridRetrieverOptions {
+    /** RRF constant — larger flattens the rank weighting. Default 60 (the value from the original paper). */
+    k?: number;
+    /** Candidates pulled from each retriever before fusion. Default 20. */
+    fetchTopK?: number;
+    /** Per-retriever multipliers on each RRF contribution (same order as `retrievers`). Default all 1. */
+    weights?: number[];
+}
+/**
+ * Fuses several retrievers with Reciprocal Rank Fusion — the robust way to combine, say, dense vector
+ * search with lexical BM25. RRF scores each passage by `Σ weight / (k + rank)` across the lists it
+ * appears in, so it needs no score normalization between incompatible scales (cosine vs BM25).
+ * Deduplicates by passage id, so aligned chunk ids from the two retrievers reinforce. Itself a
+ * {@link Retriever}. Mirrors the reference `HybridRetriever` exactly.
+ */
+export declare class HybridRetriever implements Retriever {
+    private readonly retrievers;
+    private readonly options;
+    constructor(retrievers: Retriever[], options?: HybridRetrieverOptions);
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+}
+//# sourceMappingURL=hybrid-retriever.d.ts.map

package/dist/src/rag/hybrid-retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-retriever.d.ts","sourceRoot":"","sources":["../../../src/rag/hybrid-retriever.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE/E,MAAM,WAAW,sBAAsB;IACrC,yGAAyG;IACzG,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sGAAsG;IACtG,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAE7C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,GAAE,sBAA2B;IAGjD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAgCjF"}

package/dist/src/rag/hybrid-retriever.js

@@ -0,0 +1,43 @@
+/**
+ * Fuses several retrievers with Reciprocal Rank Fusion — the robust way to combine, say, dense vector
+ * search with lexical BM25. RRF scores each passage by `Σ weight / (k + rank)` across the lists it
+ * appears in, so it needs no score normalization between incompatible scales (cosine vs BM25).
+ * Deduplicates by passage id, so aligned chunk ids from the two retrievers reinforce. Itself a
+ * {@link Retriever}. Mirrors the reference `HybridRetriever` exactly.
+ */
+export class HybridRetriever {
+    retrievers;
+    options;
+    constructor(retrievers, options = {}) {
+        this.retrievers = retrievers;
+        this.options = options;
+    }
+    async retrieve(query, options = {}) {
+        const k = this.options.k ?? 60;
+        const fetchTopK = this.options.fetchTopK ?? 20;
+        const weights = this.options.weights;
+        const lists = await Promise.all(this.retrievers.map((retriever) => retriever.retrieve(query, {
+            topK: fetchTopK,
+            ...(options.filter !== undefined ? { filter: options.filter } : {}),
+        })));
+        const fused = new Map();
+        lists.forEach((list, listIndex) => {
+            const weight = weights?.[listIndex] ?? 1;
+            list.forEach((passage, rank) => {
+                const contribution = weight / (k + rank + 1);
+                const existing = fused.get(passage.id);
+                if (existing !== undefined) {
+                    existing.score += contribution;
+                }
+                else {
+                    fused.set(passage.id, { passage, score: contribution });
+                }
+            });
+        });
+        return [...fused.values()]
+            .sort((a, b) => b.score - a.score)
+            .slice(0, options.topK ?? 5)
+            .map((entry) => ({ ...entry.passage, score: entry.score }));
+    }
+}
+//# sourceMappingURL=hybrid-retriever.js.map

package/dist/src/rag/hybrid-retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-retriever.js","sourceRoot":"","sources":["../../../src/rag/hybrid-retriever.ts"],"names":[],"mappings":"AAWA;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAEP;IACA;IAFnB,YACmB,UAAuB,EACvB,UAAkC,EAAE;QADpC,eAAU,GAAV,UAAU,CAAa;QACvB,YAAO,GAAP,OAAO,CAA6B;IACpD,CAAC;IAEJ,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,UAA2B,EAAE;QACzD,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;QAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;QACrC,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAC7B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAChC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE;YACxB,IAAI,EAAE,SAAS;YACf,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpE,CAAC,CACH,CACF,CAAC;QAEF,MAAM,KAAK,GAAG,IAAI,GAAG,EAA+C,CAAC;QACrE,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE;YAChC,MAAM,MAAM,GAAG,OAAO,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE;gBAC7B,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;gBAC7C,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;gBACvC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,QAAQ,CAAC,KAAK,IAAI,YAAY,CAAC;gBACjC,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;gBAC1D,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;aACvB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;aACjC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;aAC3B,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAChE,CAAC;CACF"}

package/dist/src/rag/index.d.ts

@@ -3,6 +3,9 @@ export { documentIdOf, type IndexedDocument, type VectorRecord, type VectorSearc
 export { matchesFilter } from './filter.js';
 export { MemoryVectorStore, cosineSimilarity } from './memory-vector-store.js';
 export { EmbeddingRetriever } from './embedding-retriever.js';
+export { RerankingRetriever, type RerankingRetrieverOptions, } from './reranking-retriever.js';
+export { KeywordRetriever, type KeywordRetrieverOptions } from './keyword-retriever.js';
+export { HybridRetriever, type HybridRetrieverOptions } from './hybrid-retriever.js';
 export { PgVectorStore, PgVectorRetriever, toVectorLiteral, type PgVectorMetric, type PgVectorColumns, type PgVectorStoreOptions, } from './pg-vector-store.js';
 export { chunkDocuments, ingestChunks, ingestDocuments, type ChunkRecord, type IngestChunksOptions, type IngestDocument, type IngestOptions, } from './ingest.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/rag/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}

package/dist/src/rag/index.js

@@ -3,6 +3,9 @@ export { documentIdOf, } from './vector-store.js';
 export { matchesFilter } from './filter.js';
 export { MemoryVectorStore, cosineSimilarity } from './memory-vector-store.js';
 export { EmbeddingRetriever } from './embedding-retriever.js';
+export { RerankingRetriever, } from './reranking-retriever.js';
+export { KeywordRetriever } from './keyword-retriever.js';
+export { HybridRetriever } from './hybrid-retriever.js';
 export { PgVectorStore, PgVectorRetriever, toVectorLiteral, } from './pg-vector-store.js';
 export { chunkDocuments, ingestChunks, ingestDocuments, } from './ingest.js';
 //# sourceMappingURL=index.js.map

package/dist/src/rag/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAqB,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,YAAY,GAKb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,GAIhB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,eAAe,GAKhB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAqB,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,YAAY,GAKb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAgC,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,eAAe,EAA+B,MAAM,uBAAuB,CAAC;AACrF,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,GAIhB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,eAAe,GAKhB,MAAM,aAAa,CAAC"}

package/dist/src/rag/keyword-retriever.d.ts

@@ -0,0 +1,28 @@
+import type { Passage, RetrieveOptions, Retriever } from '../spi/retriever.js';
+import type { ChunkRecord } from './ingest.js';
+export interface KeywordRetrieverOptions {
+    /** BM25 term-frequency saturation. Default 1.5. */
+    k1?: number;
+    /** BM25 length normalization, 0 (off) … 1 (full). Default 0.75. */
+    b?: number;
+}
+/**
+ * An in-memory BM25 lexical retriever — the keyword half of hybrid search. Feed it the SAME
+ * {@link ChunkRecord}s you upsert into the vector store (from `chunkDocuments`) so their chunk ids
+ * line up and {@link import('./hybrid-retriever.js').HybridRetriever} can fuse the two rankings. Full
+ * BM25: idf, term-frequency saturation (`k1`), and document-length normalization (`b`). Honors the
+ * same array-OR metadata {@link matchesFilter} as the vector store. Mirrors the reference exactly.
+ */
+export declare class KeywordRetriever implements Retriever {
+    private readonly docs;
+    private readonly documentFrequency;
+    private totalLength;
+    private readonly k1;
+    private readonly b;
+    constructor(options?: KeywordRetrieverOptions);
+    /** Index (or re-index) records. Re-adding an existing id replaces its posting and updates stats. */
+    add(records: ChunkRecord[]): void;
+    private remove;
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+}
+//# sourceMappingURL=keyword-retriever.d.ts.map

package/dist/src/rag/keyword-retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyword-retriever.d.ts","sourceRoot":"","sources":["../../../src/rag/keyword-retriever.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AASD;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IACtD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAS;gBAEf,OAAO,GAAE,uBAA4B;IAKjD,oGAAoG;IACpG,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI;IAgBjC,OAAO,CAAC,MAAM;IAiBR,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAoCjF"}

package/dist/src/rag/keyword-retriever.js

@@ -0,0 +1,91 @@
+import { matchesFilter } from './filter.js';
+/**
+ * An in-memory BM25 lexical retriever — the keyword half of hybrid search. Feed it the SAME
+ * {@link ChunkRecord}s you upsert into the vector store (from `chunkDocuments`) so their chunk ids
+ * line up and {@link import('./hybrid-retriever.js').HybridRetriever} can fuse the two rankings. Full
+ * BM25: idf, term-frequency saturation (`k1`), and document-length normalization (`b`). Honors the
+ * same array-OR metadata {@link matchesFilter} as the vector store. Mirrors the reference exactly.
+ */
+export class KeywordRetriever {
+    docs = new Map();
+    documentFrequency = new Map();
+    totalLength = 0;
+    k1;
+    b;
+    constructor(options = {}) {
+        this.k1 = options.k1 ?? 1.5;
+        this.b = options.b ?? 0.75;
+    }
+    /** Index (or re-index) records. Re-adding an existing id replaces its posting and updates stats. */
+    add(records) {
+        for (const record of records) {
+            this.remove(record.id);
+            const tokens = tokenize(record.text);
+            const frequencies = new Map();
+            for (const token of tokens) {
+                frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+            }
+            for (const term of frequencies.keys()) {
+                this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1);
+            }
+            this.docs.set(record.id, { record, frequencies, length: tokens.length });
+            this.totalLength += tokens.length;
+        }
+    }
+    remove(id) {
+        const existing = this.docs.get(id);
+        if (existing === undefined) {
+            return;
+        }
+        for (const term of existing.frequencies.keys()) {
+            const next = (this.documentFrequency.get(term) ?? 1) - 1;
+            if (next <= 0) {
+                this.documentFrequency.delete(term);
+            }
+            else {
+                this.documentFrequency.set(term, next);
+            }
+        }
+        this.totalLength -= existing.length;
+        this.docs.delete(id);
+    }
+    async retrieve(query, options = {}) {
+        const total = this.docs.size;
+        if (total === 0) {
+            return [];
+        }
+        const averageLength = this.totalLength / total;
+        const queryTerms = new Set(tokenize(query));
+        const scored = [];
+        for (const { record, frequencies, length } of this.docs.values()) {
+            if (options.filter !== undefined && !matchesFilter(record.metadata, options.filter)) {
+                continue;
+            }
+            let score = 0;
+            for (const term of queryTerms) {
+                const termFrequency = frequencies.get(term);
+                if (termFrequency === undefined) {
+                    continue;
+                }
+                const df = this.documentFrequency.get(term) ?? 0;
+                const idf = Math.log(1 + (total - df + 0.5) / (df + 0.5));
+                const denominator = termFrequency + this.k1 * (1 - this.b + (this.b * length) / averageLength);
+                score += idf * ((termFrequency * (this.k1 + 1)) / denominator);
+            }
+            if (score > 0) {
+                scored.push({
+                    id: record.id,
+                    text: record.text,
+                    score,
+                    ...(record.source !== undefined ? { source: record.source } : {}),
+                    ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),
+                });
+            }
+        }
+        return scored.sort((a, b) => b.score - a.score).slice(0, options.topK ?? 5);
+    }
+}
+function tokenize(text) {
+    return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+//# sourceMappingURL=keyword-retriever.js.map

package/dist/src/rag/keyword-retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyword-retriever.js","sourceRoot":"","sources":["../../../src/rag/keyword-retriever.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAiB5C;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IACV,IAAI,GAAG,IAAI,GAAG,EAAsB,CAAC;IACrC,iBAAiB,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvD,WAAW,GAAG,CAAC,CAAC;IACP,EAAE,CAAS;IACX,CAAC,CAAS;IAE3B,YAAY,UAAmC,EAAE;QAC/C,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,GAAG,CAAC;QAC5B,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC;IAC7B,CAAC;IAED,oGAAoG;IACpG,GAAG,CAAC,OAAsB;QACxB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACvB,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACrC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;YAC9C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5D,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;gBACtC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAChF,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;YACzE,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC,MAAM,CAAC;QACpC,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,EAAU;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;YAC/C,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACzD,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;gBACd,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACtC,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QACD,IAAI,CAAC,WAAW,IAAI,QAAQ,CAAC,MAAM,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,UAA2B,EAAE;QACzD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QAC7B,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QAC/C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5C,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,KAAK,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACjE,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBACpF,SAAS;YACX,CAAC;YACD,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;gBAC9B,MAAM,aAAa,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAC5C,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;oBAChC,SAAS;gBACX,CAAC;gBACD,MAAM,EAAE,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACjD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;gBAC1D,MAAM,WAAW,GACf,aAAa,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC;gBAC7E,KAAK,IAAI,GAAG,GAAG,CAAC,CAAC,aAAa,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;YACjE,CAAC;YACD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACd,MAAM,CAAC,IAAI,CAAC;oBACV,EAAE,EAAE,MAAM,CAAC,EAAE;oBACb,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,KAAK;oBACL,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACjE,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACxE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;IAC9E,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;AACtD,CAAC"}

package/dist/src/rag/pg-vector-store.d.ts

@@ -45,8 +45,9 @@ export declare function toVectorLiteral(embedding: number[]): string;
  * {@link LucidDatabaseLike} (so `@adonisjs/lucid` stays an optional peer — this file imports no Lucid
  * types) with raw SQL for the pgvector operators. Similarity ranks via the `<=>`/`<->`/`<#>` operator for
  * the configured {@link PgVectorMetric}; the query embedding is always a `?::vector` positional binding
- * (NEVER string-interpolated) and metadata filters an `@> ?::jsonb` binding, so only the (validated)
- * table/column identifiers are ever spliced into a statement.
+ * (NEVER string-interpolated). Scalar metadata filters are an `@> ?::jsonb` containment binding; an
+ * array filter value is set-membership (`jsonb_exists_any`, the `?|` function form) — the capability-token
+ * ACL primitive. Only the (validated) table/column identifiers are ever spliced into a statement.
  *
  * Usually you don't construct this directly: `config/agent.ts` selects it via `retrievers.pgvector({...})`
  * and the provider builds it, lazily importing `@adonisjs/lucid` only when the pgvector retriever is

package/dist/src/rag/pg-vector-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pg-vector-store.d.ts","sourceRoot":"","sources":["../../../src/rag/pg-vector-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAsDD,yGAAyG;AACzG,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3D;AAuCD;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,WAAW;IAQ7C,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;gBAG7B,EAAE,EAAE,iBAAiB,EACtC,OAAO,GAAE,oBAAyB;IAgBpC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnC,uGAAuG;IACvG,gBAAgB,IAAI,MAAM,EAAE;IAgBtB,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB9C,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAoB3E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAmCpF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,kBAAkB;gBAE3C,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,aAAa;CAG9D"}
+{"version":3,"file":"pg-vector-store.d.ts","sourceRoot":"","sources":["../../../src/rag/pg-vector-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAsDD,yGAAyG;AACzG,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3D;AAyFD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAc,YAAW,WAAW;IAQ7C,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;gBAG7B,EAAE,EAAE,iBAAiB,EACtC,OAAO,GAAE,oBAAyB;IAgBpC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnC,uGAAuG;IACvG,gBAAgB,IAAI,MAAM,EAAE;IAgBtB,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB9C,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAoB3E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CA6BpF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,kBAAkB;gBAE3C,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,aAAa;CAG9D"}

package/dist/src/rag/pg-vector-store.js

@@ -36,6 +36,51 @@ function assertIdentifier(name, role) {
 export function toVectorLiteral(embedding) {
     return `[${embedding.join(',')}]`;
 }
+/**
+ * Build the metadata `WHERE` fragment for a filter, using Lucid/Knex positional `?` bindings (never
+ * string interpolation). Two predicate kinds:
+ *
+ * - **scalar** filter values collapse into a single jsonb-containment check (`metadata @> ?::jsonb`) —
+ *   exact-match, byte-for-byte the previous behavior so scalar filters stay backward compatible.
+ * - an **array** filter value is a **match-any** (OR / set membership) check: the record matches when
+ *   its value for that key — scalar or array — shares an element with the filter array. An empty array
+ *   can never match (the `false` deny primitive).
+ *
+ * Set membership uses `jsonb_exists_any(jsonb, text[])` — the function form of the `?|` operator, chosen
+ * because bare `?|` collides with Knex's `?` binding placeholder. The metadata KEY is itself a `?`
+ * binding (`metadata->?`), so a caller-supplied key can never inject SQL; only the (already validated)
+ * table/column identifiers are ever spliced in. Returns `{ sql: '', bindings: [] }` when there is no
+ * filter, preserving the previous unfiltered query shape.
+ */
+function buildMetadataWhere(filter, metadataColumn) {
+    if (filter === undefined || Object.keys(filter).length === 0) {
+        return { sql: '', bindings: [] };
+    }
+    const clauses = [];
+    const bindings = [];
+    const scalar = {};
+    for (const [key, value] of Object.entries(filter)) {
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                clauses.push('false');
+                continue;
+            }
+            // Coerce the record's value to an array (a scalar becomes a one-element array) so `?|` set
+            // membership works uniformly, then test overlap with the caller's tokens.
+            clauses.push(`jsonb_exists_any(CASE WHEN jsonb_typeof(${metadataColumn}->?) = 'array' ` +
+                `THEN ${metadataColumn}->? ELSE jsonb_build_array(${metadataColumn}->?) END, ?::text[])`);
+            bindings.push(key, key, key, value.map(String));
+        }
+        else {
+            scalar[key] = value;
+        }
+    }
+    if (Object.keys(scalar).length > 0) {
+        clauses.push(`${metadataColumn} @> ?::jsonb`);
+        bindings.push(JSON.stringify(scalar));
+    }
+    return { sql: `WHERE ${clauses.join(' AND ')}`, bindings };
+}
 /** Normalize whatever a Lucid `rawQuery` returns (PG `{rows}`, SQLite array, MySQL `[rows,fields]`). */
 function normalizeRows(raw) {
     if (Array.isArray(raw)) {
@@ -79,8 +124,9 @@ function documentIdExpr(col) {
  * {@link LucidDatabaseLike} (so `@adonisjs/lucid` stays an optional peer — this file imports no Lucid
  * types) with raw SQL for the pgvector operators. Similarity ranks via the `<=>`/`<->`/`<#>` operator for
  * the configured {@link PgVectorMetric}; the query embedding is always a `?::vector` positional binding
- * (NEVER string-interpolated) and metadata filters an `@> ?::jsonb` binding, so only the (validated)
- * table/column identifiers are ever spliced into a statement.
+ * (NEVER string-interpolated). Scalar metadata filters are an `@> ?::jsonb` containment binding; an
+ * array filter value is set-membership (`jsonb_exists_any`, the `?|` function form) — the capability-token
+ * ACL primitive. Only the (validated) table/column identifiers are ever spliced into a statement.
  *
  * Usually you don't construct this directly: `config/agent.ts` selects it via `retrievers.pgvector({...})`
  * and the provider builds it, lazily importing `@adonisjs/lucid` only when the pgvector retriever is
@@ -160,11 +206,11 @@ export class PgVectorStore {
     async listDocuments(filter) {
         const c = this.col;
         const docExpr = documentIdExpr(c.id);
-        const hasFilter = filter !== undefined && Object.keys(filter).length > 0;
+        const where = buildMetadataWhere(filter, c.metadata);
         const raw = await this.db.rawQuery(`SELECT DISTINCT ON (${docExpr}) ${docExpr} AS doc_id, ${c.metadata} AS metadata
        FROM ${this.table}
-       ${hasFilter ? `WHERE ${c.metadata} @> ?::jsonb` : ''}
-       ORDER BY ${docExpr}`, hasFilter ? [JSON.stringify(filter)] : []);
+       ${where.sql}
+       ORDER BY ${docExpr}`, where.bindings);
         return normalizeRows(raw).map((row) => {
             const metadata = parseMetadata(row.metadata);
             return {
@@ -176,21 +222,15 @@ export class PgVectorStore {
     async search(embedding, options) {
         const c = this.col;
         const vector = toVectorLiteral(embedding);
-        const hasFilter = options.filter !== undefined && Object.keys(options.filter).length > 0;
+        const where = buildMetadataWhere(options.filter, c.metadata);
         // Bindings are consumed positionally, in the exact order the `?`s appear: score expr (embedding),
-        // then the optional filter, then the ORDER BY embedding, then the LIMIT. The embedding is bound
-        // TWICE — once per `?::vector` — because a positional `?` cannot be reused like a numbered `$1`.
-        const bindings = [vector];
-        let where = '';
-        if (hasFilter) {
-            where = `WHERE ${c.metadata} @> ?::jsonb`;
-            bindings.push(JSON.stringify(options.filter));
-        }
-        bindings.push(vector, options.topK);
+        // then the optional filter clause(s), then the ORDER BY embedding, then the LIMIT. The embedding is
+        // bound TWICE — once per `?::vector` — because a positional `?` cannot be reused like a numbered `$1`.
+        const bindings = [vector, ...where.bindings, vector, options.topK];
         const raw = await this.db.rawQuery(`SELECT ${c.id} AS id, ${c.text} AS text, ${c.source} AS source, ${c.metadata} AS metadata,
               ${this.metric.score(c.embedding)} AS score
        FROM ${this.table}
-       ${where}
+       ${where.sql}
        ORDER BY ${c.embedding} ${this.metric.operator} ?::vector
        LIMIT ?`, bindings);
         return normalizeRows(raw).map((row) => {

package/dist/src/rag/pg-vector-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"pg-vector-store.js","sourceRoot":"","sources":["../../../src/rag/pg-vector-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pg-vector-store.js","sourceRoot":"","sources":["../../../src/rag/pg-vector-store.ts"],"names":[],"mappings":"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"}

package/dist/src/rag/reranking-retriever.d.ts

@@ -0,0 +1,21 @@
+import type { Reranker } from '../spi/reranker.js';
+import type { Passage, RetrieveOptions, Retriever } from '../spi/retriever.js';
+export interface RerankingRetrieverOptions {
+    /** How many candidates to pull from the base retriever before reranking. Default 20. */
+    fetchTopK?: number;
+}
+/**
+ * Two-stage retrieval: over-fetch cheap candidates from a base {@link Retriever}, then reorder them with
+ * a stronger {@link Reranker} and keep the top few. The standard precision boost — a fast first stage
+ * casts a wide net, a slow accurate second stage sharpens it. Composes over ANY retriever (vector,
+ * hybrid, keyword), and is itself a `Retriever` so it drops straight into the config's `retriever` slot.
+ * Mirrors the reference `RerankingRetriever` exactly.
+ */
+export declare class RerankingRetriever implements Retriever {
+    private readonly base;
+    private readonly reranker;
+    private readonly options;
+    constructor(base: Retriever, reranker: Reranker, options?: RerankingRetrieverOptions);
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+}
+//# sourceMappingURL=reranking-retriever.d.ts.map

package/dist/src/rag/reranking-retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranking-retriever.d.ts","sourceRoot":"","sources":["../../../src/rag/reranking-retriever.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE/E,MAAM,WAAW,yBAAyB;IACxC,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,SAAS;IAEhD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAFP,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,yBAA8B;IAGpD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAOjF"}

package/dist/src/rag/reranking-retriever.js

@@ -0,0 +1,25 @@
+/**
+ * Two-stage retrieval: over-fetch cheap candidates from a base {@link Retriever}, then reorder them with
+ * a stronger {@link Reranker} and keep the top few. The standard precision boost — a fast first stage
+ * casts a wide net, a slow accurate second stage sharpens it. Composes over ANY retriever (vector,
+ * hybrid, keyword), and is itself a `Retriever` so it drops straight into the config's `retriever` slot.
+ * Mirrors the reference `RerankingRetriever` exactly.
+ */
+export class RerankingRetriever {
+    base;
+    reranker;
+    options;
+    constructor(base, reranker, options = {}) {
+        this.base = base;
+        this.reranker = reranker;
+        this.options = options;
+    }
+    async retrieve(query, options = {}) {
+        const candidates = await this.base.retrieve(query, {
+            topK: this.options.fetchTopK ?? 20,
+            ...(options.filter !== undefined ? { filter: options.filter } : {}),
+        });
+        return this.reranker.rerank(query, candidates, { topK: options.topK ?? 5 });
+    }
+}
+//# sourceMappingURL=reranking-retriever.js.map

package/dist/src/rag/reranking-retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranking-retriever.js","sourceRoot":"","sources":["../../../src/rag/reranking-retriever.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,MAAM,OAAO,kBAAkB;IAEV;IACA;IACA;IAHnB,YACmB,IAAe,EACf,QAAkB,EAClB,UAAqC,EAAE;QAFvC,SAAI,GAAJ,IAAI,CAAW;QACf,aAAQ,GAAR,QAAQ,CAAU;QAClB,YAAO,GAAP,OAAO,CAAgC;IACvD,CAAC;IAEJ,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,UAA2B,EAAE;QACzD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE;YACjD,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE;YAClC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpE,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;CACF"}

package/dist/src/rag/vector-store.d.ts

@@ -10,7 +10,11 @@ export interface VectorRecord {
 }
 export interface VectorSearchOptions {
     topK: number;
-    /** Exact-match metadata filter (all keys must equal). Passed through from `RetrieveOptions.filter`. */
+    /**
+     * Metadata filter, passed through from `RetrieveOptions.filter`. A scalar value is exact-match; an
+     * array value is match-any (OR / set membership), with an empty array denying everything — the
+     * capability-token ACL primitive. See {@link import('./filter.js').matchesFilter}.
+     */
     filter?: Record<string, unknown>;
 }
 /**

package/dist/src/rag/vector-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../../../src/rag/vector-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9E;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;;OAIG;IACH,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAC7E;AAED,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../../../src/rag/vector-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9E;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;;OAIG;IACH,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAC7E;AAED,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/src/rag/vector-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"vector-store.js","sourceRoot":"","sources":["../../../src/rag/vector-store.ts"],"names":[],"mappings":"AAiDA,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"vector-store.js","sourceRoot":"","sources":["../../../src/rag/vector-store.ts"],"names":[],"mappings":"AAqDA,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC"}

package/dist/src/spi/reranker.d.ts

@@ -7,8 +7,10 @@ export interface RerankOptions {
  * Re-scores retrieved passages against the query with a stronger (usually cross-encoder) model than
  * the first-stage retriever — the standard precision boost for RAG. It's a black box like
  * {@link import('./retriever.js').Retriever}: bring a Cohere/Voyage rerank endpoint or a local
- * cross-encoder. Provider implementations are deferred this round (SPI only); the testing kit ships a
- * trivial identity reranker. Mirrors the reference `Reranker` contract exactly.
+ * cross-encoder. Compose one over a base retriever with
+ * {@link import('../rag/reranking-retriever.js').RerankingRetriever}. Provider implementations are
+ * deferred this round (SPI only); the testing kit ships a deterministic lexical-overlap reranker.
+ * Mirrors the reference `Reranker` contract exactly.
  */
 export interface Reranker {
     /** Re-order `passages` by relevance to `query`, rewriting their `score`; may drop to `topK`. */

package/dist/src/spi/reranker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../../../src/spi/reranker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,gGAAgG;IAChG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACzF"}
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../../../src/spi/reranker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,gGAAgG;IAChG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACzF"}

package/dist/src/spi/tool.d.ts

@@ -14,8 +14,12 @@ export interface AiToolCtx {
     /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
     host?: unknown;
 }
-/** A tool implementation. `I` is the parsed (Zod-validated) input. */
-export interface ToolHandler<I = unknown> {
-    execute(input: I, ctx: AiToolCtx): Promise<unknown>;
+/**
+ * A tool implementation. `I` is the parsed (Zod-validated) input; `O` is what `execute` returns
+ * (serialized back to the model). `O` defaults to `unknown` — so `ToolHandler<I>` keeps working —
+ * but typing it lets the compiler check the return against what the tool promises.
+ */
+export interface ToolHandler<I = unknown, O = unknown> {
+    execute(input: I, ctx: AiToolCtx): Promise<O> | O;
 }
 //# sourceMappingURL=tool.d.ts.map

package/dist/src/spi/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../src/spi/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,OAAO,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../src/spi/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IACnD,OAAO,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CACnD"}

package/dist/src/testing/fake-embedding-provider.d.ts

@@ -17,11 +17,14 @@ export declare class FakeEmbeddingProvider implements EmbeddingProvider {
     private embedOne;
 }
 /**
- * A trivial identity {@link Reranker} for tests: keeps the retriever's order, only truncating to
- * `topK`. Stands in for a real cross-encoder rerank endpoint (provider impls deferred this round).
+ * A deterministic, offline {@link Reranker} for tests: re-scores each passage by how many distinct
+ * query terms it contains (lexical overlap), then sorts descending and truncates to `topK`. No model,
+ * no randomness — enough to prove {@link import('../rag/reranking-retriever.js').RerankingRetriever}
+ * genuinely RE-ORDERS candidates (not just truncates) against a known-relevant passage. Stands in for a
+ * real cross-encoder rerank endpoint (provider impls deferred this round). Mirrors the reference fake.
  */
 export declare class FakeReranker implements Reranker {
-    rerank(_query: string, passages: Passage[], options?: RerankOptions): Promise<Passage[]>;
+    rerank(query: string, passages: Passage[], options?: RerankOptions): Promise<Passage[]>;
 }
 /**
  * Build a ready-to-use in-memory {@link EmbeddingRetriever} for tests: a {@link MemoryVectorStore} fed

package/dist/src/testing/fake-embedding-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake-embedding-provider.d.ts","sourceRoot":"","sources":["../../../src/testing/fake-embedding-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,KAAK,cAAc,EAAmB,MAAM,kBAAkB,CAAC;AAExE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;GAMG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,SAAK;IAEtC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAIjD,OAAO,CAAC,QAAQ;CAWjB;AAYD;;;GAGG;AACH,qBAAa,YAAa,YAAW,QAAQ;IACrC,MAAM,CACV,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,OAAO,EAAE,CAAC;CAGtB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAY9B"}
+{"version":3,"file":"fake-embedding-provider.d.ts","sourceRoot":"","sources":["../../../src/testing/fake-embedding-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,KAAK,cAAc,EAAmB,MAAM,kBAAkB,CAAC;AAExE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;GAMG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,SAAK;IAEtC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAIjD,OAAO,CAAC,QAAQ;CAWjB;AAYD;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,QAAQ;IACrC,MAAM,CACV,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,OAAO,EAAE,CAAC;CAetB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAY9B"}

package/dist/src/testing/fake-embedding-provider.js

@@ -38,12 +38,27 @@ function hashToken(token, dimensions) {
     return (hash >>> 0) % dimensions;
 }
 /**
- * A trivial identity {@link Reranker} for tests: keeps the retriever's order, only truncating to
- * `topK`. Stands in for a real cross-encoder rerank endpoint (provider impls deferred this round).
+ * A deterministic, offline {@link Reranker} for tests: re-scores each passage by how many distinct
+ * query terms it contains (lexical overlap), then sorts descending and truncates to `topK`. No model,
+ * no randomness — enough to prove {@link import('../rag/reranking-retriever.js').RerankingRetriever}
+ * genuinely RE-ORDERS candidates (not just truncates) against a known-relevant passage. Stands in for a
+ * real cross-encoder rerank endpoint (provider impls deferred this round). Mirrors the reference fake.
  */
 export class FakeReranker {
-    async rerank(_query, passages, options = {}) {
-        return options.topK !== undefined ? passages.slice(0, options.topK) : passages;
+    async rerank(query, passages, options = {}) {
+        const terms = new Set(query.toLowerCase().match(/[a-z0-9]+/g) ?? []);
+        const scored = passages.map((passage) => {
+            const words = new Set(passage.text.toLowerCase().match(/[a-z0-9]+/g) ?? []);
+            let overlap = 0;
+            for (const term of terms) {
+                if (words.has(term)) {
+                    overlap += 1;
+                }
+            }
+            return { ...passage, score: overlap };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        return options.topK !== undefined ? scored.slice(0, options.topK) : scored;
     }
 }
 /**

package/dist/src/testing/fake-embedding-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"fake-embedding-provider.js","sourceRoot":"","sources":["../../../src/testing/fake-embedding-provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fake-embedding-provider.js","sourceRoot":"","sources":["../../../src/testing/fake-embedding-provider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {