@amodalai/runtime 0.1.26 → 0.2.0

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

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Tests for PGLiteSessionStore.
+ *
+ * Uses a real in-memory PGLite instance — no mocks.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { PGLiteSessionStore } from './store.js';
+import { createLogger } from '../logger.js';
+const logger = createLogger({ component: 'test:session-store' });
+function makeSession(overrides = {}) {
+    return {
+        version: 1,
+        id: `sess-${Math.random().toString(36).slice(2, 10)}`,
+        tenantId: 'tenant-1',
+        userId: 'user-1',
+        messages: [{ role: 'user', content: 'Hello' }],
+        tokenUsage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+        metadata: {},
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        ...overrides,
+    };
+}
+describe('PGLiteSessionStore', () => {
+    let store;
+    beforeAll(async () => {
+        store = new PGLiteSessionStore({ logger });
+        await store.initialize();
+    });
+    afterAll(async () => {
+        await store.close();
+    });
+    it('save and load a session', async () => {
+        const session = makeSession();
+        await store.save(session);
+        const loaded = await store.load(session.id);
+        expect(loaded).not.toBeNull();
+        expect(loaded.id).toBe(session.id);
+        expect(loaded.tenantId).toBe(session.tenantId);
+        expect(loaded.userId).toBe(session.userId);
+        expect(loaded.version).toBe(1);
+        expect(loaded.messages).toEqual(session.messages);
+        expect(loaded.tokenUsage).toEqual(session.tokenUsage);
+    });
+    it('load returns null for missing session', async () => {
+        const loaded = await store.load('nonexistent');
+        expect(loaded).toBeNull();
+    });
+    it('save updates existing session (upsert)', async () => {
+        const session = makeSession();
+        await store.save(session);
+        // Update messages and re-save
+        session.messages = [
+            { role: 'user', content: 'Hello' },
+            { role: 'assistant', content: 'Hi there' },
+        ];
+        session.tokenUsage = { inputTokens: 200, outputTokens: 100, totalTokens: 300 };
+        session.updatedAt = new Date();
+        await store.save(session);
+        const loaded = await store.load(session.id);
+        expect(loaded.messages).toHaveLength(2);
+        expect(loaded.tokenUsage.totalTokens).toBe(300);
+    });
+    it('list sessions filtered by tenant, newest first', async () => {
+        const tenantId = `tenant-list-${Date.now()}`;
+        const older = makeSession({
+            tenantId,
+            updatedAt: new Date('2026-01-01'),
+        });
+        const newer = makeSession({
+            tenantId,
+            updatedAt: new Date('2026-03-01'),
+        });
+        await store.save(older);
+        await store.save(newer);
+        const sessions = await store.list(tenantId);
+        expect(sessions.length).toBeGreaterThanOrEqual(2);
+        // Newest first
+        const ids = sessions.map((s) => s.id);
+        expect(ids.indexOf(newer.id)).toBeLessThan(ids.indexOf(older.id));
+    });
+    it('list does not return sessions from other tenants', async () => {
+        const tenantA = `tenant-a-${Date.now()}`;
+        const tenantB = `tenant-b-${Date.now()}`;
+        await store.save(makeSession({ tenantId: tenantA }));
+        await store.save(makeSession({ tenantId: tenantB }));
+        const sessionsA = await store.list(tenantA);
+        expect(sessionsA.every((s) => s.tenantId === tenantA)).toBe(true);
+    });
+    it('delete removes a session', async () => {
+        const session = makeSession();
+        await store.save(session);
+        const deleted = await store.delete(session.id);
+        expect(deleted).toBe(true);
+        const loaded = await store.load(session.id);
+        expect(loaded).toBeNull();
+    });
+    it('delete returns false for missing session', async () => {
+        const deleted = await store.delete('nonexistent');
+        expect(deleted).toBe(false);
+    });
+    it('cleanup removes sessions older than cutoff', async () => {
+        const tenantId = `tenant-cleanup-${Date.now()}`;
+        const old = makeSession({
+            tenantId,
+            updatedAt: new Date('2020-01-01'),
+        });
+        const recent = makeSession({
+            tenantId,
+            updatedAt: new Date(),
+        });
+        await store.save(old);
+        await store.save(recent);
+        const cleaned = await store.cleanup(new Date('2025-01-01'));
+        expect(cleaned).toBeGreaterThanOrEqual(1);
+        // Old session gone
+        const loaded = await store.load(old.id);
+        expect(loaded).toBeNull();
+        // Recent session still there
+        const loadedRecent = await store.load(recent.id);
+        expect(loadedRecent).not.toBeNull();
+    });
+    it('metadata is preserved through save/load', async () => {
+        const session = makeSession({
+            metadata: {
+                title: 'Test Session',
+                model: 'claude-sonnet-4-20250514',
+                provider: 'anthropic',
+                appId: 'my-app',
+            },
+        });
+        await store.save(session);
+        const loaded = await store.load(session.id);
+        expect(loaded.metadata.title).toBe('Test Session');
+        expect(loaded.metadata.model).toBe('claude-sonnet-4-20250514');
+        expect(loaded.metadata.provider).toBe('anthropic');
+        expect(loaded.metadata.appId).toBe('my-app');
+    });
+});
+//# sourceMappingURL=store.test.js.map

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

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

