@adonis-agora/agent 0.1.0

package/dist/src/rag-media/text-extractor.js

@@ -0,0 +1,92 @@
+/** Thrown when no extractor is registered for a content type — ingestion treats it as "skip, don't index". */
+export class UnsupportedContentTypeError extends Error {
+    contentType;
+    constructor(contentType) {
+        super(`No text extractor registered for content type "${contentType}"`);
+        this.contentType = contentType;
+        this.name = 'UnsupportedContentTypeError';
+    }
+}
+/**
+ * A {@link TextExtractor} that dispatches by content type. Register exact types (`application/json`) or
+ * a whole family (`text/*`); an exact match always wins over a family. Unregistered types throw
+ * {@link UnsupportedContentTypeError}. This is the extension point for binary formats:
+ * `.register('application/pdf', pdfFn)` — the PDF/DOCX library stays entirely on the host side.
+ */
+export class MimeTextExtractor {
+    exact = new Map();
+    families = [];
+    register(contentType, fn) {
+        if (contentType.endsWith('/*')) {
+            // "text/*" → match anything starting "text/"
+            this.families.push({ prefix: contentType.slice(0, -1), fn });
+        }
+        else {
+            this.exact.set(contentType.toLowerCase(), fn);
+        }
+        return this;
+    }
+    async extract(bytes, contentType) {
+        const normalized = normalizeContentType(contentType);
+        const fn = this.resolve(normalized);
+        if (fn === undefined) {
+            throw new UnsupportedContentTypeError(contentType);
+        }
+        return fn(bytes, normalized);
+    }
+    /** Whether a content type would resolve to an extractor (without reading bytes). */
+    supports(contentType) {
+        return this.resolve(normalizeContentType(contentType)) !== undefined;
+    }
+    resolve(contentType) {
+        const exact = this.exact.get(contentType);
+        if (exact !== undefined) {
+            return exact;
+        }
+        for (const family of this.families) {
+            if (contentType.startsWith(family.prefix)) {
+                return family.fn;
+            }
+        }
+        return undefined;
+    }
+}
+/** Strip any `; charset=…` parameter off a content type and lower-case it. */
+export function normalizeContentType(contentType) {
+    return (contentType.split(';')[0] ?? contentType).trim().toLowerCase();
+}
+/** Decode bytes as UTF-8 — the extractor for `text/*` and JSON. */
+export function decodeUtf8(bytes) {
+    return bytes.toString('utf8');
+}
+/** Decode UTF-8 then strip HTML: drop `<script>`/`<style>` bodies and tags, decode common entities. */
+export function extractHtmlText(bytes) {
+    return bytes
+        .toString('utf8')
+        .replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#0*39;|&apos;/gi, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * The default extractor: `text/plain`, `text/csv`, `text/markdown` (and the whole `text/*` family) plus
+ * `application/json` decode as UTF-8, `text/html` is tag-stripped, and everything else — PDF, DOCX,
+ * images — throws {@link UnsupportedContentTypeError} (so binary formats are skipped rather than indexed
+ * as garbage). Extend it for those: `.register('application/pdf', myPdfExtractor)`.
+ */
+export function defaultTextExtractor() {
+    return new MimeTextExtractor()
+        .register('text/html', extractHtmlText)
+        .register('text/plain', decodeUtf8)
+        .register('text/csv', decodeUtf8)
+        .register('text/markdown', decodeUtf8)
+        .register('text/*', decodeUtf8)
+        .register('application/json', decodeUtf8);
+}
+//# sourceMappingURL=text-extractor.js.map

package/dist/src/rag-media/text-extractor.js.map

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

package/dist/src/redis-stream-client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The minimal Redis surface {@link import('./redis-token-stream-sink.js').RedisTokenStreamSink} needs.
+ *
+ * The host adapts its own driver (`@adonisjs/redis` / `ioredis`) to this interface — so this package
+ * pulls in NO Redis driver of its own (bring your own, exactly like the Lucid store adapters take a
+ * database handle). The `tokenSinks.redis()` factory ships an adapter over `@adonisjs/redis` that it
+ * imports lazily, so the driver only loads when the Redis sink is actually selected.
+ *
+ * NOTE: `subscribe` needs a connection in subscriber mode; most drivers require a DEDICATED connection
+ * for that (a subscribed client can't run other commands). An adapter should use a separate connection
+ * for `subscribe` — the sink only calls `subscribe` from its own `subscribe()`.
+ */
+export interface RedisStreamClient {
+    /** Append `value` to the list at `key` (RPUSH). */
+    rpush(key: string, value: string): Promise<void>;
+    /** The list elements at `key` from `start` to `stop` inclusive; negative indices count from the end (LRANGE). */
+    lrange(key: string, start: number, stop: number): Promise<string[]>;
+    /** Set `key` to `value` (SET) — used for the terminal marker. */
+    set(key: string, value: string): Promise<void>;
+    /** The value at `key`, or `null` if unset (GET). */
+    get(key: string): Promise<string | null>;
+    /** Publish `message` on `channel` (PUBLISH). */
+    publish(channel: string, message: string): Promise<void>;
+    /** Subscribe to `channel`, invoking `onMessage` per message. Resolves to an unsubscribe function. */
+    subscribe(channel: string, onMessage: (message: string) => void): Promise<() => Promise<void>>;
+    /** Delete the given keys (DEL). */
+    del(...keys: string[]): Promise<void>;
+}
+//# sourceMappingURL=redis-stream-client.d.ts.map

package/dist/src/redis-stream-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-stream-client.d.ts","sourceRoot":"","sources":["../../src/redis-stream-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,iHAAiH;IACjH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpE,iEAAiE;IACjE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,oDAAoD;IACpD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,gDAAgD;IAChD,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,qGAAqG;IACrG,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/F,mCAAmC;IACnC,GAAG,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC"}

package/dist/src/redis-stream-client.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=redis-stream-client.js.map

package/dist/src/redis-stream-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-stream-client.js","sourceRoot":"","sources":["../../src/redis-stream-client.ts"],"names":[],"mappings":""}

package/dist/src/redis-token-stream-sink.d.ts

@@ -0,0 +1,36 @@
+import type { RedisStreamClient } from './redis-stream-client.js';
+import type { SinkWriter, TokenStreamSink } from './spi/token-stream-sink.js';
+export interface RedisTokenStreamSinkOptions {
+    /** Key/channel namespace. Defaults to `agent:stream`. Keys are `${keyPrefix}:${runId}:...`. */
+    keyPrefix?: string;
+}
+/**
+ * A multi-replica {@link TokenStreamSink} over Redis — the shared-transport counterpart to the default
+ * {@link import('./in-process-sink.js').InProcessTokenStreamSink}. The replica running the model turn
+ * `open`s the writer and appends each token chunk to a Redis LIST (`${keyPrefix}:${runId}:chunks`) so
+ * ANY replica can replay the whole stream so far (the same late-subscriber/reconnect guarantee the
+ * in-process sink gives, but shared across pods), and PUBLISHes to a per-run channel
+ * (`${keyPrefix}:${runId}`) to wake live subscribers. The run's terminal state lives in a marker key
+ * (`${keyPrefix}:${runId}:state`), so an SSE handler on ANOTHER replica that subscribes after the run
+ * finished still sees the ending and closes the stream.
+ *
+ * The yielded chunks are byte-identical to the in-process sink's, so the SSE envelope the provider
+ * pipes (`data: {"delta":...}`) is unchanged — swapping this in is transparent to clients.
+ *
+ * The host supplies a {@link RedisStreamClient} adapter over its own Redis driver; `subscribe` needs a
+ * connection in subscriber mode (see the client docs). Wire it with `defineConfig({ sink:
+ * tokenSinks.redis({...}) })`, which builds the adapter over `@adonisjs/redis` lazily.
+ */
+export declare class RedisTokenStreamSink implements TokenStreamSink {
+    private readonly client;
+    private readonly keyPrefix;
+    constructor(client: RedisStreamClient, options?: RedisTokenStreamSinkOptions);
+    private chunksKey;
+    private stateKey;
+    private channel;
+    open(runId: string): SinkWriter;
+    subscribe(runId: string): AsyncIterable<Uint8Array>;
+    close(runId: string): Promise<void>;
+    private hasEnded;
+}
+//# sourceMappingURL=redis-token-stream-sink.d.ts.map

package/dist/src/redis-token-stream-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-token-stream-sink.d.ts","sourceRoot":"","sources":["../../src/redis-token-stream-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAK9E,MAAM,WAAW,2BAA2B;IAC1C,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IAIxD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGhB,MAAM,EAAE,iBAAiB,EAC1C,OAAO,GAAE,2BAAgC;IAK3C,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;IAIf,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAaxB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,UAAU,CAAC;IAgCpD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAI3B,QAAQ;CAIvB"}

package/dist/src/redis-token-stream-sink.js

@@ -0,0 +1,94 @@
+/** Marker stored at the state key once a run's stream has finished. */
+const ENDED = 'ended';
+/**
+ * A multi-replica {@link TokenStreamSink} over Redis — the shared-transport counterpart to the default
+ * {@link import('./in-process-sink.js').InProcessTokenStreamSink}. The replica running the model turn
+ * `open`s the writer and appends each token chunk to a Redis LIST (`${keyPrefix}:${runId}:chunks`) so
+ * ANY replica can replay the whole stream so far (the same late-subscriber/reconnect guarantee the
+ * in-process sink gives, but shared across pods), and PUBLISHes to a per-run channel
+ * (`${keyPrefix}:${runId}`) to wake live subscribers. The run's terminal state lives in a marker key
+ * (`${keyPrefix}:${runId}:state`), so an SSE handler on ANOTHER replica that subscribes after the run
+ * finished still sees the ending and closes the stream.
+ *
+ * The yielded chunks are byte-identical to the in-process sink's, so the SSE envelope the provider
+ * pipes (`data: {"delta":...}`) is unchanged — swapping this in is transparent to clients.
+ *
+ * The host supplies a {@link RedisStreamClient} adapter over its own Redis driver; `subscribe` needs a
+ * connection in subscriber mode (see the client docs). Wire it with `defineConfig({ sink:
+ * tokenSinks.redis({...}) })`, which builds the adapter over `@adonisjs/redis` lazily.
+ */
+export class RedisTokenStreamSink {
+    client;
+    keyPrefix;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.keyPrefix = options.keyPrefix ?? 'agent:stream';
+    }
+    chunksKey(runId) {
+        return `${this.keyPrefix}:${runId}:chunks`;
+    }
+    stateKey(runId) {
+        return `${this.keyPrefix}:${runId}:state`;
+    }
+    channel(runId) {
+        return `${this.keyPrefix}:${runId}`;
+    }
+    open(runId) {
+        return {
+            write: async (chunk) => {
+                await this.client.rpush(this.chunksKey(runId), toBase64(chunk));
+                await this.client.publish(this.channel(runId), 'chunk');
+            },
+            end: async () => {
+                await this.client.set(this.stateKey(runId), ENDED);
+                await this.client.publish(this.channel(runId), 'end');
+            },
+        };
+    }
+    async *subscribe(runId) {
+        // Notify bridge: the pub/sub handler resolves the current `wake` promise so the drain loop
+        // re-reads the list. A promise is armed BEFORE each drain, so a publish arriving mid-drain is
+        // never lost.
+        let resolveWake = null;
+        const onMessage = () => {
+            const resolve = resolveWake;
+            resolveWake = null;
+            resolve?.();
+        };
+        const unsubscribe = await this.client.subscribe(this.channel(runId), onMessage);
+        try {
+            let index = 0;
+            while (true) {
+                const wake = new Promise((resolve) => {
+                    resolveWake = resolve;
+                });
+                const chunks = await this.client.lrange(this.chunksKey(runId), index, -1);
+                for (const encoded of chunks) {
+                    index += 1;
+                    yield fromBase64(encoded);
+                }
+                if (await this.hasEnded(runId)) {
+                    return;
+                }
+                await wake;
+            }
+        }
+        finally {
+            await unsubscribe();
+        }
+    }
+    async close(runId) {
+        await this.client.del(this.chunksKey(runId), this.stateKey(runId));
+    }
+    async hasEnded(runId) {
+        const raw = await this.client.get(this.stateKey(runId));
+        return raw === ENDED;
+    }
+}
+function toBase64(chunk) {
+    return Buffer.from(chunk).toString('base64');
+}
+function fromBase64(encoded) {
+    return new Uint8Array(Buffer.from(encoded, 'base64'));
+}
+//# sourceMappingURL=redis-token-stream-sink.js.map

package/dist/src/redis-token-stream-sink.js.map

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

package/dist/src/runners/inline-agent-runner.d.ts

@@ -0,0 +1,26 @@
+import type { AgentDepsFactory } from '../agent-deps-factory.js';
+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 in-process — the default runner (`durable: false`). HITL approval resolves a
+ * pending promise keyed run-namespaced by `${runId}:${toolCallId}`, so one run's decision can never
+ * satisfy another's pending action. Sub-agent delegation runs a nested loop; a nested sub-agent has
+ * no human to prompt, so its action tools are auto-declined rather than hang. Single-replica only —
+ * durable is the scaled path (deferred).
+ */
+export declare class InlineAgentRunner implements AgentRunner {
+    private readonly factory;
+    private readonly store;
+    private readonly pending;
+    constructor(factory: AgentDepsFactory, store: AgentStore);
+    start(input: AgentRunInput): Promise<{
+        runId: string;
+    }>;
+    signal(runId: string, toolCallId: string, decision: Decision): Promise<void>;
+    cancel(runId: string): Promise<void>;
+    private topLevelHooks;
+    /** Delegate to another agent as a nested in-process run (a transient sub-thread). */
+    private runNested;
+}
+//# sourceMappingURL=inline-agent-runner.d.ts.map

package/dist/src/runners/inline-agent-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-agent-runner.d.ts","sourceRoot":"","sources":["../../../src/runners/inline-agent-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAS,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAElE;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,WAAW;IAIjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmD;gBAGxD,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,UAAU;IAG9B,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAqBvD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5E,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1C,OAAO,CAAC,aAAa;IAerB,qFAAqF;YACvE,SAAS;CA2BxB"}

package/dist/src/runners/inline-agent-runner.js

@@ -0,0 +1,85 @@
+import { utcDay } from '../agent-deps.js';
+import { runAgentLoop } from '../agent-loop.js';
+/**
+ * Runs the agent turn in-process — the default runner (`durable: false`). HITL approval resolves a
+ * pending promise keyed run-namespaced by `${runId}:${toolCallId}`, so one run's decision can never
+ * satisfy another's pending action. Sub-agent delegation runs a nested loop; a nested sub-agent has
+ * no human to prompt, so its action tools are auto-declined rather than hang. Single-replica only —
+ * durable is the scaled path (deferred).
+ */
+export class InlineAgentRunner {
+    factory;
+    store;
+    pending = new Map();
+    constructor(factory, store) {
+        this.factory = factory;
+        this.store = store;
+    }
+    async start(input) {
+        const runId = crypto.randomUUID();
+        const day = input.day ?? utcDay();
+        const deps = this.factory.forAgent(input.agentName);
+        const hooks = this.topLevelHooks(runId, deps, input.actor, day);
+        void runAgentLoop({ ...deps, day }, input, hooks).catch(async (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`[@adonis-agora/agent] run ${runId} failed: ${message}`);
+            // Settle the run's persisted outcome — the loop only records completions (it can't catch its
+            // own crash). First-terminal, so this can't clobber a completion that already landed.
+            await this.store.recordRunEnd({ runId, status: 'failed', error: message });
+            // Surface the failure on the live stream and close it, so a subscriber isn't left hanging.
+            const writer = await deps.sink.open(runId);
+            await writer.write(new TextEncoder().encode(`\n[error] ${message}`));
+            await writer.end();
+        });
+        return { runId };
+    }
+    async signal(runId, toolCallId, decision) {
+        const key = `${runId}:${toolCallId}`;
+        const resolve = this.pending.get(key);
+        if (resolve !== undefined) {
+            this.pending.delete(key);
+            resolve(decision);
+        }
+    }
+    async cancel(runId) {
+        // Best-effort: settle the run `cancelled` (first-terminal, so a completed run stays completed),
+        // then close the live stream so a subscriber isn't left hanging.
+        await this.store.recordRunEnd({ runId, status: 'cancelled' });
+        const deps = this.factory.forAgent();
+        const writer = await deps.sink.open(runId);
+        await writer.end();
+    }
+    topLevelHooks(runId, deps, actor, day) {
+        return {
+            runId,
+            durable: false,
+            openSink: () => deps.sink.open(runId),
+            awaitApproval: (call) => new Promise((resolve) => {
+                // Run-namespaced key: `${runId}:${toolCallId}` — one run can't approve another's tool call.
+                this.pending.set(`${runId}:${call.id}`, resolve);
+            }),
+            step: (_name, fn) => fn(),
+            runAgent: (agentName, task) => this.runNested(agentName, task, actor, day),
+        };
+    }
+    /** Delegate to another agent as a nested in-process run (a transient sub-thread). */
+    async runNested(agentName, task, actor, day) {
+        const subThread = await this.store.createThread({ actor, persona: 'default', transient: true });
+        const runId = crypto.randomUUID();
+        const deps = this.factory.forAgent(agentName);
+        const hooks = {
+            runId,
+            durable: false,
+            openSink: () => deps.sink.open(runId),
+            // A nested sub-agent has no human to ask — decline action tools rather than hang.
+            awaitApproval: async () => ({
+                approved: false,
+                reason: 'nested sub-agent cannot request human approval',
+            }),
+            step: (_name, fn) => fn(),
+            runAgent: (childName, childTask) => this.runNested(childName, childTask, actor, day),
+        };
+        return runAgentLoop({ ...deps, day }, { threadId: subThread.id, actor, userText: task, agentName, day }, hooks);
+    }
+}
+//# sourceMappingURL=inline-agent-runner.js.map

