@agentuity/core 0.0.60 → 0.0.61

package/src/error.ts

@@ -0,0 +1,384 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// NOTE: these ideas are borrowed from https://github.com/Effect-TS/effect
+
+import util from 'node:util';
+import { safeStringify } from './json';
+
+type PlainObject = Record<string, any>;
+
+const _argsSym = Symbol('@@RichError:plainArgs');
+const _causeSym = Symbol('@@RichError:cause');
+const _metaSym = Symbol('@@RichError:meta'); // reserved for future use (non-enumerable)
+const _structuredSym = Symbol.for('@@StructuredError');
+
+const spacer = '  ';
+
+export class RichError extends Error {
+	// private slots (non-enumerable)
+	private [_argsSym]?: PlainObject;
+	private [_causeSym]?: unknown;
+	private [_metaSym]?: PlainObject;
+
+	constructor(args?: PlainObject) {
+		const message = args?.message ?? undefined;
+		const cause = (args?.cause ?? undefined) as unknown;
+
+		// If platform supports error cause option, pass it to Error constructor
+		// (Node 16+ / modern engines)
+		if (cause !== undefined) {
+			super(message, { cause } as any);
+		} else {
+			super(message);
+		}
+
+		// correct prototype chain when transpiled to older JS
+		Object.setPrototypeOf(this, new.target.prototype);
+
+		// capture a clean stack (omit this constructor)
+		if (typeof (Error as any).captureStackTrace === 'function') {
+			(Error as any).captureStackTrace(this, new.target);
+		} else {
+			// fallback: ensure stack exists
+			if (!this.stack) {
+				this.stack = new Error(message).stack;
+			}
+		}
+
+		if (args && typeof args === 'object') {
+			// copy all fields except cause and message (we keep them separate)
+			const { cause: _c, message: _m, ...rest } = args;
+			if (Object.keys(rest).length > 0) {
+				Object.assign(this, rest);
+				this[_argsSym] = rest;
+			}
+			if (cause !== undefined) {
+				this[_causeSym] = cause;
+			}
+		}
+		// hide internal symbols and meta (redefine non-enumerable)
+		Object.defineProperty(this, _argsSym, {
+			value: this[_argsSym],
+			enumerable: false,
+			writable: true,
+		});
+		Object.defineProperty(this, _causeSym, {
+			value: this[_causeSym],
+			enumerable: false,
+			writable: true,
+		});
+		Object.defineProperty(this, _metaSym, {
+			value: this[_metaSym] ?? {},
+			enumerable: false,
+			writable: true,
+		});
+	}
+
+	/** Return the stored plain args (if any) */
+	get plainArgs(): PlainObject | undefined {
+		return this[_argsSym];
+	}
+
+	/** Return the cause (if any) */
+	get cause(): unknown | undefined {
+		return this[_causeSym];
+	}
+
+	/** Pretty, recursive string representation (follows cause chain). */
+	prettyPrint(space = 2): string {
+		const lines: string[] = [];
+		const visited = new Set<Error>();
+
+		// eslint-disable-next-line @typescript-eslint/no-this-alias
+		let cur: Error | undefined = this;
+		let depth = 0;
+		while (cur && cur instanceof Error && !visited.has(cur)) {
+			const curAny = cur as any;
+			visited.add(cur);
+			const header = `${cur.name}${curAny._tag && curAny._tag !== cur.name ? ` (${String(curAny._tag)})` : ''}${depth === 0 ? '' : ' [cause]'}`;
+			const msg = cur.message !== undefined && cur.message !== '' ? `: ${cur.message}` : '';
+			lines.push(header + msg);
+
+			// include stack if present (limit to first line of stack header for brevity)
+			if (cur.stack) {
+				lines.push('');
+				lines.push(spacer + 'stack trace:');
+				const stackLines = String(cur.stack).split('\n').slice(1); // drop first line (it's message)
+				if (stackLines.length > 0) {
+					// indent stack
+					let s = stackLines.map((s) => spacer + spacer + s.trim());
+					if (s[s.length - 1].includes('processTicksAndRejections')) {
+						s = s.slice(0, s.length - 1);
+					}
+					lines.push(...s);
+				}
+			}
+
+			// include plain args as formatted output (if any)
+			if (curAny[_argsSym]) {
+				let argsStr = util.formatWithOptions(
+					{
+						depth: 10,
+						sorted: true,
+						showHidden: false,
+						showProxy: false,
+						maxArrayLength: 10,
+						maxStringLength: 80 - spacer.length * 2,
+					},
+					curAny[_argsSym]
+				);
+				argsStr = argsStr.replace(/^{/, '').replace(/}$/, '');
+				const jsonlines = argsStr
+					.split('\n')
+					.filter(Boolean)
+					.map((l: string) => spacer + spacer + l + '\n')
+					.join('');
+				lines.push('');
+				lines.push(spacer + 'context:\n' + jsonlines);
+			}
+
+			// include cause summary if non-Error (could be object)
+			const c: unknown = cur.cause ?? curAny[_causeSym];
+			if (c && !(c instanceof Error)) {
+				lines.push(spacer + 'cause: ' + safeStringify(c, space));
+			}
+
+			cur = c instanceof Error ? c : undefined;
+			depth += 1;
+			if (cur) lines.push('-- caused by --');
+		}
+
+		return lines.join('\n');
+	}
+
+	toJSON() {
+		// Represent as merged: args, public enumerable props, plus well-known fields
+		const output: any = {};
+
+		// include args first (non-enumerable original values)
+		if (this[_argsSym]) {
+			Object.assign(output, this[_argsSym]);
+		}
+
+		// copy enumerable own props
+		for (const k of Object.keys(this)) {
+			// skip internal symbols (they are non-enumerable anyway)
+			output[k] = (this as any)[k];
+		}
+
+		// canonical fields
+		output.name = this.name;
+		if (this.message !== undefined) output.message = this.message;
+		if (this.stack !== undefined) output.stack = this.stack;
+		if (this.cause !== undefined) {
+			if (this.cause instanceof Error) {
+				output.cause = {
+					name: this.cause.name,
+					message: this.cause.message,
+					stack: (this.cause as any).stack,
+				};
+			} else {
+				output.cause = this.cause;
+			}
+		}
+
+		return output;
+	}
+
+	toString(): string {
+		// default to pretty print with small indent
+		return this.prettyPrint(2);
+	}
+
+	[util.inspect.custom](_depth: number, _options: any) {
+		return this.prettyPrint(); // or some concise string/JSON
+	}
+}
+
+type StructuredErrorConstructor<
+	Tag extends string,
+	Shape extends PlainObject,
+	HasDefault extends boolean,
+> = {
+	new (
+		args?: Shape extends Record<string, never>
+			? HasDefault extends true
+				? { cause?: unknown }
+				: { message?: string; cause?: unknown }
+			: HasDefault extends true
+				? Shape & { cause?: unknown }
+				: Shape & { message?: string; cause?: unknown }
+	): RichError & { readonly _tag: Tag } & Readonly<Shape>;
+	readonly defaultMessage?: string;
+};
+
+/**
+ * StructuredError factory with automatic tag inference and payload typing.
+ *
+ * Creates a custom error class with:
+ * - A readonly `_tag` property for runtime type discrimination
+ * - Automatic stack trace capture
+ * - Cause chaining support
+ * - Pretty printing with `prettyPrint()` and `toString()`
+ * - JSON serialization with `toJSON()`
+ *
+ * @template Tag - The literal string tag type (automatically inferred from the tag parameter)
+ * @param tag - The unique identifier for this error type (used as the error name)
+ * @param defaultMessage - Optional default message to use when no message is provided in args
+ * @returns A constructor function that can be called directly or with a shape generic
+ *
+ * @example
+ * // Without shape (tag auto-inferred)
+ * const NotFound = StructuredError("NotFound")
+ * throw new NotFound({ id: 1, message: "nope", cause: someError })
+ *
+ * @example
+ * // With typed shape (tag auto-inferred, shape explicitly typed)
+ * const ValidationError = StructuredError("ValidationError")<{ field: string; code: string }>()
+ * throw new ValidationError({ field: "email", code: "INVALID", message: "Invalid email" })
+ *
+ * @example
+ * // With default message (message cannot be overridden)
+ * const UpgradeRequired = StructuredError("UpgradeRequired", "Upgrade required to access this feature")
+ * throw new UpgradeRequired({ feature: "advanced" }) // message is automatically set and cannot be changed
+ */
+type StructuredErrorFactory<
+	Tag extends string,
+	HasDefault extends boolean,
+> = StructuredErrorConstructor<Tag, Record<string, never>, HasDefault> &
+	(<Shape extends PlainObject = Record<string, never>>() => StructuredErrorConstructor<
+		Tag,
+		Shape,
+		HasDefault
+	>);
+
+export function StructuredError<const Tag extends string>(
+	tag: Tag,
+	defaultMessage: string
+): StructuredErrorFactory<Tag, true>;
+export function StructuredError<const Tag extends string>(
+	tag: Tag
+): StructuredErrorFactory<Tag, false>;
+export function StructuredError<const Tag extends string>(tag: Tag, defaultMessage?: string) {
+	function createErrorClass<
+		Shape extends PlainObject = Record<string, never>,
+	>(): StructuredErrorConstructor<
+		Tag,
+		Shape,
+		typeof defaultMessage extends string ? true : false
+	> {
+		// create a unique symbol for this tag's args storage so different factories don't clash
+		const tagArgsSym = Symbol.for(`@StructuredError:tag:${tag}`);
+
+		class Tagged extends RichError {
+			// runtime readonly property for tag
+			public readonly _tag: Tag = tag as Tag;
+			static readonly defaultMessage = defaultMessage;
+
+			constructor(args?: Shape & { message?: string; cause?: unknown }) {
+				// ensure `_tag` isn't copied from args accidentally
+				const safeArgs =
+					args && typeof args === 'object'
+						? (() => {
+								const { _tag: _discard, ...rest } = args as any;
+								return rest;
+							})()
+						: args;
+
+				// Apply default message if no message provided
+				const finalArgs =
+					safeArgs && typeof safeArgs === 'object'
+						? { ...safeArgs, message: safeArgs.message ?? defaultMessage }
+						: defaultMessage
+							? { message: defaultMessage }
+							: safeArgs;
+
+				super(finalArgs);
+				// name the class for nicer stacks
+				try {
+					Object.defineProperty(this, 'name', { value: tag, configurable: true });
+				} catch {
+					(this as any).name = tag;
+				}
+				// mark as StructuredError with brand symbol
+				Object.defineProperty(this, _structuredSym, {
+					value: true,
+					enumerable: false,
+					writable: false,
+				});
+				// store tag args symbol to hide anything specific to this factory (non-enumerable)
+				Object.defineProperty(this, tagArgsSym, {
+					value: safeArgs,
+					enumerable: false,
+					writable: true,
+				});
+			}
+		}
+
+		// set prototype name (works in many engines)
+		try {
+			Object.defineProperty(Tagged, 'name', { value: String(tag) });
+		} catch {
+			(Tagged as any).name = tag;
+		}
+
+		return Tagged as unknown as StructuredErrorConstructor<
+			Tag,
+			Shape,
+			typeof defaultMessage extends string ? true : false
+		>;
+	}
+
+	// Create a callable constructor: can be used directly or called with generics
+	type WithShape = <
+		Shape extends Record<string, any> = Record<string, never>,
+	>() => StructuredErrorConstructor<
+		Tag,
+		Shape,
+		typeof defaultMessage extends string ? true : false
+	>;
+	type Result = StructuredErrorConstructor<
+		Tag,
+		Record<string, never>,
+		typeof defaultMessage extends string ? true : false
+	> &
+		WithShape;
+
+	const baseClass = createErrorClass<Record<string, never>>();
+
+	// Use a Proxy to intercept calls and return shaped classes
+	const callable = new Proxy(baseClass, {
+		apply(_target, _thisArg, _args) {
+			// When called as a function (for generic type application), return a new class
+			// This happens when TypeScript sees: StructuredError("Tag")<Shape>()
+			return createErrorClass();
+		},
+	});
+
+	return callable as Result;
+}
+
+/**
+ * Returns true if the error passed is an instance of a StructuredObject
+ *
+ * @param err the error object
+ * @returns true if err is a StructuredError
+ *
+ * @example
+ * const UpgradeRequired = StructuredError("UpgradeRequired", "Upgrade required to access this feature")
+ * try {
+ *   throw UpgradeRequired();
+ * } catch (ex) {
+ *   if (isStructuredError(ex)) {
+ *     console.log(ex._tag);
+ *   }
+ * }
+ */
+export function isStructuredError(err: unknown): err is RichError & { _tag: string } {
+	return (
+		typeof err === 'object' &&
+		err !== null &&
+		(_structuredSym in err || err instanceof RichError) &&
+		typeof (err as any)._tag === 'string'
+	);
+}

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './error';
 export * from './json';
 export * from './logger';
 export * from './services';

