@adonis-agora/agent 0.8.0 → 0.10.0

package/dist/src/diagnostics.js

@@ -7,6 +7,7 @@
  * Events land on `agora:agent:<event>`; the payload shapes below are the contract every consumer
  * (dashboard / telescope) reads.
  */
+import diagnostics_channel from 'node:diagnostics_channel';
 const EMIT_SLOT = Symbol.for('@agora/diagnostics:emit');
 /**
  * Publish an agent event on `agora:agent:<event>` via the structural diagnostics slot. No-op when
@@ -47,4 +48,127 @@ export function publishAgentRetrieved(payload) {
 export function publishAgentToolRetry(payload) {
     publishAgent('tool.retry', payload);
 }
+// ── Run-tracing spans ─────────────────────────────────────────────────────────
+//
+// Point events above tell you WHAT happened; spans tell you the SHAPE of a turn — a start/end pair
+// per genuinely-executed operation, all correlated by `traceId = runId`, so telescope renders one
+// turn as a waterfall. Spans ride the SAME `agora:agent:*` convention as the point events, but on the
+// five span sub-channels `agora:agent:<event>:<phase>` (start / end / asyncStart / asyncEnd / error) —
+// byte-for-byte the wire shape `@adonis-agora/diagnostics`' own `trace()` publishes, so a span-aware
+// bridge reads agent spans with ZERO agent→diagnostics coupling.
+//
+// We publish them directly over Node's builtin `node:diagnostics_channel` (a Node builtin — no
+// diagnostics import, no emit slot needed), exactly as the media-ingestion subscribe path does. Cost
+// is a handful of `hasSubscribers` reads when nothing is listening.
+//
+// REPLAY SAFETY: `spannedAgent` MUST be called from INSIDE a `hooks.step` body (→ `ctx.localStep`).
+// Durable replay skips step bodies and returns the checkpoint, so a replayed run never re-emits a
+// span. The root `turn` span (which spans the whole loop) is therefore a RUNNER concern: the inline
+// runner emits it once around the loop; the durable runner does not emit a body-level root (it would
+// re-emit per replay slice) and relies on the `traceId = runId` grouping to root the trace.
+/** Span envelope schema version — matches `@adonis-agora/diagnostics`' `SPAN_SCHEMA_VERSION`. */
+const SPAN_SCHEMA_VERSION = 1;
+const SPAN_CHANNEL_PREFIX = 'agora';
+const SPAN_LIB = 'agent';
+/** Per-event memo of the resolved span channels — the steady state is a single `Map.get`. */
+const spanChannelCache = new Map();
+function getSpanChannels(event) {
+    const cached = spanChannelCache.get(event);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const base = `${SPAN_CHANNEL_PREFIX}:${SPAN_LIB}:${event}`;
+    const channels = {
+        start: diagnostics_channel.channel(`${base}:start`),
+        end: diagnostics_channel.channel(`${base}:end`),
+        asyncStart: diagnostics_channel.channel(`${base}:asyncStart`),
+        asyncEnd: diagnostics_channel.channel(`${base}:asyncEnd`),
+        error: diagnostics_channel.channel(`${base}:error`),
+    };
+    spanChannelCache.set(event, channels);
+    return channels;
+}
+/** True when ANY of the five span sub-channels currently has a subscriber. */
+function anySpanSubscribed(channels) {
+    return (channels.start.hasSubscribers ||
+        channels.end.hasSubscribers ||
+        channels.asyncStart.hasSubscribers ||
+        channels.asyncEnd.hasSubscribers ||
+        channels.error.hasSubscribers);
+}
+let spanCounter = 0;
+/** A cheap, process-unique span id. Allocated only when a span is actually observed. */
+function nextSpanId() {
+    spanCounter = (spanCounter + 1) >>> 0;
+    return `${Date.now().toString(36)}-${spanCounter.toString(36)}`;
+}
+/** Publish one phase on its sub-channel; never throws back into the agent loop. */
+function publishSpanPhase(channel, phase, event, spanId, traceId, extra) {
+    if (!channel.hasSubscribers) {
+        return;
+    }
+    try {
+        channel.publish({
+            v: SPAN_SCHEMA_VERSION,
+            ts: Date.now(),
+            lib: SPAN_LIB,
+            event,
+            phase,
+            spanId,
+            traceId,
+            ...extra,
+        });
+    }
+    catch {
+        // Observability must never break the traced code path.
+    }
+}
+/**
+ * Wrap a genuinely-executing async operation in an `agora:agent:<event>` span correlated to its run
+ * by `traceId = runId`, WITHOUT letting the operation's raw return value ride the span envelope: only
+ * the (redaction-safe) `summarize`d metadata is published as the span `result`, while the real value
+ * is handed straight back to the caller. Zero-cost when no span sub-channel has a subscriber (runs
+ * `run()` directly). Never throws from the span machinery — only `run()`'s own rejection propagates.
+ *
+ * Mirrors the async lifecycle of `@adonis-agora/diagnostics`' `trace()`: `start` → `end` (sync
+ * portion) → `asyncStart` → `asyncEnd` (with the summary) on success, or `error` on rejection.
+ *
+ * MUST be called from inside a `hooks.step` body (→ `ctx.localStep`) so durable replay — which skips
+ * step bodies — never re-emits the span. See the module header.
+ */
+export async function spannedAgent(event, traceId, payload, run, summarize) {
+    const channels = getSpanChannels(event);
+    if (!anySpanSubscribed(channels)) {
+        return run();
+    }
+    const spanId = nextSpanId();
+    const startedAt = performance.now();
+    publishSpanPhase(channels.start, 'start', event, spanId, traceId, { payload });
+    publishSpanPhase(channels.end, 'end', event, spanId, traceId, {
+        durationMs: performance.now() - startedAt,
+    });
+    publishSpanPhase(channels.asyncStart, 'asyncStart', event, spanId, traceId, {});
+    try {
+        const value = await run();
+        let result;
+        try {
+            result = summarize(value);
+        }
+        catch {
+            result = undefined;
+        }
+        publishSpanPhase(channels.asyncEnd, 'asyncEnd', event, spanId, traceId, {
+            ...(result !== undefined ? { result } : {}),
+            durationMs: performance.now() - startedAt,
+        });
+        return value;
+    }
+    catch (error) {
+        publishSpanPhase(channels.error, 'error', event, spanId, traceId, {
+            error,
+            durationMs: performance.now() - startedAt,
+        });
+        throw error;
+    }
+}
 //# sourceMappingURL=diagnostics.js.map

