@agentuity/core 2.0.13 → 2.0.15

package/src/services/aigateway/service.ts

@@ -0,0 +1,355 @@
+import { z } from 'zod';
+import { StructuredError } from '../../error.ts';
+import { FetchAdapter } from '../adapter.ts';
+import { buildUrl, toServiceException, toPayload } from '../_util.ts';
+
+const AIGatewayModelsResponseError = StructuredError('AIGatewayModelsResponseError')<{
+	error?: string;
+	message?: string;
+}>();
+
+export const AIGatewayPricingSchema = z.object({
+	input: z.number().describe('Input token price.'),
+	output: z.number().describe('Output token price.'),
+	cached_input: z.number().optional().describe('Cached input token price.'),
+	unit: z.string().describe('Pricing unit.'),
+	currency: z.string().describe('Pricing currency.'),
+});
+
+export type AIGatewayPricing = z.infer<typeof AIGatewayPricingSchema>;
+
+export const AIGatewayModelProviderSchema = z.object({
+	env: z.array(z.string()).optional().describe('Environment variables used by this provider.'),
+	api: z.string().optional().describe('Provider API URL.'),
+	doc: z.string().optional().describe('Provider documentation URL.'),
+	logo_url: z.string().optional().describe('Provider logo URL.'),
+});
+
+export type AIGatewayModelProvider = z.infer<typeof AIGatewayModelProviderSchema>;
+
+export const AIGatewayModelSchema = z.object({
+	id: z.string().describe('Model identifier.'),
+	name: z.string().describe('Display name.'),
+	created: z.number().optional().describe('Unix timestamp when the model was created.'),
+	api: z.string().optional().describe('Compatible provider API shape.'),
+	family: z.string().optional().describe('Model family.'),
+	context_window: z.number().optional().describe('Maximum context window.'),
+	max_output_tokens: z.number().optional().describe('Maximum output token count.'),
+	input_modalities: z.array(z.string()).optional().describe('Supported input modalities.'),
+	output_modalities: z.array(z.string()).optional().describe('Supported output modalities.'),
+	attachment: z.boolean().optional().describe('Whether the model supports attachments.'),
+	reasoning: z.boolean().optional().describe('Whether the model supports reasoning.'),
+	tool_call: z.boolean().optional().describe('Whether the model supports tool calls.'),
+	temperature: z.boolean().optional().describe('Whether the model supports temperature.'),
+	knowledge: z.string().optional().describe('Knowledge cutoff or label.'),
+	open_weights: z.boolean().optional().describe('Whether the model has open weights.'),
+	provider: AIGatewayModelProviderSchema.optional().describe('Provider metadata.'),
+	pricing: AIGatewayPricingSchema.optional().describe('Model pricing.'),
+});
+
+export type AIGatewayModel = z.infer<typeof AIGatewayModelSchema>;
+
+export const AIGatewayModelsSchema = z.record(z.string(), z.array(AIGatewayModelSchema));
+export type AIGatewayModels = z.infer<typeof AIGatewayModelsSchema>;
+
+export const AIGatewayModelsResponseSchema = z.object({
+	success: z.boolean(),
+	data: AIGatewayModelsSchema.optional(),
+	message: z.string().optional(),
+	error: z.string().optional(),
+});
+
+export type AIGatewayModelsResponse = z.infer<typeof AIGatewayModelsResponseSchema>;
+
+export const AIGatewayChatMessageSchema = z.object({
+	role: z.enum(['system', 'developer', 'user', 'assistant', 'tool']),
+	content: z
+		.union([
+			z.string(),
+			z.array(
+				z
+					.object({
+						type: z.string(),
+					})
+					.catchall(z.unknown())
+			),
+			z.null(),
+		])
+		.optional(),
+	name: z.string().optional(),
+	tool_call_id: z.string().optional(),
+	tool_calls: z.array(z.unknown()).optional(),
+});
+
+export type AIGatewayChatMessage = z.infer<typeof AIGatewayChatMessageSchema>;
+
+const missingCompletionInputMessage = 'either prompt or messages must be provided';
+
+function hasCompletionInput(params: { prompt?: string | string[]; messages?: unknown[] }): boolean {
+	if (params.messages && params.messages.length > 0) {
+		return true;
+	}
+	if (typeof params.prompt === 'string') {
+		return params.prompt.trim().length > 0;
+	}
+	if (Array.isArray(params.prompt)) {
+		return params.prompt.length > 0 && params.prompt.every((item) => item.trim().length > 0);
+	}
+	return false;
+}
+
+export const AIGatewayChatCompletionParamsSchema = z
+	.object({
+		model: z.string().describe('Model to use for the completion.'),
+		messages: z.array(AIGatewayChatMessageSchema).optional().describe('Messages to complete.'),
+		prompt: z
+			.union([z.string(), z.array(z.string())])
+			.optional()
+			.describe('Prompt to complete.'),
+		temperature: z.number().optional(),
+		top_p: z.number().optional(),
+		max_tokens: z.number().optional(),
+		stream: z.boolean().optional(),
+		stop: z.union([z.string(), z.array(z.string())]).optional(),
+	})
+	.catchall(z.unknown())
+	.superRefine((params, ctx) => {
+		if (!hasCompletionInput(params)) {
+			ctx.addIssue({
+				code: 'custom',
+				message: missingCompletionInputMessage,
+				path: ['messages'],
+			});
+		}
+	});
+
+export type AIGatewayChatCompletionParams = z.infer<typeof AIGatewayChatCompletionParamsSchema>;
+
+export const AIGatewayChatCompletionStreamParamsSchema =
+	AIGatewayChatCompletionParamsSchema.safeExtend({
+		stream: z.literal(true).describe('Enable Server-Sent Events streaming.'),
+	});
+
+export type AIGatewayChatCompletionStreamParams = z.infer<
+	typeof AIGatewayChatCompletionStreamParamsSchema
+>;
+
+export const AIGatewayChatCompletionSchema = z
+	.object({
+		id: z.string().optional(),
+		object: z.string().optional(),
+		created: z.number().optional(),
+		model: z.string().optional(),
+		choices: z.array(z.unknown()).optional(),
+		usage: z.unknown().optional(),
+		agentuity: z
+			.object({
+				headers: z
+					.record(z.string(), z.string())
+					.optional()
+					.describe('AI Gateway response headers captured from the HTTP response.'),
+				cost: z
+					.object({
+						total: z.number().optional().describe('Total estimated gateway cost in USD.'),
+						promptTokens: z
+							.number()
+							.optional()
+							.describe('Prompt token count used for gateway billing.'),
+						completionTokens: z
+							.number()
+							.optional()
+							.describe('Completion token count used for gateway billing.'),
+					})
+					.optional()
+					.describe('Parsed AI Gateway cost information when available.'),
+			})
+			.optional()
+			.describe('Agentuity AI Gateway metadata.'),
+	})
+	.catchall(z.unknown());
+
+export type AIGatewayChatCompletion = z.infer<typeof AIGatewayChatCompletionSchema>;
+
+export const AIGatewayResponseMetadataSchema = z.object({
+	headers: z.record(z.string(), z.string()).optional(),
+	cost: z
+		.object({
+			total: z.number().optional(),
+			promptTokens: z.number().optional(),
+			completionTokens: z.number().optional(),
+		})
+		.optional(),
+});
+
+export type AIGatewayResponseMetadata = z.infer<typeof AIGatewayResponseMetadataSchema>;
+
+export type AIGatewayStreamingCompletion = {
+	stream: ReadableStream<Uint8Array>;
+	metadata: Promise<AIGatewayResponseMetadata>;
+};
+
+function parseNumber(value: string | undefined): number | undefined {
+	if (value === undefined || value.trim() === '') {
+		return undefined;
+	}
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function extractGatewayMetadataFromHeaders(headers: Headers): AIGatewayResponseMetadata {
+	const captured: Record<string, string> = {};
+	for (const [key, value] of headers.entries()) {
+		const lower = key.toLowerCase();
+		if (
+			lower.startsWith('x-gateway-') ||
+			(lower.startsWith('x-agentuity-') &&
+				(lower.includes('cost') || lower.includes('token') || lower.includes('usage')))
+		) {
+			captured[lower] = value;
+		}
+	}
+
+	const total = parseNumber(captured['x-gateway-cost']);
+	const promptTokens = parseNumber(captured['x-gateway-prompt-tokens']);
+	const completionTokens = parseNumber(captured['x-gateway-completion-tokens']);
+	const cost =
+		total !== undefined || promptTokens !== undefined || completionTokens !== undefined
+			? { total, promptTokens, completionTokens }
+			: undefined;
+
+	return {
+		...(Object.keys(captured).length > 0 ? { headers: captured } : {}),
+		...(cost ? { cost } : {}),
+	};
+}
+
+async function extractGatewayMetadata(response: Response): Promise<AIGatewayResponseMetadata> {
+	const metadata = extractGatewayMetadataFromHeaders(response.headers);
+	const trailers = (response as Response & { trailers?: Promise<Headers> }).trailers;
+	if (trailers) {
+		try {
+			const trailerMetadata = extractGatewayMetadataFromHeaders(await trailers);
+			const cost =
+				metadata.cost || trailerMetadata.cost
+					? { ...(metadata.cost ?? {}), ...(trailerMetadata.cost ?? {}) }
+					: undefined;
+			return {
+				headers: { ...metadata.headers, ...trailerMetadata.headers },
+				...(cost ? { cost } : {}),
+			};
+		} catch {
+			// Some runtimes expose a trailers promise but reject when trailers are unavailable.
+		}
+	}
+	return metadata;
+}
+
+function attachGatewayMetadata<T extends Record<string, unknown>>(
+	payload: T,
+	metadata: AIGatewayResponseMetadata
+): T {
+	if (!metadata.headers && !metadata.cost) {
+		return payload;
+	}
+	return {
+		...payload,
+		agentuity: {
+			...(typeof payload.agentuity === 'object' && payload.agentuity !== null
+				? payload.agentuity
+				: {}),
+			...metadata,
+		},
+	};
+}
+
+export class AIGatewayService {
+	constructor(
+		readonly baseUrl: string,
+		readonly adapter: FetchAdapter
+	) {}
+
+	async listModels(): Promise<AIGatewayModels> {
+		const method = 'GET';
+		const url = buildUrl(this.baseUrl, '/models');
+		const response = await this.adapter.invoke<AIGatewayModelsResponse>(url, {
+			method,
+			telemetry: { name: 'aigateway.models.list' },
+		});
+		if (!response.ok) {
+			throw await toServiceException(method, url, response.response);
+		}
+		const payload = AIGatewayModelsResponseSchema.parse(response.data);
+		if (!payload.success) {
+			throw new AIGatewayModelsResponseError({
+				message: payload.error || payload.message || 'AI Gateway failed to list models',
+				error: payload.error,
+			});
+		}
+		if (!payload.data) {
+			throw new AIGatewayModelsResponseError({
+				message: 'AI Gateway model response did not include data',
+			});
+		}
+		return payload.data;
+	}
+
+	async complete(params: AIGatewayChatCompletionParams): Promise<AIGatewayChatCompletion> {
+		const method = 'POST';
+		const url = buildUrl(this.baseUrl, '/');
+		const [body, contentType] = await toPayload(
+			AIGatewayChatCompletionParamsSchema.parse(params)
+		);
+		const response = await this.adapter.invoke<AIGatewayChatCompletion>(url, {
+			method,
+			body,
+			contentType,
+			telemetry: { name: 'aigateway.completions.create' },
+		});
+		if (!response.ok) {
+			throw await toServiceException(method, url, response.response);
+		}
+		const payload = attachGatewayMetadata(
+			response.data as Record<string, unknown>,
+			await extractGatewayMetadata(response.response)
+		);
+		return AIGatewayChatCompletionSchema.parse(payload);
+	}
+
+	async streamComplete(
+		params: AIGatewayChatCompletionParams
+	): Promise<ReadableStream<Uint8Array>> {
+		return (await this.streamCompleteWithMetadata(params)).stream;
+	}
+
+	async streamCompleteWithMetadata(
+		params: AIGatewayChatCompletionParams
+	): Promise<AIGatewayStreamingCompletion> {
+		const method = 'POST';
+		const url = buildUrl(this.baseUrl, '/');
+		const [body, contentType] = await toPayload(
+			AIGatewayChatCompletionParamsSchema.parse({ ...params, stream: true })
+		);
+		const response = await this.adapter.invoke<never>(url, {
+			method,
+			body,
+			contentType,
+			headers: { Accept: 'text/event-stream' },
+			binary: true,
+			telemetry: { name: 'aigateway.completions.stream' },
+		});
+		if (!response.ok) {
+			throw await toServiceException(method, url, response.response);
+		}
+		if (!response.response.body) {
+			throw await toServiceException(
+				method,
+				url,
+				new Response('Streaming response did not include a body', { status: 502 })
+			);
+		}
+		return {
+			stream: response.response.body,
+			metadata: extractGatewayMetadata(response.response),
+		};
+	}
+}

package/src/services/api-reference.ts

@@ -60,6 +60,7 @@ interface Endpoint {
 	exampleBody?: string | object;
 	exampleHeaders?: Record<string, string>;
 	ttlNote?: string;
+	public?: boolean;
 }
 
 interface Service {

package/src/services/coder/client.ts

@@ -32,6 +32,7 @@ import {
 	coderUpdateCustomAgent,
 } from './agents.ts';
 import {
+	coderCreateCustomSkill,
 	coderCreateSkillBucket,
 	coderDeleteSavedSkill,
 	coderDeleteSkillBucket,
@@ -79,6 +80,7 @@ import type {
 	CoderSkillBucket,
 	CoderSkillBucketListResponse,
 	CoderCreateSkillBucketRequest,
+	CoderCreateCustomSkillRequest,
 	CoderUpdateCustomAgentRequest,
 	CoderCreateWorkspaceRequest,
 	CoderUpdateWorkspaceRequest,
@@ -449,6 +451,14 @@ export class CoderClient {
 		return coderSaveSkill(client, { body });
 	}
 
+	/**
+	 * Creates a custom SKILL.md-backed skill in the caller's library.
+	 */
+	async createCustomSkill(body: CoderCreateCustomSkillRequest): Promise<CoderSavedSkill> {
+		const client = await this.#getClient();
+		return coderCreateCustomSkill(client, { body });
+	}
+
 	/**
 	 * Deletes a saved skill from the caller's library.
 	 */

package/src/services/coder/skills.ts

@@ -2,12 +2,14 @@ import { z } from 'zod/v4';
 import { type APIClient } from '../api.ts';
 import {
 	CoderCreateSkillBucketRequestSchema,
+	CoderCreateCustomSkillRequestSchema,
 	CoderSavedSkillListResponseSchema,
 	CoderSavedSkillSchema,
 	CoderSaveSkillRequestSchema,
 	CoderSkillBucketListResponseSchema,
 	CoderSkillBucketSchema,
 	type CoderCreateSkillBucketRequest,
+	type CoderCreateCustomSkillRequest,
 	type CoderSavedSkill,
 	type CoderSavedSkillListResponse,
 	type CoderSaveSkillRequest,
@@ -59,6 +61,23 @@ export async function coderSaveSkill(
 	return resp.skill;
 }
 
+export async function coderCreateCustomSkill(
+	client: APIClient,
+	params: { body: CoderCreateCustomSkillRequest }
+): Promise<CoderSavedSkill> {
+	const body = CoderCreateCustomSkillRequestSchema.parse(params.body);
+	return coderSaveSkill(client, {
+		body: {
+			source: 'custom',
+			repo: 'custom',
+			skillId: body.skillId,
+			name: body.name,
+			...(body.description !== undefined ? { description: body.description } : {}),
+			content: body.content,
+		},
+	});
+}
+
 export async function coderDeleteSavedSkill(
 	client: APIClient,
 	params: { skillId: string }

package/src/services/coder/types.ts

@@ -42,12 +42,18 @@ export const CoderSessionBucketSchema = z
 	.describe('Derived bucket used for session listing and UI grouping');
 export type CoderSessionBucket = z.infer<typeof CoderSessionBucketSchema>;
 
+export const CoderWorkspaceSystemPromptModeSchema = z
+	.enum(['append', 'overwrite'])
+	.describe('How a workspace system prompt is applied to the Lead agent prompt');
+export type CoderWorkspaceSystemPromptMode = z.infer<typeof CoderWorkspaceSystemPromptModeSchema>;
+
 export const CoderSkillRefSchema = z
 	.object({
 		skillId: z.string().describe('Unique skill identifier'),
 		repo: z.string().describe('Repository slug for the skill source'),
 		name: z.string().optional().describe('Human-readable skill name'),
 		url: z.string().optional().describe('Canonical URL for the skill repository or page'),
+		content: z.string().optional().describe('Inline SKILL.md content for custom skills'),
 	})
 	.describe('Skill reference attached to a coder session');
 export type CoderSkillRef = z.infer<typeof CoderSkillRefSchema>;
@@ -83,6 +89,7 @@ export const CoderSavedSkillSchema = z
 		description: z.string().optional().describe('Skill description'),
 		url: z.string().optional().describe('Skill URL'),
 		installs: z.number().optional().describe('Number of installs'),
+		content: z.string().optional().describe('Inline SKILL.md content for custom skills'),
 		createdAt: z.string().describe('Creation timestamp (ISO-8601)'),
 		updatedAt: z.string().describe('Last update timestamp (ISO-8601)'),
 	})
@@ -123,6 +130,16 @@ export const CoderWorkspaceDetailSchema = z
 			.optional()
 			.default('')
 			.describe('Shell script run while preparing workspace snapshots'),
+		systemPrompt: z
+			.string()
+			.optional()
+			.default('')
+			.describe(
+				'Additional Lead agent system prompt applied to sessions created from this workspace'
+			),
+		systemPromptMode: CoderWorkspaceSystemPromptModeSchema.optional()
+			.default('append')
+			.describe('Whether the workspace system prompt appends to or overwrites the Lead prompt'),
 		snapshot: z
 			.object({
 				status: z.string().describe('Workspace snapshot build status'),
@@ -353,6 +370,7 @@ function hasWorkspaceSelections(input: {
 	repos?: unknown[];
 	dependencies?: unknown[];
 	setupScript?: string;
+	systemPrompt?: string;
 	savedSkillIds?: unknown[];
 	skillBucketIds?: unknown[];
 	enabledAgents?: unknown[];
@@ -361,6 +379,7 @@ function hasWorkspaceSelections(input: {
 		(input.repos?.length ?? 0) > 0 ||
 		(input.dependencies?.length ?? 0) > 0 ||
 		Boolean(input.setupScript?.trim()) ||
+		Boolean(input.systemPrompt?.trim()) ||
 		(input.savedSkillIds?.length ?? 0) > 0 ||
 		(input.skillBucketIds?.length ?? 0) > 0 ||
 		(input.enabledAgents?.length ?? 0) > 0
@@ -381,6 +400,15 @@ export const CoderCreateWorkspaceRequestSchema = z
 			.string()
 			.optional()
 			.describe('Shell script run while preparing workspace snapshots'),
+		systemPrompt: z
+			.string()
+			.optional()
+			.describe(
+				'Additional Lead agent system prompt applied to sessions created from this workspace'
+			),
+		systemPromptMode: CoderWorkspaceSystemPromptModeSchema.optional().describe(
+			'Whether the workspace system prompt appends to or overwrites the Lead prompt'
+		),
 		savedSkillIds: z.array(z.string()).optional().describe('Saved skill IDs'),
 		skillBucketIds: z.array(z.string()).optional().describe('Skill bucket IDs'),
 		enabledAgents: z
@@ -390,7 +418,7 @@ export const CoderCreateWorkspaceRequestSchema = z
 	})
 	.refine(hasWorkspaceSelections, {
 		message:
-			'A workspace needs at least one repo, dependency, setup script, saved skill, skill bucket, or agent',
+			'A workspace needs at least one repo, dependency, setup script, system prompt, saved skill, skill bucket, or agent',
 	})
 	.describe('Request body for creating a workspace');
 export type CoderCreateWorkspaceRequest = z.infer<typeof CoderCreateWorkspaceRequestSchema>;
@@ -409,6 +437,15 @@ export const CoderUpdateWorkspaceRequestSchema = z
 			.string()
 			.optional()
 			.describe('Shell script run while preparing workspace snapshots'),
+		systemPrompt: z
+			.string()
+			.optional()
+			.describe(
+				'Additional Lead agent system prompt applied to sessions created from this workspace'
+			),
+		systemPromptMode: CoderWorkspaceSystemPromptModeSchema.optional().describe(
+			'Whether the workspace system prompt appends to or overwrites the Lead prompt'
+		),
 		savedSkillIds: z.array(z.string()).optional().describe('Saved skill IDs'),
 		skillBucketIds: z.array(z.string()).optional().describe('Skill bucket IDs'),
 		enabledAgents: z
@@ -529,6 +566,19 @@ export const CoderSaveSkillRequestSchema = z
 	.describe('Request body for saving a skill to the library');
 export type CoderSaveSkillRequest = z.infer<typeof CoderSaveSkillRequestSchema>;
 
+export const CoderCreateCustomSkillRequestSchema = z
+	.object({
+		skillId: z.string().describe('Skill identifier'),
+		name: z.string().describe('Skill name'),
+		description: z.string().optional().describe('Skill description'),
+		content: z
+			.string()
+			.refine((value) => value.trim().length > 0, 'SKILL.md content is required')
+			.describe('SKILL.md content'),
+	})
+	.describe('Request body for creating a custom skill');
+export type CoderCreateCustomSkillRequest = z.infer<typeof CoderCreateCustomSkillRequestSchema>;
+
 export const CoderCreateSkillBucketRequestSchema = z
 	.object({
 		name: z.string().describe('Skill bucket name'),

package/src/services/config.ts

@@ -6,6 +6,7 @@ export const ServiceUrlsSchema = z
 		keyvalue: z.string().describe('URL for the key-value storage service.'),
 		stream: z.string().describe('URL for the stream service.'),
 		vector: z.string().describe('URL for the vector storage service.'),
+		aigateway: z.string().describe('URL for the AI Gateway service.'),
 		catalyst: z.string().describe('URL for the Catalyst API gateway.'),
 		otel: z.string().describe('URL for the OpenTelemetry collector.'),
 		sandbox: z.string().describe('URL for the sandbox service.'),
@@ -42,6 +43,7 @@ export function getServiceUrls(region?: string): ServiceUrls {
 		keyvalue: getEnv('AGENTUITY_KEYVALUE_URL') || transportUrl,
 		stream: getEnv('AGENTUITY_STREAM_URL') || buildRegionalURL(resolvedRegion, 'streams'),
 		vector: getEnv('AGENTUITY_VECTOR_URL') || transportUrl,
+		aigateway: getEnv('AGENTUITY_AIGATEWAY_URL') || buildRegionalURL(resolvedRegion, 'aigateway'),
 		catalyst: getEnv('AGENTUITY_CATALYST_URL') || transportUrl,
 		otel: getEnv('AGENTUITY_OTLP_URL') || buildRegionalURL(resolvedRegion, 'otel'),
 		sandbox: getEnv('AGENTUITY_SANDBOX_URL') || transportUrl,

package/src/services/index.ts

@@ -1,4 +1,5 @@
 export * from './adapter.ts';
+export * from './aigateway/index.ts';
 export * from './auth/index.ts';
 export * from './email/index.ts';
 export * from './exception.ts';

package/src/services/sandbox/getStatus.ts

@@ -23,6 +23,7 @@ export const SandboxGetStatusParamsSchema = z.object({
 		.nonnegative()
 		.optional()
 		.describe('Maximum time in milliseconds to wait for the desired status'),
+	signal: z.custom<AbortSignal>().optional().describe('abort signal for cancellation'),
 });
 
 export type SandboxGetStatusParams = z.infer<typeof SandboxGetStatusParamsSchema>;
@@ -36,7 +37,7 @@ export async function sandboxGetStatus(
 	client: APIClient,
 	params: SandboxGetStatusParams
 ): Promise<SandboxStatusResult> {
-	const { sandboxId, orgId, waitForStatus, waitMs } = params;
+	const { sandboxId, orgId, waitForStatus, waitMs, signal } = params;
 	const queryParams = new URLSearchParams();
 	if (orgId) {
 		queryParams.set('orgId', orgId);
@@ -55,7 +56,8 @@ export async function sandboxGetStatus(
 
 	const resp = await client.get<z.infer<typeof SandboxStatusResponseSchema>>(
 		url,
-		SandboxStatusResponseSchema
+		SandboxStatusResponseSchema,
+		signal
 	);
 
 	if (resp.success) {