package/src/json.ts

@@ -3,7 +3,7 @@
  * @param obj - The object to stringify
  * @returns JSON string representation
  */
-export function safeStringify(obj: unknown): string {
+export function safeStringify(obj: unknown, space?: number | string): string {
 	const visited = new WeakSet();
 
 	function replacer(_key: string, value: unknown): unknown {
@@ -22,5 +22,5 @@ export function safeStringify(obj: unknown): string {
 		return value;
 	}
 
-	return JSON.stringify(obj, replacer);
+	return JSON.stringify(obj, replacer, space);
 }

package/src/services/__test__/vector.test.ts

@@ -34,7 +34,7 @@ describe('VectorStorageService', () => {
 			const service = new VectorStorageService(baseUrl, adapter);
 
 			await expect(service.upsert('my-vectors')).rejects.toThrow(
-				'At least one document is required for upsert'
+				'Vector storage requires at least one document for this method'
 			);
 		});
 
@@ -43,7 +43,7 @@ describe('VectorStorageService', () => {
 			const service = new VectorStorageService(baseUrl, adapter);
 
 			await expect(service.upsert('my-vectors', { key: '', document: 'text' })).rejects.toThrow(
-				'Each document must have a non-empty key'
+				'Vector storage requires each document to have a non-empty key'
 			);
 		});
 
@@ -53,7 +53,9 @@ describe('VectorStorageService', () => {
 
 			await expect(
 				service.upsert('my-vectors', { key: 'k1' } as unknown as VectorUpsertParams)
-			).rejects.toThrow('Each document must have either embeddings or document text');
+			).rejects.toThrow(
+				'Vector storage requires each document to have either embeddings or document property'
+			);
 		});
 
 		test('rejects empty embeddings array', async () => {
@@ -61,7 +63,7 @@ describe('VectorStorageService', () => {
 			const service = new VectorStorageService(baseUrl, adapter);
 
 			await expect(service.upsert('my-vectors', { key: 'k1', embeddings: [] })).rejects.toThrow(
-				'Embeddings must be a non-empty array of numbers'
+				'Vector storage requires each embeddings property to have a non-empty array of numbers'
 			);
 		});
 
@@ -70,7 +72,7 @@ describe('VectorStorageService', () => {
 			const service = new VectorStorageService(baseUrl, adapter);
 
 			await expect(service.upsert('my-vectors', { key: 'k1', document: '   ' })).rejects.toThrow(
-				'Document must be a non-empty string'
+				'Vector storage requires each document property to have a non-empty string value'
 			);
 		});
 	});
@@ -90,7 +92,7 @@ describe('VectorStorageService', () => {
 			const service = new VectorStorageService(baseUrl, adapter);
 
 			await expect(service.get('my-vectors', '')).rejects.toThrow(
-				'Key is required and must be a non-empty string'
+				'Vector storage key is required and must be a non-empty string'
 			);
 		});
 	});
