@amodalai/runtime 0.2.0 → 0.2.1

package/dist/src/session/session-store-selector.test.js

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { selectSessionStore } from './session-store-selector.js';
+import { DrizzleSessionStore } from './drizzle-session-store.js';
+import { createLogger } from '../logger.js';
+const logger = createLogger({ component: 'test:selector' });
+/**
+ * Both backends return `DrizzleSessionStore` today; we assert on the
+ * `backendName` tag to tell them apart in tests. If that instance type
+ * ever changes, this narrow cast is the one place to update.
+ */
+function asDrizzle(store) {
+    expect(store).toBeInstanceOf(DrizzleSessionStore);
+    return store;
+}
+describe('selectSessionStore', () => {
+    const created = [];
+    afterEach(async () => {
+        while (created.length > 0) {
+            const s = created.pop();
+            await s.close();
+        }
+    });
+    it('defaults to PGLite when no backend specified', async () => {
+        const store = await selectSessionStore({ logger });
+        created.push(store);
+        expect(asDrizzle(store).backendName).toBe('pglite');
+    });
+    it('uses PGLite when backend is explicitly pglite', async () => {
+        const store = await selectSessionStore({ backend: 'pglite', logger });
+        created.push(store);
+        expect(asDrizzle(store).backendName).toBe('pglite');
+    });
+    it('falls back to PGLite when backend=postgres but no URL is set', async () => {
+        const store = await selectSessionStore({ backend: 'postgres', logger });
+        created.push(store);
+        expect(asDrizzle(store).backendName).toBe('pglite');
+    });
+    it('falls back to PGLite when postgresUrl is an empty string', async () => {
+        // Caller is responsible for resolving env: refs; empty string is
+        // what they pass when `env:VAR` was unset.
+        const store = await selectSessionStore({
+            backend: 'postgres',
+            postgresUrl: '',
+            logger,
+        });
+        created.push(store);
+        expect(asDrizzle(store).backendName).toBe('pglite');
+    });
+    it('falls back to PGLite when Postgres connection fails to initialize', async () => {
+        // Unreachable host + very short connect timeout → init throws →
+        // selector logs error and falls back to PGLite. This is the
+        // "runtime must boot even on misconfigured Postgres" path.
+        const store = await selectSessionStore({
+            backend: 'postgres',
+            // Port 1 is reserved and connection will be refused fast
+            postgresUrl: 'postgres://nobody:nothing@127.0.0.1:1/missing?connect_timeout=1',
+            logger,
+        });
+        created.push(store);
+        expect(asDrizzle(store).backendName).toBe('pglite');
+    });
+    const pgUrl = process.env['TEST_POSTGRES_URL'] ?? '';
+    const itPg = pgUrl ? it : it.skip;
+    itPg('uses Postgres backend when backend=postgres and URL is set', async () => {
+        const store = await selectSessionStore({
+            backend: 'postgres',
+            postgresUrl: pgUrl,
+            logger,
+        });
+        created.push(store);
+        expect(asDrizzle(store).backendName).toBe('postgres');
+    });
+});
+//# sourceMappingURL=session-store-selector.test.js.map

package/dist/src/session/session-store-selector.test.js.map

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

package/dist/src/session/store.d.ts

@@ -3,55 +3,169 @@
  * Copyright 2026 Amodal Labs, Inc.
  * SPDX-License-Identifier: MIT
  */
+/**
+ * Session persistence layer — interface, types, and shared helpers.
+ *
+ * Concrete implementations:
+ *   - `DrizzleSessionStore` (./drizzle-session-store.ts) — the single
+ *     query layer shared by both backends.
+ *   - `createPGLiteSessionStore` (./pglite-session-store.ts) — factory
+ *     for local-dev / in-memory PGLite.
+ *   - `createPostgresSessionStore` (./postgres-session-store.ts) —
+ *     factory for hosted runtime / ISV production.
+ *
+ * The Drizzle schema lives in `../stores/schema.ts`, shared with the
+ * store document tables.
+ */
+import { and } from 'drizzle-orm';
+import type { AnyPgColumn } from 'drizzle-orm/pg-core';
+import type { agentSessions } from '../stores/schema.js';
 import type { PersistedSession } from './types.js';