package/dist/src/diagnostics.js.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AA0ExD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAQ,EACR,OAAmC;IAEnC,MAAM,IAAI,GAAI,UAAsC,CAAC,SAAS,CAAuB,CAAC;IACtF,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;QAC9C,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAwB;IAC7D,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC;AACD,MAAM,UAAU,mBAAmB,CAAC,OAA0B;IAC5D,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC;AACD,MAAM,UAAU,oBAAoB,CAAC,OAA2B;IAC9D,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AACD,MAAM,UAAU,yBAAyB,CAAC,OAA2B;IACnE,YAAY,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AACD,MAAM,UAAU,uBAAuB,CAAC,OAAyB;IAC/D,YAAY,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AACxC,CAAC;AACD,MAAM,UAAU,qBAAqB,CAAC,OAAuB;IAC3D,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AACD,MAAM,UAAU,qBAAqB,CAAC,OAAuB;IAC3D,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AACD,MAAM,UAAU,qBAAqB,CAAC,OAAuB;IAC3D,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,mBAAqC,MAAM,0BAA0B,CAAC;AAE7E,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AA0ExD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAQ,EACR,OAAmC;IAEnC,MAAM,IAAI,GAAI,UAAsC,CAAC,SAAS,CAAuB,CAAC;IACtF,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;QAC9C,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAwB;IAC7D,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC;AACD,MAAM,UAAU,mBAAmB,CAAC,OAA0B;IAC5D,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC;AACD,MAAM,UAAU,oBAAoB,CAAC,OAA2B;IAC9D,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AACD,MAAM,UAAU,yBAAyB,CAAC,OAA2B;IACnE,YAAY,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AACD,MAAM,UAAU,uBAAuB,CAAC,OAAyB;IAC/D,YAAY,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AACxC,CAAC;AACD,MAAM,UAAU,qBAAqB,CAAC,OAAuB;IAC3D,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AACD,MAAM,UAAU,qBAAqB,CAAC,OAAuB;IAC3D,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AACD,MAAM,UAAU,qBAAqB,CAAC,OAAuB;IAC3D,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC;AAED,iFAAiF;AACjF,EAAE;AACF,mGAAmG;AACnG,kGAAkG;AAClG,sGAAsG;AACtG,uGAAuG;AACvG,qGAAqG;AACrG,iEAAiE;AACjE,EAAE;AACF,+FAA+F;AAC/F,qGAAqG;AACrG,oEAAoE;AACpE,EAAE;AACF,oGAAoG;AACpG,kGAAkG;AAClG,oGAAoG;AACpG,qGAAqG;AACrG,4FAA4F;AAE5F,iGAAiG;AACjG,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAC9B,MAAM,mBAAmB,GAAG,OAAO,CAAC;AACpC,MAAM,QAAQ,GAAG,OAAO,CAAC;AA4CzB,6FAA6F;AAC7F,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAwB,CAAC;AAEzD,SAAS,eAAe,CAAC,KAAa;IACpC,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,mBAAmB,IAAI,QAAQ,IAAI,KAAK,EAAE,CAAC;IAC3D,MAAM,QAAQ,GAAiB;QAC7B,KAAK,EAAE,mBAAmB,CAAC,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC;QACnD,GAAG,EAAE,mBAAmB,CAAC,OAAO,CAAC,GAAG,IAAI,MAAM,CAAC;QAC/C,UAAU,EAAE,mBAAmB,CAAC,OAAO,CAAC,GAAG,IAAI,aAAa,CAAC;QAC7D,QAAQ,EAAE,mBAAmB,CAAC,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC;QACzD,KAAK,EAAE,mBAAmB,CAAC,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC;KACpD,CAAC;IACF,gBAAgB,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACtC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,8EAA8E;AAC9E,SAAS,iBAAiB,CAAC,QAAsB;IAC/C,OAAO,CACL,QAAQ,CAAC,KAAK,CAAC,cAAc;QAC7B,QAAQ,CAAC,GAAG,CAAC,cAAc;QAC3B,QAAQ,CAAC,UAAU,CAAC,cAAc;QAClC,QAAQ,CAAC,QAAQ,CAAC,cAAc;QAChC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAC9B,CAAC;AACJ,CAAC;AAED,IAAI,WAAW,GAAG,CAAC,CAAC;AACpB,wFAAwF;AACxF,SAAS,UAAU;IACjB,WAAW,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACtC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,mFAAmF;AACnF,SAAS,gBAAgB,CACvB,OAAgB,EAChB,KAAgB,EAChB,KAAa,EACb,MAAc,EACd,OAAe,EACf,KAAoF;IAEpF,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;QAC5B,OAAO;IACT,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,OAAO,CAAC;YACd,CAAC,EAAE,mBAAmB;YACtB,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;YACd,GAAG,EAAE,QAAQ;YACb,KAAK;YACL,KAAK;YACL,MAAM;YACN,OAAO;YACP,GAAG,KAAK;SACT,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,uDAAuD;IACzD,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAQ,EACR,OAAe,EACf,OAA6B,EAC7B,GAAqB,EACrB,SAAgD;IAEhD,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACxC,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,OAAO,GAAG,EAAE,CAAC;IACf,CAAC;IACD,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IACpC,gBAAgB,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/E,gBAAgB,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAC5D,UAAU,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;KAC1C,CAAC,CAAC;IACH,gBAAgB,CAAC,QAAQ,CAAC,UAAU,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IAChF,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,GAAG,EAAE,CAAC;QAC1B,IAAI,MAA2C,CAAC;QAChD,IAAI,CAAC;YACH,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,SAAS,CAAC;QACrB,CAAC;QACD,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;YACtE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3C,UAAU,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;SAC1C,CAAC,CAAC;QACH,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gBAAgB,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;YAChE,KAAK;YACL,UAAU,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;SAC1C,CAAC,CAAC;QACH,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/src/durable/agent-run-workflow.d.ts

