@agentuity/core 1.0.32 → 1.0.34

package/src/services/{schedule.ts → schedule/service.ts}

@@ -1,5 +1,6 @@
-import { FetchAdapter } from './adapter.ts';
-import { buildUrl, toServiceException } from './_util.ts';
+import { FetchAdapter } from '../adapter.ts';
+import { buildUrl, toServiceException } from '../_util.ts';
+import { z } from 'zod';
 
 /**
  * A scheduled job that fires at intervals defined by a cron expression.
@@ -8,38 +9,38 @@ import { buildUrl, toServiceException } from './_util.ts';
  * {@link ScheduleDestination | destinations} that receive HTTP callbacks
  * when the schedule fires.
  */
-export interface Schedule {
+export const ScheduleSchema = z.object({
 	/**
 	 * Unique identifier for the schedule.
 	 *
 	 * @remarks Prefixed with `sch_`.
 	 */
-	id: string;
+	id: z.string().describe('Unique identifier for the schedule.'),
 
 	/**
 	 * ISO 8601 timestamp when the schedule was created.
 	 */
-	created_at: string;
+	created_at: z.string().describe('ISO 8601 timestamp when the schedule was created.'),
 
 	/**
 	 * ISO 8601 timestamp when the schedule was last modified.
 	 */
-	updated_at: string;
+	updated_at: z.string().describe('ISO 8601 timestamp when the schedule was last modified.'),
 
 	/**
 	 * ID of the user who created the schedule.
 	 */
-	created_by: string;
+	created_by: z.string().describe('ID of the user who created the schedule.'),
 
 	/**
 	 * Human-readable name for the schedule.
 	 */
-	name: string;
+	name: z.string().describe('Human-readable name for the schedule.'),
 
 	/**
 	 * Optional description of the schedule's purpose.
 	 */
-	description: string | null;
+	description: z.string().nullable().describe("Optional description of the schedule's purpose."),
 
 	/**
 	 * A cron expression defining the schedule's firing interval
@@ -48,7 +49,7 @@ export interface Schedule {
 	 * @remarks Validated on creation and update by the server.
 	 * Supports standard five-field cron syntax including step values (e.g., every 5 minutes).
 	 */
-	expression: string;
+	expression: z.string().describe("A cron expression defining the schedule's firing interval"),
 
 	/**
 	 * ISO 8601 timestamp of the next scheduled execution.
@@ -56,46 +57,52 @@ export interface Schedule {
 	 * @remarks Automatically computed from the cron expression. Updated each time
 	 * the schedule fires or the expression is changed.
 	 */
-	due_date: string;
-}
+	due_date: z.string().describe('ISO 8601 timestamp of the next scheduled execution.'),
+});
+
+export type Schedule = z.infer<typeof ScheduleSchema>;
 
 /**
  * A delivery target for a scheduled job.
  *
  * When the schedule fires, an HTTP request is sent to each of its destinations.
  */
-export interface ScheduleDestination {
+export const ScheduleDestinationSchema = z.object({
 	/**
 	 * Unique identifier for the destination.
 	 *
 	 * @remarks Prefixed with `sdst_`.
 	 */
-	id: string;
+	id: z.string().describe('Unique identifier for the destination.'),
 
 	/**
 	 * The ID of the parent schedule.
 	 */
-	schedule_id: string;
+	schedule_id: z.string().describe('The ID of the parent schedule.'),
 
 	/**
 	 * ISO 8601 timestamp when the destination was created.
 	 */
-	created_at: string;
+	created_at: z.string().describe('ISO 8601 timestamp when the destination was created.'),
 
 	/**
 	 * ISO 8601 timestamp when the destination was last updated.
 	 */
-	updated_at: string;
+	updated_at: z.string().describe('ISO 8601 timestamp when the destination was last updated.'),
 
 	/**
 	 * ID of the user who created the destination.
 	 */
-	created_by: string;
+	created_by: z.string().describe('ID of the user who created the destination.'),
 
 	/**
 	 * The destination type: `'url'` for HTTP endpoints or `'sandbox'` for Agentuity sandbox execution.
 	 */
-	type: 'url' | 'sandbox';
+	type: z
+		.enum(['url', 'sandbox'])
+		.describe(
+			"The destination type: `'url'` for HTTP endpoints or `'sandbox'` for Agentuity sandbox execution."
+		),
 
 	/**
 	 * Type-specific destination configuration.
@@ -107,8 +114,10 @@ export interface ScheduleDestination {
 	 * ```
 	 * For `'sandbox'` type: sandbox-specific configuration.
 	 */
-	config: Record<string, unknown>;
-}
+	config: z.record(z.string(), z.unknown()).describe('Type-specific destination configuration.'),
+});
+
+export type ScheduleDestination = z.infer<typeof ScheduleDestinationSchema>;
 
 /**
  * A record of a single delivery attempt for a scheduled execution.
@@ -116,61 +125,75 @@ export interface ScheduleDestination {
  * Each time a schedule fires, one delivery record is created per destination.
  * Failed deliveries may be retried automatically.
  */
