@agentuity/local 3.0.0-alpha.0

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@agentuity/local",
+	"version": "3.0.0-alpha.0",
+	"license": "Apache-2.0",
+	"author": "Agentuity employees and contributors",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": [
+		"src",
+		"dist"
+	],
+	"scripts": {
+		"clean": "rm -rf dist tsconfig.tsbuildinfo",
+		"build": "bunx tsc --build",
+		"typecheck": "bunx tsc --noEmit",
+		"prepublishOnly": "bun run clean && bun run build"
+	},
+	"dependencies": {
+		"@agentuity/core": "3.0.0-alpha.0"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"bun-types": "latest",
+		"typescript": "^5.9.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": false,
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/agentuity/sdk.git",
+		"directory": "packages/local"
+	}
+}

package/src/bun/db.ts

@@ -0,0 +1,353 @@
+import { Database } from 'bun:sqlite';
+import { mkdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+let dbInstance: Database | null = null;
+
+export function getLocalDB(): Database {
+	if (dbInstance) {
+		return dbInstance;
+	}
+
+	const configDir = join(homedir(), '.config', 'agentuity');
+
+	if (!existsSync(configDir)) {
+		mkdirSync(configDir, { recursive: true });
+	}
+
+	const dbPath = join(configDir, 'local.db');
+	dbInstance = new Database(dbPath);
+
+	initializeTables(dbInstance);
+	cleanupOrphanedProjects(dbInstance);
+
+	return dbInstance;
+}
+
+function initializeTables(db: Database): void {
+	// KeyValue Storage table
+	db.run(`
+		CREATE TABLE IF NOT EXISTS kv_storage (
+			project_path TEXT NOT NULL,
+			name TEXT NOT NULL,
+			key TEXT NOT NULL,
+			value BLOB NOT NULL,
+			content_type TEXT NOT NULL DEFAULT 'application/octet-stream',
+			expires_at INTEGER,
+			created_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL,
+			PRIMARY KEY (project_path, name, key)
+		)
+	`);
+
+	db.run(`
+		CREATE INDEX IF NOT EXISTS idx_kv_expires 
+		ON kv_storage(expires_at) 
+		WHERE expires_at IS NOT NULL
+	`);
+
+	// Stream Storage table
+	db.run(`
+		CREATE TABLE IF NOT EXISTS stream_storage (
+			project_path TEXT NOT NULL,
+			id TEXT PRIMARY KEY,
+			name TEXT NOT NULL,
+			metadata TEXT,
+			content_type TEXT NOT NULL DEFAULT 'application/octet-stream',
+			data BLOB,
+			size_bytes INTEGER NOT NULL DEFAULT 0,
+			created_at INTEGER NOT NULL
+		)
+	`);
+
+	db.run(`
+		CREATE INDEX IF NOT EXISTS idx_stream_name 
+		ON stream_storage(project_path, name)
+	`);
+
+	db.run(`
+		CREATE INDEX IF NOT EXISTS idx_stream_metadata 
+		ON stream_storage(metadata)
+	`);
+
+	// Vector Storage table
+	db.run(`
+		CREATE TABLE IF NOT EXISTS vector_storage (
+			project_path TEXT NOT NULL,
+			name TEXT NOT NULL,
+			id TEXT PRIMARY KEY,
+			key TEXT NOT NULL,
+			embedding TEXT NOT NULL,
+			document TEXT,
+			metadata TEXT,
+			created_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL,
+			UNIQUE (project_path, name, key)
+		)
+	`);
+
+	db.run(`
+		CREATE INDEX IF NOT EXISTS idx_vector_lookup 
+		ON vector_storage(project_path, name, key)
+	`);
+
+	db.run(`
+		CREATE INDEX IF NOT EXISTS idx_vector_name 
+		ON vector_storage(project_path, name)
+	`);
+
+	// Task Storage table
+	db.run(`
+		CREATE TABLE IF NOT EXISTS task_storage (
+			project_path TEXT NOT NULL,
+			id TEXT NOT NULL,
+			title TEXT NOT NULL,
+			description TEXT,
+			metadata TEXT,
+			priority TEXT NOT NULL DEFAULT 'none',
+			parent_id TEXT,
+			type TEXT NOT NULL,
+			status TEXT NOT NULL DEFAULT 'open',
+			open_date TEXT,
+			in_progress_date TEXT,
+			closed_date TEXT,
+			created_id TEXT NOT NULL,
+			assigned_id TEXT,
+			closed_id TEXT,
+			deleted INTEGER NOT NULL DEFAULT 0,
+			created_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL,
+			PRIMARY KEY (project_path, id)
+		)
+	`);
+
+	// Migration: add deleted column for existing databases
+	try {
+		db.run('ALTER TABLE task_storage ADD COLUMN deleted INTEGER NOT NULL DEFAULT 0');
+	} catch {
+		// Column already exists
+	}
+
+	// Task Changelog table
+	db.run(`
+		CREATE TABLE IF NOT EXISTS task_changelog_storage (
+			project_path TEXT NOT NULL,
+			id TEXT NOT NULL,
+			task_id TEXT NOT NULL,
+			field TEXT NOT NULL,
+			old_value TEXT,
+			new_value TEXT,
+			created_at INTEGER NOT NULL,
+			PRIMARY KEY (project_path, id)
+		)
+	`);
+
+	db.run(`
+		CREATE INDEX IF NOT EXISTS idx_task_changelog_lookup
+		ON task_changelog_storage(project_path, task_id)
+	`);
+
+	// Task Comment table
+	db.run(`
+		CREATE TABLE IF NOT EXISTS task_comment_storage (
+			project_path TEXT NOT NULL,
+			id TEXT NOT NULL,
+			task_id TEXT NOT NULL,
+			user_id TEXT NOT NULL,
+			body TEXT NOT NULL,
+			created_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL,
+			PRIMARY KEY (project_path, id)
+		)
+	`);
+
+	db.run(`
+		CREATE INDEX IF NOT EXISTS idx_task_comment_lookup
+		ON task_comment_storage(project_path, task_id)
+	`);
+
+	// Task Tag table
+	db.run(`
+		CREATE TABLE IF NOT EXISTS task_tag_storage (
+			project_path TEXT NOT NULL,
+			id TEXT NOT NULL,
+			name TEXT NOT NULL,
+			color TEXT,
+			created_at INTEGER NOT NULL,
+			PRIMARY KEY (project_path, id)
+		)
+	`);
+
+	// Task-Tag association table
+	db.run(`
+		CREATE TABLE IF NOT EXISTS task_tag_association_storage (
+			project_path TEXT NOT NULL,
+			task_id TEXT NOT NULL,
+			tag_id TEXT NOT NULL,
+			PRIMARY KEY (project_path, task_id, tag_id)
+		)
+	`);
+
+	db.run(`
+		CREATE INDEX IF NOT EXISTS idx_task_tag_assoc_task
+		ON task_tag_association_storage(project_path, task_id)
+	`);
+
+	db.run(`
+		CREATE INDEX IF NOT EXISTS idx_task_tag_assoc_tag
+		ON task_tag_association_storage(project_path, tag_id)
+	`);
+
+	// Task User table
+	db.run(`
+		CREATE TABLE IF NOT EXISTS task_user_storage (
+			project_path TEXT NOT NULL,
+			id TEXT NOT NULL,
+			name TEXT NOT NULL,
+			type TEXT NOT NULL DEFAULT 'human',
+			created_at INTEGER NOT NULL,
+			PRIMARY KEY (project_path, id)
+		)
+	`);
+
+	// Task Project table
+	db.run(`
+		CREATE TABLE IF NOT EXISTS task_project_storage (
+			project_path TEXT NOT NULL,
+			id TEXT NOT NULL,
+			name TEXT NOT NULL,
+			created_at INTEGER NOT NULL,
+			PRIMARY KEY (project_path, id)
+		)
+	`);
+}
+
+function cleanupOrphanedProjects(db: Database): void {
+	// Get the current project path to exclude from cleanup
+	const currentProjectPath = process.cwd();
+
+	// Query all tables for unique project paths
+	const kvPaths = db.query('SELECT DISTINCT project_path FROM kv_storage').all() as Array<{
+		project_path: string;
+	}>;
+	const streamPaths = db.query('SELECT DISTINCT project_path FROM stream_storage').all() as Array<{
+		project_path: string;
+	}>;
+	const vectorPaths = db.query('SELECT DISTINCT project_path FROM vector_storage').all() as Array<{
+		project_path: string;
+	}>;
+	const taskPaths = db.query('SELECT DISTINCT project_path FROM task_storage').all() as Array<{
+		project_path: string;
+	}>;
+	const taskChangelogPaths = db
+		.query('SELECT DISTINCT project_path FROM task_changelog_storage')
+		.all() as Array<{
+		project_path: string;
+	}>;
+	const taskCommentPaths = db
+		.query('SELECT DISTINCT project_path FROM task_comment_storage')
+		.all() as Array<{
+		project_path: string;
+	}>;
+	const taskTagPaths = db
+		.query('SELECT DISTINCT project_path FROM task_tag_storage')
+		.all() as Array<{
+		project_path: string;
+	}>;
+	const taskTagAssocPaths = db
+		.query('SELECT DISTINCT project_path FROM task_tag_association_storage')
+		.all() as Array<{
+		project_path: string;
+	}>;
+	const taskUserPaths = db
+		.query('SELECT DISTINCT project_path FROM task_user_storage')
+		.all() as Array<{
+		project_path: string;
+	}>;
+	const taskProjectPaths = db
+		.query('SELECT DISTINCT project_path FROM task_project_storage')
+		.all() as Array<{
+		project_path: string;
+	}>;
+
+	// Combine and deduplicate all project paths
+	const allPaths = new Set<string>();
+	[
+		...kvPaths,
+		...streamPaths,
+		...vectorPaths,
+		...taskPaths,
+		...taskChangelogPaths,
+		...taskCommentPaths,
+		...taskTagPaths,
+		...taskTagAssocPaths,
+		...taskUserPaths,
+		...taskProjectPaths,
+	].forEach((row) => {
+		allPaths.add(row.project_path);
+	});
+
+	// Check which paths no longer exist and are not the current project
+	const pathsToDelete: string[] = [];
+	for (const path of allPaths) {
+		if (path !== currentProjectPath && !existsSync(path)) {
+			pathsToDelete.push(path);
+		}
+	}
+
+	// Delete data for removed projects
+	if (pathsToDelete.length > 0) {
+		const placeholders = pathsToDelete.map(() => '?').join(', ');
+
+		// Delete from all tables
+		const deleteKv = db.prepare(`DELETE FROM kv_storage WHERE project_path IN (${placeholders})`);
+		const deleteStream = db.prepare(
+			`DELETE FROM stream_storage WHERE project_path IN (${placeholders})`
+		);
+		const deleteVector = db.prepare(
+			`DELETE FROM vector_storage WHERE project_path IN (${placeholders})`
+		);
+		const deleteTasks = db.prepare(
+			`DELETE FROM task_storage WHERE project_path IN (${placeholders})`
+		);
+		const deleteTaskChangelog = db.prepare(
+			`DELETE FROM task_changelog_storage WHERE project_path IN (${placeholders})`
+		);
+		const deleteTaskComments = db.prepare(
+			`DELETE FROM task_comment_storage WHERE project_path IN (${placeholders})`
+		);
+		const deleteTaskTags = db.prepare(
+			`DELETE FROM task_tag_storage WHERE project_path IN (${placeholders})`
+		);
+		const deleteTaskTagAssoc = db.prepare(
+			`DELETE FROM task_tag_association_storage WHERE project_path IN (${placeholders})`
+		);
+		const deleteTaskUsers = db.prepare(
+			`DELETE FROM task_user_storage WHERE project_path IN (${placeholders})`
+		);
+		const deleteTaskProjects = db.prepare(
+			`DELETE FROM task_project_storage WHERE project_path IN (${placeholders})`
+		);
+
+		deleteKv.run(...pathsToDelete);
+		deleteStream.run(...pathsToDelete);
+		deleteVector.run(...pathsToDelete);
+		deleteTasks.run(...pathsToDelete);
+		deleteTaskChangelog.run(...pathsToDelete);
+		deleteTaskComments.run(...pathsToDelete);
+		deleteTaskTags.run(...pathsToDelete);
+		deleteTaskTagAssoc.run(...pathsToDelete);
+		deleteTaskUsers.run(...pathsToDelete);
+		deleteTaskProjects.run(...pathsToDelete);
+
+		console.log(`[LocalDB] Cleaned up data for ${pathsToDelete.length} orphaned project(s)`);
+	}
+}
+
+export function closeLocalDB(): void {
+	if (dbInstance) {
+		dbInstance.close();
+		dbInstance = null;
+	}
+}

package/src/bun/email.ts

@@ -0,0 +1,91 @@
+import {
+	StructuredError,
+	type EmailService,
+	type EmailAddress,
+	type EmailDestination,
+	type EmailConnectionConfig,
+	type EmailInbound,
+	type EmailOutbound,
+	type EmailSendParams,
+	type EmailActivityParams,
+	type EmailActivityResult,
+} from '@agentuity/core';
+
+const ERROR_MESSAGE =
+	'Email service is not available in local development mode. Deploy to Agentuity Cloud to use email.';
+
+const LocalEmailNotAvailableError = StructuredError('LocalEmailNotAvailableError', ERROR_MESSAGE);
+
+/**
+ * Local development stub for the email service.
+ * All methods throw a descriptive error directing users to deploy to Agentuity Cloud.
+ */
+export class LocalEmailStorage implements EmailService {
+	async createAddress(_localPart: string): Promise<EmailAddress> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async listAddresses(): Promise<EmailAddress[]> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async getAddress(_id: string): Promise<EmailAddress | null> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async getConnectionConfig(_id: string): Promise<EmailConnectionConfig | null> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async deleteAddress(_id: string): Promise<void> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async createDestination(
+		_addressId: string,
+		_type: string,
+		_config: Record<string, unknown>
+	): Promise<EmailDestination> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async listDestinations(_addressId: string): Promise<EmailDestination[]> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async deleteDestination(_addressId: string, _destinationId: string): Promise<void> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async send(_params: EmailSendParams): Promise<EmailOutbound> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async listInbound(_addressId?: string): Promise<EmailInbound[]> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async getInbound(_id: string): Promise<EmailInbound | null> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async deleteInbound(_id: string): Promise<void> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async listOutbound(_addressId?: string): Promise<EmailOutbound[]> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async getOutbound(_id: string): Promise<EmailOutbound | null> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async deleteOutbound(_id: string): Promise<void> {
+		throw new LocalEmailNotAvailableError();
+	}
+
+	async getActivity(_params?: EmailActivityParams): Promise<EmailActivityResult> {
+		throw new LocalEmailNotAvailableError();
+	}
+}

package/src/bun/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Bun-specific local storage implementations
+ *
+ * Uses Bun's built-in SQLite for local development storage.
+ */
+
+export { getLocalDB, closeLocalDB } from './db';
+export { LocalKeyValueStorage } from './kv';
+export { LocalStreamStorage } from './stream';
+export { LocalVectorStorage } from './vector';
+export { LocalQueueStorage } from './queue';
+export { LocalEmailStorage } from './email';
+export { LocalTaskStorage } from './task';
+export { now, normalizeProjectPath } from './util';

package/src/bun/kv.ts

@@ -0,0 +1,174 @@
+import { Database } from 'bun:sqlite';
+import type {
+	KeyValueStorage,
+	DataResult,
+	DataResultNotFound,
+	KeyValueStorageSetParams,
+	KeyValueStats,
+	KeyValueItemWithMetadata,
+	CreateNamespaceParams,
+	GetAllStatsParams,
+	KeyValueStatsPaginated,
+} from '@agentuity/core';
+import { now } from './util';
+
+export class LocalKeyValueStorage implements KeyValueStorage {
+	#db: Database;
+	#projectPath: string;
+
+	constructor(db: Database, projectPath: string) {
+		this.#db = db;
+		this.#projectPath = projectPath;
+	}
+
+	async get<T>(name: string, key: string): Promise<DataResult<T>> {
+		const query = this.#db.query(`
+			SELECT value, content_type, expires_at 
+			FROM kv_storage 
+			WHERE project_path = ? AND name = ? AND key = ?
+		`);
+
+		const row = query.get(this.#projectPath, name, key) as {
+			value: Buffer;
+			content_type: string;
+			expires_at: number | null;
+		} | null;
+
+		if (!row) {
+			return { exists: false } as DataResultNotFound;
+		}
+
+		// Check expiration
+		if (row.expires_at && row.expires_at < now()) {
+			// Delete expired row
+			await this.delete(name, key);
+			return { exists: false } as DataResultNotFound;
+		}
+
+		// Deserialize based on content type
+		let data: T;
+		if (row.content_type === 'application/json') {
+			try {
+				const text = row.value.toString('utf-8');
+				data = JSON.parse(text);
+			} catch {
+				// If JSON parse fails, return the raw buffer as Uint8Array
+				data = new Uint8Array(row.value) as T;
+			}
+		} else if (row.content_type.startsWith('text/')) {
+			data = row.value.toString('utf-8') as T;
+		} else {
+			data = new Uint8Array(row.value) as T;
+		}
+
+		return {
+			data,
+			contentType: row.content_type,
+			exists: true,
+			// Include expiresAt if set (convert from Unix timestamp to ISO string)
+			...(row.expires_at && { expiresAt: new Date(row.expires_at).toISOString() }),
+		};
+	}
+
+	async set<T = unknown>(
+		name: string,
+		key: string,
+		value: T,
+		params?: KeyValueStorageSetParams
+	): Promise<void> {
+		// Serialize value
+		let buffer: Buffer;
+		let contentType = params?.contentType || 'application/octet-stream';
+
+		if (typeof value === 'string') {
+			buffer = Buffer.from(value, 'utf-8');
+			if (!params?.contentType) {
+				contentType = 'text/plain';
+			}
+		} else if (value instanceof Uint8Array) {
+			buffer = Buffer.from(value);
+		} else if (value instanceof ArrayBuffer) {
+			buffer = Buffer.from(new Uint8Array(value));
+		} else if (
+			typeof value === 'number' ||
+			typeof value === 'boolean' ||
+			typeof value === 'object'
+		) {
+			// Use JSON for numbers, booleans, and objects to preserve type on round-trip
+			buffer = Buffer.from(JSON.stringify(value), 'utf-8');
+			contentType = 'application/json';
+		} else {
+			// Fallback for other types
+			buffer = Buffer.from(String(value), 'utf-8');
+		}
+
+		// Calculate expiration
+		// TTL handling: null or 0 = no expiration, positive = TTL in seconds
+		// undefined = use default (7 days for consistency with cloud namespace default)
+		let expiresAt: number | null = null;
+		if (params?.ttl === undefined) {
+			// Default to 7 days (matching cloud namespace default behavior)
+			expiresAt = now() + 7 * 24 * 60 * 60 * 1000;
+		} else if (params.ttl !== null && params.ttl > 0) {
+			expiresAt = now() + params.ttl * 1000;
+		}
+		// else: ttl is null or 0, so expiresAt stays null (no expiration)
+		const timestamp = now();
+
+		// UPSERT
+		const stmt = this.#db.prepare(`
+			INSERT INTO kv_storage (project_path, name, key, value, content_type, expires_at, created_at, updated_at)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+			ON CONFLICT(project_path, name, key) 
+			DO UPDATE SET 
+				value = excluded.value,
+				content_type = excluded.content_type,
+				expires_at = excluded.expires_at,
+				updated_at = excluded.updated_at
+		`);
+
+		stmt.run(this.#projectPath, name, key, buffer, contentType, expiresAt, timestamp, timestamp);
+	}
+
+	async delete(name: string, key: string): Promise<void> {
+		const stmt = this.#db.prepare(`
+			DELETE FROM kv_storage 
+			WHERE project_path = ? AND name = ? AND key = ?
+		`);
+
+		stmt.run(this.#projectPath, name, key);
+	}
+
+	async getStats(_name: string): Promise<KeyValueStats> {
+		throw new Error('getStats not implemented for local storage');
+	}
+
+	async getAllStats(
+		_params?: GetAllStatsParams
+	): Promise<Record<string, KeyValueStats> | KeyValueStatsPaginated> {
+		throw new Error('getAllStats not implemented for local storage');
+	}
+
+	async getNamespaces(): Promise<string[]> {
+		throw new Error('getNamespaces not implemented for local storage');
+	}
+
+	async search<T = unknown>(
+		_name: string,
+		_keyword: string
+	): Promise<Record<string, KeyValueItemWithMetadata<T>>> {
+		throw new Error('search not implemented for local storage');
+	}
+
+	async getKeys(_name: string): Promise<string[]> {
+		throw new Error('getKeys not implemented for local storage');
+	}
+
+	async deleteNamespace(_name: string): Promise<void> {
+		throw new Error('deleteNamespace not implemented for local storage');
+	}
+
+	async createNamespace(_name: string, _params?: CreateNamespaceParams): Promise<void> {
+		throw new Error('createNamespace not implemented for local storage');
+	}
+}