@agentuity/core 1.0.32 → 1.0.34

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

@@ -1,12 +1,15 @@
-import { FetchAdapter } from './adapter.ts';
-import { buildUrl, toServiceException } from './_util.ts';
-import { StructuredError } from '../error.ts';
-import { safeStringify } from '../json.ts';
+import { FetchAdapter } from '../adapter.ts';
+import { buildUrl, toServiceException } from '../_util.ts';
+import { StructuredError } from '../../error.ts';
+import { safeStringify } from '../../json.ts';
+import { z } from 'zod';
 
 /**
  * Priority level for a task, from highest (`'high'`) to no priority (`'none'`).
  */
-export type TaskPriority = 'high' | 'medium' | 'low' | 'none';
+export const TaskPrioritySchema = z.enum(['high', 'medium', 'low', 'none']);
+
+export type TaskPriority = z.infer<typeof TaskPrioritySchema>;
 
 /**
  * The classification of a task.
@@ -17,7 +20,9 @@ export type TaskPriority = 'high' | 'medium' | 'low' | 'none';
  * - `'bug'` — Defects to be fixed.
  * - `'task'` — General work items.
  */
-export type TaskType = 'epic' | 'feature' | 'enhancement' | 'bug' | 'task';
+export const TaskTypeSchema = z.enum(['epic', 'feature', 'enhancement', 'bug', 'task']);
+
+export type TaskType = z.infer<typeof TaskTypeSchema>;
 
 /**
  * The lifecycle status of a task.
@@ -28,19 +33,20 @@ export type TaskType = 'epic' | 'feature' | 'enhancement' | 'bug' | 'task';
  * - `'closed'` — Resolved and closed.
  * - `'cancelled'` — Abandoned.
  */
-export type TaskStatus = 'open' | 'in_progress' | 'closed' | 'done' | 'cancelled';
+export const TaskStatusSchema = z.enum(['open', 'in_progress', 'closed', 'done', 'cancelled']);
+
+export type TaskStatus = z.infer<typeof TaskStatusSchema>;
 
 /**
  * A lightweight reference to a user or project entity, containing just the ID
  * and display name. Used for creator, assignee, closer, and project associations.
  */
-export interface EntityRef {
-	/** Unique identifier of the referenced entity. */
-	id: string;
+export const EntityRefSchema = z.object({
+	id: z.string().describe('Unique identifier of the referenced entity.'),
+	name: z.string().describe('Human-readable display name of the entity.'),
+});
 
-	/** Human-readable display name of the entity. */
-	name: string;
-}
+export type EntityRef = z.infer<typeof EntityRefSchema>;
 
 /**
  * The type of user entity.
@@ -48,21 +54,22 @@ export interface EntityRef {
  * - `'human'` — A human user.
  * - `'agent'` — An AI agent.
  */
-export type UserType = 'human' | 'agent';
+export const UserTypeSchema = z.enum(['human', 'agent']);
+
+export type UserType = z.infer<typeof UserTypeSchema>;
 
 /**
  * A reference to a user entity with type discrimination.
  * Extends {@link EntityRef} with a {@link UserEntityRef.type | type} field
  * to distinguish between human users and AI agents.
  */
-export interface UserEntityRef extends EntityRef {
-	/**
-	 * The type of user. Defaults to `'human'` if not specified.
-	 *
-	 * @default 'human'
-	 */
-	type?: UserType;
-}
+export const UserEntityRefSchema = EntityRefSchema.extend({
+	type: UserTypeSchema.optional().describe(
+		"The type of user. Defaults to `'human'` if not specified."
+	),
+});
+
+export type UserEntityRef = z.infer<typeof UserEntityRefSchema>;
 
 /**
  * A work item in the task management system.
@@ -76,341 +83,295 @@ export interface UserEntityRef extends EntityRef {
  * the corresponding date field (e.g., {@link Task.open_date | open_date},
  * {@link Task.in_progress_date | in_progress_date}) is set by the server.
  */