@@ -119,7 +121,7 @@ describe('VectorStorageService', () => {
 			const service = new VectorStorageService(baseUrl, adapter);
 
 			await expect(service.getMany('my-vectors', 'key1', '', 'key3')).rejects.toThrow(
-				'All keys must be non-empty strings'
+				'Vector storage requires all keys to be non-empty strings'
 			);
 		});
 	});
@@ -139,7 +141,7 @@ describe('VectorStorageService', () => {
 			const service = new VectorStorageService(baseUrl, adapter);
 
 			await expect(service.search('my-vectors', { query: '' })).rejects.toThrow(
-				'Query is required and must be a non-empty string'
+				'Vector storage query property is required and must be a non-empty string'
 			);
 		});
 
@@ -148,7 +150,7 @@ describe('VectorStorageService', () => {
 			const service = new VectorStorageService(baseUrl, adapter);
 
 			await expect(service.search('my-vectors', { query: 'test', limit: -5 })).rejects.toThrow(
-				'Limit must be a positive number'
+				'Vector storage limit property must be positive number'
 			);
 		});
 
@@ -157,7 +159,7 @@ describe('VectorStorageService', () => {
 			const service = new VectorStorageService(baseUrl, adapter);
 
 			await expect(service.search('my-vectors', { query: 'test', limit: 0 })).rejects.toThrow(
-				'Limit must be a positive number'
+				'Vector storage limit property must be positive number'
 			);
 		});
 