-import type { Logger } from '../logger.js';
+/**
+ * Options for `SessionStore.list()`.
+ *
+ * Cursor-based pagination over `updated_at` (newest first). The cursor
+ * encodes the updatedAt/id pair of the last row returned — pass it back
+ * unchanged to fetch the next page.
+ *
+ * Filters match against metadata JSONB paths using equality. Only
+ * `snake_case` / simple identifier keys are accepted — see
+ * `validateFilterKey` for the exact rules. Passing an untrusted key
+ * throws `SessionStoreError`.
+ *
+ * `updatedAfter` / `updatedBefore` filter by the `updated_at` column
+ * (inclusive). Useful for "sessions touched this week" queries.
+ */
+export interface SessionListOptions {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly filter?: Readonly<Record<string, unknown>>;
+    readonly updatedAfter?: Date;
+    readonly updatedBefore?: Date;
+}
+/**
+ * Result of `SessionStore.list()` — sessions plus an opaque cursor
+ * for the next page. `nextCursor` is `null` when there are no more rows.
+ */
+export interface SessionListResult {
+    readonly sessions: PersistedSession[];
+    readonly nextCursor: string | null;
+}
+/**
+ * Optional callbacks fired after mutations. Each hook is awaited, so
+ * a failing hook propagates to the caller. Keep hooks fast — they sit
+ * on the write path.
+ *
+ * Intended use: dual-write to a consumer's own table (hosted-runtime
+ * adoption path), emit observability events, invalidate caches.
+ */
+export interface SessionStoreHooks {
+    onAfterSave?: (session: PersistedSession) => Promise<void> | void;
+    onAfterDelete?: (sessionId: string) => Promise<void> | void;
+    onAfterCleanup?: (opts: {
+        deleted: number;
+        before: Date;
+    }) => Promise<void> | void;
+}
 /**
  * Interface for session persistence backends.
  *
- * Implementations: PGLiteSessionStore (local dev), future Postgres
- * (hosted runtime via shared Drizzle schema).
+ * One concrete implementation (`DrizzleSessionStore`) with two factories:
+ * `createPGLiteSessionStore` for local dev, `createPostgresSessionStore`
+ * for hosted runtime / ISV production. Both share the `agentSessions`
+ * Drizzle schema and the query helpers in this module.
  */
 export interface SessionStore {
     /** Initialize the backing store (create tables, run migrations). */
     initialize(): Promise<void>;
-    /** Save or update a session. */
+    /**
+     * Save or update a session.
+     *
+     * **Semantics: last-write-wins.** The implementation does an
+     * unconditional `onConflictDoUpdate` — no optimistic-concurrency
+     * version check. If two concurrent `save()` calls target the same
+     * session ID, the later write silently overwrites the earlier one,
+     * including any messages the earlier caller added.
+     *
+     * **Callers must serialize per-session writes.** The built-in
+     * `StandaloneSessionManager` does this by routing all writes for a
+     * session through a single in-memory object. External callers that
+     * share a session across workers must either (a) use a single
+     * writer per session, or (b) wrap `save()` with their own advisory
+     * locking. The `version` column is persisted and surfaced on read
+     * but is currently informational only — reserved for future OCC.
+     */
     save(session: PersistedSession): Promise<void>;
-    /** Load a session by ID. Returns null if not found. */
+    /** Load a session by id. Returns null if not found. */
     load(sessionId: string): Promise<PersistedSession | null>;
-    /** List sessions for a tenant, newest first. */
-    list(tenantId: string, opts?: {
-        limit?: number;
-    }): Promise<PersistedSession[]>;
-    /** Delete a session by ID. Returns true if deleted. */
+    /**
+     * List sessions newest first. Returns sessions + a pagination cursor.
+     * Callers that need any form of scoping should namespace their
+     * session IDs directly (e.g. `app-a:session-123`) and/or filter by
+     * `metadata` fields via `opts.filter`.
+     */
+    list(opts?: SessionListOptions): Promise<SessionListResult>;
+    /** Delete a session by id. Returns true if a row was deleted. */
     delete(sessionId: string): Promise<boolean>;
     /** Delete sessions not updated since `before`. Returns count deleted. */
     cleanup(before: Date): Promise<number>;
     /** Close the backing store. */
     close(): Promise<void>;
 }
+export declare function validateFilterKey(backend: string, key: string): void;
+/** Encode a cursor as opaque base64 of "updatedAt.ms|id". */
+export declare function encodeCursor(updatedAt: Date, id: string): string;
+/** Decode a cursor; throws SessionStoreError on malformed input. */
+export declare function decodeCursor(backend: string, cursor: string): {
+    updatedAt: Date;
+    id: string;
+};
+/**
+ * Map a `PersistedSession` to its row shape for insert/update. Separate
+ * function so both backends do the exact same type conversion.
+ */
+export declare function sessionToRow(session: PersistedSession): {
+    id: string;
+    messages: unknown[];
+    tokenUsage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    metadata: Record<string, unknown>;
+    version: number;
+    createdAt: Date;
+    updatedAt: Date;
+};
 /**
- * PGLite-backed session store using Drizzle ORM.
+ * Inverse of `sessionToRow`.
  *
- * Runs an in-process WASM Postgres instance. Data is persisted to a
- * configurable directory (default: in-memory).
+ * Validates at the JSONB boundary: rejects rows with an unknown
+ * `version` (future schema migration signal) or a non-array `messages`
+ * payload (would indicate a malformed write from an older runtime or
+ * manual DB edit). Throws `SessionStoreError` with context when a row
+ * fails validation rather than returning a quietly-broken session
+ * that crashes deep in the agent loop.
  */
