@agentuity/core 1.0.41 → 1.0.42

package/src/services/sandbox/types.ts

@@ -843,6 +843,106 @@ export interface SandboxService {
 	snapshot: SnapshotService;
 }
 
+// ===== API Reference Schemas =====
+
+/**
+ * Request body for updating sandbox environment variables.
+ */
+export const SandboxEnvUpdateRequestSchema = z.object({
+	/** Key-value pairs. Set value to null to delete a variable. */
+	env: z
+		.record(z.string(), z.string().nullable())
+		.describe('Key-value pairs. Set value to null to delete a variable.'),
+});
+export type SandboxEnvUpdateRequest = z.infer<typeof SandboxEnvUpdateRequestSchema>;
+
+/**
+ * Response data for updating sandbox environment variables.
+ */
+export const SandboxEnvUpdateResponseSchema = z.object({
+	/** Current environment after update */
+	env: z.record(z.string(), z.string()).describe('Current environment after update'),
+});
+export type SandboxEnvUpdateResponse = z.infer<typeof SandboxEnvUpdateResponseSchema>;
+
+/**
+ * Response data for sandbox status check (mirrors private SandboxStatusDataSchema in getStatus.ts).
+ */
+export const SandboxStatusResponseDataSchema = z.object({
+	/** Unique identifier for the sandbox */
+	sandboxId: z.string().describe('Unique identifier for the sandbox.'),
+	/** Current status of the sandbox */
+	status: z.string().describe('Current status of the sandbox.'),
+	/** Exit code from the last execution, if terminated */
+	exitCode: z.number().optional().describe('Exit code from the last execution, if terminated.'),
+});
+export type SandboxStatusResponseData = z.infer<typeof SandboxStatusResponseDataSchema>;
+
+/**
+ * Request body for initializing a snapshot build (mirrors private _SnapshotBuildInitParamsSchema in snapshot.ts).
+ */
+export const SnapshotBuildInitRequestSchema = z.object({
+	/** Runtime identifier (name:tag or runtime ID) */
+	runtime: z.string().describe('Runtime identifier (name:tag or runtime ID)'),
+	/** Display name for the snapshot */
+	name: z.string().optional().describe('Display name for the snapshot'),
+	/** Tag for the snapshot */
+	tag: z.string().optional().describe('Tag for the snapshot'),
+	/** Description of the snapshot */
+	description: z.string().optional().describe('Description of the snapshot'),
+	/** SHA-256 hash of snapshot content for change detection */
+	contentHash: z
+		.string()
+		.optional()
+		.describe('SHA-256 hash of snapshot content for change detection'),
+	/** Force rebuild even if content is unchanged */
+	force: z.boolean().optional().describe('Force rebuild even if content is unchanged'),
+	/** Request encryption for the snapshot archive */
+	encrypt: z.boolean().optional().describe('Request encryption for the snapshot archive'),
+	/** Make snapshot public (enables virus scanning, disables encryption) */
+	public: z
+		.boolean()
+		.optional()
+		.describe('Make snapshot public (enables virus scanning, disables encryption)'),
+});
+export type SnapshotBuildInitRequest = z.infer<typeof SnapshotBuildInitRequestSchema>;
+
+/**
+ * Request body for finalizing a snapshot build (mirrors private _SnapshotBuildFinalizeParamsSchema in snapshot.ts).
+ */
+export const SnapshotBuildFinalizeRequestSchema = z.object({
+	/** Total size of the snapshot in bytes */
+	sizeBytes: z.number().describe('Total size of the snapshot in bytes'),
+	/** Number of files in the snapshot */
+	fileCount: z.number().describe('Number of files in the snapshot'),
+	/** Array of file metadata */
+	files: z.array(SnapshotFileInfoSchema).describe('Array of file metadata'),
+	/** List of apt packages to install */
+	dependencies: z.array(z.string()).optional().describe('List of apt packages to install'),
+	/** List of npm/bun packages to install globally */
+	packages: z
+		.array(z.string())
+		.optional()
+		.describe('List of npm/bun packages to install globally'),
+	/** Environment variables to set */
+	env: z.record(z.string(), z.string()).optional().describe('Environment variables to set'),
+	/** User-defined metadata key-value pairs */
+	metadata: z
+		.record(z.string(), z.string())
+		.optional()
+		.describe('User-defined metadata key-value pairs'),
+});
+export type SnapshotBuildFinalizeRequest = z.infer<typeof SnapshotBuildFinalizeRequestSchema>;
+
+/**
+ * Request body for updating a snapshot tag.
+ */
+export const SnapshotTagUpdateRequestSchema = z.object({
+	/** New tag or null to remove tag */
+	tag: z.string().nullable().describe('New tag or null to remove tag'),
+});
+export type SnapshotTagUpdateRequest = z.infer<typeof SnapshotTagUpdateRequestSchema>;
+
 /** Structured error for sandbox operations */
 export const SandboxError = StructuredError('SandboxError')<{
 	sandboxId?: string;

package/src/services/schedule/api-reference.ts

@@ -0,0 +1,228 @@
+import type { Service } from '../api-reference.ts';
+import {
+	CreateScheduleDestinationParamsSchema,
+	CreateScheduleParamsSchema,
+	ScheduleCreateResultSchema,
+	ScheduleDeliveryListResultSchema,
+	ScheduleGetResultSchema,
+	ScheduleListResultSchema,
+	UpdateScheduleParamsSchema,
+} from './service.ts';
+import { ScheduleCreateDestinationResultSchema, ScheduleUpdateResultSchema } from './types.ts';
+
+const service: Service = {
+	name: 'Schedules',
+	slug: 'schedules',
+	description:
+		'Create and manage cron-based scheduled jobs with destinations and delivery tracking',
+	endpoints: [
+		{
+			id: 'create-schedule',
+			title: 'Create Schedule',
+			sectionTitle: 'Schedule Management',
+			method: 'POST',
+			path: '/schedule/create',
+			description: 'Create a new cron-based schedule with optional destinations.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'Schedule creation payload.',
+				fields: { schema: CreateScheduleParamsSchema },
+			},
+			responseDescription: 'Returns the created schedule and its destinations.',
+			responseFields: { schema: ScheduleCreateResultSchema },
+			statuses: [
+				{ code: 201, description: 'Schedule created' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+			],
+			examplePath: '/schedule/create',
+			exampleBody: {
+				name: 'Daily Report',
+				expression: '0 9 * * *',
+				destinations: [{ type: 'url', config: { url: 'https://example.com/webhook' } }],
+			},
+		},
+		{
+			id: 'list-schedules',
+			title: 'List Schedules',
+			sectionTitle: 'Schedule Management',
+			method: 'GET',
+			path: '/schedule/list',
+			description: 'List all schedules with optional pagination.',
+			pathParams: [],
+			queryParams: [
+				{
+					name: 'limit',
+					type: 'number',
+					description: 'Max results (max 500)',
+					required: false,
+				},
+				{ name: 'offset', type: 'number', description: 'Pagination offset', required: false },
+			],
+			requestBody: null,
+			responseDescription: 'Returns paginated list of schedules.',
+			responseFields: { schema: ScheduleListResultSchema },
+			statuses: [
+				{ code: 200, description: 'Schedules returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+			],
+			examplePath: '/schedule/list',
+		},
+		{
+			id: 'get-schedule',
+			title: 'Get Schedule',
+			sectionTitle: 'Schedule Management',
+			method: 'GET',
+			path: '/schedule/get/{scheduleId}',
+			description: 'Get a specific schedule by ID.',
+			pathParams: [
+				{
+					name: 'scheduleId',
+					type: 'string',
+					description: 'Schedule ID (sch_ prefix)',
+					required: true,
+				},
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns the schedule object.',
+			responseFields: { schema: ScheduleGetResultSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Schedule returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Schedule not found' },
+			],
+			examplePath: '/schedule/get/sch_abc123',
+		},
+		{
+			id: 'update-schedule',
+			title: 'Update Schedule',
+			sectionTitle: 'Schedule Management',
+			method: 'PUT',
+			path: '/schedule/update/{scheduleId}',
+			description: "Update a schedule's name, description, or cron expression.",
+			pathParams: [
+				{ name: 'scheduleId', type: 'string', description: 'Schedule ID', required: true },
+			],
+			queryParams: [],
+			requestBody: {
+				description: 'Fields to update.',
+				fields: { schema: UpdateScheduleParamsSchema },
+			},
+			responseDescription: 'Returns the updated schedule.',
+			responseFields: { schema: ScheduleUpdateResultSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Schedule updated' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Schedule not found' },
+			],
+			examplePath: '/schedule/update/sch_abc123',
+			exampleBody: { expression: '0 */6 * * *' },
+		},
+		{
+			id: 'delete-schedule',
+			title: 'Delete Schedule',
+			sectionTitle: 'Schedule Management',
+			method: 'DELETE',
+			path: '/schedule/delete/{scheduleId}',
+			description: 'Delete a schedule and all associated destinations and delivery history.',
+			pathParams: [
+				{ name: 'scheduleId', type: 'string', description: 'Schedule ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription:
+				'Deletes the schedule and all associated destinations and delivery history.',
+			statuses: [
+				{ code: 204, description: 'Schedule deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Schedule not found' },
+			],
+			examplePath: '/schedule/delete/sch_abc123',
+		},
+		{
+			id: 'create-schedule-destination',
+			title: 'Create Destination',
+			sectionTitle: 'Destinations',
+			method: 'POST',
+			path: '/schedule/destinations/create/{scheduleId}',
+			description: 'Add a destination to a schedule.',
+			pathParams: [
+				{ name: 'scheduleId', type: 'string', description: 'Schedule ID', required: true },
+			],
+			queryParams: [],
+			requestBody: {
+				description: 'Destination creation payload.',
+				fields: { schema: CreateScheduleDestinationParamsSchema },
+			},
+			responseDescription: 'Returns the created destination.',
+			responseFields: { schema: ScheduleCreateDestinationResultSchema, stripRequired: true },
+			statuses: [
+				{ code: 201, description: 'Destination created' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Schedule not found' },
+			],
+			examplePath: '/schedule/destinations/create/sch_abc123',
+			exampleBody: {
+				type: 'url',
+				config: { url: 'https://example.com/callback', method: 'POST' },
+			},
+		},
+		{
+			id: 'delete-schedule-destination',
+			title: 'Delete Destination',
+			sectionTitle: 'Destinations',
+			method: 'DELETE',
+			path: '/schedule/destinations/delete/{destinationId}',
+			description: 'Delete a destination from a schedule.',
+			pathParams: [
+				{
+					name: 'destinationId',
+					type: 'string',
+					description: 'Destination ID (sdst_ prefix)',
+					required: true,
+				},
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 204, description: 'Destination deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Destination not found' },
+			],
+			examplePath: '/schedule/destinations/delete/sdst_abc123',
+		},
+		{
+			id: 'list-schedule-deliveries',
+			title: 'List Deliveries',
+			sectionTitle: 'Deliveries',
+			method: 'GET',
+			path: '/schedule/deliveries/{scheduleId}',
+			description: 'List delivery attempts for a schedule.',
+			pathParams: [
+				{ name: 'scheduleId', type: 'string', description: 'Schedule ID', required: true },
+			],
+			queryParams: [
+				{
+					name: 'limit',
+					type: 'number',
+					description: 'Maximum results to return',
+					required: false,
+				},
+				{ name: 'offset', type: 'number', description: 'Pagination offset', required: false },
+			],
+			requestBody: null,
+			responseDescription: 'Returns delivery attempts with status, retries, and error details.',
+			responseFields: { schema: ScheduleDeliveryListResultSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Deliveries returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Schedule not found' },
+			],
+			examplePath: '/schedule/deliveries/sch_abc123',
+		},
+	],
+};
+
+export default service;

package/src/services/schedule/types.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { ScheduleSchema, ScheduleDestinationSchema } from './service.ts';
+
+// ============================================================================
+// API Response Schemas for Schedule Service
+// ============================================================================
+
+/**
+ * Response schema for the update-schedule endpoint.
+ */
+export const ScheduleUpdateResultSchema = z.object({
+	/** The updated schedule record */
+	schedule: ScheduleSchema.describe('The updated schedule record.'),
+});
+
+export type ScheduleUpdateResult = z.infer<typeof ScheduleUpdateResultSchema>;
+
+/**
+ * Response schema for the create-schedule-destination endpoint.
+ */
+export const ScheduleCreateDestinationResultSchema = z.object({
+	/** The newly created destination record */
+	destination: ScheduleDestinationSchema.describe('The newly created destination record.'),
+});
+
+export type ScheduleCreateDestinationResult = z.infer<typeof ScheduleCreateDestinationResultSchema>;

package/src/services/session/api-reference.ts

@@ -0,0 +1,160 @@
+import type { Service } from '../api-reference.ts';
+import { EnrichedSessionDataSchema } from './get.ts';
+import { SessionSchema } from './list.ts';
+import { LogSchema } from './logs.ts';
+
+const service: Service = {
+	name: 'Sessions',
+	slug: 'sessions',
+	description: 'View agent execution sessions with timing, cost, and observability data',
+	endpoints: [
+		{
+			id: 'list-sessions',
+			title: 'List Sessions',
+			method: 'GET',
+			path: '/session',
+			description: 'List sessions with optional filtering, sorting, and pagination.',
+			pathParams: [],
+			queryParams: [
+				{
+					name: 'limit',
+					type: 'number',
+					description: 'Max results, default 10',
+					required: false,
+				},
+				{ name: 'offset', type: 'number', description: 'Pagination offset', required: false },
+				{
+					name: 'sort',
+					type: 'string',
+					description: '\\`created\\`, \\`updated\\`, \\`duration\\`, or \\`startTime\\`',
+					required: false,
+				},
+				{
+					name: 'direction',
+					type: 'string',
+					description: '\\`asc\\` or \\`desc\\`',
+					required: false,
+				},
+				{
+					name: 'orgId',
+					type: 'string',
+					description: 'Filter by organization ID',
+					required: false,
+				},
+				{
+					name: 'projectId',
+					type: 'string',
+					description: 'Filter by project ID',
+					required: false,
+				},
+				{
+					name: 'deploymentId',
+					type: 'string',
+					description: 'Filter by deployment ID',
+					required: false,
+				},
+				{
+					name: 'trigger',
+					type: 'string',
+					description:
+						'\\`agent\\`, \\`api\\`, \\`email\\`, \\`sms\\`, \\`cron\\`, \\`manual\\`, \\`discord\\`, or \\`websocket\\`',
+					required: false,
+				},
+				{ name: 'env', type: 'string', description: 'Filter by environment', required: false },
+				{
+					name: 'devmode',
+					type: 'boolean',
+					description: 'Filter by devmode status',
+					required: false,
+				},
+				{
+					name: 'success',
+					type: 'boolean',
+					description: 'Filter by success status',
+					required: false,
+				},
+				{
+					name: 'threadId',
+					type: 'string',
+					description: 'Filter by thread ID',
+					required: false,
+				},
+				{
+					name: 'agentIdentifier',
+					type: 'string',
+					description: 'Filter by agent identifier',
+					required: false,
+				},
+				{
+					name: 'startAfter',
+					type: 'string',
+					description: 'ISO 8601 start-after filter',
+					required: false,
+				},
+				{
+					name: 'startBefore',
+					type: 'string',
+					description: 'ISO 8601 start-before filter',
+					required: false,
+				},
+				{
+					name: 'metadata',
+					type: 'string',
+					description: 'JSON-serialized filter',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Returns sessions matching the specified filters.',
+			responseFields: { schema: SessionSchema },
+			statuses: [
+				{ code: 200, description: 'Sessions returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+			],
+			examplePath: '/session',
+		},
+		{
+			id: 'get-session',
+			title: 'Get Session',
+			method: 'GET',
+			path: '/session/{id}',
+			description:
+				'Retrieve a specific session with enriched data including agent info, eval runs, and route details.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Session ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription:
+				'Returns the session with enriched data including agent info, eval runs, and route details.',
+			responseFields: { schema: EnrichedSessionDataSchema },
+			statuses: [
+				{ code: 200, description: 'Session returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Session not found' },
+			],
+			examplePath: '/session/ses_abc123',
+		},
+		{
+			id: 'get-session-logs',
+			title: 'Get Session Logs',
+			sectionTitle: 'Logs',
+			method: 'GET',
+			path: '/cli/session/{id}/logs',
+			description: 'Retrieve log entries for a specific session.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Session ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns log entries for the session.',
+			responseFields: { schema: LogSchema },
+			statuses: [
+				{ code: 200, description: 'Logs returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Session not found' },
+			],
+			examplePath: '/cli/session/ses_abc123/logs',
+			ttlNote:
+				'This endpoint uses the App API base URL (`api.agentuity.com`), not the regional Catalyst URL.',
+		},
+	],
+};
+
+export default service;