-export interface ScheduleDelivery {
+export const ScheduleDeliverySchema = z.object({
 	/**
 	 * Unique identifier for the delivery attempt.
 	 */
-	id: string;
+	id: z.string().describe('Unique identifier for the delivery attempt.'),
 
 	/**
 	 * ISO 8601 timestamp when the delivery was attempted.
 	 */
-	date: string;
+	date: z.string().describe('ISO 8601 timestamp when the delivery was attempted.'),
 
 	/**
 	 * The ID of the schedule that triggered this delivery.
 	 */
-	schedule_id: string;
+	schedule_id: z.string().describe('The ID of the schedule that triggered this delivery.'),
 
 	/**
 	 * The ID of the destination this delivery was sent to.
 	 */
-	schedule_destination_id: string;
+	schedule_destination_id: z
+		.string()
+		.describe('The ID of the destination this delivery was sent to.'),
 
 	/**
 	 * Delivery status: `'pending'` (queued), `'success'` (delivered), or `'failed'` (delivery error).
 	 */
-	status: 'pending' | 'success' | 'failed';
+	status: z
+		.enum(['pending', 'success', 'failed'])
+		.describe(
+			"Delivery status: `'pending'` (queued), `'success'` (delivered), or `'failed'` (delivery error)."
+		),
 
 	/**
 	 * Number of retry attempts made for this delivery.
 	 */
-	retries: number;
+	retries: z.number().describe('Number of retry attempts made for this delivery.'),
 
 	/**
 	 * Error message if the delivery failed, `null` on success.
 	 */
-	error: string | null;
+	error: z
+		.string()
+		.nullable()
+		.describe('Error message if the delivery failed, `null` on success.'),
 
 	/**
 	 * The response received from the destination, or `null` if no response.
 	 */
-	response: Record<string, unknown> | null;
-}
+	response: z
+		.record(z.string(), z.unknown())
+		.nullable()
+		.describe('The response received from the destination, or `null` if no response.'),
+});
+
+export type ScheduleDelivery = z.infer<typeof ScheduleDeliverySchema>;
 
 /**
  * Parameters for creating a new schedule.
  */
-export interface CreateScheduleParams {
+export const CreateScheduleParamsSchema = z.object({
 	/**
 	 * Human-readable name for the schedule.
 	 */
-	name: string;
+	name: z.string().describe('Human-readable name for the schedule.'),
 
 	/**
 	 * Optional description of the schedule's purpose.
 	 */
-	description?: string;
+	description: z.string().optional().describe("Optional description of the schedule's purpose."),
 
 	/**
 	 * Cron expression defining when the schedule fires
@@ -179,7 +202,7 @@ export interface CreateScheduleParams {
 	 * @remarks Must be a valid cron expression. Validated by the server on creation.
 	 * Supports standard five-field cron syntax including step values.
 	 */
-	expression: string;
+	expression: z.string().describe('Cron expression defining when the schedule fires'),
 
 	/**
 	 * Optional array of destinations to create alongside the schedule.
@@ -187,17 +210,26 @@ export interface CreateScheduleParams {
 	 * @remarks Destinations are created atomically with the schedule — if any destination
 	 * fails validation, the entire creation is rolled back.
 	 */
-	destinations?: CreateScheduleDestinationParams[];
-}
+	destinations: z
+		.array(z.lazy(() => CreateScheduleDestinationParamsSchema))
+		.optional()
+		.describe('Optional array of destinations to create alongside the schedule.'),
+});
+
+export type CreateScheduleParams = z.infer<typeof CreateScheduleParamsSchema>;
 
 /**
  * Parameters for creating a new destination on a schedule.
  */