package/dist/src/session/stream-hooks.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Stream hooks type.
+ *
+ * These callbacks are invoked by route handlers after runMessage() drains.
+ * Hosted-mode consumers use them for audit logging, usage reporting, and
+ * external persistence.
+ */
+export interface TokenCounts {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+}
+/**
+ * Hooks invoked by chat route handlers after the message stream completes.
+ */
+export interface StreamHooks {
+    /** Log an audit event */
+    onAuditLog?: (entry: {
+        event: string;
+        resource_name: string;
+        details?: Record<string, unknown>;
+    }) => void;
+    /** Report token usage after each turn (fire-and-forget) */
+    onUsageReport?: (usage: {
+        model: string;
+        taskAgentRuns: number;
+        tokens: TokenCounts;
+    }) => void;
+    /** Persist session history (fire-and-forget). Messages array is empty for new-stack sessions. */
+    onSessionPersist?: (sessionId: string, messages: unknown[], status: 'active' | 'completed' | 'error', meta?: {
+        model?: string;
+        provider?: string;
+    }) => void;
+}

package/dist/src/session/stream-hooks.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=stream-hooks.js.map

package/dist/src/session/stream-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-hooks.js","sourceRoot":"","sources":["../../../src/session/stream-hooks.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/session/tool-context-factory.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Tool Context Factory.
+ *
+ * Builds a ToolContext from session-level dependencies. This is the bridge
+ * between the agent loop and tool implementations.
+ *
+ * Replaces the old `buildToolContext()` in agent/tool-context-builder.ts
+ * which depended on the legacy AgentSession type. This factory takes
+ * explicit dependencies and returns a factory function matching the
+ * `AgentContext.buildToolContext` signature: `(callId: string) => ToolContext`.
+ */
+import type { LoadedStore, StoreBackend } from '@amodalai/types';
+import type { FieldScrubber } from '@amodalai/core';
+import type { ConnectionsMap } from '../tools/request-tool.js';
+import type { ToolContext } from '../tools/types.js';
+import type { Logger } from '../logger.js';
+/** Dependencies for creating tool contexts. */
+export interface ToolContextFactoryOptions {
+    /** Connection configs (base_url, auth headers, etc.) */
+    connectionsMap: ConnectionsMap;
+    /** Shared store backend for ctx.store() */
+    storeBackend: StoreBackend;
+    /** Store definitions for key resolution */
+    storeDefinitions: LoadedStore[];
+    /** App ID for store isolation */
+    appId: string;
+    /** Allowlisted env vars: name → value. Only these are exposed via ctx.env(). */
+    envAllowlist: Record<string, string | undefined>;
+    /** Session-scoped logger */
+    logger: Logger;
+    /** Field scrubber for response sanitization (optional) */
+    fieldScrubber?: FieldScrubber | null;
+    /** User info */
+    user: {
+        roles: string[];
+        [key: string]: unknown;
+    };
+    /** Session ID for correlation */
+    sessionId: string;
+    /** Tenant ID for multi-tenant isolation */
+    tenantId: string;
+}
+/**
+ * Create a factory function that builds ToolContext instances for tool execution.
+ *
+ * The returned factory is passed as `AgentContext.buildToolContext`. The EXECUTING
+ * state handler calls it once per tool execution with the tool call ID.
+ *
+ * The EXECUTING handler composes its own AbortSignal (session + per-tool timeout)
+ * and overrides `ctx.signal` via object spread before passing to the tool's
+ * execute function. Methods on this context read `ctx.signal` at call time
+ * (not at creation time) so that the overridden signal propagates to HTTP
+ * requests and other async operations.
+ */
+export declare function createToolContextFactory(opts: ToolContextFactoryOptions): (callId: string) => ToolContext;