package/dist/src/runners/inline-agent-runner.js.map

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

package/dist/src/spi/actor-directory.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Optional read-side lookup from opaque `actorRef`s to human display labels.
+ *
+ * The agent store keeps an `actorRef` opaque by design (no FK into the host's user table — hosts own
+ * their own identity schema). That is fine for enforcement and accounting, but a governance/dashboard
+ * read surface showing a raw ref (`"u_8f21..."`) instead of a name is a poor experience. Binding an
+ * `ActorDirectory` via `defineConfig({ actorDirectory })` lets those surfaces resolve refs to labels;
+ * leaving it unbound just means they render the raw ref.
+ *
+ * This is the read-side dual of the {@link import('./actor-resolver.js').ActorResolver} write seam:
+ * the resolver turns an inbound request into an acting `Actor`, the directory turns a persisted
+ * `actorRef` back into something a human can read. Configure one with a factory (e.g.
+ * `actorDirectories.memory({ labels })`) or your own implementation over the host's user table.
+ */
+export interface ActorDirectory {
+    /**
+     * Resolve opaque actor refs to display labels. The returned map is keyed by the input ref; a ref
+     * with no known label may be omitted (callers fall back to rendering the raw ref). Never throws for
+     * an unknown ref — a missing entry is a normal, expected outcome.
+     */
+    resolveDisplay(refs: readonly string[]): Promise<Record<string, string>>;
+}
+//# sourceMappingURL=actor-directory.d.ts.map

