@agentuity/core 1.0.33 → 1.0.34

package/src/services/session/get.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { SessionSchema, type Session } from './list.ts';
+import { SessionResponseError } from './util.ts';
+
+export const _SessionGetRequestSchema = z.object({
+	id: z.string().describe('the session id'),
+});
+
+export const SessionEvalRunSchema = z.object({
+	id: z.string().describe('eval run id'),
+	created_at: z.string().describe('creation timestamp'),
+	eval_id: z.string().describe('evaluation id'),
+	pending: z.boolean().describe('pending status'),
+	success: z.boolean().describe('success status'),
+	error: z.string().nullable().describe('error message'),
+	result: z.record(z.string(), z.unknown()).nullable().describe('result object'),
+});
+
+type SpanNodeRecursive = {
+	id: string;
+	duration: number;
+	operation: string;
+	attributes: Record<string, unknown>;
+	children?: SpanNodeRecursive[];
+	error?: string;
+};
+
+export const SpanNodeSchema: z.ZodType<SpanNodeRecursive> = z.lazy(() =>
+	z.object({
+		id: z.string().describe('span ID'),
+		duration: z.number().describe('duration in milliseconds'),
+		operation: z.string().describe('operation name'),
+		attributes: z.record(z.string(), z.unknown()).describe('span attributes'),
+		children: z.array(SpanNodeSchema).optional().describe('child spans'),
+		error: z.string().optional().describe('error message'),
+	})
+);
+
+export type SpanNode = z.infer<typeof SpanNodeSchema>;
+
+export const RouteInfoSchema = z
+	.object({
+		id: z.string().describe('route id'),
+		method: z.string().describe('HTTP method'),
+		path: z.string().describe('route path'),
+	})
+	.nullable();
+
+export const AgentInfoSchema = z.object({
+	name: z.string().describe('agent name'),
+	identifier: z.string().describe('agent identifier'),
+});
+
+export const EnrichedSessionDataSchema = z.object({
+	session: SessionSchema,
+	agents: z.array(AgentInfoSchema).describe('resolved agents'),
+	eval_runs: z.array(SessionEvalRunSchema).describe('eval runs for this session'),
+	route: RouteInfoSchema.describe('route information'),
+});
+
+export const SessionGetResponseSchema = APIResponseSchema(EnrichedSessionDataSchema);
+
+type SessionGetRequest = z.infer<typeof _SessionGetRequestSchema>;
+type SessionGetResponse = z.infer<typeof SessionGetResponseSchema>;
+
+/**
+ * Get a single session by id
+ *
+ * @param client
+ * @param request
+ * @returns
+ */
+export type SessionEvalRun = z.infer<typeof SessionEvalRunSchema>;
+/** @deprecated Use SessionEvalRun instead */
+export type EvalRun = SessionEvalRun;
+export type RouteInfo = z.infer<typeof RouteInfoSchema>;
+export type AgentInfo = z.infer<typeof AgentInfoSchema>;
+export type EnrichedSession = {
+	session: Session;
+	agents: AgentInfo[];
+	evalRuns: SessionEvalRun[];
+	timeline: SpanNode | null;
+	route: RouteInfo;
+};
+
+export async function sessionGet(
+	client: APIClient,
+	request: SessionGetRequest
+): Promise<EnrichedSession> {
+	const resp = await client.request<SessionGetResponse>(
+		'GET',
+		`/session/${request.id}`,
+		SessionGetResponseSchema
+	);
+
+	if (resp.success) {
+		return {
+			session: resp.data.session,
+			agents: resp.data.agents,
+			evalRuns: resp.data.eval_runs,
+			timeline: (resp.data.session.timeline as SpanNode) ?? null,
+			route: resp.data.route,
+		};
+	}
+
+	throw new SessionResponseError({ message: resp.message });
+}

package/src/services/session/index.ts

@@ -0,0 +1,4 @@
+export * from './events.ts';
+export * from './get.ts';
+export * from './list.ts';
+export * from './logs.ts';

package/src/services/session/list.ts

