@adonis-agora/agent 0.1.0

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

@@ -0,0 +1,128 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var AgentRunWorkflow_1;
+import { ContinueAsNew, Workflow, WorkflowSuspended, } from '@adonis-agora/durable';
+import { utcDay } from '../agent-deps.js';
+import { runAgentLoop } from '../agent-loop.js';
+import { getDurableAgentContext } from './agent-run-context.js';
+/**
+ * A control-flow signal (suspend / continue-as-new) the durable engine throws THROUGH the workflow
+ * body to pause it — NOT a failure. `runAgentLoop` suspends by letting `ctx.waitForSignal` (HITL) or
+ * `ctx.child` (delegation) throw here; the workflow's catch must re-throw it so the engine handles
+ * it. Checked by `instanceof` AND by `name` so a duplicated copy of the durable module (whose class
+ * identity differs) is still recognised.
+ */
+function isControlFlowSignal(error) {
+    if (error instanceof WorkflowSuspended || error instanceof ContinueAsNew) {
+        return true;
+    }
+    const name = error?.name;
+    return name === 'WorkflowSuspended' || name === 'ContinueAsNew';
+}
+/**
+ * Wrap a {@link SinkWriter} so a CHILD run forwards tokens into the top-level stream but never closes
+ * it: the top-level run owns the stream's lifecycle across however many delegations it spans, so a
+ * child's `end()` must be a no-op (ending the shared stream mid-parent-run would cut the human off).
+ */
+function childSinkWriter(inner) {
+    return {
+        write: (chunk) => inner.write(chunk),
+        end: () => {
+            /* the top-level run owns end() */
+        },
+    };
+}
+/**
+ * The agent turn AS a durable workflow — the replay-safe counterpart of `InlineAgentRunner`. The
+ * shared `runAgentLoop` body drives model→tools→model exactly as inline; the durable hooks make it
+ * 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).
+ *  - `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).
+ *  - `runAgent(name, task)` → `ctx.child(AgentRunWorkflow, …)` — sub-agent delegation is a tracked,
+ *    replay-safe CHILD run (a node in the durable dashboard) that streams into the top-level sink.
+ *  - `openSink()` → the run's own sink writer (top-level) or a {@link childSinkWriter} (a child).
+ *
+ * Instantiated by the engine with no arguments; its deps come from {@link getDurableAgentContext}.
+ */
+let AgentRunWorkflow = AgentRunWorkflow_1 = class AgentRunWorkflow {
+    async run(ctx, input) {
+        const { factory, store } = getDurableAgentContext();
+        const day = input.day ?? utcDay();
+        const deps = factory.forAgent(input.agentName);
+        const isChild = input.sinkRunId !== undefined;
+        const sinkRunId = input.sinkRunId ?? ctx.runId;
+        const hooks = {
+            runId: ctx.runId,
+            durable: true,
+            // A child forwards into the top-level sink (so the human watching the parent sees it) but must
+            // not end it; a top-level run opens and owns its own sink keyed by its runId.
+            openSink: async () => isChild ? childSinkWriter(await deps.sink.open(sinkRunId)) : deps.sink.open(ctx.runId),
+            // HITL: suspend until the run-namespaced signal arrives. This throw escapes the loop cleanly —
+            // it happens BEFORE the loop's tool try/catch, so a suspend is never seen as a tool failure.
+            awaitApproval: (call) => ctx.waitForSignal(`tool:${ctx.runId}:${call.id}`),
+            // Every side effect + control-flow read is a durable local step (memoized on replay).
+            step: (name, fn) => ctx.localStep(name, fn),
+            // Lets the tool transient-retry loop tell a real suspend/continue-as-new apart from a
+            // retryable tool error, so a control-flow signal is never swallowed by a retry.
+            isControlFlowError: isControlFlowSignal,
+            // Delegation: a fresh transient subthread (checkpointed so its id is replay-stable), then a
+            // tracked child run that streams into this run's own top-level sink.
+            runAgent: async (agentName, task) => {
+                const subThreadId = await ctx.localStep(`subthread:${agentName}`, async () => {
+                    const thread = await store.createThread({
+                        actor: input.actor,
+                        persona: 'default',
+                        transient: true,
+                    });
+                    return thread.id;
+                });
+                return ctx.child(AgentRunWorkflow_1, {
+                    agentName,
+                    threadId: subThreadId,
+                    actor: input.actor,
+                    userText: task,
+                    day,
+                    delegationDepth: (input.delegationDepth ?? 0) + 1,
+                    sinkRunId,
+                });
+            },
+        };
+        try {
+            return await runAgentLoop({ ...deps, day }, input, hooks);
+        }
+        catch (error) {
+            // A suspend / continue-as-new is control flow, not a failure — let the engine handle it.
+            if (isControlFlowSignal(error)) {
+                throw error;
+            }
+            // A real failure (e.g. quota exceeded, which throws before the sink is opened) would otherwise
+            // leave an HTTP subscriber hanging on a stream that never ends. Surface it on the stream and
+            // close it, then rethrow so the engine still records the run as failed. Only a top-level run
+            // owns the stream — a child defers the surfaced error to its ancestor, which also unwinds.
+            const message = error instanceof Error ? error.message : String(error);
+            // Settle the run's persisted outcome (the loop only records completions — it can't catch its
+            // own crash). A checkpointed step so a replay re-settles the ONE row idempotently; first-
+            // terminal, so it can't clobber a completion. Each run (parent AND child) owns its own row.
+            await ctx.localStep('persist:run:fail', () => store.recordRunEnd({ runId: ctx.runId, status: 'failed', error: message }));
+            if (!isChild) {
+                const writer = await deps.sink.open(ctx.runId);
+                await writer.write(new TextEncoder().encode(`\n[error] ${message}`));
+                await writer.end();
+            }
+            throw error;
+        }
+    }
+};
+AgentRunWorkflow = AgentRunWorkflow_1 = __decorate([
+    Workflow({ name: 'agora.agent.run', version: '1' })
+], AgentRunWorkflow);
+export { AgentRunWorkflow };
+//# sourceMappingURL=agent-run-workflow.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-run-workflow.js","sourceRoot":"","sources":["../../../src/durable/agent-run-workflow.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EACL,aAAa,EACb,QAAQ,EAER,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;;;;;;;;;;;;;;;GAeG;AAEI,IAAM,gBAAgB,wBAAtB,MAAM,gBAAgB;IAC3B,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,kBAAgB,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;CACF,CAAA;AAxEY,gBAAgB;IAD5B,QAAQ,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;GACvC,gBAAgB,CAwE5B"}

