@agentuity/core 1.0.41 → 1.0.43

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

@@ -0,0 +1,124 @@
+import type { Service } from '../api-reference.ts';
+import { EvaluationSchema } from './list.ts';
+import { EvalRunSchema } from './run-list.ts';
+
+const service: Service = {
+	name: 'Evaluations',
+	slug: 'evaluations',
+	description: 'List and retrieve evaluations and their run history',
+	endpoints: [
+		{
+			id: 'list-evaluations',
+			title: 'List Evaluations',
+			method: 'GET',
+			path: '/cli/eval',
+			description:
+				'List evaluations with optional filtering by organization, project, or agent.',
+			pathParams: [],
+			queryParams: [
+				{
+					name: 'orgId',
+					type: 'string',
+					description: 'Filter by organization ID',
+					required: false,
+				},
+				{
+					name: 'projectId',
+					type: 'string',
+					description: 'Filter by project ID',
+					required: false,
+				},
+				{ name: 'agentId', type: 'string', description: 'Filter by agent ID', required: false },
+			],
+			requestBody: null,
+			responseDescription: 'Array of evaluation objects.',
+			responseFields: { schema: EvaluationSchema },
+			statuses: [
+				{ code: 200, description: 'Evaluations returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+			],
+			examplePath: '/cli/eval',
+		},
+		{
+			id: 'get-evaluation',
+			title: 'Get Evaluation',
+			method: 'GET',
+			path: '/cli/eval/{id}',
+			description: 'Get a specific evaluation by ID.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Evaluation ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Evaluation object.',
+			statuses: [
+				{ code: 200, description: 'Evaluation returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Evaluation not found' },
+			],
+			examplePath: '/cli/eval/eval_abc123',
+		},
+		{
+			id: 'list-eval-runs',
+			title: 'List Eval Runs',
+			sectionTitle: 'Eval Runs',
+			method: 'GET',
+			path: '/cli/eval-run',
+			description: 'List evaluation runs with optional filtering.',
+			pathParams: [],
+			queryParams: [
+				{
+					name: 'orgId',
+					type: 'string',
+					description: 'Filter by organization ID',
+					required: false,
+				},
+				{
+					name: 'projectId',
+					type: 'string',
+					description: 'Filter by project ID',
+					required: false,
+				},
+				{ name: 'agentId', type: 'string', description: 'Filter by agent ID', required: false },
+				{
+					name: 'evalId',
+					type: 'string',
+					description: 'Filter by evaluation ID',
+					required: false,
+				},
+				{
+					name: 'sessionId',
+					type: 'string',
+					description: 'Filter by session ID',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Array of evaluation run objects.',
+			responseFields: { schema: EvalRunSchema },
+			statuses: [
+				{ code: 200, description: 'Eval runs returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+			],
+			examplePath: '/cli/eval-run',
+		},
+		{
+			id: 'get-eval-run',
+			title: 'Get Eval Run',
+			sectionTitle: 'Eval Runs',
+			method: 'GET',
+			path: '/cli/eval-run/{id}',
+			description: 'Get a specific evaluation run by ID.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Eval run ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Evaluation run object.',
+			statuses: [
+				{ code: 200, description: 'Eval run returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Eval run not found' },
+			],
+			examplePath: '/cli/eval-run/er_abc123',
+		},
+	],
+};
+
+export default service;

package/src/services/index.ts

@@ -16,6 +16,8 @@ export * from './apikey/index.ts';
 export * from './db/index.ts';
 export * from './eval/index.ts';
 export * from './machine/index.ts';
+export * from './monitoring/index.ts';
+export * from './oauth/index.ts';
 export * from './org/index.ts';
 export * from './project/index.ts';
 export * from './queue/index.ts';

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

@@ -0,0 +1,280 @@
+import { KeyValueStatsPaginatedSchema, KeyValueStatsSchema } from './service.ts';
+import { CreateNamespaceApiRequestSchema, KeyValueItemMetadataSchema } from './types.ts';
+import type { Service } from '../api-reference.ts';
+
+const service: Service = {
+	name: 'Key-Value Storage',
+	slug: 'key-value',
+	description: 'Store and retrieve arbitrary data by key within namespaces',
+	endpoints: [
+		{
+			id: 'get-value',
+			title: 'Get Value',
+			method: 'GET',
+			path: '/kv/{namespace}/{key}',
+			description:
+				'Retrieve a stored value by its namespace and key. Returns the raw value with the original content type.',
+			pathParams: [
+				{ name: 'namespace', type: 'string', description: 'The namespace name' },
+				{ name: 'key', type: 'string', description: 'The key to retrieve' },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription:
+				'Returns the raw stored value with the original content type. The response body is the value itself (not wrapped in JSON).',
+			responseHeaders: [
+				{
+					name: 'Content-Type',
+					description:
+						'MIME type of the stored value (e.g., `application/json`, `text/plain`, `application/octet-stream`)',
+				},
+				{
+					name: 'x-expires-at',
+					description: 'ISO 8601 expiration timestamp. Omitted if the key does not expire.',
+				},
+			],
+			statuses: [
+				{ code: 200, description: 'Value found and returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Key does not exist in the namespace' },
+			],
+			examplePath: '/kv/my-namespace/user-123',
+		},
+		{
+			id: 'set-value',
+			title: 'Store Value',
+			method: 'PUT',
+			path: '/kv/{namespace}/{key}[/{ttl}]',
+			description:
+				"Store a value in key-value storage. The namespace is auto-created if it doesn't exist. Set the Content-Type header to match your data format.",
+			pathParams: [
+				{
+					name: 'namespace',
+					type: 'string',
+					description: 'The namespace name (auto-created if not exists)',
+				},
+				{ name: 'key', type: 'string', description: 'The key to store the value under' },
+				{
+					name: 'ttl',
+					type: 'number',
+					description:
+						'Optional TTL in seconds (60–31,536,000). Omit for namespace default. Use `0` for no expiration.',
+					required: false,
+				},
+			],
+			queryParams: [],
+			requestBody: {
+				description: 'The raw value to store. Can be any content type — JSON, text, or binary.',
+			},
+			responseDescription: 'Empty response on success.',
+			responseHeaders: [],
+			statuses: [
+				{ code: 200, description: 'Value stored successfully' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 402, description: 'Payment required — upgrade to a paid plan' },
+			],
+			examplePath: '/kv/my-namespace/user-123',
+			exampleBody: { name: 'Alice', email: 'alice@example.com' },
+			ttlNote:
+				'TTL behavior:\n- **Omitted**: Key inherits namespace default TTL (7 days if not configured)\n- **`0`**: Key never expires\n- **60–31,536,000**: Expires after specified seconds (values outside range are clamped)',
+		},
+		{
+			id: 'delete-value',
+			title: 'Delete Value',
+			method: 'DELETE',
+			path: '/kv/{namespace}/{key}',
+			description: 'Delete a specific key from a namespace.',
+			pathParams: [
+				{ name: 'namespace', type: 'string', description: 'The namespace name' },
+				{ name: 'key', type: 'string', description: 'The key to delete' },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			responseHeaders: [],
+			statuses: [
+				{ code: 200, description: 'Key deleted successfully' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/kv/my-namespace/user-123',
+		},
+		{
+			id: 'search-keys',
+			title: 'Search Keys',
+			method: 'GET',
+			path: '/kv/search/{namespace}/{keyword}',
+			description:
+				'Search for keys matching a keyword within a namespace. Returns matching keys with their values and metadata.',
+			pathParams: [
+				{ name: 'namespace', type: 'string', description: 'The namespace to search in' },
+				{
+					name: 'keyword',
+					type: 'string',
+					description: 'The keyword to search for in key names',
+				},
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'JSON object mapping key names to their values and metadata.',
+			responseFields: {
+				schema: KeyValueItemMetadataSchema,
+				prefix: '{key}',
+				stripRequired: true,
+			},
+			statuses: [
+				{ code: 200, description: 'Search results returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/kv/search/my-namespace/user',
+		},
+		{
+			id: 'get-keys',
+			title: 'List Keys',
+			method: 'GET',
+			path: '/kv/keys/{namespace}',
+			description: 'Get all key names in a namespace.',
+			pathParams: [
+				{ name: 'namespace', type: 'string', description: 'The namespace to list keys from' },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'JSON array of key name strings.',
+			responseHeaders: [],
+			statuses: [
+				{ code: 200, description: 'Key list returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/kv/keys/my-namespace',
+		},
+		{
+			id: 'get-namespace-stats',
+			title: 'Get Namespace Stats',
+			method: 'GET',
+			path: '/kv/stats/{namespace}',
+			description: 'Get statistics for a specific namespace including record count and size.',
+			pathParams: [
+				{ name: 'namespace', type: 'string', description: 'The namespace to get stats for' },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'JSON object with namespace statistics.',
+			responseFields: { schema: KeyValueStatsSchema, omit: ['internal'] },
+			statuses: [
+				{ code: 200, description: 'Stats returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/kv/stats/my-namespace',
+		},
+		{
+			id: 'get-all-stats',
+			title: 'List All Namespace Stats',
+			method: 'GET',
+			path: '/kv/stats',
+			description: 'Get statistics for all namespaces with optional pagination and filtering.',
+			pathParams: [],
+			queryParams: [
+				{
+					name: 'limit',
+					type: 'number',
+					description: 'Maximum namespaces to return (default: 100, max: 1000)',
+					required: false,
+				},
+				{
+					name: 'offset',
+					type: 'number',
+					description: 'Number of namespaces to skip (default: 0)',
+					required: false,
+				},
+				{
+					name: 'sort',
+					type: 'string',
+					description: 'Sort field: `name`, `size`, `records`, `created`, or `lastUsed`',
+					required: false,
+				},
+				{
+					name: 'direction',
+					type: 'string',
+					description: 'Sort direction: `asc` or `desc` (default: `desc`)',
+					required: false,
+				},
+				{
+					name: 'name',
+					type: 'string',
+					description: 'Filter namespaces by name substring',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Paginated response with namespace statistics.',
+			responseFields: { schema: KeyValueStatsPaginatedSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Stats returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/kv/stats?limit=10&sort=size&direction=desc',
+		},
+		{
+			id: 'list-namespaces',
+			title: 'List Namespaces',
+			method: 'GET',
+			path: '/kv/namespaces',
+			description:
+				'Get all namespace names (up to 1000, ordered by creation date, most recent first).',
+			pathParams: [],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'JSON array of namespace name strings.',
+			responseHeaders: [],
+			statuses: [
+				{ code: 200, description: 'Namespace list returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/kv/namespaces',
+		},
+		{
+			id: 'create-namespace',
+			title: 'Create Namespace',
+			method: 'POST',
+			path: '/kv/{namespace}',
+			description: 'Create a new namespace with optional default TTL configuration.',
+			pathParams: [
+				{ name: 'namespace', type: 'string', description: 'The namespace name to create' },
+			],
+			queryParams: [],
+			requestBody: {
+				description: 'Optional JSON body with namespace configuration.',
+				fields: { schema: CreateNamespaceApiRequestSchema },
+			},
+			responseDescription: 'Empty response on success.',
+			responseHeaders: [],
+			statuses: [
+				{ code: 200, description: 'Namespace created successfully' },
+				{ code: 401, description: 'Unauthorized' },
+				{ code: 402, description: 'Payment required' },
+			],
+			examplePath: '/kv/my-namespace',
+			exampleBody: { default_ttl_seconds: 86400 },
+		},
+		{
+			id: 'delete-namespace',
+			title: 'Delete Namespace',
+			method: 'DELETE',
+			path: '/kv/{namespace}',
+			description: 'Delete an entire namespace and all its keys.',
+			pathParams: [
+				{ name: 'namespace', type: 'string', description: 'The namespace to delete' },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			responseHeaders: [],
+			statuses: [
+				{ code: 200, description: 'Namespace deleted successfully' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/kv/my-namespace',
+		},
+	],
+};
+
+export default service;

package/src/services/keyvalue/types.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+/** API-level request for creating a namespace (uses snake_case field names) */
+export const CreateNamespaceApiRequestSchema = z.object({
+	default_ttl_seconds: z
+		.number()
+		.optional()
+		.describe(
+			'Default TTL for keys in this namespace (in seconds). If omitted, defaults to 7 days (604,800). Use 0 for keys that never expire.'
+		),
+});
+
+/** Metadata for a key-value item in search results */
+export const KeyValueItemMetadataSchema = z.object({
+	value: z.unknown().describe('The stored value (base64-encoded for binary)'),
+	contentType: z.string().describe('MIME type of the stored value'),
+	size: z.number().describe('Size in bytes'),
+	expiresAt: z.string().nullable().describe('ISO 8601 expiration timestamp'),
+	firstUsed: z.number().nullable().describe('Unix timestamp (ms) of first access'),
+	lastUsed: z.number().nullable().describe('Unix timestamp (ms) of last access'),
+	count: z.number().nullable().describe('Number of times accessed'),
+});
+
+export type CreateNamespaceApiRequest = z.infer<typeof CreateNamespaceApiRequestSchema>;
+export type KeyValueItemMetadata = z.infer<typeof KeyValueItemMetadataSchema>;

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

@@ -0,0 +1,158 @@
+import { MachineSchema } from './machine.ts';
+import {
+	OrgAuthEnrollRequestSchema,
+	OrgAuthEnrollDataSchema,
+	OrgAuthStatusDataSchema,
+} from './types.ts';
+import type { Service } from '../api-reference.ts';
+
+const service: Service = {
+	name: 'Machines',
+	slug: 'machines',
+	description: 'Manage compute nodes and organization authentication enrollment',
+	endpoints: [
+		{
+			id: 'list-machines',
+			title: 'List Machines',
+			sectionTitle: 'Machine Management',
+			method: 'GET',
+			path: '/machine',
+			description: 'List all machines visible to the authenticated user.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns all machines visible to the authenticated user.',
+			statuses: [
+				{ code: 200, description: 'Machines returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+			],
+			examplePath: '/machine',
+		},
+		{
+			id: 'get-machine',
+			title: 'Get Machine',
+			sectionTitle: 'Machine Management',
+			method: 'GET',
+			path: '/machine/{machineId}',
+			description: 'Get details for a specific machine.',
+			pathParams: [
+				{ name: 'machineId', type: 'string', description: 'Machine ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns machine details.',
+			responseFields: { schema: MachineSchema },
+			statuses: [
+				{ code: 200, description: 'Machine returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Machine not found' },
+			],
+			examplePath: '/machine/mch_abc123',
+		},
+		{
+			id: 'delete-machine',
+			title: 'Delete Machine',
+			sectionTitle: 'Machine Management',
+			method: 'DELETE',
+			path: '/machine/{machineId}',
+			description: 'Delete a machine by ID.',
+			pathParams: [
+				{ name: 'machineId', type: 'string', description: 'Machine ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 204, description: 'Machine deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Machine not found' },
+			],
+			examplePath: '/machine/mch_abc123',
+		},
+		{
+			id: 'list-machine-deployments',
+			title: 'List Machine Deployments',
+			sectionTitle: 'Machine Management',
+			method: 'GET',
+			path: '/machine/deployments/{machineId}',
+			description: 'List all deployments currently running on a specific machine.',
+			pathParams: [
+				{ name: 'machineId', type: 'string', description: 'Machine ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns all deployments currently running on the specified machine.',
+			statuses: [
+				{ code: 200, description: 'Deployments returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Machine not found' },
+			],
+			examplePath: '/machine/deployments/mch_abc123',
+		},
+		{
+			id: 'enroll-organization',
+			title: 'Enroll Organization',
+			sectionTitle: 'Auth Enrollment',
+			method: 'POST',
+			path: '/cli/auth/org/enroll',
+			description: 'Enroll an organization for machine authentication.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'Enrollment payload with organization ID and public key.',
+				fields: { schema: OrgAuthEnrollRequestSchema },
+			},
+			responseDescription: 'Returns the enrolled organization ID.',
+			responseFields: { schema: OrgAuthEnrollDataSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Organization enrolled' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+			],
+			examplePath: '/cli/auth/org/enroll',
+			exampleBody: { orgId: 'org_abc123', publicKey: 'ssh-ed25519 AAAA...' },
+		},
+		{
+			id: 'get-enrollment-status',
+			title: 'Get Enrollment Status',
+			sectionTitle: 'Auth Enrollment',
+			method: 'GET',
+			path: '/cli/auth/org/status/{orgId}',
+			description: 'Get the enrollment status for an organization.',
+			pathParams: [
+				{ name: 'orgId', type: 'string', description: 'Organization ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns the enrollment status. A null publicKey means not enrolled.',
+			responseFields: { schema: OrgAuthStatusDataSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Enrollment status returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Organization not found' },
+			],
+			examplePath: '/cli/auth/org/status/org_abc123',
+		},
+		{
+			id: 'unenroll-organization',
+			title: 'Unenroll Organization',
+			sectionTitle: 'Auth Enrollment',
+			method: 'DELETE',
+			path: '/cli/auth/org/unenroll/{orgId}',
+			description: 'Remove enrollment for an organization.',
+			pathParams: [
+				{ name: 'orgId', type: 'string', description: 'Organization ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 204, description: 'Organization unenrolled' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Organization not found' },
+			],
+			examplePath: '/cli/auth/org/unenroll/org_abc123',
+		},
+	],
+};
+
+export default service;

package/src/services/machine/types.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+/** Request payload for enrolling an organization */
+export const OrgAuthEnrollRequestSchema = z.object({
+	orgId: z.string().describe('Organization ID'),
+	publicKey: z.string().describe('Public key for machine authentication'),
+});
+
+/** Response data from enrolling an organization */
+export const OrgAuthEnrollDataSchema = z.object({
+	orgId: z.string().describe('The enrolled organization ID'),
+});
+
+/** Response data from getting enrollment status */
+export const OrgAuthStatusDataSchema = z.object({
+	publicKey: z.string().nullable().describe('Public key or null if not enrolled'),
+});
+
+export type OrgAuthEnrollRequest = z.infer<typeof OrgAuthEnrollRequestSchema>;
+export type OrgAuthEnrollData = z.infer<typeof OrgAuthEnrollDataSchema>;
+export type OrgAuthStatusData = z.infer<typeof OrgAuthStatusDataSchema>;

package/src/services/monitoring/index.ts

@@ -0,0 +1,2 @@
+export * from './types.ts';
+export * from './service.ts';