@ixo/oracle-runtime 0.0.1

package/dist/modules/blob-store/blob-store.service.d.ts

@@ -0,0 +1,66 @@
+import { Cache } from '@nestjs/cache-manager';
+/**
+ * BlobStore — short-TTL keyed value store for content that the LLM should
+ * never have to relay verbatim.
+ *
+ * Use case: tools that produce long, opaque, error-prone strings (UCAN
+ * invocation/delegation CARs, JWTs, signed envelopes, etc.). The producing
+ * tool stores the value here and returns a short hex blobId. A consuming
+ * tool (e.g. `sandbox_write_blob`) takes the blobId, looks the value up
+ * server-side, and forwards it to its destination — the value never enters
+ * the LLM's context.
+ *
+ * Backed by `@nestjs/cache-manager`'s global Cache (in-memory by default;
+ * swap to Redis by changing the CacheModule factory if/when needed).
+ *
+ * Ownership: blobs are namespaced by issuing user DID. A blob produced for
+ * user A cannot be retrieved with user B's DID — the lookup just misses,
+ * same as it would for a non-existent ID.
+ */
+export declare class BlobStoreService {
+    private readonly cacheManager;
+    private readonly logger;
+    /** Default TTL when none specified. 1 hour is a sensible cap for anything
+     * routed through here — most callers will pass a tighter value (e.g. an
+     * invocation's own expiration, ~60s). */
+    static readonly DEFAULT_TTL_SECONDS: number;
+    /** Hard ceiling enforced regardless of caller request. Protects the cache
+     * from being held hostage by a buggy producer. */
+    static readonly MAX_TTL_SECONDS: number;
+    /** Hex-character ID, prefixed so callers can validate format before
+     * paying for a cache lookup. 16 hex chars = 64 bits of entropy — enough
+     * to be unguessable for short-lived blobs. */
+    static readonly ID_PREFIX = "blob_";
+    static readonly ID_PATTERN: RegExp;
+    constructor(cacheManager: Cache);
+    private cacheKey;
+    /**
+     * Validate that a string is a well-formed blob ID. Use this in tool
+     * input schemas / handlers to reject malformed IDs early — the cache
+     * lookup would miss anyway, but failing fast gives a clearer error.
+     */
+    isValidBlobId(value: unknown): value is string;
+    /**
+     * Store a value and return a fresh blobId. The TTL is clamped to
+     * `MAX_TTL_SECONDS`. Callers should pass `userDid` from a trusted source
+     * (auth middleware / agent state), NOT from LLM-supplied arguments.
+     */
+    put(params: {
+        userDid: string;
+        name: string;
+        value: string;
+        ttlSeconds?: number;
+    }): Promise<string>;
+    /**
+     * Retrieve a blob by id, scoped to the requesting user. Returns null if
+     * the blob doesn't exist, has expired, or belongs to a different user.
+     */
+    get(params: {
+        userDid: string;
+        blobId: string;
+    }): Promise<{
+        name: string;
+        value: string;
+    } | null>;
+}
+//# sourceMappingURL=blob-store.service.d.ts.map

package/dist/modules/blob-store/blob-store.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-store.service.d.ts","sourceRoot":"","sources":["../../../src/modules/blob-store/blob-store.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAiB,MAAM,uBAAuB,CAAC;AAI7D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBACa,gBAAgB;IAkBQ,OAAO,CAAC,QAAQ,CAAC,YAAY;IAjBhE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAE5D;;6CAEyC;IACzC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,SAAW;IAE9C;sDACkD;IAClD,MAAM,CAAC,QAAQ,CAAC,eAAe,SAAgB;IAE/C;;kDAE8C;IAC9C,MAAM,CAAC,QAAQ,CAAC,SAAS,WAAW;IACpC,MAAM,CAAC,QAAQ,CAAC,UAAU,SAAyB;gBAEC,YAAY,EAAE,KAAK;IAEvE,OAAO,CAAC,QAAQ;IAIhB;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM;IAI9C;;;;OAIG;IACG,GAAG,CAAC,MAAM,EAAE;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC;IA6BnB;;;OAGG;IACG,GAAG,CAAC,MAAM,EAAE;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAqBpD"}

package/dist/modules/blob-store/blob-store.service.js

