@agentuity/runtime 0.0.6

package/src/_context.ts

@@ -0,0 +1,86 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Tracer } from '@opentelemetry/api';
+import type { KeyValueStorage, ObjectStorage, StreamStorage, VectorStorage } from '@agentuity/core';
+import type { AgentContext, AgentName } from './agent';
+import type { Logger } from './logger';
+import WaitUntilHandler from './_waituntil';
+import { registerServices } from './_services';
+
+export interface RequestAgentContextArgs<TAgentMap, TAgent> {
+	sessionId: string;
+	agent: TAgentMap;
+	current: TAgent;
+	agentName: AgentName;
+	logger: Logger;
+	tracer: Tracer;
+	setHeader: (k: string, v: string) => void;
+}
+
+export class RequestAgentContext<TAgentMap, TAgent> implements AgentContext {
+	agent: TAgentMap;
+	current: TAgent;
+	agentName: AgentName;
+	logger: Logger;
+	sessionId: string;
+	tracer: Tracer;
+	kv!: KeyValueStorage;
+	objectstore!: ObjectStorage;
+	stream!: StreamStorage;
+	vector!: VectorStorage;
+	private waituntilHandler: WaitUntilHandler;
+
+	constructor(args: RequestAgentContextArgs<TAgentMap, TAgent>) {
+		this.agent = args.agent;
+		this.current = args.current;
+		this.agentName = args.agentName;
+		this.logger = args.logger;
+		this.sessionId = args.sessionId;
+		this.tracer = args.tracer;
+		this.waituntilHandler = new WaitUntilHandler(args.setHeader, args.tracer);
+		registerServices(this);
+	}
+
+	waitUntil(callback: Promise<void> | (() => void | Promise<void>)): void {
+		this.waituntilHandler.waitUntil(callback);
+	}
+
+	waitUntilAll(): Promise<void> {
+		return this.waituntilHandler.waitUntilAll(this.logger, this.sessionId);
+	}
+}
+
+const asyncLocalStorage = new AsyncLocalStorage<AgentContext>();
+
+export const inAgentContext = (): boolean => {
+	const context = asyncLocalStorage.getStore();
+	return !!context;
+};
+
+export const getAgentContext = (): AgentContext => {
+	const context = asyncLocalStorage.getStore();
+	if (!context) {
+		throw new Error('AgentContext is not available');
+	}
+	return context;
+};
+
+export const runInAgentContext = <TAgentMap, TAgent>(
+	ctxObject: Record<string, unknown>,
+	args: RequestAgentContextArgs<TAgentMap, TAgent>,
+	next: () => Promise<void>
+) => {
+	const ctx = new RequestAgentContext(args);
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const _ctx = ctx as any;
+	Object.getOwnPropertyNames(ctx).forEach((k) => {
+		ctxObject[k] = _ctx[k];
+	});
+	for (const k of ['waitUntil']) {
+		ctxObject[k] = _ctx[k];
+	}
+	return asyncLocalStorage.run(ctx, async () => {
+		return next().then(() => {
+			setImmediate(() => ctx.waitUntilAll()); // TODO: move until session
+		});
+	});
+};

package/src/_idle.ts

@@ -0,0 +1,26 @@
+import { getServer } from './_server';
+import { hasWaitUntilPending } from './_waituntil';
+
+/**
+ * returns true if the server is idle (no pending requests, websockets, or waitUntil tasks)
+ *
+ * @returns true if idle
+ */
+export function isIdle() {
+	if (hasWaitUntilPending()) {
+		return false;
+	}
+
+	const _server = getServer();
+	if (_server) {
+		// we have to check >1 since the idle request itself will show up as a pending request
+		if (_server.pendingRequests > 1) {
+			return false;
+		}
+		if (_server.pendingWebSockets > 0) {
+			return false;
+		}
+	}
+
+	return true;
+}

package/src/_server.ts