-export interface CreateScheduleDestinationParams {
+export const CreateScheduleDestinationParamsSchema = z.object({
 	/**
 	 * The destination type: `'url'` for HTTP endpoints or `'sandbox'` for Agentuity sandbox execution.
 	 */
-	type: 'url' | 'sandbox';
+	type: z
+		.enum(['url', 'sandbox'])
+		.describe(
+			"The destination type: `'url'` for HTTP endpoints or `'sandbox'` for Agentuity sandbox execution."
+		),
 
 	/**
 	 * Type-specific destination configuration.
@@ -209,87 +241,106 @@ export interface CreateScheduleDestinationParams {
 	 * ```
 	 * For `'sandbox'` type: sandbox-specific configuration.
 	 */
-	config: Record<string, unknown>;
-}
+	config: z.record(z.string(), z.unknown()).describe('Type-specific destination configuration.'),
+});
+
+export type CreateScheduleDestinationParams = z.infer<typeof CreateScheduleDestinationParamsSchema>;
 
 /**
  * Parameters for updating an existing schedule.
  *
  * All fields are optional; only provided fields are updated.
  */
-export interface UpdateScheduleParams {
+export const UpdateScheduleParamsSchema = z.object({
 	/**
 	 * Updated human-readable name for the schedule.
 	 */
-	name?: string;
+	name: z.string().optional().describe('Updated human-readable name for the schedule.'),
 
 	/**
 	 * Updated description.
 	 */
-	description?: string;
+	description: z.string().optional().describe('Updated description.'),
 
 	/**
 	 * Updated cron expression. If changed, the `due_date` is automatically recomputed.
 	 *
 	 * @remarks Must be a valid cron expression. Validated by the server on update.
 	 */
-	expression?: string;
-}
+	expression: z
+		.string()
+		.optional()
+		.describe('Updated cron expression. If changed, the `due_date` is automatically recomputed.'),
+});
+
+export type UpdateScheduleParams = z.infer<typeof UpdateScheduleParamsSchema>;
 
 /**
  * Paginated list of schedules.
  */
-export interface ScheduleListResult {
+export const ScheduleListResultSchema = z.object({
 	/**
 	 * Array of schedule records for the current page.
 	 */
-	schedules: Schedule[];
+	schedules: z.array(ScheduleSchema).describe('Array of schedule records for the current page.'),
 
 	/**
 	 * Total number of schedules across all pages.
 	 */
-	total: number;
-}
+	total: z.number().describe('Total number of schedules across all pages.'),
+});
+
+export type ScheduleListResult = z.infer<typeof ScheduleListResultSchema>;
 
 /**
  * A schedule with its associated destinations.
  */
-export interface ScheduleGetResult {
+export const ScheduleGetResultSchema = z.object({
 	/**
 	 * The schedule record.
 	 */
-	schedule: Schedule;
+	schedule: ScheduleSchema.describe('The schedule record.'),
 
 	/**
 	 * Array of destinations configured for this schedule.
 	 */
-	destinations: ScheduleDestination[];
-}
+	destinations: z
+		.array(ScheduleDestinationSchema)
+		.describe('Array of destinations configured for this schedule.'),
+});
+
+export type ScheduleGetResult = z.infer<typeof ScheduleGetResultSchema>;
 
 /**
  * Result of creating a schedule, including any destinations created atomically.
  */
-export interface ScheduleCreateResult {
+export const ScheduleCreateResultSchema = z.object({
 	/**
 	 * The newly created schedule record.
 	 */
-	schedule: Schedule;
+	schedule: ScheduleSchema.describe('The newly created schedule record.'),
 
 	/**
 	 * Array of destinations that were created alongside the schedule.
 	 */
-	destinations: ScheduleDestination[];
-}
+	destinations: z
+		.array(ScheduleDestinationSchema)
+		.describe('Array of destinations that were created alongside the schedule.'),
+});
+
+export type ScheduleCreateResult = z.infer<typeof ScheduleCreateResultSchema>;
 
 /**
  * List of delivery attempts for a schedule.
  */