@@ -0,0 +1,143 @@
+import { SortDirectionSchema } from '../pagination.ts';
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { SessionResponseError } from './util.ts';
+
+const SessionSchema = z.object({
+	id: z.string().describe('the session id'),
+	created_at: z.string().describe('the creation timestamp'),
+	updated_at: z.string().describe('the last update timestamp'),
+	deleted: z.boolean().describe('whether the session is deleted'),
+	deleted_at: z.string().nullable().describe('the deletion timestamp'),
+	deleted_by: z.string().nullable().describe('who deleted the session'),
+	start_time: z.string().describe('the session start time'),
+	end_time: z.string().nullable().describe('the session end time'),
+	duration: z.number().nullable().describe('the session duration in nanoseconds'),
+	org_id: z.string().describe('the organization id'),
+	project_id: z.string().describe('the project id'),
+	deployment_id: z.string().describe('the deployment id'),
+	agent_ids: z.array(z.string()).describe('the agent ids involved'),
+	trigger: z.string().describe('how the session was triggered'),
+	env: z.string().describe('the environment'),
+	devmode: z.boolean().describe('whether dev mode was enabled'),
+	pending: z.boolean().describe('whether the session is pending'),
+	success: z.boolean().describe('whether the session succeeded'),
+	error: z.string().nullable().describe('the error message if failed'),
+	metadata: z
+		.record(z.string(), z.unknown())
+		.nullable()
+		.optional()
+		.describe('unencrypted key-value metadata'),
+	cpu_time: z.number().nullable().describe('the CPU time in nanoseconds'),
+	llm_cost: z.number().nullable().describe('the LLM cost'),
+	llm_prompt_token_count: z.number().nullable().describe('the LLM prompt token count'),
+	llm_completion_token_count: z.number().nullable().describe('the LLM completion token count'),
+	total_cost: z.number().nullable().describe('the total cost'),
+	method: z.string().nullable().describe('the HTTP method'),
+	url: z.string().nullable().describe('the request URL'),
+	route_id: z.string().nullable().describe('the route id'),
+	thread_id: z.string().nullable().describe('the thread id'),
+	timeline: z.unknown().nullable().optional().describe('the session timeline tree'),
+	user_data: z.string().nullable().optional().describe('the user data as JSON'),
+});
+
+export { SessionSchema };
+
+export const SessionListResponse = z.array(SessionSchema);
+
+export const SessionListResponseSchema = APIResponseSchema(SessionListResponse);
+
+export type SessionListResponse = z.infer<typeof SessionListResponseSchema>;
+export type SessionList = z.infer<typeof SessionListResponse>;
+export type Session = z.infer<typeof SessionSchema>;
+
+export type SessionSortField = 'created' | 'updated' | 'duration' | 'startTime';
+
+export const SessionListOptionsSchema = z.object({
+	count: z.number().optional().describe('Deprecated alias for limit'),
+	limit: z.number().optional().describe('Maximum number of sessions to return'),
+	offset: z.number().optional().describe('Pagination offset'),
+	sort: z
+		.enum(['created', 'updated', 'duration', 'startTime'])
+		.optional()
+		.describe('Field to sort sessions by'),
+	direction: SortDirectionSchema.optional().describe('Sort direction for session listing'),
+	orgId: z.string().optional().describe('Optional organization id filter'),
+	projectId: z.string().optional().describe('Optional project id filter'),
+	deploymentId: z.string().optional().describe('Optional deployment id filter'),
+	trigger: z.string().optional().describe('Optional trigger filter'),
+	env: z.string().optional().describe('Optional environment filter'),
+	devmode: z.boolean().optional().describe('Optional devmode filter'),
+	success: z.boolean().optional().describe('Optional success status filter'),
+	threadId: z.string().optional().describe('Optional thread id filter'),
+	agentIdentifier: z.string().optional().describe('Optional agent identifier filter'),
+	startAfter: z.string().optional().describe('Filter sessions starting after this timestamp'),
+	startBefore: z.string().optional().describe('Filter sessions starting before this timestamp'),
+	metadata: z
+		.record(z.string(), z.unknown())
+		.optional()
+		.describe('Optional metadata match filter serialized as JSON'),
+});
+
+export type SessionListOptions = z.infer<typeof SessionListOptionsSchema>;
+
+/**
+ * List sessions
+ *
+ * @param client
+ * @param options filtering and pagination options
+ * @returns
+ */
+export async function sessionList(
+	client: APIClient,
+	options: SessionListOptions = {}
+): Promise<SessionList> {
+	const {
+		count,
+		limit,
+		offset,
+		sort,
+		direction,
+		orgId,
+		projectId,
+		deploymentId,
+		trigger,
+		env,
+		devmode,
+		success,
+		threadId,
+		agentIdentifier,
+		startAfter,
+		startBefore,
+		metadata,
+	} = options;
+	const resolvedLimit = limit ?? count ?? 10;
+	const params = new URLSearchParams({ limit: resolvedLimit.toString() });
+	if (orgId) params.set('orgId', orgId);
+	if (projectId) params.set('projectId', projectId);
+	if (deploymentId) params.set('deploymentId', deploymentId);
+	if (trigger) params.set('trigger', trigger);
+	if (env) params.set('env', env);
+	if (offset !== undefined) params.set('offset', offset.toString());
+	if (sort) params.set('sort', sort);
+	if (direction) params.set('direction', direction);
+	if (devmode !== undefined) params.set('devmode', devmode.toString());
+	if (success !== undefined) params.set('success', success.toString());
+	if (threadId) params.set('threadId', threadId);
+	if (agentIdentifier) params.set('agentIdentifier', agentIdentifier);
+	if (startAfter) params.set('startAfter', startAfter);
+	if (startBefore) params.set('startBefore', startBefore);
+	if (metadata) params.set('metadata', JSON.stringify(metadata));
+
+	const resp = await client.request<SessionListResponse>(
+		'GET',
+		`/session?${params.toString()}`,
+		SessionListResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new SessionResponseError({ message: resp.message });
+}

package/src/services/stats.ts

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from './api.ts';
+import { StructuredError } from '../error.ts';
+
+// --- Error ---
+
+export const ServiceStatsError = StructuredError('ServiceStatsError')<{
+	message: string;
+}>();
+
+// --- Per-Service Stat Schemas ---
+
+export const KeyValueStatSchema = z
+	.object({
+		namespaceCount: z.number().describe('Total number of key-value namespaces.'),
+		keyCount: z.number().describe('Total number of keys across all namespaces.'),
+		totalSizeBytes: z.number().describe('Total storage size in bytes across all namespaces.'),
+	})
+	.describe('Key-value service statistics.');
+
+export const VectorStatSchema = z
+	.object({
+		namespaceCount: z.number().describe('Total number of vector namespaces.'),
+		documentCount: z.number().describe('Total number of documents across all namespaces.'),
+		totalSizeBytes: z.number().describe('Total storage size in bytes across all namespaces.'),
+	})
+	.describe('Vector service statistics.');
+
+export const QueueStatSchema = z
+	.object({
+		queueCount: z.number().describe('Total number of queues.'),
+		totalMessages: z.number().describe('Total number of messages across all queues.'),
+		totalDlq: z
+			.number()
+			.describe('Total number of dead letter queue messages across all queues.'),
+	})
+	.describe('Queue service statistics.');
+
+export const StreamStatSchema = z
+	.object({
+		streamCount: z.number().describe('Total number of streams.'),
+		totalSizeBytes: z.number().describe('Total storage size in bytes across all streams.'),
+	})
+	.describe('Stream service statistics.');
+
+export const SandboxStatSchema = z
+	.object({
+		totalActive: z.number().describe('Total number of active sandboxes.'),
+		running: z.number().describe('Number of sandboxes currently running.'),
+		idle: z.number().describe('Number of sandboxes currently idle.'),
+		creating: z.number().describe('Number of sandboxes being created.'),
+		totalExecutions: z.number().describe('Total number of sandbox executions.'),
+		totalCpuTimeMs: z.number().describe('Total CPU time consumed in milliseconds.'),
+		totalMemoryByteSec: z.number().describe('Total memory usage in byte-seconds.'),
+		totalNetworkEgressBytes: z.number().describe('Total network egress in bytes.'),
+	})
+	.describe('Sandbox service statistics.');
+
+export const EmailStatSchema = z
+	.object({
+		addressCount: z.number().describe('Total number of email addresses.'),
+		inboundCount: z.number().describe('Total number of inbound emails received.'),
+		outboundCount: z.number().describe('Total number of outbound emails sent.'),
+		outboundSuccess: z.number().describe('Number of outbound emails delivered successfully.'),
+		outboundFailed: z.number().describe('Number of outbound emails that failed delivery.'),
+	})
+	.describe('Email service statistics.');
+
+export const TaskStatSchema = z
+	.object({
+		total: z.number().default(0).describe('Total number of tasks.'),
+		open: z.number().default(0).describe('Number of open tasks.'),
+		inProgress: z.number().default(0).describe('Number of tasks currently in progress.'),
+		done: z.number().default(0).describe('Number of completed tasks.'),
+		closed: z.number().default(0).describe('Number of closed tasks.'),
+		cancelled: z.number().default(0).describe('Number of cancelled tasks.'),
+	})
+	.describe('Task service statistics.');
+
+export const ScheduleStatSchema = z
+	.object({
+		scheduleCount: z.number().describe('Total number of schedules.'),
+		totalDeliveries: z.number().describe('Total number of scheduled deliveries.'),
+		successDeliveries: z.number().describe('Number of successful scheduled deliveries.'),
+		failedDeliveries: z.number().describe('Number of failed scheduled deliveries.'),
+	})
+	.describe('Schedule service statistics.');
+
+export const DatabaseStatSchema = z
+	.object({
+		databaseCount: z.number().describe('Total number of databases.'),
+		totalTableCount: z.number().describe('Total number of tables across all databases.'),
+		totalRecordCount: z.number().describe('Total number of records across all tables.'),
+		totalSizeBytes: z.number().describe('Total storage size in bytes across all databases.'),
+	})
+	.describe('Database service statistics.');
+
+// --- Aggregate Schema ---
+
+export const ServiceStatsDataSchema = z
+	.object({
+		services: z
+			.object({
+				database: DatabaseStatSchema.optional().describe('Database service statistics.'),
+				keyvalue: KeyValueStatSchema.optional().describe('Key-value service statistics.'),
+				vector: VectorStatSchema.optional().describe('Vector service statistics.'),
+				queue: QueueStatSchema.optional().describe('Queue service statistics.'),
+				stream: StreamStatSchema.optional().describe('Stream service statistics.'),
+				sandbox: SandboxStatSchema.optional().describe('Sandbox service statistics.'),
+				email: EmailStatSchema.optional().describe('Email service statistics.'),
+				task: TaskStatSchema.optional().describe('Task service statistics.'),
+				schedule: ScheduleStatSchema.optional().describe('Schedule service statistics.'),
+			})
+			.describe('Per-service statistics breakdown.'),
+	})
+	.describe('Aggregated service statistics data.');
+
+export const ServiceStatsResponseSchema = APIResponseSchema(ServiceStatsDataSchema);
+
+// --- Types ---
+
+export type KeyValueStat = z.infer<typeof KeyValueStatSchema>;
+export type VectorStat = z.infer<typeof VectorStatSchema>;
+export type QueueStat = z.infer<typeof QueueStatSchema>;
+export type StreamStat = z.infer<typeof StreamStatSchema>;
+export type SandboxStat = z.infer<typeof SandboxStatSchema>;
+export type EmailStat = z.infer<typeof EmailStatSchema>;
+export type TaskStat = z.infer<typeof TaskStatSchema>;
+export type ScheduleStat = z.infer<typeof ScheduleStatSchema>;
+export type DatabaseStat = z.infer<typeof DatabaseStatSchema>;
+export type ServiceStatsData = z.infer<typeof ServiceStatsDataSchema>;
+export type ServiceStatsResponse = z.infer<typeof ServiceStatsResponseSchema>;
+
+// --- Valid Services ---
+
+/**
+ * Valid service names that can be used to filter stats.
+ */
+export const VALID_SERVICES = [
+	'database',
+	'keyvalue',
+	'email',
+	'vector',
+	'schedule',
+	'task',
+	'stream',
+	'sandbox',
+	'queue',
+] as const;
+
+export type ServiceName = (typeof VALID_SERVICES)[number];
+
+// --- Options ---
+
+export const ServiceStatsOptionsSchema = z.object({
+	service: z
+		.enum(VALID_SERVICES)
+		.optional()
+		.describe('Optional service filter; when omitted returns all services'),
+	start: z.string().optional().describe('Optional start timestamp (ISO 8601)'),
+	end: z.string().optional().describe('Optional end timestamp (ISO 8601)'),
+	orgIdHeader: z
+		.string()
+		.optional()
+		.describe('Optional org id header for CLI token authentication'),
+});
+
+export type ServiceStatsOptions = z.infer<typeof ServiceStatsOptionsSchema>;
+
+// --- API Function ---
+
+/**
+ * Get aggregated stats for services used by an organization.
+ *
+ * Returns per-service stats with service-specific fields (counts, sizes, etc.).
+ * Services that error on the backend are omitted from the response.
+ * Services with no provisioned tenant DB return zero values.
+ *
+ * @param client - The API client instance
+ * @param orgId - The organization ID
+ * @param options - Optional filtering (service, time range)
+ * @returns Service stats data with per-service breakdown
+ * @throws {ServiceStatsError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // Get stats for all services
+ * const stats = await getServiceStats(client, 'org_123');
+ * console.log(`KV keys: ${stats.services.keyvalue?.keyCount}`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Get stats for a specific service
+ * const stats = await getServiceStats(client, 'org_123', {
+ *   service: 'keyvalue',
+ * });
+ * ```
+ */
+export async function getServiceStats(
+	client: APIClient,
+	orgId: string,
+	options?: ServiceStatsOptions
+): Promise<ServiceStatsData> {
+	const params = new URLSearchParams();
+	if (options?.service) params.set('service', options.service);
+	if (options?.start) params.set('start', options.start);
+	if (options?.end) params.set('end', options.end);
+
+	const queryString = params.toString();
+	const url = `/services/stats/${encodeURIComponent(orgId)}${queryString ? `?${queryString}` : ''}`;
+
+	const headers: Record<string, string> = {};
+	if (options?.orgIdHeader) {
+		headers['x-agentuity-orgid'] = options.orgIdHeader;
+	}
+
+	const resp = await client.get(
+		url,
+		ServiceStatsResponseSchema,
+		undefined,
+		Object.keys(headers).length > 0 ? headers : undefined
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new ServiceStatsError({
+		message: resp.message || 'Failed to get service stats',
+	});
+}