package/dist/src/durable/durable-agent-runner.d.ts

@@ -0,0 +1,25 @@
+import type { WorkflowEngine } from '@adonis-agora/durable';
+import type { AgentRunner } from '../spi/agent-runner.js';
+import type { AgentStore } from '../spi/agent-store.js';
+import type { AgentRunInput, Decision } from '../types.js';
+/**
+ * Runs the agent turn as an `@adonis-agora/durable` workflow ({@link AgentRunWorkflow}) — the opt-in
+ * runner (`durable: true`). `start` enqueues the run and returns its id immediately (a worker runs the
+ * body and streams to the sink meanwhile); HITL approval is delivered as a durable signal namespaced
+ * by run, so it can never cross-resolve another run. Mirrors the {@link InlineAgentRunner} interface.
+ */
+export declare class DurableAgentRunner implements AgentRunner {
+    private readonly engine;
+    private readonly store?;
+    /**
+     * `store` is optional so a bare `new DurableAgentRunner(engine)` still works; when passed (the
+     * provider does), {@link cancel} settles the `agent_run` row `cancelled` for governance.
+     */
+    constructor(engine: WorkflowEngine, store?: AgentStore | undefined);
+    start(input: AgentRunInput): Promise<{
+        runId: string;
+    }>;
+    signal(runId: string, toolCallId: string, decision: Decision): Promise<void>;
+    cancel(runId: string): Promise<void>;
+}
+//# sourceMappingURL=durable-agent-runner.d.ts.map