@@ -0,0 +1,279 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import {
+	context,
+	SpanKind,
+	SpanStatusCode,
+	type Context,
+	type Tracer,
+	trace,
+	type Attributes,
+} from '@opentelemetry/api';
+import type { Span } from '@opentelemetry/sdk-trace-base';
+import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { ServiceException } from '@agentuity/core';
+import { createMiddleware } from 'hono/factory';
+import { Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { BunWebSocketData } from 'hono/bun';
+import { websocket } from 'hono/bun';
+import type { AppConfig, Env } from './app';
+import { extractTraceContextFromRequest } from './otel/http';
+import { register } from './otel/config';
+import type { Logger } from './logger';
+import { isIdle } from './_idle';
+import * as runtimeConfig from './_config';
+import { inAgentContext, getAgentContext } from './_context';
+
+let globalServerInstance: Bun.Server<BunWebSocketData> | null = null;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let globalAppInstance: Hono<any> | null = null;
+
+let globalLogger: Logger | null = null;
+let globalTracer: Tracer | null = null;
+
+export function getServer() {
+	return globalServerInstance;
+}
+
+export function getApp() {
+	return globalAppInstance;
+}
+
+export function getLogger() {
+	return globalLogger;
+}
+
+export function getTracer() {
+	return globalTracer;
+}
+
+function isDevelopment(): boolean {
+	const devmode = runtimeConfig.isDevMode();
+	const environment = runtimeConfig.getEnvironment();
+	return devmode || environment === 'development';
+}
+
+function getPort(): number {
+	return Number.parseInt(process.env.AGENTUITY_PORT ?? process.env.PORT ?? '3000') || 3000;
+}
+
+const spanProcessors: SpanProcessor[] = [];
+
+/**
+ * add a custom span processor that will be added to the otel configuration. this method must be
+ * called before the createApp is called for it to be added.
+ */
+export function addSpanProcessor(processor: SpanProcessor) {
+	spanProcessors.push(processor);
+}
+
+function registerAgentuitySpanProcessor() {
+	const orgId = runtimeConfig.getOrganizationId();
+	const projectId = runtimeConfig.getProjectId();
+	const deploymentId = runtimeConfig.getDeploymentId();
+	const devmode = runtimeConfig.isDevMode();
+	const environment = runtimeConfig.getEnvironment();
+
+	class RegisterAgentSpanProcessor implements SpanProcessor {
+		onStart(span: Span, _context: Context) {
+			const attrs: Attributes = {
+				'@agentuity/orgId': orgId,
+				'@agentuity/projectId': projectId,
+				'@agentuity/deploymentId': deploymentId,
+				'@agentuity/devmode': devmode,
+				'@agentuity/environment': environment,
+			};
+			if (inAgentContext()) {
+				const agentCtx = getAgentContext();
+				if (agentCtx.current?.metadata) {
+					attrs['@agentuity/agentId'] = agentCtx.current.metadata.id;
+					attrs['@agentuity/agentName'] = agentCtx.current.metadata.name;
+				}
+			}
+			span.setAttributes(attrs);
+		}
+
+		onEnd(_span: Span) {
+			/* */
+		}
+
+		forceFlush() {
+			return Promise.resolve();
+		}
+
+		shutdown() {
+			return Promise.resolve();
+		}
+	}
+	addSpanProcessor(new RegisterAgentSpanProcessor());
+}
+
+export const createServer = <E extends Env>(app: Hono<E>, _config?: AppConfig) => {
+	if (globalServerInstance) {
+		return globalServerInstance;
+	}
+
+	registerAgentuitySpanProcessor();
+
+	const server = Bun.serve({
+		hostname: '127.0.0.1',
+		development: isDevelopment(),
+		fetch: app.fetch,
+		idleTimeout: 0,
+		port: getPort(),
+		websocket,
+	});
+
+	const otel = register({ processors: spanProcessors });
+
+	globalAppInstance = app;
+	globalServerInstance = server;
+	globalLogger = otel.logger;
+	globalTracer = otel.tracer;
+
+	let isShutdown = false;
+
+	app.onError((error, _c) => {
+		if (error instanceof HTTPException) {
+			otel.logger.error('HTTP Error: %s (%d)', error.cause, error.status);
+			return error.getResponse();
+		}
+		if (
+			error instanceof ServiceException ||
+			('statusCode' in error && typeof error.statusCode === 'number')
+		) {
+			otel.logger.error('Service Exception: %s (%d)', error.message, error.statusCode);
+			return new Response(error.message, {
+				status: (error.statusCode as number) ?? 500,
+			});
+		}
+		return new Response('Internal Server Error', { status: 500 });
+	});
+
+	app.use(async (c, next) => {
+		c.set('logger', otel.logger);
+		c.set('tracer', otel.tracer);
+		c.set('meter', otel.meter);
+		const skipLogging = c.req.path.startsWith('/_agentuity/');
+		const started = performance.now();
+		if (!skipLogging) {
+			otel.logger.debug('%s %s started', c.req.method, c.req.path);
+		}
+		await next();
+		if (!skipLogging) {
+			otel.logger.debug(
+				'%s %s completed (%d) in %sms',
+				c.req.method,
+				c.req.path,
+				c.res.status,
+				Number(performance.now() - started).toFixed(2)
+			);
+		}
+	});
+
+	app.route('/_agentuity', createAgentuityAPIs());
+
+	// Attach services to context for API routes
+	app.use('/api/*', async (c, next) => {
+		const { registerServices } = await import('./_services');
+		registerServices(c);
+		await next();
+	});
+
+	app.use('/api/*', otelMiddleware);
+	app.use('/agent/*', otelMiddleware);
+
+	const shutdown = async () => {
+		if (isShutdown) {
+			return;
+		}
+		otel.logger.info('shutdown started');
+		isShutdown = true;
+		// Force exit after timeout if cleanup hangs
+		setTimeout(() => process.exit(1), 30_000).unref();
+		await server.stop();
+		await otel.shutdown();
+		otel.logger.info('shutdown completed');
+	};
+
+	process.on('beforeExit', async () => await shutdown());
+	process.on('exit', async () => await shutdown());
+	process.once('SIGINT', async () => {
+		await shutdown();
+		process.exit(0);
+	});
+	process.once('SIGTERM', async () => {
+		await shutdown();
+		process.exit(0);
+	});
+	process.once('uncaughtException', async (err) => {
+		otel.logger.error('An uncaught exception was received: %s', err);
+		await shutdown();
+		process.exit(1);
+	});
+	process.once('unhandledRejection', async (reason) => {
+		otel.logger.error('An unhandled promise rejection was received: %s', reason);
+		await shutdown();
+		process.exit(1);
+	});
+
+	return server;
+};
+
+const createAgentuityAPIs = () => {
+	const router = new Hono<Env>();
+	router.get('idle', (c) => {
+		if (isIdle()) {
+			return new Response('OK', { status: 200 });
+		}
+		return new Response('NO', { status: 200 });
+	});
+	return router;
+};
+
+const otelMiddleware = createMiddleware<Env>(async (c, next) => {
+	// Extract trace context from headers
+	const extractedContext = extractTraceContextFromRequest(c.req.raw);
+
+	const method = c.req.method;
+	const url = new URL(c.req.url);
+
+	// Execute the request handler within the extracted context
+	await context.with(extractedContext, async (): Promise<void> => {
+		// Create a span for this incoming request
+		await trace.getTracer('http-server').startActiveSpan(
+			`HTTP ${method}`,
+			{
+				kind: SpanKind.SERVER,
+				attributes: {
+					'http.method': method,
+					'http.host': url.host,
+					'http.user_agent': c.req.header('user-agent') || '',
+					'http.path': url.pathname,
+				},
+			},
+			async (span): Promise<void> => {
+				try {
+					await next();
+					span.setStatus({
+						code: SpanStatusCode.OK,
+					});
+				} catch (ex) {
+					if (ex instanceof Error) {
+						span.recordException(ex);
+					}
+					const message = (ex as Error).message ?? String(ex);
+					span.setStatus({
+						code: SpanStatusCode.ERROR,
+						message,
+					});
+					c.var.logger.error('ERROR: %s', message);
+					throw ex;
+				} finally {
+					span.end();
+				}
+			}
+		);
+	});
+});

package/src/_services.ts

@@ -0,0 +1,164 @@
+import { context, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
+import {
+	KeyValueStorageService,
+	ObjectStorageService,
+	StreamStorageService,
+	VectorStorageService,
+	type ListStreamsResponse,
+	type VectorUpsertResult,
+	type VectorSearchResult,
+} from '@agentuity/core';
+import { createServerFetchAdapter, getServiceUrls } from '@agentuity/server';
+import { injectTraceContextToHeaders } from './otel/http';
+import { getLogger, getTracer } from './_server';
+import { getSDKVersion } from './_config';
+
+const userAgent = `Agentuity SDK/${getSDKVersion()}`;
+const bearerKey = `Bearer ${process.env.AGENTUITY_SDK_KEY}`;
+
+const serviceUrls = getServiceUrls();
+const kvBaseUrl = serviceUrls.keyvalue;
+const streamBaseUrl = serviceUrls.stream;
+const vectorBaseUrl = serviceUrls.vector;
+const objectBaseUrl = serviceUrls.objectstore;
+
+const adapter = createServerFetchAdapter({
+	headers: {
+		Authorization: bearerKey,
+		'User-Agent': userAgent,
+	},
+	onBefore: async (url, options, callback) => {
+		getLogger()?.debug('before request: %s with options: %s', url, options);
+		if (!options.telemetry) {
+			return callback();
+		}
+		options.headers = { ...options.headers, ...injectTraceContextToHeaders() };
+		const tracer = getTracer() ?? trace.getTracer('agentuity');
+		const currentContext = context.active();
+		const span = tracer.startSpan(
+			options.telemetry.name,
+			{ attributes: options.telemetry.attributes, kind: SpanKind.CLIENT },
+			currentContext
+		);
+		const spanContext = trace.setSpan(currentContext, span);
+		try {
+			await context.with(spanContext, callback);
+			span.setStatus({ code: SpanStatusCode.OK });
+		} catch (err) {
+			const e = err as Error;
+			span.recordException(e);
+			span.setStatus({ code: SpanStatusCode.ERROR, message: e?.message ?? String(err) });
+			throw err;
+		} finally {
+			span.end();
+		}
+	},
+	onAfter: async (url, options, result, err) => {
+		getLogger()?.debug('after request: %s (%d) => %s', url, result.response.status, err);
+		if (err) {
+			return;
+		}
+		const span = trace.getSpan(context.active());
+		switch (options.telemetry?.name) {
+			case 'agentuity.keyvalue.get': {
+				if (result.response.status === 404) {
+					span?.addEvent('miss');
+				} else if (result.response.ok) {
+					span?.addEvent('hit');
+				}
+				break;
+			}
+			case 'agentuity.stream.create': {
+				if (result.response.ok) {
+					const res = result.data as { id: string };
+					span?.setAttributes({
+						'stream.id': res.id,
+						'stream.url': `${streamBaseUrl}/${res.id}`,
+					});
+				}
+				break;
+			}
+			case 'agentuity.stream.list': {
+				const response = result.data as ListStreamsResponse;
+				if (response && span) {
+					span.setAttributes({
+						'stream.count': response.streams.length,
+						'stream.total': response.total,
+					});
+				}
+				break;
+			}
+			case 'agentuity.vector.upsert': {
+				if (result.response.ok) {
+					const data = result.data as VectorUpsertResult[];
+					span?.setAttributes({
+						'vector.count': data.length,
+					});
+				}
+				break;
+			}
+			case 'agentuity.vector.search': {
+				if (result.response.ok) {
+					const data = result.data as VectorSearchResult[];
+					span?.setAttributes({
+						'vector.results': data.length,
+					});
+				}
+				break;
+			}
+			case 'agentuity.vector.get': {
+				if (result.response.status === 404) {
+					span?.addEvent('miss');
+				} else if (result.response.ok) {
+					span?.addEvent('hit');
+				}
+				break;
+			}
+			case 'agentuity.objectstore.get': {
+				if (result.response.status === 404) {
+					span?.addEvent('miss');
+				} else if (result.response.ok) {
+					span?.addEvent('hit');
+				}
+				break;
+			}
+			case 'agentuity.objectstore.delete': {
+				if (result.response.status === 404) {
+					span?.addEvent('not_found', { deleted: false });
+				} else if (result.response.ok) {
+					span?.addEvent('deleted', { deleted: true });
+				}
+				break;
+			}
+		}
+	},
+});
+
+const kv = new KeyValueStorageService(kvBaseUrl, adapter);
+const objectStore = new ObjectStorageService(objectBaseUrl, adapter);
+const stream = new StreamStorageService(streamBaseUrl, adapter);
+const vector = new VectorStorageService(vectorBaseUrl, adapter);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerServices(o: any) {
+	Object.defineProperty(o, 'kv', {
+		get: () => kv,
+		enumerable: false,
+		configurable: false,
+	});
+	Object.defineProperty(o, 'objectstore', {
+		get: () => objectStore,
+		enumerable: false,
+		configurable: false,
+	});
+	Object.defineProperty(o, 'stream', {
+		get: () => stream,
+		enumerable: false,
+		configurable: false,
+	});
+	Object.defineProperty(o, 'vector', {
+		get: () => vector,
+		enumerable: false,
+		configurable: false,
+	});
+}

package/src/_util.ts

@@ -0,0 +1,63 @@
+import type { Context } from 'hono';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function returnResponse(ctx: Context, result: any) {
+	if (result instanceof ReadableStream) return ctx.body(result);
+	if (result instanceof Response) return result;
+	if (typeof result === 'string') return ctx.text(result);
+	if (typeof result === 'number' || typeof result === 'boolean') return ctx.text(String(result));
+	return ctx.json(result);
+}
+
+/**
+ * SHA256 hash of the given values
+ *
+ * @param val one or more strings to hash
+ * @returns hash string in hex format
+ */
+export function hash(...val: string[]): string {
+	const hasher = new Bun.CryptoHasher('sha256');
+	val.forEach((val) => hasher.update(val));
+	return hasher.digest().toHex();
+}
+
+/**
+ * Safely stringify an object to JSON, handling circular references
+ * @param obj - The object to stringify
+ * @returns JSON string representation
+ */
+export function safeStringify(obj: unknown): string {
+	const stack: unknown[] = [];
+
+	function replacer(_key: string, value: unknown): unknown {
+		if (typeof value === 'bigint') {
+			return value.toString();
+		}
+
+		if (typeof value === 'object' && value !== null) {
+			// Check if this object is already in our ancestor chain
+			if (stack.includes(value)) {
+				return '[Circular]';
+			}
+
+			// Add to stack before processing
+			stack.push(value);
+
+			// Process the object
+			const result = Array.isArray(value) ? [] : {};
+
+			for (const [k, v] of Object.entries(value)) {
+				(result as Record<string, unknown>)[k] = replacer(k, v);
+			}
+
+			// Remove from stack after processing
+			stack.pop();
+
+			return result;
+		}
+
+		return value;
+	}
+
+	return JSON.stringify(replacer('', obj));
+}