@@ -167,7 +169,9 @@ describe('VectorStorageService', () => {
 
 			await expect(
 				service.search('my-vectors', { query: 'test', similarity: -0.1 })
-			).rejects.toThrow('Similarity must be a number between 0.0 and 1.0');
+			).rejects.toThrow(
+				'Vector storage similarity property must be a number between 0.0 and 1.0'
+			);
 		});
 
 		test('rejects similarity > 1', async () => {
@@ -176,7 +180,9 @@ describe('VectorStorageService', () => {
 
 			await expect(
 				service.search('my-vectors', { query: 'test', similarity: 1.5 })
-			).rejects.toThrow('Similarity must be a number between 0.0 and 1.0');
+			).rejects.toThrow(
+				'Vector storage similarity property must be a number between 0.0 and 1.0'
+			);
 		});
 
 		test('rejects invalid metadata', async () => {
@@ -188,7 +194,7 @@ describe('VectorStorageService', () => {
 					query: 'test',
 					metadata: null as unknown as Record<string, unknown>,
 				})
-			).rejects.toThrow('Metadata must be a valid object');
+			).rejects.toThrow('Vector storage metadata property must be a valid object');
 		});
 
 		test('accepts boundary similarity values', async () => {
@@ -221,7 +227,7 @@ describe('VectorStorageService', () => {
 			const service = new VectorStorageService(baseUrl, adapter);
 
 			await expect(service.delete('my-vectors', 'key1', '', 'key3')).rejects.toThrow(
-				'All keys must be non-empty strings'
+				'Vector storage requires all keys to be non-empty strings'
 			);
 		});
 

package/src/services/_util.ts

@@ -1,12 +1,7 @@
 import { safeStringify } from '../json';
-import type { Body } from './adapter';
+import type { Body, HttpMethod } from './adapter';
 import { ServiceException } from './exception';
 
-/**
- * Valid HTTP methods for service calls
- */
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
-
 export const buildUrl = (
 	base: string,
 	path: string,
@@ -29,13 +24,26 @@ export async function toServiceException(
 	method: HttpMethod,
 	url: string,
 	response: Response
-): Promise<ServiceException> {
+): Promise<InstanceType<typeof ServiceException>> {
+	const sessionId = response.headers.get('x-session-id');
 	switch (response.status) {
 		case 401:
 		case 403:
-			return new ServiceException('Unauthorized', method, url, response.status);
+			return new ServiceException({
+				message: 'Unauthorized',
+				method,
+				url,
+				statusCode: response.status,
+				sessionId,
+			});
 		case 404:
-			return new ServiceException('Not Found', method, url, response.status);
+			return new ServiceException({
+				message: 'Not Found',
+				method,
+				url,
+				statusCode: response.status,
+				sessionId,
+			});
 		default:
 	}
 	const ct = response.headers.get('content-type');
@@ -43,24 +51,54 @@ export async function toServiceException(
 		try {
 			const payload = (await response.json()) as { message?: string; error?: string };
 			if (payload.error) {
-				return new ServiceException(payload.error, method, url, response.status);
+				return new ServiceException({
+					message: payload.error,
+					method,
+					url,
+					statusCode: response.status,
+					sessionId,
+				});
 			}
 			if (payload.message) {
-				return new ServiceException(payload.message, method, url, response.status);
+				return new ServiceException({
+					message: payload.message,
+					method,
+					url,
+					statusCode: response.status,
+					sessionId,
+				});
 			}
-			return new ServiceException(JSON.stringify(payload), method, url, response.status);
+			return new ServiceException({
+				message: JSON.stringify(payload),
+				method,
+				url,
+				statusCode: response.status,
+				sessionId,
+			});
 		} catch {
 			/** don't worry */
 		}
 	}
 	try {
 		const body = await response.text();
-		return new ServiceException(body, method, url, response.status);
+		return new ServiceException({
+			message: body,
+			method,
+			url,
+			statusCode: response.status,
+			sessionId,
+		});
 	} catch {
 		/* fall through */
 	}
 
-	return new ServiceException(response.statusText, method, url, response.status);
+	return new ServiceException({
+		message: response.statusText,
+		method,
+		url,
+		statusCode: response.status,
+		sessionId,
+	});
 }
 
 const binaryContentType = 'application/octet-stream';
@@ -126,10 +164,10 @@ export async function fromResponse<T>(
 	if (contentType?.includes(binaryContentType)) {
 		return (await response.arrayBuffer()) as T;
 	}
-	throw new ServiceException(
-		`Unsupported content-type: ${contentType}`,
+	throw new ServiceException({
+		message: `Unsupported content-type: ${contentType}`,
 		method,
 		url,
-		response.status
-	);
+		statusCode: response.status,
+	});
 }

package/src/services/adapter.ts

@@ -14,8 +14,10 @@ export type FetchResponse<T> = FetchErrorResponse | FetchSuccessResponse<T>;
 
 export type Body = string | Buffer | ArrayBuffer | ReadableStream;
 
+export type HttpMethod = 'GET' | 'PUT' | 'POST' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'PATCH';
+
 export interface FetchRequest {
-	method: 'GET' | 'PUT' | 'POST' | 'DELETE' | 'HEAD';
+	method: HttpMethod;
 	body?: Body;
 	signal?: AbortSignal;
 	contentType?: string;

package/src/services/exception.ts

@@ -1,11 +1,9 @@
-export class ServiceException extends Error {
+import { StructuredError } from '../error';
+import { HttpMethod } from './adapter';
+
+export const ServiceException = StructuredError('ServiceException')<{
 	statusCode: number;
-	method: string;
+	method: HttpMethod;
 	url: string;
-	constructor(message: string, method: string, url: string, statusCode: number) {
-		super(message);
-		this.method = method;
-		this.url = url;
-		this.statusCode = statusCode;
-	}
-}
+	sessionId?: string | null;
+}>();

package/src/services/index.ts

@@ -7,4 +7,3 @@ export * from './session';
 export * from './stream';
 export * from './vector';
 export { buildUrl, toServiceException, toPayload, fromResponse } from './_util';
-export type { HttpMethod } from './_util';