package/dist/src/durable/durable-agent-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-agent-runner.d.ts","sourceRoot":"","sources":["../../../src/durable/durable-agent-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAe3D;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IAMlD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IANzB;;;OAGG;gBAEgB,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,UAAU,YAAA;IAG/B,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAiBvD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAO3C"}

package/dist/src/durable/durable-agent-runner.js

@@ -0,0 +1,59 @@
+import { utcDay } from '../agent-deps.js';
+import { AgentRunWorkflow } from './agent-run-workflow.js';
+/**
+ * A control-flow signal surfaced out of `engine.start`. With the default in-process dispatcher the
+ * body runs on a microtask AFTER `start` returns, so this never fires; but an app that configures a
+ * DRIVING dispatcher (a durable worker/tenant) can surface the engine's internal suspend synchronously
+ * here — expected control flow, NOT a start failure. Recognised by `name` so it survives a duplicated
+ * durable module copy (whose class identity would differ).
+ */
+function isControlFlowSignal(error) {
+    const name = error?.name;
+    return name === 'WorkflowSuspended' || name === 'ContinueAsNew';
+}
+/**
+ * Runs the agent turn as an `@adonis-agora/durable` workflow ({@link AgentRunWorkflow}) — the opt-in
+ * runner (`durable: true`). `start` enqueues the run and returns its id immediately (a worker runs the
+ * body and streams to the sink meanwhile); HITL approval is delivered as a durable signal namespaced
+ * by run, so it can never cross-resolve another run. Mirrors the {@link InlineAgentRunner} interface.
+ */
+export class DurableAgentRunner {
+    engine;
+    store;
+    /**
+     * `store` is optional so a bare `new DurableAgentRunner(engine)` still works; when passed (the
+     * provider does), {@link cancel} settles the `agent_run` row `cancelled` for governance.
+     */
+    constructor(engine, store) {
+        this.engine = engine;
+        this.store = store;
+    }
+    async start(input) {
+        const stamped = { ...input, day: input.day ?? utcDay() };
+        // Own the run id so we can still return it when the run suspends synchronously on start (below).
+        const runId = crypto.randomUUID();
+        try {
+            await this.engine.start(AgentRunWorkflow, stamped, runId);
+        }
+        catch (error) {
+            // A run that suspends on its first step under a driving dispatcher surfaces a control-flow
+            // signal here — the run is already persisted and a worker resumes it, so swallow it and return
+            // the id; any other error is a real start failure and propagates.
+            if (!isControlFlowSignal(error)) {
+                throw error;
+            }
+        }
+        return { runId };
+    }
+    async signal(runId, toolCallId, decision) {
+        await this.engine.signal(`tool:${runId}:${toolCallId}`, decision);
+    }
+    async cancel(runId) {
+        // Best-effort: cascade cancellation to children and broadcast to the owning worker. A run that
+        // already settled is a no-op. Errors are swallowed — cancel is advisory, not a guarantee.
+        await this.engine.cancel(runId).catch(() => undefined);
+        // Settle the persisted run `cancelled` (first-terminal: a run that already completed stays put).
+        await this.store?.recordRunEnd({ runId, status: 'cancelled' }).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=durable-agent-runner.js.map

package/dist/src/durable/durable-agent-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-agent-runner.js","sourceRoot":"","sources":["../../../src/durable/durable-agent-runner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAI1C,OAAO,EAAE,gBAAgB,EAA6B,MAAM,yBAAyB,CAAC;AAEtF;;;;;;GAMG;AACH,SAAS,mBAAmB,CAAC,KAAc;IACzC,MAAM,IAAI,GAAI,KAAmC,EAAE,IAAI,CAAC;IACxD,OAAO,IAAI,KAAK,mBAAmB,IAAI,IAAI,KAAK,eAAe,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,kBAAkB;IAMV;IACA;IANnB;;;OAGG;IACH,YACmB,MAAsB,EACtB,KAAkB;QADlB,WAAM,GAAN,MAAM,CAAgB;QACtB,UAAK,GAAL,KAAK,CAAa;IAClC,CAAC;IAEJ,KAAK,CAAC,KAAK,CAAC,KAAoB;QAC9B,MAAM,OAAO,GAAyB,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,MAAM,EAAE,EAAE,CAAC;QAC/E,iGAAiG;QACjG,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,2FAA2F;YAC3F,+FAA+F;YAC/F,kEAAkE;YAClE,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChC,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,UAAkB,EAAE,QAAkB;QAChE,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,KAAK,IAAI,UAAU,EAAE,EAAE,QAAQ,CAAC,CAAC;IACpE,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa;QACxB,+FAA+F;QAC/F,0FAA0F;QAC1F,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACvD,iGAAiG;QACjG,MAAM,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACxF,CAAC;CACF"}

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

@@ -0,0 +1,17 @@
+import type { WorkflowEngine } from '@adonis-agora/durable';
+/**
+ * The durable agent runner surface, kept in its OWN entry point (`@adonis-agora/agent/durable`) so
+ * the main package never eagerly pulls in the optional `@adonis-agora/durable` peer — the provider
+ * imports this lazily only when `durable: true` is configured. Mirrors how the `ai-sdk` entry isolates
+ * the optional `ai` peer.
+ */
+export { DurableAgentRunner } from './durable-agent-runner.js';
+export { AgentRunWorkflow, type DurableAgentRunInput, } from './agent-run-workflow.js';
+export { setDurableAgentContext, getDurableAgentContext, type DurableAgentContext, } from './agent-run-context.js';
+/**
+ * Register {@link AgentRunWorkflow} on a durable engine so `engine.start(AgentRunWorkflow, …)` and a
+ * delegating `ctx.child(AgentRunWorkflow, …)` resolve. Idempotent per engine (re-registering the same
+ * name+version overwrites). Call once at boot after the durable context is set.
+ */
+export declare function registerAgentWorkflow(engine: WorkflowEngine): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/durable/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAI5D;;;;;GAKG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EACL,gBAAgB,EAChB,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,mBAAmB,GACzB,MAAM,wBAAwB,CAAC;AAEhC;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAElE"}

package/dist/src/durable/index.js

@@ -0,0 +1,20 @@
+import { registerWorkflowClass } from '@adonis-agora/durable';
+import { AgentRunWorkflow } from './agent-run-workflow.js';
+/**
+ * The durable agent runner surface, kept in its OWN entry point (`@adonis-agora/agent/durable`) so
+ * the main package never eagerly pulls in the optional `@adonis-agora/durable` peer — the provider
+ * imports this lazily only when `durable: true` is configured. Mirrors how the `ai-sdk` entry isolates
+ * the optional `ai` peer.
+ */
+export { DurableAgentRunner } from './durable-agent-runner.js';
+export { AgentRunWorkflow, } from './agent-run-workflow.js';
+export { setDurableAgentContext, getDurableAgentContext, } from './agent-run-context.js';
+/**
+ * Register {@link AgentRunWorkflow} on a durable engine so `engine.start(AgentRunWorkflow, …)` and a
+ * delegating `ctx.child(AgentRunWorkflow, …)` resolve. Idempotent per engine (re-registering the same
+ * name+version overwrites). Call once at boot after the durable context is set.
+ */
+export function registerAgentWorkflow(engine) {
+    registerWorkflowClass(engine, AgentRunWorkflow);
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/durable/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;GAKG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EACL,gBAAgB,GAEjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,wBAAwB,CAAC;AAEhC;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAsB;IAC1D,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAClD,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,55 @@
+export declare const VERSION = "0.1.0";
+export * from './types.js';
+export * from './spi/tool.js';
+export * from './spi/model-provider.js';
+export * from './spi/token-stream-sink.js';
+export * from './spi/agent-store.js';
+export * from './spi/roles-policy.js';
+export * from './spi/quota-store.js';
+export * from './spi/pricing-store.js';
+export * from './spi/agent-runner.js';
+export * from './spi/actor-resolver.js';
+export * from './spi/actor-directory.js';
+export * from './spi/attachment-staging.js';
+export * from './spi/governance-queries.js';
+export * from './spi/embedding-provider.js';
+export * from './spi/retriever.js';
+export * from './spi/reranker.js';
+export * from './rag/index.js';
+export * from './rag-media/index.js';
+export * from './personas.js';
+export { AgentRegistry } from './agent-registry.js';
+export { ToolRegistry, DefaultRolesPolicy, ToolForbiddenError, ToolNotFoundError, ToolInputInvalidError, } from './tool-registry.js';
+export { runAgentLoop, QuotaExceededError, type AgentLoopDeps, type AgentLoopHooks, } from './agent-loop.js';
+export { invokeWithTransientRetry, isTransientToolError, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, } from './tool-retry.js';
+export type { ToolTransientRetryOptions, ToolTransientRetrySetting, InvokeWithTransientRetryOptions, } from './tool-retry.js';
+export * from './diagnostics.js';
+export { defineConfig, stores, quotas, pricingStores, governanceQueries, retrievers, attachmentStores, tokenSinks, streamTransports, actorDirectories, } from './define_config.js';
+export type { AgentConfig, DefaultAgentOptions, ModelFactory, SinkFactory, TokenSinkFactory, RedisTokenSinkConfig, ActorDirectoryFactory, MemoryActorDirectoryConfig, QuotaFactory, QuotaContext, QuotaConfig, PricingFactory, PricingContext, LucidPricingConfig, GovernanceQueriesContext, GovernanceQueriesFactory, LucidGovernanceConfig, RetrieverContext, RetrieverFactory, MemoryRetrieverConfig, PgVectorRetrieverConfig, EmbeddingFactory, AttachmentStagingContext, AttachmentStagingFactory, StoreContext, StoreFactory, LucidStoreConfig, MemoryStoreConfig, } from './define_config.js';
+export { AiTool, defineTool, readAiToolMeta, isBrandedFunctionalTool, AI_TOOL_META_KEY, AGENT_TOOL_BRAND, } from './ai-tool-ref.js';
+export type { AiToolOptions, AiToolMeta, ToolClass, FunctionalTool, BrandedFunctionalTool, } from './ai-tool-ref.js';
+export { discoverTools, registerToolExport, registerFunctionalTool, registerToolsFromBarrel, } from './tool-discovery.js';
+export type { ToolsBarrel, RegisteredTool } from './tool-discovery.js';
+export { AgentDepsFactory, delegateToolName, registerDelegateTools } from './agent-deps-factory.js';
+export type { AgentDepsFactoryConfig } from './agent-deps-factory.js';
+export { utcDay } from './agent-deps.js';
+export type { AgentDeps } from './agent-deps.js';
+export { InProcessTokenStreamSink } from './in-process-sink.js';
+export { RedisTokenStreamSink, type RedisTokenStreamSinkOptions, } from './redis-token-stream-sink.js';
+export type { RedisStreamClient } from './redis-stream-client.js';
+export { UnconfiguredActorResolver, HeaderActorResolver, AuthActorResolver, } from './actor-resolver.js';
+export type { AuthActorResolverOptions } from './actor-resolver.js';
+export { AgentService } from './agent-service.js';
+export type { ChatParams } from './agent-service.js';
+export { DefaultToolAuthorizer } from './authorizer.js';
+export type { RolesPolicy as ToolAuthorizer } from './spi/roles-policy.js';
+export { InlineAgentRunner } from './runners/inline-agent-runner.js';
+export { LucidAgentStore } from './stores/lucid.js';
+export type { LucidAgentStoreOptions, LucidDatabaseLike, LucidClientLike, LucidQueryBuilderLike, LucidInsertBuilderLike, } from './stores/lucid.js';
+export { createTableStatements, createAgentTables, AGENT_TABLES } from './stores/lucid-schema.js';
+export { LedgerQuotaStore } from './stores/ledger-quota.js';
+export { LucidPricingStore } from './stores/lucid-pricing.js';
+export { LucidGovernanceQueries } from './stores/lucid-governance-queries.js';
+export { dataTool, SqlValidator, SqlValidationError, GroupTableAccessPolicy, TenantScopeRewriter, injectLimit, loadSqlParser, } from './data/index.js';
+export type { DataToolConfig, DataToolResult, QueryRunner, SqlValidationResult, TableAccessPolicy, GroupTableAccessConfig, TenantScopeConfig, SqlParserLike, } from './data/index.js';
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/src/index.js

@@ -0,0 +1,45 @@
+export const VERSION = '0.1.0';
+export * from './types.js';
+export * from './spi/tool.js';
+export * from './spi/model-provider.js';
+export * from './spi/token-stream-sink.js';
+export * from './spi/agent-store.js';
+export * from './spi/roles-policy.js';
+export * from './spi/quota-store.js';
+export * from './spi/pricing-store.js';
+export * from './spi/agent-runner.js';
+export * from './spi/actor-resolver.js';
+export * from './spi/actor-directory.js';
+export * from './spi/attachment-staging.js';
+export * from './spi/governance-queries.js';
+export * from './spi/embedding-provider.js';
+export * from './spi/retriever.js';
+export * from './spi/reranker.js';
+export * from './rag/index.js';
+export * from './rag-media/index.js';
+export * from './personas.js';
+export { AgentRegistry } from './agent-registry.js';
+export { ToolRegistry, DefaultRolesPolicy, ToolForbiddenError, ToolNotFoundError, ToolInputInvalidError, } from './tool-registry.js';
+export { runAgentLoop, QuotaExceededError, } from './agent-loop.js';
+export { invokeWithTransientRetry, isTransientToolError, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, } from './tool-retry.js';
+export * from './diagnostics.js';
+// ── Wave 2: Adonis integration shell ─────────────────────────────────────────
+export { defineConfig, stores, quotas, pricingStores, governanceQueries, retrievers, attachmentStores, tokenSinks, streamTransports, actorDirectories, } from './define_config.js';
+export { AiTool, defineTool, readAiToolMeta, isBrandedFunctionalTool, AI_TOOL_META_KEY, AGENT_TOOL_BRAND, } from './ai-tool-ref.js';
+export { discoverTools, registerToolExport, registerFunctionalTool, registerToolsFromBarrel, } from './tool-discovery.js';
+export { AgentDepsFactory, delegateToolName, registerDelegateTools } from './agent-deps-factory.js';
+export { utcDay } from './agent-deps.js';
+export { InProcessTokenStreamSink } from './in-process-sink.js';
+export { RedisTokenStreamSink, } from './redis-token-stream-sink.js';
+export { UnconfiguredActorResolver, HeaderActorResolver, AuthActorResolver, } from './actor-resolver.js';
+export { AgentService } from './agent-service.js';
+export { DefaultToolAuthorizer } from './authorizer.js';
+export { InlineAgentRunner } from './runners/inline-agent-runner.js';
+export { LucidAgentStore } from './stores/lucid.js';
+export { createTableStatements, createAgentTables, AGENT_TABLES } from './stores/lucid-schema.js';
+export { LedgerQuotaStore } from './stores/ledger-quota.js';
+export { LucidPricingStore } from './stores/lucid-pricing.js';
+export { LucidGovernanceQueries } from './stores/lucid-governance-queries.js';
+// ── Data satellite: governed read-only SQL tool ──────────────────────────────
+export { dataTool, SqlValidator, SqlValidationError, GroupTableAccessPolicy, TenantScopeRewriter, injectLimit, loadSqlParser, } from './data/index.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,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;AA+B5B,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,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAClG,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/personas.d.ts

@@ -0,0 +1,7 @@
+import type { RolesPolicy } from './spi/roles-policy.js';
+import type { Actor, ToolSpec } from './types.js';
+/** First filter layer: drop tools the actor's role may not invoke. `can` may be async (authz). */
+export declare function filterToolsByRole(tools: ToolSpec[], actor: Actor, policy: RolesPolicy): Promise<ToolSpec[]>;
+/** Second filter layer: if the persona pins an allow-list, keep only those tool names. */
+export declare function personaFilterTools(tools: ToolSpec[], allowedTools: string[] | undefined): ToolSpec[];
+//# sourceMappingURL=personas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"personas.d.ts","sourceRoot":"","sources":["../../src/personas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAElD,kGAAkG;AAClG,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,QAAQ,EAAE,EACjB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAKrB;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,QAAQ,EAAE,EACjB,YAAY,EAAE,MAAM,EAAE,GAAG,SAAS,GACjC,QAAQ,EAAE,CAMZ"}

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

@@ -0,0 +1,14 @@
+export interface ChunkOptions {
+    /** Target max characters per chunk. Default 800. */
+    chunkSize?: number;
+    /** Characters of overlap carried from the end of one chunk into the next. Default 100. */
+    overlap?: number;
+}
+/**
+ * Splits text into overlapping chunks for embedding. Greedy up to `chunkSize`, but prefers to break on
+ * a paragraph → sentence → word boundary in the back half of the window (so a chunk rarely cuts
+ * mid-sentence), then carries `overlap` characters into the next chunk to preserve context across the
+ * seam. Pure and deterministic.
+ */
+export declare function chunkText(text: string, options?: ChunkOptions): string[];
+//# sourceMappingURL=chunk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../../src/rag/chunk.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,EAAE,CAuC5E"}

package/dist/src/rag/chunk.js

@@ -0,0 +1,42 @@
+/**
+ * Splits text into overlapping chunks for embedding. Greedy up to `chunkSize`, but prefers to break on
+ * a paragraph → sentence → word boundary in the back half of the window (so a chunk rarely cuts
+ * mid-sentence), then carries `overlap` characters into the next chunk to preserve context across the
+ * seam. Pure and deterministic.
+ */
+export function chunkText(text, options = {}) {
+    const chunkSize = options.chunkSize ?? 800;
+    const overlap = options.overlap ?? 100;
+    const normalized = text.trim();
+    if (normalized.length === 0) {
+        return [];
+    }
+    if (normalized.length <= chunkSize) {
+        return [normalized];
+    }
+    const chunks = [];
+    let start = 0;
+    while (start < normalized.length) {
+        const end = Math.min(start + chunkSize, normalized.length);
+        let breakAt = end;
+        if (end < normalized.length) {
+            const window = normalized.slice(start, end);
+            const boundary = Math.max(window.lastIndexOf('\n\n'), window.lastIndexOf('. '), window.lastIndexOf(' '));
+            // Only honour a boundary in the back half, else a tiny chunk cascades.
+            if (boundary > chunkSize / 2) {
+                breakAt = start + boundary + 1;
+            }
+        }
+        const chunk = normalized.slice(start, breakAt).trim();
+        if (chunk.length > 0) {
+            chunks.push(chunk);
+        }
+        if (breakAt >= normalized.length) {
+            break;
+        }
+        // Step forward with overlap, but always make progress (guards against a stuck boundary).
+        start = Math.max(breakAt - overlap, start + 1);
+    }
+    return chunks;
+}
+//# sourceMappingURL=chunk.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../../src/rag/chunk.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,UAAwB,EAAE;IAChE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IAC3C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,GAAG,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;QACnC,OAAO,CAAC,UAAU,CAAC,CAAC;IACtB,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QAC3D,IAAI,OAAO,GAAG,GAAG,CAAC;QAClB,IAAI,GAAG,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CACvB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,EAC1B,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EACxB,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CACxB,CAAC;YACF,uEAAuE;YACvE,IAAI,QAAQ,GAAG,SAAS,GAAG,CAAC,EAAE,CAAC;gBAC7B,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QACtD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;QACD,IAAI,OAAO,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;YACjC,MAAM;QACR,CAAC;QACD,yFAAyF;QACzF,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,15 @@
+import type { EmbeddingProvider } from '../spi/embedding-provider.js';
+import type { Passage, RetrieveOptions, Retriever } from '../spi/retriever.js';
+import type { VectorStore } from './vector-store.js';
+/**
+ * Bridges an {@link EmbeddingProvider} + {@link VectorStore} into the {@link Retriever} SPI: embed the
+ * query, then vector-search. This is what you wire as the agent's `retriever` (via the `retrievers`
+ * factory namespace) for inject-mode retrieval. Mirrors the reference `EmbeddingRetriever` exactly.
+ */
+export declare class EmbeddingRetriever implements Retriever {
+    private readonly embedder;
+    private readonly store;
+    constructor(embedder: EmbeddingProvider, store: VectorStore);
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+}
+//# sourceMappingURL=embedding-retriever.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-retriever.d.ts","sourceRoot":"","sources":["../../../src/rag/embedding-retriever.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,SAAS;IAEhD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,WAAW;IAG/B,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAUjF"}

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

@@ -0,0 +1,24 @@
+/**
+ * Bridges an {@link EmbeddingProvider} + {@link VectorStore} into the {@link Retriever} SPI: embed the
+ * query, then vector-search. This is what you wire as the agent's `retriever` (via the `retrievers`
+ * factory namespace) for inject-mode retrieval. Mirrors the reference `EmbeddingRetriever` exactly.
+ */
+export class EmbeddingRetriever {
+    embedder;
+    store;
+    constructor(embedder, store) {
+        this.embedder = embedder;
+        this.store = store;
+    }
+    async retrieve(query, options = {}) {
+        const [embedding] = await this.embedder.embed([query]);
+        if (embedding === undefined) {
+            return [];
+        }
+        return this.store.search(embedding, {
+            topK: options.topK ?? 5,
+            ...(options.filter !== undefined ? { filter: options.filter } : {}),
+        });
+    }
+}
+//# sourceMappingURL=embedding-retriever.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-retriever.js","sourceRoot":"","sources":["../../../src/rag/embedding-retriever.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,OAAO,kBAAkB;IAEV;IACA;IAFnB,YACmB,QAA2B,EAC3B,KAAkB;QADlB,aAAQ,GAAR,QAAQ,CAAmB;QAC3B,UAAK,GAAL,KAAK,CAAa;IAClC,CAAC;IAEJ,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,UAA2B,EAAE;QACzD,MAAM,CAAC,SAAS,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QACvD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE;YAClC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC;YACvB,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;IACL,CAAC;CACF"}

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

@@ -0,0 +1,6 @@
+/**
+ * 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.
+ */
+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

@@ -0,0 +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"}

package/dist/src/rag/filter.js

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export function matchesFilter(metadata, filter) {
+    if (metadata === undefined) {
+        return Object.keys(filter).length === 0;
+    }
+    return Object.entries(filter).every(([key, value]) => metadata[key] === value);
+}
+//# sourceMappingURL=filter.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,8 @@
+export { chunkText, type ChunkOptions } from './chunk.js';
+export { documentIdOf, type IndexedDocument, type VectorRecord, type VectorSearchOptions, type VectorStore, } from './vector-store.js';
+export { matchesFilter } from './filter.js';
+export { MemoryVectorStore, cosineSimilarity } from './memory-vector-store.js';
+export { EmbeddingRetriever } from './embedding-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

@@ -0,0 +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"}

package/dist/src/rag/index.js

@@ -0,0 +1,8 @@
+export { chunkText } from './chunk.js';
+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 { 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

@@ -0,0 +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"}