-export interface Task {
-	/** Unique identifier for the task. */
-	id: string;
-
-	/** ISO 8601 timestamp when the task was created. */
-	created_at: string;
-
-	/** ISO 8601 timestamp when the task was last modified. */
-	updated_at: string;
-
-	/**
-	 * The task title.
-	 *
-	 * @remarks Must be non-empty and at most 1024 characters.
-	 */
-	title: string;
-
-	/**
-	 * Detailed description of the task.
-	 *
-	 * @remarks Maximum 65,536 characters.
-	 */
-	description?: string;
-
-	/**
-	 * Arbitrary key-value metadata attached to the task.
-	 * Can be used for custom fields, integrations, or filtering.
-	 */
-	metadata?: Record<string, unknown>;
-
-	/** The priority level of the task. */
-	priority: TaskPriority;
-
-	/**
-	 * ID of the parent task, enabling hierarchical task organization
-	 * (e.g., an epic containing features).
-	 */
-	parent_id?: string;
-
-	/** The classification of this task. */
-	type: TaskType;
-
-	/** The current lifecycle status of the task. */
-	status: TaskStatus;
-
-	/** ISO 8601 timestamp when the task was moved to `'open'` status. */
-	open_date?: string;
-
-	/** ISO 8601 timestamp when the task was moved to `'in_progress'` status. */
-	in_progress_date?: string;
-
-	/** ISO 8601 timestamp when the task was closed. */
-	closed_date?: string;
-
-	/**
-	 * ID of the user who created the task.
-	 *
-	 * @remarks Legacy field; prefer {@link Task.creator | creator}.
-	 */
-	created_id: string;
-
-	/**
-	 * ID of the user the task is assigned to.
-	 *
-	 * @remarks Legacy field; prefer {@link Task.assignee | assignee}.
-	 */
-	assigned_id?: string;
-
-	/**
-	 * ID of the user who closed the task.
-	 *
-	 * @remarks Legacy field; prefer {@link Task.closer | closer}.
-	 */
-	closed_id?: string;
-
-	/** Reference to the user who created the task. */
-	creator?: UserEntityRef;
-
-	/** Reference to the user the task is assigned to. */
-	assignee?: UserEntityRef;
-
-	/** Reference to the user who closed the task. */
-	closer?: UserEntityRef;
-
-	/** Reference to the project this task belongs to. */
-	project?: EntityRef;
-
-	/** ISO 8601 timestamp when the task was cancelled. */
-	cancelled_date?: string;
-
-	/** Array of tags associated with this task. */
-	tags?: Tag[];
-
-	/** Array of comments on this task. */
-	comments?: Comment[];
-}
+export const TaskSchema = z.object({
+	id: z.string().describe('Unique identifier for the task.'),
+	created_at: z.string().describe('ISO 8601 timestamp when the task was created.'),
+	updated_at: z.string().describe('ISO 8601 timestamp when the task was last modified.'),
+	title: z.string().describe('The task title.'),
+	description: z.string().optional().describe('Detailed description of the task.'),
+	metadata: z
+		.record(z.string(), z.unknown())
+		.optional()
+		.describe('Arbitrary key-value metadata attached to the task.'),
+	priority: TaskPrioritySchema.describe('The priority level of the task.'),
+	parent_id: z
+		.string()
+		.optional()
+		.describe('ID of the parent task, enabling hierarchical task organization'),
+	type: TaskTypeSchema.describe('The classification of this task.'),
+	status: TaskStatusSchema.describe('The current lifecycle status of the task.'),
+	open_date: z
+		.string()
+		.optional()
+		.describe("ISO 8601 timestamp when the task was moved to `'open'` status."),
+	in_progress_date: z
+		.string()
+		.optional()
+		.describe("ISO 8601 timestamp when the task was moved to `'in_progress'` status."),
+	closed_date: z.string().optional().describe('ISO 8601 timestamp when the task was closed.'),
+	created_id: z.string().describe('ID of the user who created the task.'),
+	assigned_id: z.string().optional().describe('ID of the user the task is assigned to.'),
+	closed_id: z.string().optional().describe('ID of the user who closed the task.'),
+	creator: z
+		.lazy(() => UserEntityRefSchema)
+		.optional()
+		.describe('Reference to the user who created the task.'),
+	assignee: z
+		.lazy(() => UserEntityRefSchema)
+		.optional()
+		.describe('Reference to the user the task is assigned to.'),
+	closer: z
+		.lazy(() => UserEntityRefSchema)
+		.optional()
+		.describe('Reference to the user who closed the task.'),
+	project: EntityRefSchema.optional().describe('Reference to the project this task belongs to.'),
+	cancelled_date: z
+		.string()
+		.optional()
+		.describe('ISO 8601 timestamp when the task was cancelled.'),
+	tags: z
+		.lazy(() => z.array(TagSchema))
+		.optional()
+		.describe('Array of tags associated with this task.'),
+	comments: z
+		.lazy(() => z.array(CommentSchema))
+		.optional()
+		.describe('Array of comments on this task.'),
+});
+
+export type Task = z.infer<typeof TaskSchema>;
 
 /**
  * A comment on a task, supporting threaded discussion.
  */