package/dist/src/spi/actor-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-directory.d.ts","sourceRoot":"","sources":["../../../src/spi/actor-directory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC1E"}

package/dist/src/spi/actor-directory.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=actor-directory.js.map

package/dist/src/spi/actor-directory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-directory.js","sourceRoot":"","sources":["../../../src/spi/actor-directory.ts"],"names":[],"mappings":""}

package/dist/src/spi/actor-resolver.d.ts

@@ -0,0 +1,18 @@
+import type { Actor } from '../types.js';
+/**
+ * Resolves the acting {@link Actor} for an inbound request. This is the identity seam:
+ * the agent NEVER fabricates a caller. Configure one via `defineConfig({ actorResolver })`
+ * that reads your authenticated principal (Adonis `ctx.auth.user`, a verified session/JWT, ...).
+ *
+ * When no resolver is configured, the provider installs the `UnconfiguredActorResolver`, which
+ * throws on every request — an identity is never invented from a default. See `HeaderActorResolver`
+ * for a header-based resolver suitable for demos and gateways that strip/re-set the headers, and
+ * `AuthActorResolver` for reading Adonis's `ctx.auth.user`.
+ *
+ * `req` is the transport request object, typed `unknown` to keep core framework-agnostic;
+ * an AdonisJS app receives the `HttpContext`.
+ */
+export interface ActorResolver {
+    resolve(req: unknown): Actor | Promise<Actor>;
+}
+//# sourceMappingURL=actor-resolver.d.ts.map

