@agentuity/runtime 0.0.42 → 0.0.44

package/src/services/local/stream.ts

@@ -0,0 +1,296 @@
+import type { Database } from 'bun:sqlite';
+import type {
+	StreamStorage,
+	Stream,
+	CreateStreamProps,
+	ListStreamsParams,
+	ListStreamsResponse,
+	StreamInfo,
+} from '@agentuity/core';
+import { now } from './_util';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, existsSync, unlinkSync } from 'node:fs';
+import { openSync, writeSync, closeSync, readFileSync } from 'node:fs';
+
+export class LocalStreamStorage implements StreamStorage {
+	#db: Database;
+	#projectPath: string;
+	#serverUrl: string;
+	#tempDir: string;
+
+	constructor(db: Database, projectPath: string, serverUrl: string) {
+		this.#db = db;
+		this.#projectPath = projectPath;
+		this.#serverUrl = serverUrl;
+
+		// Create temp directory for stream buffering
+		this.#tempDir = join(homedir(), '.config', 'agentuity', 'streams');
+		if (!existsSync(this.#tempDir)) {
+			mkdirSync(this.#tempDir, { recursive: true });
+		}
+	}
+
+	async create(name: string, props?: CreateStreamProps): Promise<Stream> {
+		if (!name || name.length < 1 || name.length > 254) {
+			throw new Error('Stream name must be between 1 and 254 characters');
+		}
+
+		const id = randomUUID();
+		const timestamp = now();
+		const metadata = props?.metadata ? JSON.stringify(props.metadata) : null;
+
+		// Insert stream record with NULL data
+		const stmt = this.#db.prepare(`
+			INSERT INTO stream_storage (
+				project_path, id, name, metadata, content_type, created_at
+			)
+			VALUES (?, ?, ?, ?, ?, ?)
+		`);
+
+		stmt.run(
+			this.#projectPath,
+			id,
+			name,
+			metadata,
+			props?.contentType || 'application/octet-stream',
+			timestamp
+		);
+
+		const url = `${this.#serverUrl}/_agentuity/local/stream/${id}`;
+
+		return new LocalStream(
+			id,
+			url,
+			this.#db,
+			this.#projectPath,
+			this.#tempDir,
+			props?.compress ?? false
+		);
+	}
+
+	async list(params?: ListStreamsParams): Promise<ListStreamsResponse> {
+		if (params?.limit && (params.limit <= 0 || params.limit > 1000)) {
+			throw new Error('limit must be between 1 and 1000');
+		}
+
+		let query = `
+			SELECT id, name, metadata, size_bytes 
+			FROM stream_storage 
+			WHERE project_path = ?
+		`;
+		const queryParams: (string | number)[] = [this.#projectPath];
+
+		// Add filters
+		if (params?.name) {
+			query += ` AND name = ?`;
+			queryParams.push(params.name);
+		}
+
+		if (params?.metadata) {
+			// Simple JSON matching - check if metadata contains all key-value pairs
+			for (const [key, value] of Object.entries(params.metadata)) {
+				query += ` AND metadata LIKE ?`;
+				queryParams.push(`%"${key}":"${value}"%`);
+			}
+		}
+
+		// Get total count
+		const countQuery = this.#db.query(
+			query.replace('SELECT id, name, metadata, size_bytes', 'SELECT COUNT(*) as count')
+		);
+		const { count } = countQuery.get(...queryParams) as { count: number };
+
+		// Add pagination
+		query += ` ORDER BY created_at DESC`;
+		if (params?.limit) {
+			query += ` LIMIT ${params.limit}`;
+		}
+		if (params?.offset) {
+			query += ` OFFSET ${params.offset}`;
+		}
+
+		const stmt = this.#db.query(query);
+		const rows = stmt.all(...queryParams) as Array<{
+			id: string;
+			name: string;
+			metadata: string | null;
+			size_bytes: number;
+		}>;
+
+		const streams: StreamInfo[] = rows.map((row) => ({
+			id: row.id,
+			name: row.name,
+			metadata: row.metadata ? JSON.parse(row.metadata) : {},
+			url: `${this.#serverUrl}/_agentuity/local/stream/${row.id}`,
+			sizeBytes: row.size_bytes,
+		}));
+
+		return {
+			success: true,
+			streams,
+			total: count,
+		};
+	}
+
+	async delete(id: string): Promise<void> {
+		if (!id?.trim()) {
+			throw new Error('Stream id is required');
+		}
+
+		const stmt = this.#db.prepare(`
+			DELETE FROM stream_storage 
+			WHERE project_path = ? AND id = ?
+		`);
+
+		stmt.run(this.#projectPath, id);
+	}
+}
+
+class LocalStream extends WritableStream implements Stream {
+	public readonly id: string;
+	public readonly url: string;
+
+	#db: Database;
+	#projectPath: string;
+	#compressed: boolean;
+	#tempFilePath: string;
+	#fileHandle: number | null = null;
+	#bytesWritten = 0;
+	#closed = false;
+
+	constructor(
+		id: string,
+		url: string,
+		db: Database,
+		projectPath: string,
+		tempDir: string,
+		compressed: boolean
+	) {
+		super({
+			write: async (chunk: Uint8Array) => {
+				await this.#writeToFile(chunk);
+			},
+			close: async () => {
+				await this.#persist();
+			},
+		});
+
+		this.id = id;
+		this.url = url;
+		this.#db = db;
+		this.#projectPath = projectPath;
+		this.#compressed = compressed;
+		this.#tempFilePath = join(tempDir, `${id}.tmp`);
+
+		// Open file for writing
+		this.#fileHandle = openSync(this.#tempFilePath, 'w');
+	}
+
+	get bytesWritten(): number {
+		return this.#bytesWritten;
+	}
+
+	get compressed(): boolean {
+		return this.#compressed;
+	}
+
+	async write(chunk: string | Uint8Array | ArrayBuffer | Buffer | object): Promise<void> {
+		if (this.#closed) {
+			throw new Error('Stream is closed');
+		}
+
+		let binary: Uint8Array;
+		if (chunk instanceof Uint8Array) {
+			binary = chunk;
+		} else if (typeof chunk === 'string') {
+			binary = new TextEncoder().encode(chunk);
+		} else if (chunk instanceof ArrayBuffer) {
+			binary = new Uint8Array(chunk);
+		} else if (typeof chunk === 'object') {
+			binary = new TextEncoder().encode(JSON.stringify(chunk));
+		} else {
+			binary = new TextEncoder().encode(String(chunk));
+		}
+
+		await this.#writeToFile(binary);
+	}
+
+	override async close(): Promise<void> {
+		if (this.#closed) {
+			return;
+		}
+
+		this.#closed = true;
+
+		// Close file handle if open
+		if (this.#fileHandle !== null) {
+			closeSync(this.#fileHandle);
+			this.#fileHandle = null;
+		}
+
+		await this.#persist();
+	}
+
+	getReader(): ReadableStream<Uint8Array> {
+		const db = this.#db;
+		const projectPath = this.#projectPath;
+		const id = this.id;
+
+		return new ReadableStream({
+			start(controller) {
+				const query = db.query(`
+					SELECT data FROM stream_storage 
+					WHERE project_path = ? AND id = ?
+				`);
+
+				const row = query.get(projectPath, id) as { data: Buffer | null } | null;
+
+				if (!row || !row.data) {
+					controller.error(new Error('Stream not found or not finalized'));
+					return;
+				}
+
+				controller.enqueue(new Uint8Array(row.data));
+				controller.close();
+			},
+		});
+	}
+
+	async #writeToFile(chunk: Uint8Array): Promise<void> {
+		if (this.#fileHandle === null) {
+			throw new Error('File handle is closed');
+		}
+
+		const written = writeSync(this.#fileHandle, chunk);
+		this.#bytesWritten += written;
+	}
+
+	async #persist(): Promise<void> {
+		// Read buffered file
+		let data = readFileSync(this.#tempFilePath);
+
+		// Optional: Apply compression if enabled
+		if (this.#compressed) {
+			const { gzipSync } = await import('node:zlib');
+			data = gzipSync(data);
+		}
+
+		// Update DB with finalized data
+		const stmt = this.#db.prepare(`
+			UPDATE stream_storage 
+			SET data = ?, size_bytes = ? 
+			WHERE project_path = ? AND id = ?
+		`);
+
+		stmt.run(data, this.#bytesWritten, this.#projectPath, this.id);
+
+		// Clean up temp file
+		try {
+			unlinkSync(this.#tempFilePath);
+		} catch {
+			// Ignore cleanup errors
+		}
+	}
+}

package/src/services/local/vector.ts

@@ -0,0 +1,264 @@
+import type { Database } from 'bun:sqlite';
+import type {
+	VectorStorage,
+	VectorUpsertParams,
+	VectorUpsertResult,
+	VectorResult,
+	VectorResultNotFound,
+	VectorSearchResultWithDocument,
+	VectorSearchParams,
+	VectorSearchResult,
+} from '@agentuity/core';
+import { randomUUID } from 'node:crypto';
+import { simpleEmbedding, cosineSimilarity, now } from './_util';
+
+export class LocalVectorStorage implements VectorStorage {
+	#db: Database;
+	#projectPath: string;
+
+	constructor(db: Database, projectPath: string) {
+		this.#db = db;
+		this.#projectPath = projectPath;
+	}
+
+	async upsert(name: string, ...documents: VectorUpsertParams[]): Promise<VectorUpsertResult[]> {
+		if (!name?.trim()) {
+			throw new Error('Vector storage name is required');
+		}
+		if (documents.length === 0) {
+			throw new Error('At least one document is required');
+		}
+
+		const results: VectorUpsertResult[] = [];
+		const stmt = this.#db.prepare(`
+			INSERT INTO vector_storage (
+				project_path, name, id, key, embedding, document, metadata, created_at, updated_at
+			)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+			ON CONFLICT(project_path, name, key) 
+			DO UPDATE SET 
+				embedding = excluded.embedding,
+				document = excluded.document,
+				metadata = excluded.metadata,
+				updated_at = excluded.updated_at
+		`);
+
+		for (const doc of documents) {
+			if (!doc.key?.trim()) {
+				throw new Error('Each document must have a non-empty key');
+			}
+
+			// Generate or use provided embeddings
+			let embedding: number[];
+			if ('embeddings' in doc && doc.embeddings) {
+				if (!Array.isArray(doc.embeddings) || doc.embeddings.length === 0) {
+					throw new Error('Embeddings must be a non-empty array');
+				}
+				embedding = doc.embeddings;
+			} else if ('document' in doc && doc.document) {
+				if (!doc.document?.trim()) {
+					throw new Error('Document text must be non-empty');
+				}
+				embedding = simpleEmbedding(doc.document);
+			} else {
+				throw new Error('Each document must have either embeddings or document text');
+			}
+
+			const id = randomUUID();
+			const timestamp = now();
+			const embeddingJson = JSON.stringify(embedding);
+			const documentText = 'document' in doc ? doc.document : null;
+			const metadata = doc.metadata ? JSON.stringify(doc.metadata) : null;
+
+			stmt.run(
+				this.#projectPath,
+				name,
+				id,
+				doc.key,
+				embeddingJson,
+				documentText ?? null,
+				metadata ?? null,
+				timestamp,
+				timestamp
+			);
+
+			const row = this.#db
+				.prepare(
+					'SELECT id FROM vector_storage WHERE project_path = ? AND name = ? AND key = ?'
+				)
+				.get(this.#projectPath, name, doc.key) as { id: string } | undefined;
+
+			const actualId = row?.id ?? id;
+			results.push({ key: doc.key, id: actualId });
+		}
+
+		return results;
+	}
+
+	async get<T extends Record<string, unknown> = Record<string, unknown>>(
+		name: string,
+		key: string
+	): Promise<VectorResult<T>> {
+		if (!name?.trim() || !key?.trim()) {
+			throw new Error('Vector storage name and key are required');
+		}
+
+		const query = this.#db.query(`
+			SELECT id, key, embedding, document, metadata 
+			FROM vector_storage 
+			WHERE project_path = ? AND name = ? AND key = ?
+		`);
+
+		const row = query.get(this.#projectPath, name, key) as {
+			id: string;
+			key: string;
+			embedding: string;
+			document: string | null;
+			metadata: string | null;
+		} | null;
+
+		if (!row) {
+			return { exists: false } as VectorResultNotFound;
+		}
+
+		return {
+			exists: true,
+			data: {
+				id: row.id,
+				key: row.key,
+				embeddings: JSON.parse(row.embedding),
+				document: row.document || undefined,
+				metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+				similarity: 1.0, // Perfect match for direct get
+			} as VectorSearchResultWithDocument<T>,
+		};
+	}
+
+	async getMany<T extends Record<string, unknown> = Record<string, unknown>>(
+		name: string,
+		...keys: string[]
+	): Promise<Map<string, VectorSearchResultWithDocument<T>>> {
+		if (!name?.trim()) {
+			throw new Error('Vector storage name is required');
+		}
+		if (keys.length === 0) {
+			return new Map();
+		}
+
+		const results = await Promise.all(
+			keys.map(async (key) => {
+				const result = await this.get<T>(name, key);
+				return { key, result };
+			})
+		);
+
+		const map = new Map<string, VectorSearchResultWithDocument<T>>();
+		for (const { key, result } of results) {
+			if (result.exists) {
+				map.set(key, result.data);
+			}
+		}
+
+		return map;
+	}
+
+	async search<T extends Record<string, unknown> = Record<string, unknown>>(
+		name: string,
+		params: VectorSearchParams<T>
+	): Promise<VectorSearchResult<T>[]> {
+		if (!name?.trim()) {
+			throw new Error('Vector storage name is required');
+		}
+		if (!params.query?.trim()) {
+			throw new Error('Query is required');
+		}
+
+		// Generate query embedding
+		const queryEmbedding = simpleEmbedding(params.query);
+
+		// Fetch all vectors for this name
+		const query = this.#db.query(`
+			SELECT id, key, embedding, metadata 
+			FROM vector_storage 
+			WHERE project_path = ? AND name = ?
+		`);
+
+		const rows = query.all(this.#projectPath, name) as Array<{
+			id: string;
+			key: string;
+			embedding: string;
+			metadata: string | null;
+		}>;
+
+		// Calculate similarities
+		const results: Array<VectorSearchResult<T> & { similarity: number }> = [];
+
+		for (const row of rows) {
+			const embedding = JSON.parse(row.embedding);
+			const similarity = cosineSimilarity(queryEmbedding, embedding);
+
+			// Apply similarity threshold
+			if (params.similarity !== undefined && similarity < params.similarity) {
+				continue;
+			}
+
+			// Apply metadata filter
+			if (params.metadata) {
+				const rowMetadata = row.metadata ? JSON.parse(row.metadata) : {};
+				const matches = Object.entries(params.metadata).every(
+					([key, value]) => rowMetadata[key] === value
+				);
+				if (!matches) {
+					continue;
+				}
+			}
+
+			results.push({
+				id: row.id,
+				key: row.key,
+				metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+				similarity,
+			} as VectorSearchResult<T> & { similarity: number });
+		}
+
+		// Sort by similarity descending
+		results.sort((a, b) => b.similarity - a.similarity);
+
+		// Apply limit
+		const limit = params.limit || 10;
+		return results.slice(0, limit);
+	}
+
+	async delete(name: string, ...keys: string[]): Promise<number> {
+		if (!name?.trim()) {
+			throw new Error('Vector storage name is required');
+		}
+		if (keys.length === 0) {
+			return 0;
+		}
+
+		const placeholders = keys.map(() => '?').join(', ');
+		const stmt = this.#db.prepare(`
+			DELETE FROM vector_storage 
+			WHERE project_path = ? AND name = ? AND key IN (${placeholders})
+		`);
+
+		const result = stmt.run(this.#projectPath, name, ...keys);
+		return result.changes;
+	}
+
+	async exists(name: string): Promise<boolean> {
+		if (!name?.trim()) {
+			throw new Error('Vector storage name is required');
+		}
+
+		const query = this.#db.query(`
+			SELECT COUNT(*) as count 
+			FROM vector_storage 
+			WHERE project_path = ? AND name = ?
+		`);
+
+		const { count } = query.get(this.#projectPath, name) as { count: number };
+		return count > 0;
+	}
+}

package/src/services/session/composite.ts

@@ -0,0 +1,33 @@
+import {
+	type SessionCompleteEvent,
+	type SessionEventProvider,
+	type SessionStartEvent,
+} from '@agentuity/core';
+
+/**
+ * A composite implementation of SessionEventProvider that forwards events to multiple providers
+ */
+export class CompositeSessionEventProvider implements SessionEventProvider {
+	private providers: SessionEventProvider[];
+
+	constructor(...providers: SessionEventProvider[]) {
+		this.providers = providers;
+	}
+	/**
+	 * called when the session starts
+	 *
+	 * @param event SessionStartEvent
+	 */
+	async start(event: SessionStartEvent): Promise<void> {
+		await Promise.all(this.providers.map((p) => p.start(event)));
+	}
+
+	/**
+	 * called when the session completes
+	 *
+	 * @param event SessionCompleteEvent
+	 */
+	async complete(event: SessionCompleteEvent): Promise<void> {
+		await Promise.all(this.providers.map((p) => p.complete(event)));
+	}
+}

package/src/services/session/http.ts

@@ -0,0 +1,64 @@
+import { APIClient, APIResponseSchemaNoData } from '@agentuity/server';
+import {
+	type SessionEventProvider,
+	type SessionStartEvent,
+	SessionStartEventDelayedSchema,
+	SessionCompleteEventDelayedSchema,
+	type SessionCompleteEvent,
+	type Logger,
+} from '@agentuity/core';
+
+/**
+ * An implementation of the SessionEventProvider which uses HTTP for delivery
+ */
+export class HTTPSessionEventProvider implements SessionEventProvider {
+	private apiClient: APIClient;
+	private logger: Logger;
+
+	constructor(client: APIClient, logger: Logger) {
+		this.apiClient = client;
+		this.logger = logger;
+	}
+
+	/**
+	 * called when the session starts
+	 *
+	 * @param event SessionStartEvent
+	 */
+	async start(event: SessionStartEvent): Promise<void> {
+		this.logger.debug('Sending session start event: %s', event.id);
+		const resp = await this.apiClient.request(
+			'POST',
+			'/session/2025-03-17',
+			APIResponseSchemaNoData(),
+			{ ...event, timestamp: Date.now() },
+			SessionStartEventDelayedSchema
+		);
+		if (resp.success) {
+			this.logger.debug('Session start event sent successfully: %s', event.id);
+			return;
+		}
+		throw new Error(resp.message);
+	}
+
+	/**
+	 * called when the session completes
+	 *
+	 * @param event SessionCompleteEvent
+	 */
+	async complete(event: SessionCompleteEvent): Promise<void> {
+		this.logger.debug('Sending session complete event: %s', event.id);
+		const resp = await this.apiClient.request(
+			'PUT',
+			'/session/2025-03-17',
+			APIResponseSchemaNoData(),
+			{ ...event, timestamp: Date.now() },
+			SessionCompleteEventDelayedSchema
+		);
+		if (resp.success) {
+			this.logger.debug('Session complete event sent successfully: %s', event.id);
+			return;
+		}
+		throw new Error(resp.message);
+	}
+}

package/src/services/session/index.ts

@@ -0,0 +1,4 @@
+export * from './composite';
+export * from './http';
+export * from './json';
+export * from './local';

package/src/services/session/json.ts

@@ -0,0 +1,42 @@
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import {
+	type SessionEventProvider,
+	type SessionStartEvent,
+	type SessionCompleteEvent,
+} from '@agentuity/core';
+
+/**
+ * An implementation of the SessionEventProvider which uses JSON logs for delivery
+ */
+export class JSONSessionEventProvider implements SessionEventProvider {
+	private directory: string;
+
+	constructor(directory: string) {
+		this.directory = directory;
+	}
+	private makeFilename(type: 'start' | 'complete'): string {
+		return join(this.directory, `session-${type}.${Date.now()}${randomUUID()}.json`);
+	}
+	/**
+	 * called when the session starts
+	 *
+	 * @param event SessionStartEvent
+	 */
+	async start(event: SessionStartEvent): Promise<void> {
+		const filename = this.makeFilename('start');
+		const payload = JSON.stringify({ ...event, timestamp: new Date() }) + '\n';
+		await Bun.file(filename).write(payload);
+	}
+
+	/**
+	 * called when the session completes
+	 *
+	 * @param event SessionCompleteEvent
+	 */
+	async complete(event: SessionCompleteEvent): Promise<void> {
+		const filename = this.makeFilename('complete');
+		const payload = JSON.stringify({ ...event, timestamp: new Date() }) + '\n';
+		await Bun.file(filename).write(payload);
+	}
+}