@@ -0,0 +1,108 @@
+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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var BlobStoreService_1;
+import { Cache, CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { randomBytes } from 'node:crypto';
+/**
+ * BlobStore — short-TTL keyed value store for content that the LLM should
+ * never have to relay verbatim.
+ *
+ * Use case: tools that produce long, opaque, error-prone strings (UCAN
+ * invocation/delegation CARs, JWTs, signed envelopes, etc.). The producing
+ * tool stores the value here and returns a short hex blobId. A consuming
+ * tool (e.g. `sandbox_write_blob`) takes the blobId, looks the value up
+ * server-side, and forwards it to its destination — the value never enters
+ * the LLM's context.
+ *
+ * Backed by `@nestjs/cache-manager`'s global Cache (in-memory by default;
+ * swap to Redis by changing the CacheModule factory if/when needed).
+ *
+ * Ownership: blobs are namespaced by issuing user DID. A blob produced for
+ * user A cannot be retrieved with user B's DID — the lookup just misses,
+ * same as it would for a non-existent ID.
+ */
+let BlobStoreService = class BlobStoreService {
+    static { BlobStoreService_1 = this; }
+    cacheManager;
+    logger = new Logger(BlobStoreService_1.name);
+    /** Default TTL when none specified. 1 hour is a sensible cap for anything
+     * routed through here — most callers will pass a tighter value (e.g. an
+     * invocation's own expiration, ~60s). */
+    static DEFAULT_TTL_SECONDS = 60 * 60;
+    /** Hard ceiling enforced regardless of caller request. Protects the cache
+     * from being held hostage by a buggy producer. */
+    static MAX_TTL_SECONDS = 24 * 60 * 60;
+    /** Hex-character ID, prefixed so callers can validate format before
+     * paying for a cache lookup. 16 hex chars = 64 bits of entropy — enough
+     * to be unguessable for short-lived blobs. */
+    static ID_PREFIX = 'blob_';
+    static ID_PATTERN = /^blob_[0-9a-f]{16}$/;
+    constructor(cacheManager) {
+        this.cacheManager = cacheManager;
+    }
+    cacheKey(userDid, blobId) {
+        return `blob:${userDid}:${blobId}`;
+    }
+    /**
+     * Validate that a string is a well-formed blob ID. Use this in tool
+     * input schemas / handlers to reject malformed IDs early — the cache
+     * lookup would miss anyway, but failing fast gives a clearer error.
+     */
+    isValidBlobId(value) {
+        return typeof value === 'string' && BlobStoreService_1.ID_PATTERN.test(value);
+    }
+    /**
+     * Store a value and return a fresh blobId. The TTL is clamped to
+     * `MAX_TTL_SECONDS`. Callers should pass `userDid` from a trusted source
+     * (auth middleware / agent state), NOT from LLM-supplied arguments.
+     */
+    async put(params) {
+        if (!params.userDid) {
+            throw new Error('BlobStore.put: userDid is required');
+        }
+        if (typeof params.value !== 'string' || params.value.length === 0) {
+            throw new Error('BlobStore.put: value must be a non-empty string');
+        }
+        const ttlSeconds = Math.min(Math.max(1, params.ttlSeconds ?? BlobStoreService_1.DEFAULT_TTL_SECONDS), BlobStoreService_1.MAX_TTL_SECONDS);
+        const blobId = `${BlobStoreService_1.ID_PREFIX}${randomBytes(8).toString('hex')}`;
+        const key = this.cacheKey(params.userDid, blobId);
+        await this.cacheManager.set(key, { name: params.name, value: params.value }, ttlSeconds * 1000);
+        this.logger.debug(`[blob-store] put ${blobId} (name=${params.name}, ttl=${ttlSeconds}s, valueLen=${params.value.length}, user=${params.userDid})`);
+        return blobId;
+    }
+    /**
+     * Retrieve a blob by id, scoped to the requesting user. Returns null if
+     * the blob doesn't exist, has expired, or belongs to a different user.
+     */
+    async get(params) {
+        if (!params.userDid)
+            return null;
+        if (!this.isValidBlobId(params.blobId))
+            return null;
+        const key = this.cacheKey(params.userDid, params.blobId);
+        const cached = await this.cacheManager.get(key);
+        if (!cached) {
+            this.logger.debug(`[blob-store] miss ${params.blobId} (user=${params.userDid})`);
+            return null;
+        }
+        this.logger.debug(`[blob-store] hit ${params.blobId} (name=${cached.name}, user=${params.userDid})`);
+        return cached;
+    }
+};
+BlobStoreService = BlobStoreService_1 = __decorate([
+    Injectable(),
+    __param(0, Inject(CACHE_MANAGER)),
+    __metadata("design:paramtypes", [Cache])
+], BlobStoreService);
+export { BlobStoreService };

package/dist/modules/blob-store/index.d.ts

@@ -0,0 +1,3 @@
+export { BlobStoreModule } from './blob-store.module.js';
+export { BlobStoreService } from './blob-store.service.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/blob-store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/blob-store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/modules/blob-store/index.js

@@ -0,0 +1,2 @@
+export { BlobStoreModule } from './blob-store.module.js';
+export { BlobStoreService } from './blob-store.service.js';

package/dist/modules/health/health.controller.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Always-on health surface. Both routes are excluded from the auth
+ * middleware (see `RuntimeAppModule.AUTH_EXCLUDED_ROUTES`) so probes
+ * (Railway, Fly, k8s liveness/readiness) and a friendly landing page
+ * can hit the oracle without a UCAN delegation header.
+ */
+export declare class HealthController {
+    root(): {
+        status: string;
+        message: string;
+        timestamp: string;
+    };
+    health(): {
+        status: string;
+        timestamp: string;
+    };
+}
+//# sourceMappingURL=health.controller.d.ts.map

package/dist/modules/health/health.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.controller.d.ts","sourceRoot":"","sources":["../../../src/modules/health/health.controller.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,qBAEa,gBAAgB;IAG3B,IAAI;;;;;IAUJ,MAAM;;;;CAGP"}

package/dist/modules/health/health.controller.js

@@ -0,0 +1,48 @@
+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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Controller, Get } from '@nestjs/common';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
+/**
+ * Always-on health surface. Both routes are excluded from the auth
+ * middleware (see `RuntimeAppModule.AUTH_EXCLUDED_ROUTES`) so probes
+ * (Railway, Fly, k8s liveness/readiness) and a friendly landing page
+ * can hit the oracle without a UCAN delegation header.
+ */
+let HealthController = class HealthController {
+    root() {
+        return {
+            status: 'ok',
+            message: 'QiForge oracle is running. See /docs for the API.',
+            timestamp: new Date().toISOString(),
+        };
+    }
+    health() {
+        return { status: 'ok', timestamp: new Date().toISOString() };
+    }
+};
+__decorate([
+    Get(),
+    ApiOperation({ summary: 'Root — oracle landing.' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", void 0)
+], HealthController.prototype, "root", null);
+__decorate([
+    Get('health'),
+    ApiOperation({ summary: 'Liveness probe.' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", void 0)
+], HealthController.prototype, "health", null);
+HealthController = __decorate([
+    ApiTags('health'),
+    Controller()
+], HealthController);
+export { HealthController };

package/dist/modules/health/health.module.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Always-on health surface registered by `RuntimeAppModule`. Both routes
+ * are auth-excluded so probes (load balancers, k8s liveness/readiness,
+ * uptime monitors) can hit the oracle without a UCAN delegation header.
+ */
+export declare class HealthModule {
+}
+//# sourceMappingURL=health.module.d.ts.map

package/dist/modules/health/health.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.module.d.ts","sourceRoot":"","sources":["../../../src/modules/health/health.module.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAGa,YAAY;CAAG"}

package/dist/modules/health/health.module.js

@@ -0,0 +1,21 @@
+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;
+};
+import { Module } from '@nestjs/common';
+import { HealthController } from './health.controller.js';
+/**
+ * Always-on health surface registered by `RuntimeAppModule`. Both routes
+ * are auth-excluded so probes (load balancers, k8s liveness/readiness,
+ * uptime monitors) can hit the oracle without a UCAN delegation header.
+ */
+let HealthModule = class HealthModule {
+};
+HealthModule = __decorate([
+    Module({
+        controllers: [HealthController],
+    })
+], HealthModule);
+export { HealthModule };

package/dist/modules/index.d.ts

@@ -0,0 +1,8 @@
+export { SubscriptionModule } from './subscription/subscription.module.js';
+export { SubscriptionMiddleware, SUBSCRIPTION_CREDIT_SINK, } from './subscription/subscription.middleware.js';
+export type { SubscriptionCreditSink } from './subscription/subscription.middleware.js';
+export { ThrottlerModule } from './throttler/throttler.module.js';
+export { SessionsModule } from './sessions/sessions.module.js';
+export { MessagesModule } from './messages/messages.module.js';
+export { WsModule } from './ws/ws.module.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/modules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,2CAA2C,CAAC;AACnD,YAAY,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAExF,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/modules/index.js

@@ -0,0 +1,6 @@
+export { SubscriptionModule } from './subscription/subscription.module.js';
+export { SubscriptionMiddleware, SUBSCRIPTION_CREDIT_SINK, } from './subscription/subscription.middleware.js';
+export { ThrottlerModule } from './throttler/throttler.module.js';
+export { SessionsModule } from './sessions/sessions.module.js';
+export { MessagesModule } from './messages/messages.module.js';
+export { WsModule } from './ws/ws.module.js';

package/dist/modules/messages/__test-fixtures__/deps.d.ts

@@ -0,0 +1,41 @@
+import { type PreparedRequest } from '../request-preparer.js';
+/**
+ * Stub for `UserMatrixSqliteSyncService`. Only the methods the chat
+ * pipeline touches are present — `markUserActive`/`markUserInactive`
+ * (ref-count contract), `getUserDatabase` (initial sync), and
+ * `getUserDatabaseNoSync` (cached connection used by `PostMessageSyncer`).
+ */
+export declare function makeCheckpointSync(): {
+    markUserActive: import("vitest").Mock<(...args: any[]) => any>;
+    markUserInactive: import("vitest").Mock<(...args: any[]) => any>;
+    getUserDatabase: import("vitest").Mock<(...args: any[]) => any>;
+    getUserDatabaseNoSync: import("vitest").Mock<(...args: any[]) => any>;
+};
+/**
+ * Stub for `SessionManagerService` plus its embedded `matrixManger`.
+ * Returns `vi.fn()` for every method the chat pipeline calls so tests
+ * can target individual methods with `.mockResolvedValueOnce(...)`.
+ */
+export declare function makeSessionManagerStub(): {
+    createSession: import("vitest").Mock<(...args: any[]) => any>;
+    listSessions: import("vitest").Mock<(...args: any[]) => any>;
+    deleteSession: import("vitest").Mock<(...args: any[]) => any>;
+    getSession: import("vitest").Mock<(...args: any[]) => any>;
+    updateLastProcessedCount: import("vitest").Mock<(...args: any[]) => any>;
+    syncSessionSet: import("vitest").Mock<(...args: any[]) => any>;
+    matrixManger: {
+        sendMessage: import("vitest").Mock<(...args: any[]) => any>;
+        getOracleRoomIdWithHomeServer: import("vitest").Mock<(...args: any[]) => any>;
+        getDisplayName: import("vitest").Mock<(...args: any[]) => any>;
+        getEventById: import("vitest").Mock<(...args: any[]) => any>;
+        onMessage: import("vitest").Mock<() => () => undefined>;
+        init: import("vitest").Mock<(...args: any[]) => any>;
+    };
+};
+/**
+ * Build a `PreparedRequest` with sensible defaults that downstream
+ * consumers (`SseStreamRunner`, `BatchInvoker`, `MessagesService`) can
+ * use as-is. Pass `overrides` to mutate any field per-test.
+ */
+export declare function makePrepared(overrides?: Partial<PreparedRequest>): PreparedRequest;
+//# sourceMappingURL=deps.d.ts.map

package/dist/modules/messages/__test-fixtures__/deps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deps.d.ts","sourceRoot":"","sources":["../../../../src/modules/messages/__test-fixtures__/deps.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,kBAAkB;;;;;EAOjC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB;;;;;;;;;;;;;;;EAiBrC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GACvC,eAAe,CA6BjB"}

package/dist/modules/messages/__test-fixtures__/deps.js

@@ -0,0 +1,73 @@
+import { vi } from 'vitest';
+/**
+ * Stub for `UserMatrixSqliteSyncService`. Only the methods the chat
+ * pipeline touches are present — `markUserActive`/`markUserInactive`
+ * (ref-count contract), `getUserDatabase` (initial sync), and
+ * `getUserDatabaseNoSync` (cached connection used by `PostMessageSyncer`).
+ */
+export function makeCheckpointSync() {
+    return {
+        markUserActive: vi.fn(),
+        markUserInactive: vi.fn(),
+        getUserDatabase: vi.fn(),
+        getUserDatabaseNoSync: vi.fn(),
+    };
+}
+/**
+ * Stub for `SessionManagerService` plus its embedded `matrixManger`.
+ * Returns `vi.fn()` for every method the chat pipeline calls so tests
+ * can target individual methods with `.mockResolvedValueOnce(...)`.
+ */
+export function makeSessionManagerStub() {
+    return {
+        createSession: vi.fn(),
+        listSessions: vi.fn(),
+        deleteSession: vi.fn(),
+        getSession: vi.fn(),
+        updateLastProcessedCount: vi.fn(),
+        syncSessionSet: vi.fn(),
+        matrixManger: {
+            sendMessage: vi.fn().mockResolvedValue(undefined),
+            getOracleRoomIdWithHomeServer: vi.fn(),
+            getDisplayName: vi.fn(),
+            getEventById: vi.fn(),
+            onMessage: vi.fn(() => () => undefined),
+            init: vi.fn().mockResolvedValue(undefined),
+        },
+    };
+}
+/**
+ * Build a `PreparedRequest` with sensible defaults that downstream
+ * consumers (`SseStreamRunner`, `BatchInvoker`, `MessagesService`) can
+ * use as-is. Pass `overrides` to mutate any field per-test.
+ */
+export function makePrepared(overrides = {}) {
+    const baseSession = {
+        sessionId: 'sess-1',
+        lastUpdatedAt: '2026-05-21T00:00:00.000Z',
+        createdAt: '2026-05-20T00:00:00.000Z',
+        oracleName: 'TestOracle',
+        oracleDid: 'did:ixo:oracle',
+        oracleEntityDid: 'did:ixo:oracle-entity',
+        lastProcessedCount: 0,
+        roomId: '!room:home',
+    };
+    return {
+        sessionId: 'sess-1',
+        langchainThreadId: 'sess-1',
+        roomId: '!room:home',
+        homeServerName: 'home.server',
+        requestId: 'req-1',
+        runnableConfig: {
+            configurable: {
+                thread_id: 'sess-1',
+                requestId: 'req-1',
+                sessionId: 'sess-1',
+            },
+        },
+        targetSession: baseSession,
+        timezone: 'UTC',
+        currentTime: '2026-05-21T00:00:00Z',
+        ...overrides,
+    };
+}

package/dist/modules/messages/__test-fixtures__/fake-agent.d.ts

@@ -0,0 +1,27 @@
+import type { StreamEvent } from '@langchain/core/tracers/log_stream';
+/**
+ * Minimal `CompiledMainAgent` surface used by `SseStreamRunner` and the
+ * batch invoker — `streamEvents` (async iterable of `StreamEvent`) and
+ * `invoke` (single result). The runner only reads `event`, `data`,
+ * `run_id`, and `name` from each yielded event, so the fixture pins a
+ * `StreamEvent[]` and replays them in order.
+ */
+export interface FakeAgent {
+    streamEvents: (input: unknown, cfg: unknown) => AsyncIterable<StreamEvent>;
+    invoke: (input: unknown, cfg: unknown) => Promise<{
+        messages: unknown[];
+    }>;
+}
+/**
+ * Build a fake agent that yields the provided events one-by-one with a
+ * microtask boundary between each. The boundary gives callers a chance
+ * to call `abortController.abort()` between events and observe the
+ * runner break out of its for-await loop on the next iteration.
+ */
+export declare function makeFakeAgent(events: StreamEvent[]): FakeAgent;
+/**
+ * Build a fake agent whose stream throws when consumed. Used for the
+ * non-abort error branch test.
+ */
+export declare function makeThrowingFakeAgent(error: Error): FakeAgent;
+//# sourceMappingURL=fake-agent.d.ts.map

package/dist/modules/messages/__test-fixtures__/fake-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-agent.d.ts","sourceRoot":"","sources":["../../../../src/modules/messages/__test-fixtures__/fake-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,aAAa,CAAC,WAAW,CAAC,CAAC;IAC3E,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC,CAAC;CAC5E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAgB9D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAc7D"}

package/dist/modules/messages/__test-fixtures__/fake-agent.js

@@ -0,0 +1,41 @@
+/**
+ * Build a fake agent that yields the provided events one-by-one with a
+ * microtask boundary between each. The boundary gives callers a chance
+ * to call `abortController.abort()` between events and observe the
+ * runner break out of its for-await loop on the next iteration.
+ */
+export function makeFakeAgent(events) {
+    return {
+        streamEvents() {
+            return (async function* () {
+                for (const evt of events) {
+                    // Microtask boundary — lets tests call `abortController.abort()`
+                    // between events and observe the runner break out on the next loop.
+                    await Promise.resolve();
+                    yield evt;
+                }
+            })();
+        },
+        async invoke() {
+            return { messages: [] };
+        },
+    };
+}
+/**
+ * Build a fake agent whose stream throws when consumed. Used for the
+ * non-abort error branch test.
+ */
+export function makeThrowingFakeAgent(error) {
+    return {
+        streamEvents() {
+            return (async function* () {
+                await Promise.resolve();
+                throw error;
+                yield undefined;
+            })();
+        },
+        async invoke() {
+            return { messages: [] };
+        },
+    };
+}

package/dist/modules/messages/__test-fixtures__/fake-response.d.ts

@@ -0,0 +1,29 @@
+import { EventEmitter } from 'node:events';
+/**
+ * Structurally-typed `express.Response` test double. Captures every
+ * `write` chunk into a buffer so tests can assert on the SSE wire
+ * format directly. Inherits from `EventEmitter` so `res.on('close', …)`
+ * registrations from the SUT can be triggered via `emit('close')`.
+ *
+ * Not declared as `implements Pick<Response, ...>` because Express's
+ * method signatures return `Response<...>` (not `this`), which the
+ * chainable methods here can't satisfy. The type contract lives at the
+ * SUT injection site (`as unknown as Response`), where the partial-mock
+ * intent is surface-visible.
+ */
+export declare class FakeResponse extends EventEmitter {
+    writes: string[];
+    headersSent: boolean;
+    writableEnded: boolean;
+    setHeaders: Record<string, string>;
+    statusCode: number;
+    jsonBody: unknown;
+    set(field: Record<string, string>): this;
+    set(field: string, value?: string | string[]): this;
+    flushHeaders(): void;
+    write(chunk: string | Buffer): boolean;
+    end(): this;
+    status(code: number): this;
+    json(body: unknown): this;
+}
+//# sourceMappingURL=fake-response.d.ts.map

package/dist/modules/messages/__test-fixtures__/fake-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-response.d.ts","sourceRoot":"","sources":["../../../../src/modules/messages/__test-fixtures__/fake-response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,SAAQ,YAAY;IACrC,MAAM,EAAE,MAAM,EAAE,CAAM;IACtB,WAAW,UAAS;IACpB,aAAa,UAAS;IACtB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM;IACxC,UAAU,SAAO;IACjB,QAAQ,EAAE,OAAO,CAAC;IAEzB,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IACxC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAcnD,YAAY,IAAI,IAAI;IAIpB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IAQtC,GAAG,IAAI,IAAI;IAKX,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK1B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;CAK1B"}

package/dist/modules/messages/__test-fixtures__/fake-response.js

@@ -0,0 +1,55 @@
+import { EventEmitter } from 'node:events';
+/**
+ * Structurally-typed `express.Response` test double. Captures every
+ * `write` chunk into a buffer so tests can assert on the SSE wire
+ * format directly. Inherits from `EventEmitter` so `res.on('close', …)`
+ * registrations from the SUT can be triggered via `emit('close')`.
+ *
+ * Not declared as `implements Pick<Response, ...>` because Express's
+ * method signatures return `Response<...>` (not `this`), which the
+ * chainable methods here can't satisfy. The type contract lives at the
+ * SUT injection site (`as unknown as Response`), where the partial-mock
+ * intent is surface-visible.
+ */
+export class FakeResponse extends EventEmitter {
+    writes = [];
+    headersSent = false;
+    writableEnded = false;
+    setHeaders = {};
+    statusCode = 200;
+    jsonBody;
+    set(field, value) {
+        if (typeof field === 'string') {
+            if (value !== undefined) {
+                this.setHeaders[field] = Array.isArray(value)
+                    ? value.join(', ')
+                    : value;
+            }
+            return this;
+        }
+        this.setHeaders = { ...this.setHeaders, ...field };
+        return this;
+    }
+    flushHeaders() {
+        this.headersSent = true;
+    }
+    write(chunk) {
+        if (this.writableEnded)
+            return false;
+        this.writes.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+        return true;
+    }
+    end() {
+        this.writableEnded = true;
+        return this;
+    }
+    status(code) {
+        this.statusCode = code;
+        return this;
+    }
+    json(body) {
+        this.jsonBody = body;
+        this.writableEnded = true;
+        return this;
+    }
+}