-export interface Comment {
-	/** Unique identifier for the comment. */
-	id: string;
-
-	/** ISO 8601 timestamp when the comment was created. */
-	created_at: string;
-
-	/** ISO 8601 timestamp when the comment was last edited. */
-	updated_at: string;
-
-	/** ID of the task this comment belongs to. */
-	task_id: string;
-
-	/** ID of the user who authored the comment. */
-	user_id: string;
-
-	/** Reference to the comment author with display name. */
-	author?: UserEntityRef;
-
-	/**
-	 * The comment text content.
-	 *
-	 * @remarks Must be non-empty.
-	 */
-	body: string;
-}
+export const CommentSchema = z.object({
+	id: z.string().describe('Unique identifier for the comment.'),
+	created_at: z.string().describe('ISO 8601 timestamp when the comment was created.'),
+	updated_at: z.string().describe('ISO 8601 timestamp when the comment was last edited.'),
+	task_id: z.string().describe('ID of the task this comment belongs to.'),
+	user_id: z.string().describe('ID of the user who authored the comment.'),
+	author: UserEntityRefSchema.optional().describe(
+		'Reference to the comment author with display name.'
+	),
+	body: z.string().describe('The comment text content.'),
+});
+
+export type Comment = z.infer<typeof CommentSchema>;
 
 /**
  * A label that can be applied to tasks for categorization and filtering.
  */
-export interface Tag {
-	/** Unique identifier for the tag. */
-	id: string;
-
-	/** ISO 8601 timestamp when the tag was created. */
-	created_at: string;
-
-	/** Display name of the tag. */
-	name: string;
+export const TagSchema = z.object({
+	id: z.string().describe('Unique identifier for the tag.'),
+	created_at: z.string().describe('ISO 8601 timestamp when the tag was created.'),
+	name: z.string().describe('Display name of the tag.'),
+	color: z.string().optional().describe('Optional hex color code for the tag.'),
+});
 
-	/**
-	 * Optional hex color code for the tag.
-	 *
-	 * @example '#ff0000'
-	 */
-	color?: string;
-}
+export type Tag = z.infer<typeof TagSchema>;
 
 /**
  * A record of a single field change on a task, providing an audit trail.
  */
-export interface TaskChangelogEntry {
-	/** Unique identifier for the changelog entry. */
-	id: string;
-
-	/** ISO 8601 timestamp when the change occurred. */
-	created_at: string;
-
-	/** ID of the task that was changed. */
-	task_id: string;
-
-	/**
-	 * Name of the field that was changed.
-	 *
-	 * @example 'status'
-	 * @example 'priority'
-	 * @example 'assigned_id'
-	 */
-	field: string;
-
-	/** The previous value of the field (as a string), or `undefined` if the field was newly set. */
-	old_value?: string;
-
-	/** The new value of the field (as a string), or `undefined` if the field was cleared. */
-	new_value?: string;
-}
+export const TaskChangelogEntrySchema = z.object({
+	id: z.string().describe('Unique identifier for the changelog entry.'),
+	created_at: z.string().describe('ISO 8601 timestamp when the change occurred.'),
+	task_id: z.string().describe('ID of the task that was changed.'),
+	field: z.string().describe('Name of the field that was changed.'),
+	old_value: z
+		.string()
+		.optional()
+		.describe(
+			'The previous value of the field (as a string), or `undefined` if the field was newly set.'
+		),
+	new_value: z
+		.string()
+		.optional()
+		.describe(
+			'The new value of the field (as a string), or `undefined` if the field was cleared.'
+		),
+});
+
+export type TaskChangelogEntry = z.infer<typeof TaskChangelogEntrySchema>;
 
 /**
  * Parameters for creating a new task.
  */
