@amodalai/runtime 0.1.26 → 0.2.1

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

@@ -0,0 +1,171 @@
+/**
+ * @license
+ * 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';
+/**
+ * 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.
+ *
+ * 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.
+     *
+     * **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(sessionId: string): Promise<PersistedSession | null>;
+    /**
+     * 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;
+};
+/**
+ * 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 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

@@ -0,0 +1,155 @@
+/**
+ * @license
+ * 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, eq, lt, or, gte, lte, sql } from 'drizzle-orm';
+import { SessionStoreError } from '../errors.js';
+// ---------------------------------------------------------------------------
+// Shared helpers — used by both PGLite and Postgres implementations
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+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' },
+        });
+    }
+}
+/** 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 };
+    }
+    catch (cause) {
+        throw new SessionStoreError('Invalid pagination cursor', {
+            backend,
+            operation: 'list',
+            cause,
+        });
+    }
+}
+/**
+ * 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 },
+        });
+    }
+    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 },
+        });
+    }
+    return {
+        version: 1,
+        id: row.id,
+        // 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 ?? {}),
+        createdAt: row.createdAt,
+        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

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/session/store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAC,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAC,MAAM,aAAa,CAAC;AAM3D,OAAO,EAAC,iBAAiB,EAAC,MAAM,cAAc,CAAC;AA4G/C,8EAA8E;AAC9E,oEAAoE;AACpE,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,WAAW,GAAG,0BAA0B,CAAC;AAE/C,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,GAAW;IAC5D,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,iBAAiB,CACzB,8BAA8B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EACnD;YACE,OAAO;YACP,SAAS,EAAE,MAAM;YACjB,OAAO,EAAE,EAAC,GAAG,EAAE,QAAQ,EAAE,8CAA8C,EAAC;SACzE,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,YAAY,CAAC,SAAe,EAAE,EAAU;IACtD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACnF,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAC1B,OAAe,EACf,MAAc;IAEd,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClE,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,GAAG,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAClD,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QACzC,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,WAAW,CAAC,CAAC;QAC9D,OAAO,EAAC,SAAS,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,EAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CAAC,2BAA2B,EAAE;YACvD,OAAO;YACP,SAAS,EAAE,MAAM;YACjB,KAAK;SACN,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAyB;IASpD,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,QAAQ,EAAE,OAAO,CAAC,QAAqB;QACvC,UAAU,EAAE,OAAO,CAAC,UAInB;QACD,QAAQ,EAAE,OAAO,CAAC,QAAmC;QACrD,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,GAAsC;IAEtC,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,iBAAiB,CACzB,0CAA0C,GAAG,CAAC,OAAO,EAAE,EACvD;YACE,OAAO;YACP,SAAS,EAAE,MAAM;YACjB,OAAO,EAAE,EAAC,SAAS,EAAE,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,EAAC;SACjE,CACF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,iBAAiB,CAAC,kDAAkD,EAAE;YAC9E,OAAO;YACP,SAAS,EAAE,MAAM;YACjB,OAAO,EAAE,EAAC,SAAS,EAAE,GAAG,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,GAAG,CAAC,QAAQ,EAAC;SAChE,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,OAAO,EAAE,CAAC;QACV,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,oJAAoJ;QACpJ,QAAQ,EAAE,GAAG,CAAC,QAA0B;QAExC,UAAU,EAAE,GAAG,CAAC,UAAwB;QAExC,QAAQ,EAAE,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAoB;QACjD,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,CAAC;AACJ,CAAC;AAcD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,IAAoC,EACpC,KAA2B;IAE3B,MAAM,UAAU,GAAiC,EAAE,CAAC;IAEpD,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,MAAM,EAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAC,GAAG,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/E,oEAAoE;QACpE,mEAAmE;QACnE,iEAAiE;QACjE,mEAAmE;QACnE,MAAM,eAAe,GAAG,EAAE,CACxB,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,EAC7B,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAC3D,CAAC;QACF,IAAI,eAAe;YAAE,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,IAAI,EAAE,YAAY;QAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IACjF,IAAI,IAAI,EAAE,aAAa;QAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;IAEnF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACrD,iBAAiB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAChC,kEAAkE;YAClE,kEAAkE;YAClE,iEAAiE;YACjE,4CAA4C;YAC5C,MAAM,OAAO,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YACpE,UAAU,CAAC,IAAI,CACb,GAAG,CAAA,GAAG,KAAK,CAAC,QAAQ,MAAM,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,OAAO,EAAE,CAC7D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;AAC5B,CAAC"}

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

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};