@@ -19,7 +19,11 @@ export interface DurableAgentRunInput extends AgentRunInput {
  * suspend-and-resume:
  *  - `step(name, fn)` → `ctx.localStep` — every LLM turn, tool execution, and persist/quota write is a
  *    checkpoint, so a replay returns the cached result instead of re-running it (stable ids, no
- *    double-write, no re-streamed tokens).
+ *    double-write, no re-streamed tokens). The run-tracing SPANS (`agora:agent:llm.turn` /
+ *    `tool.execution` / `retrieval`) are emitted from INSIDE these step bodies, so a replay — which
+ *    skips the bodies — never re-emits them. Unlike the inline runner, the durable workflow does NOT
+ *    emit a body-level root `turn` span (the body replays, which would duplicate it); the trace is
+ *    rooted implicitly by `traceId = runId`, which every child span already carries.
  *  - `awaitApproval(call)` → `ctx.waitForSignal('tool:<runId>:<callId>')` — an action tool suspends the
  *    run with zero compute until an approve/reject signal arrives (namespaced by run, so one run's
  *    decision can never satisfy another's).

package/dist/src/durable/agent-run-workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-run-workflow.d.ts","sourceRoot":"","sources":["../../../src/durable/agent-run-workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAEZ,KAAK,WAAW,EAEjB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAG3D;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AA+BD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,OAAgB,QAAQ;;;MAA6C;IAE/D,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAuEpF"}
+{"version":3,"file":"agent-run-workflow.d.ts","sourceRoot":"","sources":["../../../src/durable/agent-run-workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAEZ,KAAK,WAAW,EAEjB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAG3D;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AA+BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,OAAgB,QAAQ;;;MAA6C;IAE/D,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAuEpF"}

package/dist/src/durable/agent-run-workflow.js

@@ -35,7 +35,11 @@ function childSinkWriter(inner) {
  * suspend-and-resume:
  *  - `step(name, fn)` → `ctx.localStep` — every LLM turn, tool execution, and persist/quota write is a
  *    checkpoint, so a replay returns the cached result instead of re-running it (stable ids, no
- *    double-write, no re-streamed tokens).
+ *    double-write, no re-streamed tokens). The run-tracing SPANS (`agora:agent:llm.turn` /
+ *    `tool.execution` / `retrieval`) are emitted from INSIDE these step bodies, so a replay — which
+ *    skips the bodies — never re-emits them. Unlike the inline runner, the durable workflow does NOT
+ *    emit a body-level root `turn` span (the body replays, which would duplicate it); the trace is
+ *    rooted implicitly by `traceId = runId`, which every child span already carries.
  *  - `awaitApproval(call)` → `ctx.waitForSignal('tool:<runId>:<callId>')` — an action tool suspends the
  *    run with zero compute until an approve/reject signal arrives (namespaced by run, so one run's
  *    decision can never satisfy another's).

package/dist/src/durable/agent-run-workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-run-workflow.js","sourceRoot":"","sources":["../../../src/durable/agent-run-workflow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-run-workflow.js","sourceRoot":"","sources":["../../../src/durable/agent-run-workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,aAAa,EAEb,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAuB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAgBhE;;;;;;GAMG;AACH,SAAS,mBAAmB,CAAC,KAAc;IACzC,IAAI,KAAK,YAAY,iBAAiB,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;QACzE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAI,KAAmC,EAAE,IAAI,CAAC;IACxD,OAAO,IAAI,KAAK,mBAAmB,IAAI,IAAI,KAAK,eAAe,CAAC;AAClE,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,KAAiB;IACxC,OAAO;QACL,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;QACpC,GAAG,EAAE,GAAG,EAAE;YACR,kCAAkC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAChD,MAAM,CAAU,QAAQ,GAAG,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAErE,KAAK,CAAC,GAAG,CAAC,GAAgB,EAAE,KAA2B;QACrD,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,sBAAsB,EAAE,CAAC;QACpD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,MAAM,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC;QAC9C,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,GAAG,CAAC,KAAK,CAAC;QAE/C,MAAM,KAAK,GAAmB;YAC5B,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,OAAO,EAAE,IAAI;YACb,+FAA+F;YAC/F,8EAA8E;YAC9E,QAAQ,EAAE,KAAK,IAAI,EAAE,CACnB,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YACxF,+FAA+F;YAC/F,6FAA6F;YAC7F,aAAa,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,aAAa,CAAW,QAAQ,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;YACpF,sFAAsF;YACtF,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3C,sFAAsF;YACtF,gFAAgF;YAChF,kBAAkB,EAAE,mBAAmB;YACvC,4FAA4F;YAC5F,qEAAqE;YACrE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE;gBAClC,MAAM,WAAW,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,aAAa,SAAS,EAAE,EAAE,KAAK,IAAI,EAAE;oBAC3E,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC;wBACtC,KAAK,EAAE,KAAK,CAAC,KAAK;wBAClB,OAAO,EAAE,SAAS;wBAClB,SAAS,EAAE,IAAI;qBAChB,CAAC,CAAC;oBACH,OAAO,MAAM,CAAC,EAAE,CAAC;gBACnB,CAAC,CAAC,CAAC;gBACH,OAAO,GAAG,CAAC,KAAK,CAAC,gBAAgB,EAAE;oBACjC,SAAS;oBACT,QAAQ,EAAE,WAAW;oBACrB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,IAAI;oBACd,GAAG;oBACH,eAAe,EAAE,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,CAAC,GAAG,CAAC;oBACjD,SAAS;iBACV,CAAC,CAAC;YACL,CAAC;SACF,CAAC;QAEF,IAAI,CAAC;YACH,OAAO,MAAM,YAAY,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,yFAAyF;YACzF,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/B,MAAM,KAAK,CAAC;YACd,CAAC;YACD,+FAA+F;YAC/F,6FAA6F;YAC7F,6FAA6F;YAC7F,2FAA2F;YAC3F,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,6FAA6F;YAC7F,0FAA0F;YAC1F,4FAA4F;YAC5F,MAAM,GAAG,CAAC,SAAS,CAAC,kBAAkB,EAAE,GAAG,EAAE,CAC3C,KAAK,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAC3E,CAAC;YACF,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBAC/C,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,aAAa,OAAO,EAAE,CAAC,CAAC,CAAC;gBACrE,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC;YACrB,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC"}

package/dist/src/index.d.ts

@@ -1,6 +1,7 @@
-export declare const VERSION = "0.8.0";
+export declare const VERSION = "0.10.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.10.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":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;AAEhC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,YAAY,EACZ,kBAAkB,GAGnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,qCAAqC,EACrC,uCAAuC,GACxC,MAAM,iBAAiB,CAAC;AAMzB,cAAc,kBAAkB,CAAC;AAEjC,gFAAgF;AAChF,OAAO,EACL,YAAY,EACZ,MAAM,EACN,MAAM,EACN,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAgCnD,OAAO,EACL,MAAM,EACN,UAAU,EACV,cAAc,EACd,uBAAuB,EACvB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEpG,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EACL,oBAAoB,GAErB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAQpD,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,GACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAE9E,gFAAgF;AAChF,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,WAAW,EACX,aAAa,GACd,MAAM,iBAAiB,CAAC"}

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":"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"}

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"}