package/dist/src/spi/actor-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-resolver.d.ts","sourceRoot":"","sources":["../../../src/spi/actor-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;CAC/C"}

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

@@ -0,0 +1,20 @@
+import type { AgentRunInput, Decision } from '../types.js';
+/**
+ * Runs an agent turn. Two impls exist:
+ *  - InlineAgentRunner (default): the loop runs in-process — no extra dependencies. This is what
+ *    `AGENT_RUNNER` binds to unless `durable: true` is set.
+ *  - DurableAgentRunner (opt-in via `durable: true`): the turn is a `@dudousxd/nestjs-durable`
+ *    `@Workflow`, so each model/tool call is a checkpointed step and HITL is `ctx.waitForSignal`.
+ *
+ * `start` ENQUEUES and returns immediately with the runId — the live tokens flow on the
+ * TokenStreamSink, not through this call.
+ */
+export interface AgentRunner {
+    start(input: AgentRunInput): Promise<{
+        runId: string;
+    }>;
+    /** Deliver a HITL decision for a pending action tool call. */
+    signal(runId: string, toolCallId: string, decision: Decision): Promise<void>;
+    cancel(runId: string): Promise<void>;
+}
+//# sourceMappingURL=agent-runner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.d.ts","sourceRoot":"","sources":["../../../src/spi/agent-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE3D;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,8DAA8D;IAC9D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC"}