-export interface CreateTaskParams {
+export const CreateTaskParamsSchema = z.object({
 	/**
 	 * The task title (required).
 	 *
 	 * @remarks Must be non-empty and at most 1024 characters.
 	 */
-	title: string;
+	title: z.string().describe('The task title (required).'),
 
 	/**
 	 * Detailed description of the task.
 	 *
 	 * @remarks Maximum 65,536 characters.
 	 */
-	description?: string;
+	description: z.string().optional().describe('Detailed description of the task.'),
 
 	/** Arbitrary key-value metadata. */
-	metadata?: Record<string, unknown>;
+	metadata: z.record(z.string(), z.unknown()).optional().describe('Arbitrary key-value metadata.'),
 
 	/**
 	 * Priority level. Defaults to `'none'` if not provided.
 	 *
 	 * @default 'none'
 	 */
-	priority?: TaskPriority;
+	priority: TaskPrioritySchema.optional().describe(
+		"Priority level. Defaults to `'none'` if not provided."
+	),
 
 	/** ID of the parent task for hierarchical organization. */
-	parent_id?: string;
+	parent_id: z
+		.string()
+		.optional()
+		.describe('ID of the parent task for hierarchical organization.'),
 
 	/** The task classification (required). */
-	type: TaskType;
+	type: TaskTypeSchema.describe('The task classification (required).'),
 
 	/**
 	 * Initial status. Defaults to `'open'` if not provided.
 	 *
 	 * @default 'open'
 	 */
-	status?: TaskStatus;
+	status: TaskStatusSchema.optional().describe(
+		"Initial status. Defaults to `'open'` if not provided."
+	),
 
 	/**
 	 * ID of the creator.
 	 *
 	 * @remarks Legacy field; prefer {@link CreateTaskParams.creator | creator}.
 	 */
-	created_id: string;
+	created_id: z.string().describe('ID of the creator.'),
 
 	/**
 	 * ID of the assigned user.
 	 *
 	 * @remarks Legacy field; prefer {@link CreateTaskParams.assignee | assignee}.
 	 */
-	assigned_id?: string;
+	assigned_id: z.string().optional().describe('ID of the assigned user.'),
 
 	/** Reference to the user creating the task (id, name, and optional type). */
-	creator?: UserEntityRef;
+	creator: UserEntityRefSchema.optional().describe(
+		'Reference to the user creating the task (id, name, and optional type).'
+	),
 
 	/** Reference to the user being assigned the task. */
-	assignee?: UserEntityRef;
+	assignee: UserEntityRefSchema.optional().describe(
+		'Reference to the user being assigned the task.'
+	),
 
 	/** Reference to the project this task belongs to. */
-	project?: EntityRef;
+	project: EntityRefSchema.optional().describe('Reference to the project this task belongs to.'),
 
 	/** Array of tag IDs to associate with the task at creation. */
-	tag_ids?: string[];
-}
+	tag_ids: z
+		.array(z.string())
+		.optional()
+		.describe('Array of tag IDs to associate with the task at creation.'),
+});
+
+export type CreateTaskParams = z.infer<typeof CreateTaskParamsSchema>;
 
 /**
  * Parameters for partially updating an existing task.
  *
  * @remarks Only provided fields are modified; omitted fields remain unchanged.
  */
