@agentuity/server 1.0.22 → 1.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/server",
-	"version": "1.0.22",
+	"version": "1.0.24",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -25,12 +25,12 @@
 		"prepublishOnly": "bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@agentuity/core": "1.0.22",
-		"@agentuity/schema": "1.0.22",
+		"@agentuity/core": "1.0.24",
+		"@agentuity/schema": "1.0.24",
 		"zod": "^4.3.5"
 	},
 	"devDependencies": {
-		"@agentuity/test-utils": "1.0.22",
+		"@agentuity/test-utils": "1.0.24",
 		"@types/bun": "latest",
 		"@types/node": "^22.0.0",
 		"bun-types": "latest",

package/src/api/index.ts

@@ -7,7 +7,9 @@ export * from './org/index.ts';
 export * from './project/index.ts';
 export * from './queue/index.ts';
 export * from './region/index.ts';
+export * from './webhook/index.ts';
 export * from './sandbox/index.ts';
+export * from './services/index.ts';
 export * from './session/index.ts';
 export * from './stream/index.ts';
 export * from './thread/index.ts';

package/src/api/project/deploy.ts

@@ -16,6 +16,18 @@ export const Mode = z.object({
 	idle: z.string().optional().describe('duration in seconds if on-demand'),
 });
 
+export const ProjectBuildConfig = z.object({
+	timeout: z.string().optional().describe('Build execution timeout (e.g. "30m")'),
+	resources: z
+		.object({
+			memory: z.string().optional().describe('Build sandbox memory (e.g. "4Gi")'),
+			cpu: z.string().optional().describe('Build sandbox CPU (e.g. "2")'),
+			disk: z.string().optional().describe('Build sandbox disk (e.g. "4Gi")'),
+		})
+		.optional()
+		.describe('Build sandbox resource limits'),
+});
+
 export const DeploymentConfig = z.object({
 	resources: Resources.optional().describe('the resource requirements for your deployed project'),
 	mode: Mode.optional().describe('the provisioning mode for the project'),
@@ -70,14 +82,8 @@ export const BuildMetadataSchema = z.object({
 			method: z.enum(['get', 'post', 'put', 'delete', 'patch']).describe('the HTTP method'),
 			version: z.string().describe('the SHA256 content of the file'),
 			type: z.enum(['api', 'sms', 'email', 'cron', 'websocket', 'sse', 'stream']),
-			agentIds: z
-				.array(z.string())
-				.optional()
-				.describe('the agent ids associated with this route'),
-			config: z
-				.record(z.string(), z.unknown())
-				.optional()
-				.describe('type specific configuration'),
+			agentIds: z.array(z.string()).optional().describe('the agent ids associated with this route'),
+			config: z.record(z.string(), z.unknown()).optional().describe('type specific configuration'),
 			schema: z
 				.object({
 					input: z.string().optional().describe('JSON schema for input (stringified JSON)'),
@@ -127,11 +133,7 @@ export const BuildMetadataSchema = z.object({
 						.default('cli')
 						.optional()
 						.describe('the trigger that caused the build'),
-					url: z
-						.string()
-						.url()
-						.optional()
-						.describe('the url to the commit for the CI provider'),
+					url: z.string().url().optional().describe('the url to the commit for the CI provider'),
 					buildUrl: z
 						.string()
 						.url()
@@ -150,9 +152,7 @@ export const BuildMetadataSchema = z.object({
 							url: z.string().optional(),
 						})
 						.optional()
-						.describe(
-							'This is only present when the deployment was triggered via a pull request.'
-						),
+						.describe('This is only present when the deployment was triggered via a pull request.'),
 				})
 				.optional()
 				.describe('git commit information'),

package/src/api/sandbox/disk-checkpoint.ts

@@ -0,0 +1,179 @@
+import { z } from 'zod';
+import type { z as zType } from 'zod';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api';
+import { API_VERSION, throwSandboxError } from './util';
+
+// --- Schemas ---
+
+export const DiskCheckpointInfoSchema = z.object({
+	id: z.string().describe('Globally unique checkpoint ID (ckpt_xxx)'),
+	name: z.string().describe('User-provided checkpoint name'),
+	createdAt: z.string().describe('ISO timestamp of creation'),
+	parent: z.string().describe('Parent checkpoint name (empty for base)'),
+});
+
+export type DiskCheckpointInfo = z.infer<typeof DiskCheckpointInfoSchema>;
+
+const CreateDiskCheckpointDataSchema = DiskCheckpointInfoSchema;
+export const CreateDiskCheckpointResponseSchema = APIResponseSchema(CreateDiskCheckpointDataSchema);
+
+const ListDiskCheckpointsDataSchema = z.object({
+	checkpoints: z.array(DiskCheckpointInfoSchema),
+});
+export const ListDiskCheckpointsResponseSchema = APIResponseSchema(ListDiskCheckpointsDataSchema);
+
+export const RestoreDiskCheckpointResponseSchema = APIResponseSchemaNoData();
+export const DeleteDiskCheckpointResponseSchema = APIResponseSchemaNoData();
+
+// --- Params ---
+
+export interface DiskCheckpointCreateParams {
+	sandboxId: string;
+	name: string;
+	orgId?: string;
+}
+
+export interface DiskCheckpointListParams {
+	sandboxId: string;
+	orgId?: string;
+}
+
+export interface DiskCheckpointRestoreParams {
+	sandboxId: string;
+	checkpointId: string;
+	orgId?: string;
+}
+
+export interface DiskCheckpointDeleteParams {
+	sandboxId: string;
+	checkpointId: string;
+	orgId?: string;
+}
+
+// --- API Functions ---
+
+/**
+ * Creates a new disk checkpoint for a sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID and checkpoint name
+ * @throws {SandboxResponseError} If the sandbox is not found or checkpoint creation fails
+ */
+export async function diskCheckpointCreate(
+	client: APIClient,
+	params: DiskCheckpointCreateParams
+): Promise<DiskCheckpointInfo> {
+	const { sandboxId, name, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${API_VERSION}/${encodeURIComponent(sandboxId)}/checkpoint${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<zType.infer<typeof CreateDiskCheckpointResponseSchema>>(
+		url,
+		{ name },
+		CreateDiskCheckpointResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+/**
+ * Lists all disk checkpoints for a sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID
+ * @throws {SandboxResponseError} If the sandbox is not found or listing fails
+ */
+export async function diskCheckpointList(
+	client: APIClient,
+	params: DiskCheckpointListParams
+): Promise<DiskCheckpointInfo[]> {
+	const { sandboxId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${API_VERSION}/checkpoints/${encodeURIComponent(sandboxId)}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<zType.infer<typeof ListDiskCheckpointsResponseSchema>>(
+		url,
+		ListDiskCheckpointsResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data.checkpoints;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+/**
+ * Restores a sandbox to a specific disk checkpoint.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID and checkpoint ID
+ * @throws {SandboxResponseError} If the sandbox or checkpoint is not found, or restore fails
+ */
+export async function diskCheckpointRestore(
+	client: APIClient,
+	params: DiskCheckpointRestoreParams
+): Promise<void> {
+	const { sandboxId, checkpointId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${API_VERSION}/${encodeURIComponent(sandboxId)}/checkpoint/${encodeURIComponent(checkpointId)}/restore${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<zType.infer<typeof RestoreDiskCheckpointResponseSchema>>(
+		url,
+		undefined,
+		RestoreDiskCheckpointResponseSchema
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+/**
+ * Deletes a disk checkpoint from a sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID and checkpoint ID
+ * @throws {SandboxResponseError} If the sandbox or checkpoint is not found, or deletion fails
+ */
+export async function diskCheckpointDelete(
+	client: APIClient,
+	params: DiskCheckpointDeleteParams
+): Promise<void> {
+	const { sandboxId, checkpointId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${API_VERSION}/${encodeURIComponent(sandboxId)}/checkpoint/${encodeURIComponent(checkpointId)}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.delete<zType.infer<typeof DeleteDiskCheckpointResponseSchema>>(
+		url,
+		DeleteDiskCheckpointResponseSchema
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}

package/src/api/sandbox/index.ts

@@ -16,6 +16,24 @@ export {
 } from './create.ts';
 export type { SandboxDestroyParams } from './destroy.ts';
 export { DestroyResponseSchema, sandboxDestroy } from './destroy.ts';
+export type {
+	DiskCheckpointInfo,
+	DiskCheckpointCreateParams,
+	DiskCheckpointListParams,
+	DiskCheckpointRestoreParams,
+	DiskCheckpointDeleteParams,
+} from './disk-checkpoint.ts';
+export {
+	DiskCheckpointInfoSchema,
+	CreateDiskCheckpointResponseSchema,
+	ListDiskCheckpointsResponseSchema,
+	RestoreDiskCheckpointResponseSchema,
+	DeleteDiskCheckpointResponseSchema,
+	diskCheckpointCreate,
+	diskCheckpointList,
+	diskCheckpointRestore,
+	diskCheckpointDelete,
+} from './disk-checkpoint.ts';
 export type { SandboxPauseParams } from './pause.ts';
 export { PauseResponseSchema, sandboxPause } from './pause.ts';
 export type { SandboxResumeParams } from './resume.ts';

package/src/api/sandbox/snapshot-build.ts

@@ -28,6 +28,12 @@ export const SnapshotBuildFileBaseSchema = z
 			.optional()
 			.describe('Snapshot name (alphanumeric, underscores, dashes only)'),
 		description: z.string().optional().describe('Human-readable description of the snapshot'),
+		dir: z
+			.string()
+			.optional()
+			.describe(
+				'Subdirectory to use as the build context for file resolution (relative to the CLI directory argument)'
+			),
 		dependencies: z
 			.array(z.string())
 			.optional()

package/src/api/services/index.ts

@@ -0,0 +1 @@
+export * from './stats.ts';

package/src/api/services/stats.ts

@@ -0,0 +1,211 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { StructuredError } from '@agentuity/core';
+
+// --- Error ---
+
+export const ServiceStatsError = StructuredError('ServiceStatsError')<{
+	message: string;
+}>();
+
+// --- Per-Service Stat Schemas ---
+
+export const KeyValueStatSchema = z.object({
+	namespaceCount: z.number(),
+	keyCount: z.number(),
+	totalSizeBytes: z.number(),
+});
+
+export const VectorStatSchema = z.object({
+	namespaceCount: z.number(),
+	documentCount: z.number(),
+	totalSizeBytes: z.number(),
+});
+
+export const QueueStatSchema = z.object({
+	queueCount: z.number(),
+	totalMessages: z.number(),
+	totalDlq: z.number(),
+});
+
+export const StreamStatSchema = z.object({
+	streamCount: z.number(),
+	totalSizeBytes: z.number(),
+});
+
+export const SandboxStatSchema = z.object({
+	totalActive: z.number(),
+	running: z.number(),
+	idle: z.number(),
+	creating: z.number(),
+	totalExecutions: z.number(),
+	totalCpuTimeMs: z.number(),
+	totalMemoryByteSec: z.number(),
+	totalNetworkEgressBytes: z.number(),
+});
+
+export const EmailStatSchema = z.object({
+	addressCount: z.number(),
+	inboundCount: z.number(),
+	outboundCount: z.number(),
+	outboundSuccess: z.number(),
+	outboundFailed: z.number(),
+});
+
+export const TaskStatSchema = z.object({
+	total: z.number(),
+	open: z.number(),
+	inProgress: z.number(),
+	closed: z.number(),
+});
+
+export const ScheduleStatSchema = z.object({
+	scheduleCount: z.number(),
+	totalDeliveries: z.number(),
+	successDeliveries: z.number(),
+	failedDeliveries: z.number(),
+});
+
+export const DatabaseStatSchema = z.object({
+	databaseCount: z.number(),
+	totalTableCount: z.number(),
+	totalRecordCount: z.number(),
+	totalSizeBytes: z.number(),
+});
+
+// --- Aggregate Schema ---
+
+export const ServiceStatsDataSchema = z.object({
+	services: z.object({
+		database: DatabaseStatSchema.optional(),
+		keyvalue: KeyValueStatSchema.optional(),
+		vector: VectorStatSchema.optional(),
+		queue: QueueStatSchema.optional(),
+		stream: StreamStatSchema.optional(),
+		sandbox: SandboxStatSchema.optional(),
+		email: EmailStatSchema.optional(),
+		task: TaskStatSchema.optional(),
+		schedule: ScheduleStatSchema.optional(),
+	}),
+});
+
+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 interface ServiceStatsOptions {
+	/**
+	 * Filter to a specific service. If omitted, returns stats for all services.
+	 */
+	service?: ServiceName;
+	/**
+	 * Start time filter (ISO 8601 timestamp).
+	 */
+	start?: string;
+	/**
+	 * End time filter (ISO 8601 timestamp).
+	 */
+	end?: string;
+	/**
+	 * For CLI auth: sets x-agentuity-orgid header.
+	 * Required when using CLI token auth (bearer tokens without embedded org).
+	 */
+	orgIdHeader?: string;
+}
+
+// --- 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/2026-02-26/${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',
+	});
+}

package/src/api/webhook/deliveries.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import {
+	type ListWebhookDeliveriesRequest,
+	type WebhookApiOptions,
+	type WebhookDelivery,
+	WebhookDeliverySchema,
+} from './types.ts';
+import {
+	buildWebhookHeaders,
+	WebhookError,
+	webhookApiPath,
+	webhookApiPathWithQuery,
+	withWebhookErrorHandling,
+} from './util.ts';
+
+export const WebhookDeliveryResponseSchema = APIResponseSchema(WebhookDeliverySchema);
+export const WebhookDeliveriesListResponseSchema = APIResponseSchema(
+	z.array(WebhookDeliverySchema)
+);
+
+/**
+ * List deliveries for a webhook with optional pagination.
+ *
+ * Deliveries represent attempts to forward a received webhook payload to a destination.
+ *
+ * @param client - The API client instance
+ * @param webhookId - The webhook ID (prefixed with wh_)
+ * @param params - Optional pagination parameters
+ * @param options - Optional API options (e.g., orgId)
+ * @returns Object containing the list of deliveries
+ * @throws {WebhookNotFoundError} If the webhook does not exist
+ * @throws {WebhookError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const { deliveries } = await listWebhookDeliveries(client, 'wh_abc123', { limit: 10 });
+ * for (const delivery of deliveries) {
+ *   console.log(`Delivery ${delivery.id}: ${delivery.status}`);
+ * }
+ * ```
+ */
+export async function listWebhookDeliveries(
+	client: APIClient,
+	webhookId: string,
+	params?: ListWebhookDeliveriesRequest,
+	options?: WebhookApiOptions
+): Promise<{ deliveries: WebhookDelivery[] }> {
+	const searchParams = new URLSearchParams();
+	if (params?.limit !== undefined) {
+		searchParams.set('limit', String(params.limit));
+	}
+	if (params?.offset !== undefined) {
+		searchParams.set('offset', String(params.offset));
+	}
+
+	const queryString = searchParams.toString();
+	const url = webhookApiPathWithQuery('delivery-list', queryString || undefined, webhookId);
+	const resp = await withWebhookErrorHandling(
+		() =>
+			client.get(
+				url,
+				WebhookDeliveriesListResponseSchema,
+				undefined,
+				buildWebhookHeaders(options?.orgId)
+			),
+		{ webhookId }
+	);
+
+	if (resp.success) {
+		return { deliveries: resp.data };
+	}
+
+	throw new WebhookError({
+		webhookId,
+		message: resp.message || 'Failed to list webhook deliveries',
+	});
+}
+
+/**
+ * Retry a failed webhook delivery.
+ *
+ * Re-attempts delivery of a webhook payload to the destination. This creates
+ * a new delivery attempt for the same receipt and destination.
+ *
+ * @param client - The API client instance
+ * @param webhookId - The webhook ID (prefixed with wh_)
+ * @param deliveryId - The delivery ID to retry (prefixed with whdv_)
+ * @param options - Optional API options (e.g., orgId)
+ * @returns The new delivery attempt
+ * @throws {WebhookDeliveryNotFoundError} If the delivery does not exist
+ * @throws {WebhookNotFoundError} If the webhook does not exist
+ * @throws {WebhookError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const delivery = await retryWebhookDelivery(client, 'wh_abc123', 'whdv_def456');
+ * console.log(`Retry delivery ${delivery.id}: ${delivery.status}`);
+ * ```
+ */
+export async function retryWebhookDelivery(
+	client: APIClient,
+	webhookId: string,
+	deliveryId: string,
+	options?: WebhookApiOptions
+): Promise<WebhookDelivery> {
+	const url = webhookApiPath('delivery-retry', webhookId, deliveryId);
+	const resp = await withWebhookErrorHandling(
+		() =>
+			client.post(
+				url,
+				{},
+				WebhookDeliveryResponseSchema,
+				z.object({}),
+				undefined,
+				buildWebhookHeaders(options?.orgId)
+			),
+		{ webhookId, deliveryId }
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new WebhookError({
+		webhookId,
+		message: resp.message || 'Failed to retry webhook delivery',
+	});
+}