package/dist/src/spi/agent-store.d.ts

@@ -0,0 +1,104 @@
+import type { Actor, MessageAttachment, MessageUsage, StoredMessage, ThreadDetail, ThreadSummary, ToolCallRequest, ToolCallStatus, ToolResult, UsagePurpose } from '../types.js';
+export interface CreateThreadInput {
+    actor: Actor;
+    persona: string;
+    transient?: boolean;
+    title?: string;
+}
+export interface AppendMessageInput {
+    threadId: string;
+    role: StoredMessage['role'];
+    content: string;
+    persona?: string;
+    toolCalls?: ToolCallRequest[];
+    toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF); persisted with it and replayed to the model. */
+    attachments?: MessageAttachment[];
+    followUps?: string[];
+    usage?: MessageUsage;
+    /** The run (turn) this message belongs to, for run-detail assembly + trace deep-links. */
+    runId?: string;
+}
+export interface RecordToolCallInput {
+    toolCallId: string;
+    messageId: string;
+    toolName: string;
+    toolType: 'read' | 'action';
+    input: unknown;
+    status: ToolCallStatus;
+    /** The run (turn) this tool call belongs to, for run-detail assembly + trace deep-links. */
+    runId?: string;
+}
+export interface UpdateToolCallInput {
+    toolCallId: string;
+    status: ToolCallStatus;
+    output?: unknown;
+    error?: string;
+    executionMs?: number;
+    executedByRef?: string;
+}
+export interface RecordUsageInput {
+    threadId: string;
+    actorRef: string;
+    messageId?: string;
+    modelId: string;
+    purpose: UsagePurpose;
+    usage: MessageUsage;
+    /** Provider-reported actual USD cost for this turn, when known (gateways report it). */
+    costUsd?: number;
+    /** The run (turn) this usage row belongs to, for run-detail assembly + trace deep-links. */
+    runId?: string;
+}
+/** A run's lifecycle status: created `running`, then settled once (terminal). */
+export type AgentRunStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+/** Opens a run (turn) row at start — status `running`, `started_at` stamped by the store. */
+export interface RecordRunStartInput {
+    runId: string;
+    threadId: string;
+    /** Acting identity; the store persists `actor.id` as `actor_ref` and `actor.tenantRef` as `tenant_ref`. */
+    actor: Actor;
+    /** The agent that handled the run; `null`/omitted for the default agent. */
+    agentName?: string;
+    /** True when the run executes as a replay-safe durable workflow, false for the inline runner. */
+    durable?: boolean;
+}
+/**
+ * Settles a run's outcome (terminal). A store MUST apply this only while the run is still `running`
+ * (first terminal wins) so a late `completed` from the loop can never overwrite a `failed`/`cancelled`
+ * already recorded by the runner. `error` is set only for `failed`. Token/step/cost totals are the
+ * loop's run-level rollup on `completed`; a runner-recorded failure/cancel may omit them.
+ */
+export interface RecordRunEndInput {
+    runId: string;
+    status: Exclude<AgentRunStatus, 'running'>;
+    /** Epoch-ms finish time; defaults to now inside the store when omitted. */
+    finishedAt?: number;
+    stepCount?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+    error?: string;
+}
+/** ORM-agnostic persistence. Refs are string ids; adapters may add real relations. */
+export interface AgentStore {
+    createThread(input: CreateThreadInput): Promise<ThreadSummary>;
+    getThread(threadId: string): Promise<ThreadDetail | null>;
+    listThreads(actorRef: string, limit?: number): Promise<ThreadSummary[]>;
+    softDeleteThread(threadId: string): Promise<void>;
+    forkThread(threadId: string, fromMessageId: string): Promise<ThreadSummary>;
+    setTitle(threadId: string, title: string): Promise<void>;
+    setActiveStream(threadId: string, runId: string | null): Promise<void>;
+    appendMessage(input: AppendMessageInput): Promise<StoredMessage>;
+    truncateFrom(threadId: string, messageId: string): Promise<void>;
+    recordToolCall(input: RecordToolCallInput): Promise<void>;
+    updateToolCall(input: UpdateToolCallInput): Promise<void>;
+    recordUsage(input: RecordUsageInput): Promise<void>;
+    quotaToday(actorRef: string, day: string): Promise<{
+        usedTokens: number;
+    }>;
+    /** Open a run (turn) row at start. Replay-safe: the loop calls it under a durable step. */
+    recordRunStart(input: RecordRunStartInput): Promise<void>;
+    /** Settle a run's outcome (terminal, first-wins). A no-op when the run is unknown or already settled. */
+    recordRunEnd(input: RecordRunEndInput): Promise<void>;
+}
+//# sourceMappingURL=agent-store.d.ts.map

package/dist/src/spi/agent-store.d.ts.map

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

package/dist/src/spi/agent-store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-store.js.map

package/dist/src/spi/agent-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-store.js","sourceRoot":"","sources":["../../../src/spi/agent-store.ts"],"names":[],"mappings":""}