-export interface UpdateTaskParams {
+export const UpdateTaskParamsSchema = z.object({
 	/**
 	 * Updated task title.
 	 *
 	 * @remarks Must be non-empty and at most 1024 characters if provided.
 	 */
-	title?: string;
+	title: z.string().optional().describe('Updated task title.'),
 
 	/**
 	 * Updated description.
 	 *
 	 * @remarks Maximum 65,536 characters.
 	 */
-	description?: string;
+	description: z.string().optional().describe('Updated description.'),
 
 	/** Updated key-value metadata. */
-	metadata?: Record<string, unknown>;
+	metadata: z.record(z.string(), z.unknown()).optional().describe('Updated key-value metadata.'),
 
 	/** Updated priority level. */
-	priority?: TaskPriority;
+	priority: TaskPrioritySchema.optional().describe('Updated priority level.'),
 
 	/** Updated parent task ID. */
-	parent_id?: string;
+	parent_id: z.string().optional().describe('Updated parent task ID.'),
 
 	/** Updated task classification. */
-	type?: TaskType;
+	type: TaskTypeSchema.optional().describe('Updated task classification.'),
 
 	/** Updated lifecycle status. */
-	status?: TaskStatus;
+	status: TaskStatusSchema.optional().describe('Updated lifecycle status.'),
 
 	/**
 	 * Updated assigned user ID.
 	 *
 	 * @remarks Legacy field; prefer {@link UpdateTaskParams.assignee | assignee}.
 	 */
-	assigned_id?: string;
+	assigned_id: z.string().optional().describe('Updated assigned user ID.'),
 
 	/**
 	 * ID of the user closing the task.
 	 *
 	 * @remarks Legacy field; prefer {@link UpdateTaskParams.closer | closer}.
 	 */
-	closed_id?: string;
+	closed_id: z.string().optional().describe('ID of the user closing the task.'),
 
 	/** Reference to the user being assigned the task. */
-	assignee?: UserEntityRef;
+	assignee: UserEntityRefSchema.optional().describe(
+		'Reference to the user being assigned the task.'
+	),
 
 	/** Reference to the user closing the task. */
-	closer?: UserEntityRef;
+	closer: UserEntityRefSchema.optional().describe('Reference to the user closing the task.'),
 
 	/** Reference to the project this task belongs to. */
-	project?: EntityRef;
-}
+	project: EntityRefSchema.optional().describe('Reference to the project this task belongs to.'),
+});
+
+export type UpdateTaskParams = z.infer<typeof UpdateTaskParamsSchema>;
 
 /**
  * Parameters for filtering and paginating the task list.
  */
-export interface ListTasksParams {
+export const ListTasksParamsSchema = z.object({
 	/** Filter by task status. */
-	status?: TaskStatus;
+	status: TaskStatusSchema.optional().describe('Filter by task status.'),
 
 	/** Filter by task type. */
-	type?: TaskType;
+	type: TaskTypeSchema.optional().describe('Filter by task type.'),
 
 	/** Filter by priority level. */
-	priority?: TaskPriority;
+	priority: TaskPrioritySchema.optional().describe('Filter by priority level.'),
 
 	/** Filter by assigned user ID. */
-	assigned_id?: string;
+	assigned_id: z.string().optional().describe('Filter by assigned user ID.'),
 
 	/** Filter by parent task ID (get subtasks). */
-	parent_id?: string;
+	parent_id: z.string().optional().describe('Filter by parent task ID (get subtasks).'),
 
 	/** Filter by project ID. */
-	project_id?: string;
+	project_id: z.string().optional().describe('Filter by project ID.'),
 
 	/** Filter by tag ID. */
-	tag_id?: string;
+	tag_id: z.string().optional().describe('Filter by tag ID.'),
 
 	/**
 	 * Filter for soft-deleted tasks.
 	 *
 	 * @default false
 	 */
-	deleted?: boolean;
+	deleted: z.boolean().optional().describe('Filter for soft-deleted tasks.'),
 
 	/**
 	 * Sort field. Prefix with `-` for descending order.
@@ -418,282 +379,283 @@ export interface ListTasksParams {
 	 * @remarks Supported values: `'created_at'`, `'updated_at'`, `'priority'`.
 	 * Prefix with `-` for descending (e.g., `'-created_at'`).
 	 */
-	sort?: string;
+	sort: z.string().optional().describe('Sort field. Prefix with `-` for descending order.'),
 
 	/** Sort direction: `'asc'` or `'desc'`. */
-	order?: 'asc' | 'desc';
+	order: z.enum(['asc', 'desc']).optional().describe("Sort direction: `'asc'` or `'desc'`."),
 
 	/** Maximum number of results to return. */
-	limit?: number;
+	limit: z.number().optional().describe('Maximum number of results to return.'),
 
 	/** Number of results to skip for pagination. */
-	offset?: number;
-}
+	offset: z.number().optional().describe('Number of results to skip for pagination.'),
+});
+
+export type ListTasksParams = z.infer<typeof ListTasksParamsSchema>;
 
 /**
  * Paginated list of tasks with total count.
  */