-export declare class PGLiteSessionStore implements SessionStore {
-    private db;
-    private pglite;
-    private readonly dataDir;
-    private readonly logger;
-    constructor(opts: {
-        dataDir?: string;
-        logger: Logger;
-    });
-    initialize(): Promise<void>;
-    save(session: PersistedSession): Promise<void>;
-    load(sessionId: string): Promise<PersistedSession | null>;
-    list(tenantId: string, opts?: {
-        limit?: number;
-    }): Promise<PersistedSession[]>;
-    delete(sessionId: string): Promise<boolean>;
-    cleanup(before: Date): Promise<number>;
-    close(): Promise<void>;
-    private ensureDb;
+export declare function rowToPersistedSession(backend: string, row: typeof agentSessions.$inferSelect): PersistedSession;
+/**
+ * Structural shape the `buildListConditions` helper needs. Any
+ * `agent_sessions`-compatible Drizzle pgTable (default name or a
+ * consumer-supplied one) satisfies this — both backends use the same
+ * column names, only the table name differs.
+ */
+export interface AgentSessionsColumns {
+    updatedAt: AnyPgColumn;
+    id: AnyPgColumn;
+    metadata: AnyPgColumn;
 }
+/**
+ * Build the where-clause fragments for `list()`. Generic over the
+ * table's column bindings so both PGLite (static `agentSessions`) and
+ * Postgres (dynamic `makeAgentSessionsTable(name)`) pass their own
+ * tables without a cast.
+ *
+ * Returns `undefined` when `opts` yields no conditions — drizzle's
+ * `.where(undefined)` is a no-op, equivalent to "no filter".
+ */
+export declare function buildListConditions(backend: string, opts: SessionListOptions | undefined, table: AgentSessionsColumns): ReturnType<typeof and>;

package/dist/src/session/store.js

@@ -4,159 +4,109 @@
  * SPDX-License-Identifier: MIT
  */
 /**
- * Session persistence layer.
+ * Session persistence layer — interface, types, and shared helpers.
  *
- * Defines the `SessionStore` interface and a PGLite implementation
- * backed by Drizzle ORM. The Drizzle schema is in `stores/schema.ts`,
- * shared with the store document tables.
+ * Concrete implementations:
+ *   - `DrizzleSessionStore` (./drizzle-session-store.ts) — the single
+ *     query layer shared by both backends.
+ *   - `createPGLiteSessionStore` (./pglite-session-store.ts) — factory
+ *     for local-dev / in-memory PGLite.
+ *   - `createPostgresSessionStore` (./postgres-session-store.ts) —
+ *     factory for hosted runtime / ISV production.
+ *
+ * The Drizzle schema lives in `../stores/schema.ts`, shared with the
+ * store document tables.
  */
-import { eq, lt, desc } from 'drizzle-orm';
-import { drizzle } from 'drizzle-orm/pglite';
-import { agentSessions } from '../stores/schema.js';
-import { ConfigError } from '../errors.js';
+import { and, eq, lt, or, gte, lte, sql } from 'drizzle-orm';
+import { SessionStoreError } from '../errors.js';
 // ---------------------------------------------------------------------------
-// PGLite implementation
+// Shared helpers — used by both PGLite and Postgres implementations
 // ---------------------------------------------------------------------------
 /**
- * PGLite-backed session store using Drizzle ORM.
- *
- * Runs an in-process WASM Postgres instance. Data is persisted to a
- * configurable directory (default: in-memory).
+ * Reject filter keys that could be used for SQL injection. We only
+ * allow simple identifiers: letters, digits, underscores. The keys
+ * become part of a JSONB path (`metadata->>'key'`) so they must be
+ * safe to interpolate.
  */
-export class PGLiteSessionStore {
-    db = null;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- PGLite instance type is not exported cleanly
-    pglite = null;
-    dataDir;
-    logger;
-    constructor(opts) {
-        this.dataDir = opts.dataDir;
-        this.logger = opts.logger;
-    }
-    async initialize() {
-        if (this.db)
-            return;
-        if (this.dataDir) {
-            const { mkdirSync } = await import('node:fs');
-            mkdirSync(this.dataDir, { recursive: true });
-        }
-        const { PGlite } = await import('@electric-sql/pglite');
-        this.pglite = new PGlite(this.dataDir ?? undefined);
-        this.db = drizzle(this.pglite);
-        // Create table via raw SQL — Drizzle schema defines the shape,
-        // but we use raw DDL for initialization (no drizzle-kit in runtime).
-        await this.pglite.exec(`
-      CREATE TABLE IF NOT EXISTS agent_sessions (
-        id TEXT PRIMARY KEY,
-        tenant_id TEXT NOT NULL,
-        user_id TEXT NOT NULL,
-        messages JSONB NOT NULL,
-        token_usage JSONB NOT NULL,
-        metadata JSONB DEFAULT '{}',
-        version INTEGER NOT NULL DEFAULT 1,
-        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-      );
-
-      CREATE INDEX IF NOT EXISTS idx_agent_sessions_tenant
-        ON agent_sessions (tenant_id, updated_at DESC);
-    `);
-        this.logger.info('session_store_initialized', {
-            dataDir: this.dataDir ?? 'in-memory',
+const SAFE_KEY_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+export function validateFilterKey(backend, key) {
+    if (!SAFE_KEY_RE.test(key)) {
+        throw new SessionStoreError(`Invalid filter field name: ${JSON.stringify(key)}`, {
+            backend,
+            operation: 'list',
+            context: { key, expected: 'identifier: letters, digits, underscore only' },
         });
     }
-    async save(session) {
-        this.ensureDb();
-        const values = {
-            id: session.id,
-            tenantId: session.tenantId,
-            userId: session.userId,
-            messages: session.messages,
-            tokenUsage: session.tokenUsage,
-            metadata: session.metadata,
-            version: session.version,
-            createdAt: session.createdAt,
-            updatedAt: session.updatedAt,
-        };
-        await this.db
-            .insert(agentSessions)
-            .values(values)
-            .onConflictDoUpdate({
-            target: agentSessions.id,
-            set: {
-                messages: values.messages,
-                tokenUsage: values.tokenUsage,
-                metadata: values.metadata,
-                updatedAt: values.updatedAt,
-            },
-        });
-    }
-    async load(sessionId) {
-        this.ensureDb();
-        const rows = await this.db
-            .select()
-            .from(agentSessions)
-            .where(eq(agentSessions.id, sessionId))
-            .limit(1);
-        if (rows.length === 0)
-            return null;
-        return rowToPersistedSession(rows[0]);
-    }
-    async list(tenantId, opts) {
-        this.ensureDb();
-        const rows = await this.db
-            .select()
-            .from(agentSessions)
-            .where(eq(agentSessions.tenantId, tenantId))
-            .orderBy(desc(agentSessions.updatedAt))
-            .limit(opts?.limit ?? 50);
-        return rows.map(rowToPersistedSession);
-    }
-    async delete(sessionId) {
-        this.ensureDb();
-        const result = await this.db
-            .delete(agentSessions)
-            .where(eq(agentSessions.id, sessionId))
-            .returning({ id: agentSessions.id });
-        return result.length > 0;
+}
+/** Encode a cursor as opaque base64 of "updatedAt.ms|id". */
+export function encodeCursor(updatedAt, id) {
+    return Buffer.from(`${updatedAt.getTime()}|${id}`, 'utf8').toString('base64url');
+}
+/** Decode a cursor; throws SessionStoreError on malformed input. */
+export function decodeCursor(backend, cursor) {
+    try {
+        const decoded = Buffer.from(cursor, 'base64url').toString('utf8');
+        const sep = decoded.indexOf('|');
+        if (sep < 0)
+            throw new Error('missing separator');
+        const ms = Number(decoded.slice(0, sep));
+        const id = decoded.slice(sep + 1);
+        if (!Number.isFinite(ms) || !id)
+            throw new Error('bad parts');
+        return { updatedAt: new Date(ms), id };
     }
-    async cleanup(before) {
-        this.ensureDb();
-        const result = await this.db
-            .delete(agentSessions)
-            .where(lt(agentSessions.updatedAt, before))
-            .returning({ id: agentSessions.id });
-        if (result.length > 0) {
-            this.logger.info('session_store_cleanup', { deleted: result.length });
-        }
-        return result.length;
+    catch (cause) {
+        throw new SessionStoreError('Invalid pagination cursor', {
+            backend,
+            operation: 'list',
+            cause,
+        });
     }
-    async close() {
-        if (this.pglite) {
-            await this.pglite.close();
-            this.pglite = null;
-            this.db = null;
-        }
+}
+/**
+ * Map a `PersistedSession` to its row shape for insert/update. Separate
+ * function so both backends do the exact same type conversion.
+ */
+export function sessionToRow(session) {
+    return {
+        id: session.id,
+        messages: session.messages,
+        tokenUsage: session.tokenUsage,
+        metadata: session.metadata,
+        version: session.version,
+        createdAt: session.createdAt,
+        updatedAt: session.updatedAt,
+    };
+}
+/**
+ * Inverse of `sessionToRow`.
+ *
+ * Validates at the JSONB boundary: rejects rows with an unknown
+ * `version` (future schema migration signal) or a non-array `messages`
+ * payload (would indicate a malformed write from an older runtime or
+ * manual DB edit). Throws `SessionStoreError` with context when a row
+ * fails validation rather than returning a quietly-broken session
+ * that crashes deep in the agent loop.
+ */
+export function rowToPersistedSession(backend, row) {
+    if (row.version !== 1) {
+        throw new SessionStoreError(`Unsupported persisted session version: ${row.version}`, {
+            backend,
+            operation: 'load',
+            context: { sessionId: row.id, version: row.version, supported: 1 },
+        });
     }
-    ensureDb() {
-        if (!this.db) {
-            throw new ConfigError('PGLiteSessionStore not initialized — call initialize() first', {
-                key: 'sessionStore',
-                suggestion: 'Call initialize() before using the session store',
-            });
-        }
+    if (!Array.isArray(row.messages)) {
+        throw new SessionStoreError('Persisted session has non-array messages payload', {
+            backend,
+            operation: 'load',
+            context: { sessionId: row.id, messagesType: typeof row.messages },
+        });
     }
-}
-// ---------------------------------------------------------------------------
-// Row conversion
-// ---------------------------------------------------------------------------
-function rowToPersistedSession(row) {
     return {
         version: 1,
         id: row.id,
-        tenantId: row.tenantId,
-        userId: row.userId,
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- JSONB boundary: we wrote these values
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- JSONB boundary: array-shape checked above; element shape is not validated
         messages: row.messages,
         tokenUsage: row.tokenUsage,
         metadata: (row.metadata ?? {}),
@@ -164,4 +114,42 @@ function rowToPersistedSession(row) {
         updatedAt: row.updatedAt,
     };
 }
+/**
+ * Build the where-clause fragments for `list()`. Generic over the
+ * table's column bindings so both PGLite (static `agentSessions`) and
+ * Postgres (dynamic `makeAgentSessionsTable(name)`) pass their own
+ * tables without a cast.
+ *
+ * Returns `undefined` when `opts` yields no conditions — drizzle's
+ * `.where(undefined)` is a no-op, equivalent to "no filter".
+ */
+export function buildListConditions(backend, opts, table) {
+    const conditions = [];
+    if (opts?.cursor) {
+        const { updatedAt: cursorTs, id: cursorId } = decodeCursor(backend, opts.cursor);
+        // Compound (updated_at, id) comparison makes pagination stable even
+        // when multiple rows share the same `updated_at` (batch inserts in
+        // the same ms, clock-skewed sources). Matches the secondary sort
+        // key on `id` used by list() so every row is visited exactly once.
+        const cursorCondition = or(lt(table.updatedAt, cursorTs), and(eq(table.updatedAt, cursorTs), lt(table.id, cursorId)));
+        if (cursorCondition)
+            conditions.push(cursorCondition);
+    }
+    if (opts?.updatedAfter)
+        conditions.push(gte(table.updatedAt, opts.updatedAfter));
+    if (opts?.updatedBefore)
+        conditions.push(lte(table.updatedAt, opts.updatedBefore));
+    if (opts?.filter) {
+        for (const [key, val] of Object.entries(opts.filter)) {
+            validateFilterKey(backend, key);
+            // metadata->>'key' = value (string equality). JSONB `->>` returns
+            // text; we coerce the user-supplied value to its JSON string form
+            // via parameter binding, so non-string values like numbers/bools
+            // compare correctly: metadata->>'n' = '42'.
+            const textVal = typeof val === 'string' ? val : JSON.stringify(val);
+            conditions.push(sql `${table.metadata}->>${sql.raw(`'${key}'`)} = ${textVal}`);
+        }
+    }
+    return and(...conditions);
+}
 //# sourceMappingURL=store.js.map

package/dist/src/session/store.js.map

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