-export interface ScheduleDeliveryListResult {
+export const ScheduleDeliveryListResultSchema = z.object({
 	/**
 	 * Array of delivery attempt records.
 	 */
-	deliveries: ScheduleDelivery[];
-}
+	deliveries: z.array(ScheduleDeliverySchema).describe('Array of delivery attempt records.'),
+});
+
+export type ScheduleDeliveryListResult = z.infer<typeof ScheduleDeliveryListResultSchema>;
 
 /**
  * Client for the Agentuity Schedule service.
@@ -361,7 +412,7 @@ export class ScheduleService {
 	 * ```
 	 */
 	async create(params: CreateScheduleParams): Promise<ScheduleCreateResult> {
-		const url = buildUrl(this.#baseUrl, '/schedule/create/2026-02-24');
+		const url = buildUrl(this.#baseUrl, '/schedule/create');
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<ScheduleCreateResult>(url, {
 			method: 'POST',
@@ -412,9 +463,7 @@ export class ScheduleService {
 			qs.set('offset', String(params.offset));
 		}
 
-		const path = qs.toString()
-			? `/schedule/list/2026-02-24?${qs.toString()}`
-			: '/schedule/list/2026-02-24';
+		const path = qs.toString() ? `/schedule/list?${qs.toString()}` : '/schedule/list';
 		const url = buildUrl(this.#baseUrl, path);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<ScheduleListResult>(url, {
@@ -452,10 +501,7 @@ export class ScheduleService {
 	 * ```
 	 */
 	async get(scheduleId: string): Promise<ScheduleGetResult> {
-		const url = buildUrl(
-			this.#baseUrl,
-			`/schedule/get/2026-02-24/${encodeURIComponent(scheduleId)}`
-		);
+		const url = buildUrl(this.#baseUrl, `/schedule/get/${encodeURIComponent(scheduleId)}`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<ScheduleGetResult>(url, {
 			method: 'GET',
@@ -501,10 +547,7 @@ export class ScheduleService {
 	 * ```
 	 */
 	async update(scheduleId: string, params: UpdateScheduleParams): Promise<{ schedule: Schedule }> {
-		const url = buildUrl(
-			this.#baseUrl,
-			`/schedule/update/2026-02-24/${encodeURIComponent(scheduleId)}`
-		);
+		const url = buildUrl(this.#baseUrl, `/schedule/update/${encodeURIComponent(scheduleId)}`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<{ schedule: Schedule }>(url, {
 			method: 'PUT',
@@ -539,10 +582,7 @@ export class ScheduleService {
 	 * ```
 	 */
 	async delete(scheduleId: string): Promise<void> {
-		const url = buildUrl(
-			this.#baseUrl,
-			`/schedule/delete/2026-02-24/${encodeURIComponent(scheduleId)}`
-		);
+		const url = buildUrl(this.#baseUrl, `/schedule/delete/${encodeURIComponent(scheduleId)}`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<void>(url, {
 			method: 'DELETE',
@@ -588,7 +628,7 @@ export class ScheduleService {
 	): Promise<{ destination: ScheduleDestination }> {
 		const url = buildUrl(
 			this.#baseUrl,
-			`/schedule/destinations/create/2026-02-24/${encodeURIComponent(scheduleId)}`
+			`/schedule/destinations/create/${encodeURIComponent(scheduleId)}`
 		);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<{ destination: ScheduleDestination }>(url, {
@@ -627,7 +667,7 @@ export class ScheduleService {
 	async deleteDestination(destinationId: string): Promise<void> {
 		const url = buildUrl(
 			this.#baseUrl,
-			`/schedule/destinations/delete/2026-02-24/${encodeURIComponent(destinationId)}`
+			`/schedule/destinations/delete/${encodeURIComponent(destinationId)}`
 		);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<void>(url, {
@@ -681,7 +721,7 @@ export class ScheduleService {
 			qs.set('offset', String(params.offset));
 		}
 
-		const basePath = `/schedule/deliveries/2026-02-24/${encodeURIComponent(scheduleId)}`;
+		const basePath = `/schedule/deliveries/${encodeURIComponent(scheduleId)}`;
 		const path = qs.toString() ? `${basePath}?${qs.toString()}` : basePath;
 		const url = buildUrl(this.#baseUrl, path);
 		const signal = AbortSignal.timeout(30_000);

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';