-export interface ListTasksResult {
+export const ListTasksResultSchema = z.object({
 	/** Array of tasks matching the query. */
-	tasks: Task[];
+	tasks: z.array(TaskSchema).describe('Array of tasks matching the query.'),
 
 	/** Total number of tasks matching the filters (before pagination). */
-	total: number;
+	total: z.number().describe('Total number of tasks matching the filters (before pagination).'),
 
 	/** The limit that was applied. */
-	limit: number;
+	limit: z.number().describe('The limit that was applied.'),
 
 	/** The offset that was applied. */
-	offset: number;
-}
+	offset: z.number().describe('The offset that was applied.'),
+});
+
+export type ListTasksResult = z.infer<typeof ListTasksResultSchema>;
 
 /**
  * Parameters for batch-deleting tasks by filter.
  * At least one filter must be provided.
  */
-export interface BatchDeleteTasksParams {
+export const BatchDeleteTasksParamsSchema = z.object({
 	/** Filter by task status. */
-	status?: TaskStatus;
+	status: TaskStatusSchema.optional().describe('Filter by task status.'),
 
 	/** Filter by task type. */
-	type?: TaskType;
+	type: TaskTypeSchema.optional().describe('Filter by task type.'),
 
 	/** Filter by priority level. */
-	priority?: TaskPriority;
+	priority: TaskPrioritySchema.optional().describe('Filter by priority level.'),
 
 	/** Filter by parent task ID (delete subtasks). */
-	parent_id?: string;
+	parent_id: z.string().optional().describe('Filter by parent task ID (delete subtasks).'),
 
 	/** Filter by creator ID. */
-	created_id?: string;
+	created_id: z.string().optional().describe('Filter by creator ID.'),
 
 	/**
 	 * Delete tasks older than this duration.
 	 * Accepts Go-style duration strings: `'30m'`, `'24h'`, `'7d'`, `'2w'`.
 	 */
-	older_than?: string;
+	older_than: z.string().optional().describe('Delete tasks older than this duration.'),
 
 	/**
 	 * Maximum number of tasks to delete.
 	 * @default 50
 	 * @maximum 200
 	 */
-	limit?: number;
-}
+	limit: z.number().optional().describe('Maximum number of tasks to delete.'),
+});
+
+export type BatchDeleteTasksParams = z.infer<typeof BatchDeleteTasksParamsSchema>;
 
 /**
  * A single task that was deleted in a batch operation.
  */
-export interface BatchDeletedTask {
-	/** The ID of the deleted task. */
-	id: string;
+export const BatchDeletedTaskSchema = z.object({
+	id: z.string().describe('The ID of the deleted task.'),
+	title: z.string().describe('The title of the deleted task.'),
+});
 
-	/** The title of the deleted task. */
-	title: string;
-}
+export type BatchDeletedTask = z.infer<typeof BatchDeletedTaskSchema>;
 
 /**
  * Result of a batch delete operation.
  */
-export interface BatchDeleteTasksResult {
+export const BatchDeleteTasksResultSchema = z.object({
 	/** Array of tasks that were deleted. */
-	deleted: BatchDeletedTask[];
+	deleted: z.array(BatchDeletedTaskSchema).describe('Array of tasks that were deleted.'),
 
 	/** Total number of tasks deleted. */
-	count: number;
-}
+	count: z.number().describe('Total number of tasks deleted.'),
+});
+
+export type BatchDeleteTasksResult = z.infer<typeof BatchDeleteTasksResultSchema>;
 
 /**
  * Paginated list of changelog entries for a task.
  */
-export interface TaskChangelogResult {
+export const TaskChangelogResultSchema = z.object({
 	/** Array of change records. */
-	changelog: TaskChangelogEntry[];
+	changelog: z.array(TaskChangelogEntrySchema).describe('Array of change records.'),
 
 	/** Total number of changelog entries. */
-	total: number;
+	total: z.number().describe('Total number of changelog entries.'),
 
 	/** Applied limit. */
-	limit: number;
+	limit: z.number().describe('Applied limit.'),
 
 	/** Applied offset. */
-	offset: number;
-}
+	offset: z.number().describe('Applied offset.'),
+});
+
+export type TaskChangelogResult = z.infer<typeof TaskChangelogResultSchema>;
 
 /**
  * Paginated list of comments on a task.
  */