package/dist/src/session/tool-context-factory.js

@@ -0,0 +1,190 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { ConnectionError, StoreError } from '../errors.js';
+import { resolveKey } from '../stores/key-resolver.js';
+// ---------------------------------------------------------------------------
+// Request implementation (internalized from request-helper.ts)
+// ---------------------------------------------------------------------------
+const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Resolve auth template variables: "Bearer {{API_KEY}}" → "Bearer token123"
+ */
+function resolveAuthTemplate(template, connectionConfig) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_match, varName) => {
+        const value = connectionConfig[varName];
+        return value !== undefined ? String(value) : '';
+    });
+}
+async function makeRequest(opts, connection, endpoint, params, signal) {
+    const method = params?.method ?? 'GET';
+    const connConfig = opts.connectionsMap[connection];
+    if (!connConfig) {
+        const available = Object.keys(opts.connectionsMap);
+        const suggestion = available.find((n) => n.toLowerCase() === connection.toLowerCase())
+            ?? available.find((n) => connection.toLowerCase().includes(n.toLowerCase()) || n.toLowerCase().includes(connection.toLowerCase()));
+        throw new ConnectionError(`Connection "${connection}" not found. Available: ${available.join(', ') || '(none)'}${suggestion ? `. Did you mean "${suggestion}"?` : ''}`, { connection, action: `${method} ${endpoint}` });
+    }
+    const baseUrl = connConfig.base_url;
+    if (!baseUrl) {
+        throw new ConnectionError(`Connection "${connection}" has no base_url`, { connection, action: `${method} ${endpoint}` });
+    }
+    let url = `${baseUrl.replace(/\/$/, '')}/${endpoint.replace(/^\//, '')}`;
+    // Add query params
+    if (params?.params) {
+        const searchParams = new URLSearchParams();
+        for (const [k, v] of Object.entries(params.params)) {
+            searchParams.set(k, v);
+        }
+        const qs = searchParams.toString();
+        if (qs) {
+            url += `?${qs}`;
+        }
+    }
+    // Build headers
+    const headers = { 'Content-Type': 'application/json' };
+    const reqConfig = connConfig._request_config;
+    if (reqConfig?.auth) {
+        for (const entry of reqConfig.auth) {
+            headers[entry.header] = resolveAuthTemplate(entry.value_template, connConfig);
+        }
+    }
+    if (reqConfig?.default_headers) {
+        for (const [k, v] of Object.entries(reqConfig.default_headers)) {
+            headers[k] = v;
+        }
+    }
+    const requestSignal = signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+    const fetchOpts = { method, headers, signal: requestSignal };
+    if (params?.data && (method === 'POST' || method === 'PUT' || method === 'PATCH')) {
+        fetchOpts.body = JSON.stringify(params.data);
+    }
+    const response = await fetch(url, fetchOpts);
+    const text = await response.text();
+    // Field scrubbing — only attempt on valid JSON; scrubber errors propagate
+    let output = text;
+    if (opts.fieldScrubber) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            // Not JSON — skip scrubbing, return text as-is
+            parsed = undefined;
+        }
+        if (parsed !== undefined) {
+            const scrubResult = opts.fieldScrubber.scrub(parsed, connection, endpoint);
+            output = JSON.stringify(scrubResult.data);
+        }
+    }
+    if (!response.ok) {
+        if (response.status === 401 || response.status === 403) {
+            throw new ConnectionError(`Authentication failed (${String(response.status)}) for connection "${connection}". Check credentials.`, { connection, action: `${method} ${endpoint}` });
+        }
+        throw new ConnectionError(`HTTP ${String(response.status)} from "${connection}" ${method} ${endpoint}: ${output.substring(0, 500)}`, { connection, action: `${method} ${endpoint}` });
+    }
+    // Parse JSON response if possible
+    try {
+        return JSON.parse(output);
+    }
+    catch {
+        return output;
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a factory function that builds ToolContext instances for tool execution.
+ *
+ * The returned factory is passed as `AgentContext.buildToolContext`. The EXECUTING
+ * state handler calls it once per tool execution with the tool call ID.
+ *
+ * The EXECUTING handler composes its own AbortSignal (session + per-tool timeout)
+ * and overrides `ctx.signal` via object spread before passing to the tool's
+ * execute function. Methods on this context read `ctx.signal` at call time
+ * (not at creation time) so that the overridden signal propagates to HTTP
+ * requests and other async operations.
+ */
+export function createToolContextFactory(opts) {
+    return (callId) => {
+        // Build ctx as a named object so methods can reference ctx.signal at
+        // call time. When EXECUTING does `{...toolCtx, signal: combined}`, the
+        // spread creates a new object — but the closures still capture `ctx`.
+        // To fix this, EXECUTING must mutate `toolCtx.signal` directly instead
+        // of spreading. The default signal here is a safety net in case
+        // the caller doesn't override.
+        const ctx = {
+            async request(connection, endpoint, params) {
+                opts.logger.debug('tool_context_request', {
+                    callId,
+                    connection,
+                    endpoint,
+                    method: params?.method ?? 'GET',
+                    session: opts.sessionId,
+                });
+                return makeRequest(opts, connection, endpoint, params, ctx.signal);
+            },
+            async store(storeName, payload) {
+                const storeDef = opts.storeDefinitions.find((s) => s.name === storeName);
+                if (!storeDef) {
+                    const available = opts.storeDefinitions.map((s) => s.name).join(', ');
+                    throw new StoreError(`Store "${storeName}" not found. Available: ${available || '(none)'}`, {
+                        store: storeName,
+                        operation: 'put',
+                        context: { available, session: opts.sessionId },
+                    });
+                }
+                const key = resolveKey(storeDef.entity.key, payload);
+                opts.logger.debug('tool_context_store_write', {
+                    callId,
+                    store: storeName,
+                    key,
+                    session: opts.sessionId,
+                });
+                // Race against abort signal so a hung PGLite doesn't block forever
+                await Promise.race([
+                    opts.storeBackend.put(opts.appId, storeName, key, payload, {}),
+                    new Promise((_resolve, reject) => {
+                        if (ctx.signal.aborted) {
+                            reject(new StoreError('Store write timed out', { store: storeName, operation: 'put', context: { callId, key } }));
+                            return;
+                        }
+                        ctx.signal.addEventListener('abort', () => {
+                            reject(new StoreError('Store write timed out', { store: storeName, operation: 'put', context: { callId, key } }));
+                        }, { once: true });
+                    }),
+                ]);
+                opts.logger.debug('tool_context_store_complete', {
+                    callId,
+                    store: storeName,
+                    key,
+                    session: opts.sessionId,
+                });
+                return { key };
+            },
+            env(name) {
+                if (!(name in opts.envAllowlist)) {
+                    return undefined;
+                }
+                return opts.envAllowlist[name];
+            },
+            log(message) {
+                opts.logger.info('tool_log', {
+                    callId,
+                    message,
+                    session: opts.sessionId,
+                    tenant: opts.tenantId,
+                });
+            },
+            user: opts.user,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            sessionId: opts.sessionId,
+            tenantId: opts.tenantId,
+        };
+        return ctx;
+    };
+}
+//# sourceMappingURL=tool-context-factory.js.map

package/dist/src/session/tool-context-factory.js.map

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

package/dist/src/session/tool-context-factory.test.d.ts

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