-export interface ListCommentsResult {
+export const ListCommentsResultSchema = z.object({
 	/** Array of comments. */
-	comments: Comment[];
+	comments: z.array(CommentSchema).describe('Array of comments.'),
 
 	/** Total number of comments. */
-	total: number;
+	total: z.number().describe('Total number of comments.'),
 
 	/** Applied limit. */
-	limit: number;
+	limit: z.number().describe('Applied limit.'),
 
 	/** Applied offset. */
-	offset: number;
-}
+	offset: z.number().describe('Applied offset.'),
+});
+
+export type ListCommentsResult = z.infer<typeof ListCommentsResultSchema>;
 
 /**
  * List of all tags in the organization.
  */
-export interface ListTagsResult {
-	/** Array of tags. */
-	tags: Tag[];
-}
+export const ListTagsResultSchema = z.object({
+	tags: z.array(TagSchema).describe('Array of tags.'),
+});
+
+export type ListTagsResult = z.infer<typeof ListTagsResultSchema>;
 
 /**
  * A file attachment on a task. Attachments are stored in S3 and accessed via presigned URLs.
  */
-export interface Attachment {
-	/** Unique identifier for the attachment. */
-	id: string;
-
-	/** ISO 8601 timestamp when the attachment was uploaded. */
-	created_at: string;
-
-	/** ID of the task this attachment belongs to. */
-	task_id: string;
-
-	/** ID of the user who uploaded the attachment. */
-	user_id: string;
-
-	/** Reference to the uploader with display name. */
-	author?: UserEntityRef;
-
-	/** Original filename of the uploaded file. */
-	filename: string;
-
-	/**
-	 * MIME type of the file.
-	 *
-	 * @example 'application/pdf'
-	 */
-	content_type?: string;
-
-	/** File size in bytes. */
-	size?: number;
-}
+export const AttachmentSchema = z.object({
+	id: z.string().describe('Unique identifier for the attachment.'),
+	created_at: z.string().describe('ISO 8601 timestamp when the attachment was uploaded.'),
+	task_id: z.string().describe('ID of the task this attachment belongs to.'),
+	user_id: z.string().describe('ID of the user who uploaded the attachment.'),
+	author: UserEntityRefSchema.optional().describe('Reference to the uploader with display name.'),
+	filename: z.string().describe('Original filename of the uploaded file.'),
+	content_type: z.string().optional().describe('MIME type of the file.'),
+	size: z.number().optional().describe('File size in bytes.'),
+});
+
+export type Attachment = z.infer<typeof AttachmentSchema>;
 
 /**
  * Parameters for initiating a file upload to a task.
  */
-export interface CreateAttachmentParams {
-	/** The filename for the attachment (required). */
-	filename: string;
-
-	/** MIME type of the file. */
-	content_type?: string;
+export const CreateAttachmentParamsSchema = z.object({
+	filename: z.string().describe('The filename for the attachment (required).'),
+	content_type: z.string().optional().describe('MIME type of the file.'),
+	size: z.number().optional().describe('File size in bytes.'),
+});
 
-	/** File size in bytes. */
-	size?: number;
-}
+export type CreateAttachmentParams = z.infer<typeof CreateAttachmentParamsSchema>;
 
 /**
  * Response from initiating an attachment upload. Contains a presigned S3 URL for direct upload.
  */
-export interface PresignUploadResponse {
-	/** The created attachment record. */
-	attachment: Attachment;
-
-	/** A presigned S3 URL to upload the file content via HTTP PUT. */
-	presigned_url: string;
+export const PresignUploadResponseSchema = z.object({
+	attachment: AttachmentSchema.describe('The created attachment record.'),
+	presigned_url: z
+		.string()
+		.describe('A presigned S3 URL to upload the file content via HTTP PUT.'),
+	expiry_seconds: z.number().describe('Number of seconds until the presigned URL expires.'),
+});
 
-	/** Number of seconds until the presigned URL expires. */
-	expiry_seconds: number;
-}
+export type PresignUploadResponse = z.infer<typeof PresignUploadResponseSchema>;
 
 /**
  * Response containing a presigned S3 URL for downloading an attachment.
  */
-export interface PresignDownloadResponse {
-	/** A presigned S3 URL to download the file via HTTP GET. */
-	presigned_url: string;
+export const PresignDownloadResponseSchema = z.object({
+	presigned_url: z.string().describe('A presigned S3 URL to download the file via HTTP GET.'),
+	expiry_seconds: z.number().describe('Number of seconds until the presigned URL expires.'),
+});
 
-	/** Number of seconds until the presigned URL expires. */
-	expiry_seconds: number;
-}
+export type PresignDownloadResponse = z.infer<typeof PresignDownloadResponseSchema>;
 
 /**
  * List of attachments on a task.
  */
-export interface ListAttachmentsResult {
+export const ListAttachmentsResultSchema = z.object({
 	/** Array of attachment records. */
-	attachments: Attachment[];
+	attachments: z.array(AttachmentSchema).describe('Array of attachment records.'),
 
 	/** Total number of attachments. */
-	total: number;
-}
+	total: z.number().describe('Total number of attachments.'),
+});
+
+export type ListAttachmentsResult = z.infer<typeof ListAttachmentsResultSchema>;
 
 /**
  * List of all users who have been referenced in tasks (as creators, assignees, or closers).
  */
-export interface ListUsersResult {
-	/** Array of user entity references with type information. */
-	users: UserEntityRef[];
-}
+export const ListUsersResultSchema = z.object({
+	users: z
+		.array(UserEntityRefSchema)
+		.describe('Array of user entity references with type information.'),
+});
+
+export type ListUsersResult = z.infer<typeof ListUsersResultSchema>;
 
 /**
  * List of all projects that have been referenced in tasks.
  */
-export interface ListProjectsResult {
-	/** Array of project entity references. */
-	projects: EntityRef[];
-}
+export const ListProjectsResultSchema = z.object({
+	projects: z.array(EntityRefSchema).describe('Array of project entity references.'),
+});
+
+export type ListProjectsResult = z.infer<typeof ListProjectsResultSchema>;
 
 /**
  * Parameters for querying task activity time-series data.
  */
-export interface TaskActivityParams {
+export const TaskActivityParamsSchema = z.object({
 	/**
 	 * Number of days of activity to retrieve.
 	 *
 	 * @remarks Minimum 7, maximum 365.
 	 * @default 90
 	 */
-	days?: number;
-}
+	days: z.number().min(7).max(365).optional().describe('Number of days of activity to retrieve.'),
+});
+
+export type TaskActivityParams = z.infer<typeof TaskActivityParamsSchema>;
 
 /**
  * A single day's snapshot of task counts by status.
  */
-export interface TaskActivityDataPoint {
+export const TaskActivityDataPointSchema = z.object({
 	/**
 	 * The date in `YYYY-MM-DD` format.
 	 *
 	 * @example '2026-02-28'
 	 */
-	date: string;
+	date: z.string().describe('The date in `YYYY-MM-DD` format.'),
 
 	/** Number of tasks in `'open'` status on this date. */
-	open: number;
+	open: z.number().describe("Number of tasks in `'open'` status on this date."),
 
 	/** Number of tasks in `'in_progress'` status on this date. */
-	inProgress: number;
+	inProgress: z.number().describe("Number of tasks in `'in_progress'` status on this date."),
 
 	/** Number of tasks in `'done'` status on this date. */
-	done: number;
+	done: z.number().describe("Number of tasks in `'done'` status on this date."),
 
 	/** Number of tasks in `'closed'` status on this date. */
-	closed: number;
+	closed: z.number().describe("Number of tasks in `'closed'` status on this date."),
 
 	/** Number of tasks in `'cancelled'` status on this date. */
-	cancelled: number;
-}
+	cancelled: z.number().describe("Number of tasks in `'cancelled'` status on this date."),
+});
+
+export type TaskActivityDataPoint = z.infer<typeof TaskActivityDataPointSchema>;
 
 /**
  * Task activity time-series data.
  */
-export interface TaskActivityResult {
-	/** Array of daily activity snapshots, ordered chronologically. */
-	activity: TaskActivityDataPoint[];
-
-	/** The number of days of data returned. */
-	days: number;
-}
+export const TaskActivityResultSchema = z.object({
+	activity: z
+		.array(TaskActivityDataPointSchema)
+		.describe('Array of daily activity snapshots, ordered chronologically.'),
+	days: z.number().describe('The number of days of data returned.'),
+});
+
+export type TaskActivityResult = z.infer<typeof TaskActivityResultSchema>;
 
 /**
  * Interface defining the contract for task storage operations.