@archastro/sdk 0.5.2 → 0.5.3

package/dist/types/common.js

@@ -1,369 +1,1732 @@
 // Copyright (c) 2026 ArchAstro Inc. All Rights Reserved.
 // This file is auto-generated by @archastro/sdk-generator. Do not edit.
-// Content hash: 4303c5c9f783
+// Content hash: 0024f11212a3
 import { z } from "zod";
+import { configSchema } from "./config.js";
 import { imageSourceSchema } from "./image.js";
 import { userSchema } from "./users.js";
-/** API schema for a single ACL grant entry. */
+/** Runtime validator for {@link AclGrant}. */
 export const aclGrantSchema = z.object({
-    actions: z.array(z.string()), // List of allowed actions (e.g. read, write)
-    principal: z.string().optional(), // Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)
-    principal_type: z.string(), // Principal type: user, team, org, org_role, agent, or everyone
-});
-/** API schema for identifying a principal to remove from an ACL. */
+    /** Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry. */
+    actions: z.array(z.string()).describe("Array of action strings the principal is permitted to perform, e.g. `[\"read\", \"write\"]`. Must contain at least one entry."),
+    /** The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`. */
+    principal: z.string().optional().describe("The identifier of the principal. A string ID for `\"user\"`, `\"team\"`, `\"org\"`, and `\"agent\"` types; one of `\"admin\"`, `\"member\"`, or `\"viewer\"` for `\"org_role\"`; omit entirely when `principal_type` is `\"everyone\"`."),
+    /** The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. */
+    principal_type: z.string().describe("The kind of principal receiving the grant. One of `\"user\"`, `\"team\"`, `\"org\"`, `\"org_role\"`, `\"agent\"`, or `\"everyone\"`."),
+}).describe("A single access-control grant that pairs a principal with the set of actions it is allowed to perform.");
+/** Runtime validator for {@link AclRemoveTarget}. */
 export const aclRemoveTargetSchema = z.object({
-    principal: z.string().optional(), // Principal identifier to remove (omit for everyone)
-    principal_type: z.string(), // Principal type to remove
-});
-/** Reusable API schema for access control lists.
-
-Supports two modes (mutually exclusive):
-
-**Replace mode** — send `grants` to replace all entries:
-
-    {"grants": [{"principal_type": "user", "principal": "...", "actions": ["read"]}]}
-
-Use `{"grants": []}` to clear all entries.
-
-**Patch mode** — send `add` and/or `remove`:
-
-    {"add": [...grants...], "remove": [{"principal_type": "user", "principal": "..."}]}
-
-Cannot mix `grants` with `add`/`remove`.
- */
+    /** The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`. */
+    principal: z.string().optional().describe("The identifier of the principal to remove. A string ID for `\"user\"`, `\"team\"`, `\"org\"`, and `\"agent\"` types; one of `\"admin\"`, `\"member\"`, or `\"viewer\"` for `\"org_role\"`. Omit when `principal_type` is `\"everyone\"`."),
+    /** The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. */
+    principal_type: z.string().describe("The kind of principal to remove. One of `\"user\"`, `\"team\"`, `\"org\"`, `\"org_role\"`, `\"agent\"`, or `\"everyone\"`."),
+}).describe("Identifies a principal to be removed from an access-control list.");
+/** Runtime validator for {@link Acl}. */
 export const aclSchema = z.object({
-    add: z.array(aclGrantSchema).optional(), // Patch mode: grants to add or merge into existing
-    grants: z.array(aclGrantSchema).optional(), // Replace mode: full list of grants (replaces all existing). Use [] to clear.
-    remove: z.array(aclRemoveTargetSchema).optional(), // Patch mode: principals to remove from existing
-});
-/** Schema for a message actor (user or agent).
-
-Actors represent the entity that sent a message.
-Maps to the actor format from MessageActorHelper.build_actor/1.
- */
+    /** Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`. */
+    add: z.array(aclGrantSchema).optional().describe("Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`."),
+    /** Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`. */
+    grants: z.array(aclGrantSchema).optional().describe("Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`."),
+    /** Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`. */
+    remove: z.array(aclRemoveTargetSchema).optional().describe("Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."),
+}).describe("An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants.");
+/** Runtime validator for {@link ActivityFeedEntry}. */
+export const activityFeedEntrySchema = z.object({
+    /** The agent that produced this event. Returns an agent ID (`agi_...`) by default, or an expanded agent object when the association is loaded. `null` if no agent is associated. */
+    agent: z.union([z.string(), z.object({ acl: z.object({ add: z.array(z.object({ actions: z.array(z.string()), principal: z.string().optional(), principal_type: z.string() })).optional(), grants: z.array(z.object({ actions: z.array(z.string()), principal: z.string().optional(), principal_type: z.string() })).optional(), remove: z.array(z.object({ principal: z.string().optional(), principal_type: z.string() })).optional() }).optional(), app: z.string().optional(), created_at: z.string().optional(), default_model: z.string().optional(), email: z.string().optional(), id: z.string(), identity: z.string().optional(), last_applied_template_config: z.string().optional(), lookup_key: z.string().optional(), metadata: z.record(z.unknown()).optional(), name: z.string().optional(), org: z.string().optional(), org_name: z.string().optional(), originator: z.string().optional(), phone_number: z.string().optional(), sandbox: z.string().optional(), source_solution: z.object({ solution: z.object({ category_keys: z.array(z.string()).optional(), created_at: z.string().optional(), description: z.string().optional(), id: z.string(), kind: z.string(), latest_solution: z.string().optional(), latest_version: z.string().optional(), lookup_key: z.string().optional(), metadata: z.record(z.unknown()).optional(), name: z.string().optional(), org: z.string().optional(), org_logo: z.object({ file: z.string().optional(), height: z.number().int().optional(), media: z.string().optional(), mime_type: z.string().optional(), refresh_url: z.string().optional(), url: z.string().optional(), width: z.number().int().optional() }).optional(), org_name: z.string().optional(), org_slug: z.string().optional(), owners: z.array(z.string()), readme_url: z.string().optional(), solution_id: z.string().optional(), solution_version: z.string().optional(), tag_keys: z.array(z.string()).optional(), template_kind: z.string().optional(), templates: z.array(z.object({ description: z.string().optional(), display_name: z.string().optional(), id: z.string().optional(), kind: z.string(), lookup_key: z.string().optional(), name: z.string().optional(), readme_url: z.string().optional(), virtual_path: z.string().optional() })), updated_at: z.string().optional(), upgrade_available: z.boolean(), virtual_path: z.string().optional() }), template: z.object({ created_at: z.string().optional(), description: z.string().optional(), display_name: z.string().optional(), id: z.string(), kind: z.string(), lookup_key: z.string().optional(), name: z.string().optional(), updated_at: z.string().optional(), virtual_path: z.string().optional() }) }).optional(), team: z.string().optional(), updated_at: z.string().optional(), user: z.string().optional() })]).optional().describe("The agent that produced this event. Returns an agent ID (`agi_...`) by default, or an expanded agent object when the association is loaded. `null` if no agent is associated."),
+    /** ID of the application that produced this entry (`dap_...`). `null` if not scoped to an app. */
+    app: z.string().optional().describe("ID of the application that produced this entry (`dap_...`). `null` if not scoped to an app."),
+    /** Array of attachment objects associated with this entry. Each attachment has a `type` field (e.g. `"file"`, `"task"`, `"artifact"`) and type-specific additional fields. Empty array when there are no attachments. */
+    attachments: z.array(z.record(z.unknown())).optional().describe("Array of attachment objects associated with this entry. Each attachment has a `type` field (e.g. `\"file\"`, `\"task\"`, `\"artifact\"`) and type-specific additional fields. Empty array when there are no attachments."),
+    /** ID of the automation run that produced this entry (`atr_...`). `null` if not produced by an automation run. */
+    automation_run: z.string().optional().describe("ID of the automation run that produced this entry (`atr_...`). `null` if not produced by an automation run."),
+    /** A longer explanation of the event rendered as Markdown. `null` if no additional content is available. */
+    content: z.string().optional().describe("A longer explanation of the event rendered as Markdown. `null` if no additional content is available."),
+    /** An opaque string used to group related entries together. Entries sharing the same `correlation_id` belong to a single logical operation. `null` if not correlated. */
+    correlation_id: z.string().optional().describe("An opaque string used to group related entries together. Entries sharing the same `correlation_id` belong to a single logical operation. `null` if not correlated."),
+    /** When this activity feed entry was created (ISO 8601). */
+    created_at: z.string().optional().describe("When this activity feed entry was created (ISO 8601)."),
+    /** Activity feed entry ID (`afe_...`). */
+    id: z.string().describe("Activity feed entry ID (`afe_...`)."),
+    /** The type of event this entry represents, e.g. `"agent_step"` or `"tool_call"`. Determines how `title`, `content`, and `attachments` should be interpreted. */
+    kind: z.string().optional().describe("The type of event this entry represents, e.g. `\"agent_step\"` or `\"tool_call\"`. Determines how `title`, `content`, and `attachments` should be interpreted."),
+    /** Severity level of the event. One of `"info"`, `"warning"`, or `"error"`. `null` if no severity is set. */
+    level: z.string().optional().describe("Severity level of the event. One of `\"info\"`, `\"warning\"`, or `\"error\"`. `null` if no severity is set."),
+    /** Arbitrary key-value metadata stored on this entry. Returns an empty object when no metadata is set. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata stored on this entry. Returns an empty object when no metadata is set."),
+    /** ID of the organization this entry belongs to (`org_...`). `null` if not org-scoped. */
+    org: z.string().optional().describe("ID of the organization this entry belongs to (`org_...`). `null` if not org-scoped."),
+    /** ID of the agent routine run that produced this entry (`arr_...`). `null` if not produced by a routine run. */
+    routine_run: z.string().optional().describe("ID of the agent routine run that produced this entry (`arr_...`). `null` if not produced by a routine run."),
+    /** Identifier of the sandbox environment this entry was generated in. `null` in production contexts. */
+    sandbox: z.string().optional().describe("Identifier of the sandbox environment this entry was generated in. `null` in production contexts."),
+    /** ID of the agent session record this entry belongs to (`ase_...`). `null` if not part of an agent session. */
+    session_record: z.string().optional().describe("ID of the agent session record this entry belongs to (`ase_...`). `null` if not part of an agent session."),
+    /** ID of the team this entry is associated with (`tem_...`). `null` if not team-scoped. */
+    team: z.string().optional().describe("ID of the team this entry is associated with (`tem_...`). `null` if not team-scoped."),
+    /** ID of the thread this entry is associated with (`thr_...`). `null` if not linked to a thread. */
+    thread: z.string().optional().describe("ID of the thread this entry is associated with (`thr_...`). `null` if not linked to a thread."),
+    /** A one-line human-readable summary of the event. `null` if the entry has no title. */
+    title: z.string().optional().describe("A one-line human-readable summary of the event. `null` if the entry has no title."),
+    /** When this activity feed entry was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When this activity feed entry was last modified (ISO 8601)."),
+    /** The user who triggered this event. Returns a user ID (`usr_...`) by default, or an expanded user object when the association is loaded. `null` if no user is associated. */
+    user: z.union([z.string(), z.object({ alias: z.string().optional(), app: z.string().optional(), app_name: z.string().optional(), email: z.string().optional(), id: z.string(), is_system_user: z.boolean().optional(), metadata: z.record(z.unknown()).optional(), name: z.string().optional(), org: z.string().optional(), org_name: z.string().optional(), org_role: z.string().optional(), sandbox: z.string().optional(), sandbox_name: z.string().optional() })]).optional().describe("The user who triggered this event. Returns a user ID (`usr_...`) by default, or an expanded user object when the association is loaded. `null` if no user is associated."),
+}).describe("A single event record in an activity feed, capturing what happened, who caused it, and which resources were involved.");
+/** Runtime validator for {@link ActivityFeedEntryListResponse}. */
+export const activityFeedEntryListResponseSchema = z.object({
+    /** Opaque cursor to pass as `after` to retrieve the next page of entries. `null` when this is the last page. */
+    after_cursor: z.string().optional().describe("Opaque cursor to pass as `after` to retrieve the next page of entries. `null` when this is the last page."),
+    /** Opaque cursor to pass as `before` to retrieve the previous page of entries. `null` when this is the first page. */
+    before_cursor: z.string().optional().describe("Opaque cursor to pass as `before` to retrieve the previous page of entries. `null` when this is the first page."),
+    /** Array of activity feed entry objects for the current page, ordered by time descending. */
+    entries: z.array(activityFeedEntrySchema).describe("Array of activity feed entry objects for the current page, ordered by time descending."),
+    /** Whether additional entries exist beyond the current page. When `true`, use `after_cursor` to fetch the next page. */
+    has_more: z.boolean().describe("Whether additional entries exist beyond the current page. When `true`, use `after_cursor` to fetch the next page."),
+}).describe("A paginated list of activity feed entries returned by a feed query, with cursors for navigating backward and forward through results.");
+/** Runtime validator for {@link Actor}. */
 export const actorSchema = z.object({
-    alias: z.string().optional(), // Actor alias/handle
-    id: z.string().optional(), // Actor ID (format: user-xxx or agent-xxx)
-    name: z.string().optional(), // Actor display name
-    profile_picture: imageSourceSchema.optional(), // Profile picture
-});
-/** API schema for per-routine LLM invocation settings.
-
-Mirrors `ArchAstro.Agents.Routines.LLMConfig`. When `model` is present,
-it overrides the agent's `default_model` for the routine (or step).
- */
+    /** Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured. */
+    alias: z.string().optional().describe("Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured."),
+    /** Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents. */
+    id: z.string().optional().describe("Composite actor identifier. Format is `\"user-<usr_...>\"` for human users or `\"agent-<agi_...>\"` for agents."),
+    /** Display name of the actor shown in the UI. `null` if no name is set. */
+    name: z.string().optional().describe("Display name of the actor shown in the UI. `null` if no name is set."),
+    /** Profile picture for the actor. `null` if the actor has no profile picture. */
+    profile_picture: imageSourceSchema.optional().describe("Profile picture for the actor. `null` if the actor has no profile picture."),
+}).describe("The entity that authored a message, either a human user or an agent.");
+/** Runtime validator for {@link UpgradeTemplateSummary}. */
+export const upgradeTemplateSummarySchema = z.object({
+    /** When this template config was created (ISO 8601). */
+    created_at: z.string().optional().describe("When this template config was created (ISO 8601)."),
+    /** Description of the template from the config body. `null` if the current version has no `description` field. */
+    description: z.string().optional().describe("Description of the template from the config body. `null` if the current version has no `description` field."),
+    /** Human-readable display name from the config body. `null` if the current version has no `display_name` field. */
+    display_name: z.string().optional().describe("Human-readable display name from the config body. `null` if the current version has no `display_name` field."),
+    /** Template config ID (`cfg_...`). */
+    id: z.string().describe("Template config ID (`cfg_...`)."),
+    /** Config kind identifier for this template (e.g. `"agent_tool_template"`). */
+    kind: z.string().describe("Config kind identifier for this template (e.g. `\"agent_tool_template\"`)."),
+    /** Stable lookup key assigned to this template config. `null` if no lookup key is set. */
+    lookup_key: z.string().optional().describe("Stable lookup key assigned to this template config. `null` if no lookup key is set."),
+    /** Template name as stored in the config body. `null` if the current version has no `name` field. */
+    name: z.string().optional().describe("Template name as stored in the config body. `null` if the current version has no `name` field."),
+    /** When this template config was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When this template config was last modified (ISO 8601)."),
+    /** Virtual filesystem path for this template config. `null` if not set. */
+    virtual_path: z.string().optional().describe("Virtual filesystem path for this template config. `null` if not set."),
+}).describe("Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response.");
+/** Runtime validator for {@link InstalledConfigEntry}. */
+export const installedConfigEntrySchema = z.object({
+    /** ID of the persisted config record (`cfg_...`). */
+    id: z.string().describe("ID of the persisted config record (`cfg_...`)."),
+    /** Caller-supplied correlation key echoed back from the request. For top-level configs this is the original `lookup_key` (before any suffix is applied). For skill file children it is the composite `"<skill_lookup_key>:<relative_path>"` string, since file rows have no lookup_key of their own. */
+    key: z.string().describe("Caller-supplied correlation key echoed back from the request. For top-level configs this is the original `lookup_key` (before any suffix is applied). For skill file children it is the composite `\"<skill_lookup_key>:<relative_path>\"` string, since file rows have no lookup_key of their own."),
+    /** Type of config that was created. One of `"Skill"`, `"File"`, `"Script"`, `"AgentTemplate"`, or `"Config"`. */
+    kind: z.string().describe("Type of config that was created. One of `\"Skill\"`, `\"File\"`, `\"Script\"`, `\"AgentTemplate\"`, or `\"Config\"`."),
+    /** Stored `lookup_key` for this config after any suffix has been applied. `null` for `File` children inside a skill bundle, which are keyed by `(parent_id, relative_path)` rather than by `lookup_key`. */
+    lookup_key: z.string().optional().describe("Stored `lookup_key` for this config after any suffix has been applied. `null` for `File` children inside a skill bundle, which are keyed by `(parent_id, relative_path)` rather than by `lookup_key`."),
+}).describe("A slim summary of a single config record created during an agent install transaction. Returned as an entry in `AgentCreateResponse.installed_configs`.");
+/** Runtime validator for {@link LLMConfig}. */
 export const lLMConfigSchema = z.object({
-    model: z.string().optional(), // Model identifier. When set, overrides the agent's default_model.
-});
-/** API schema for preset handler configuration.
-
-Mirrors `ArchAstro.Agents.Routines.PresetConfig`. Used wherever a request
-or response carries a preset config — routine-level and chain-step-level.
-
-Server-side validation (length/format rules on `instructions`, enum checks
-on `session_mode`/`session_scope`, model lookup against
-`ChatCompletion.models/0`) is authoritative. This schema defines the
-request shape and typed response shape so OpenAPI consumers see real
-types instead of an opaque object.
- */
+    /** Model identifier to use for this routine or step, e.g. `"claude-sonnet-4-5"`. When omitted, the agent's default model is used. */
+    model: z.string().optional().describe("Model identifier to use for this routine or step, e.g. `\"claude-sonnet-4-5\"`. When omitted, the agent's default model is used."),
+}).describe("LLM invocation settings for a routine or chain step. When present, overrides the agent-level model selection.");
+/** Runtime validator for {@link PresetConfig}. */
 export const presetConfigSchema = z.object({
-    instructions: z.string().optional(), // Custom task or behavior instructions for the preset (max 10,000 chars).
-    llm: lLMConfigSchema.optional(), // LLM invocation settings (e.g. a `model` override for this routine/step).
-    session_mode: z.string().optional(), // Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).
-    session_scope: z.string().optional(), // When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.
-    structured_message_template_ids: z.array(z.string()).optional(), // Config IDs of AgentMessageSchema templates that constrain the agent's responses to predefined structured formats.
-});
-/** API schema for background worker status on a routine run. */
+    /** Custom task or behavior instructions for the preset (max 10,000 chars). */
+    instructions: z.string().optional().describe("Custom task or behavior instructions for the preset (max 10,000 chars)."),
+    /** LLM invocation settings (e.g. a `model` override for this routine/step). */
+    llm: lLMConfigSchema.optional().describe("LLM invocation settings (e.g. a `model` override for this routine/step)."),
+    /** Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`). */
+    session_mode: z.string().optional().describe("Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`)."),
+    /** When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`. */
+    session_scope: z.string().optional().describe("When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`."),
+    /** IDs of structured message templates that constrain the agent's responses to predefined structured formats. */
+    structured_message_template_ids: z.array(z.string()).optional().describe("IDs of structured message templates that constrain the agent's responses to predefined structured formats."),
+}).describe("Configuration for a preset routine handler. Controls the agent's behavior, session persistence, and model selection for a given routine or chain step.");
+/** Runtime validator for {@link WorkerStatus}. */
 export const workerStatusSchema = z.object({
-    attempt: z.number().int(), // Current attempt number (0 = not yet attempted)
-    max_attempts: z.number().int(), // Maximum allowed attempts
-    status: z.string(), // Worker state: queued, executing, retrying, completed, discarded, or cancelled
-});
-/** API schema for a media variant. */
+    /** Number of times the worker has been attempted so far. `0` means the job has been enqueued but not yet started. */
+    attempt: z.number().int().describe("Number of times the worker has been attempted so far. `0` means the job has been enqueued but not yet started."),
+    /** Maximum number of attempts the worker is allowed before the job is marked `"discarded"`. */
+    max_attempts: z.number().int().describe("Maximum number of attempts the worker is allowed before the job is marked `\"discarded\"`."),
+    /** Current execution state of the worker. One of `"queued"`, `"executing"`, `"retrying"`, `"completed"`, `"discarded"`, or `"cancelled"`. */
+    status: z.string().describe("Current execution state of the worker. One of `\"queued\"`, `\"executing\"`, `\"retrying\"`, `\"completed\"`, `\"discarded\"`, or `\"cancelled\"`."),
+}).describe("Execution state of the background worker processing a routine run. Reflects the current job status and retry progress.");
+/** Runtime validator for {@link MediaVariant}. */
 export const mediaVariantSchema = z.object({
-    content_type: z.string().optional(), // File content type
-    created_at: z.string().optional(), // Creation timestamp
-    file: z.string().optional(), // Storage file
-    filename: z.string().optional(), // Original filename
-    height: z.number().int().optional(), // Height in pixels
-    id: z.string(), // Variant ID
-    image_source: imageSourceSchema.optional(), // Image source metadata
-    updated_at: z.string().optional(), // Last update timestamp
-    url: z.string().optional(), // Signed download URL
-    variant_key: z.string().optional(), // Variant key (original, thumbnail, etc)
-    width: z.number().int().optional(), // Width in pixels
-});
-/** Schema for a message attachment.
-
-Attachments can be of various types (file, scraped_link, artifact, task, media, action).
-Fields present depend on the attachment type.
-Maps to format_attachments_for_client/1 output.
- */
+    /** MIME type of this variant's file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded. */
+    content_type: z.string().optional().describe("MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded."),
+    /** When this variant was created (ISO 8601). */
+    created_at: z.string().optional().describe("When this variant was created (ISO 8601)."),
+    /** ID of the underlying storage file that backs this variant (`fil_...`). */
+    file: z.string().optional().describe("ID of the underlying storage file that backs this variant (`fil_...`)."),
+    /** Original filename of the uploaded file for this variant. `null` if the file is not loaded. */
+    filename: z.string().optional().describe("Original filename of the uploaded file for this variant. `null` if the file is not loaded."),
+    /** Height of this variant in pixels. `null` if not recorded. */
+    height: z.number().int().optional().describe("Height of this variant in pixels. `null` if not recorded."),
+    /** Media variant ID (`mvr_...`). */
+    id: z.string().describe("Media variant ID (`mvr_...`)."),
+    /** Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types. */
+    image_source: imageSourceSchema.optional().describe("Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types."),
+    /** When this variant was last updated (ISO 8601). */
+    updated_at: z.string().optional().describe("When this variant was last updated (ISO 8601)."),
+    /** Signed download URL for this variant, resolved at request time. `null` if the file is unavailable. */
+    url: z.string().optional().describe("Signed download URL for this variant, resolved at request time. `null` if the file is unavailable."),
+    /** Identifier for this variant's processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview). */
+    variant_key: z.string().optional().describe("Identifier for this variant's processing tier. Common values include `\"original\"` (the unmodified upload) and `\"thumbnail\"` (a resized preview)."),
+    /** Width of this variant in pixels. `null` if not recorded. */
+    width: z.number().int().optional().describe("Width of this variant in pixels. `null` if not recorded."),
+}).describe("A processed variant of a media item, such as the original upload or a resized thumbnail, including a signed download URL resolved at request time.");
+/** Runtime validator for {@link Attachment}. */
 export const attachmentSchema = z.object({
-    content_type: z.string().optional(), // MIME content type (file, artifact, media types)
-    description: z.string().optional(), // Description (scraped_link, artifact, task types)
-    filename: z.string().optional(), // File name (file, artifact, media types)
-    height: z.number().int().optional(), // Media height (media type)
-    id: z.string(), // Attachment ID
-    image_height: z.number().int().optional(), // Preview image height (scraped_link type)
-    image_source: imageSourceSchema.optional(), // Image metadata (file, scraped_link, artifact, media types)
-    image_url: z.string().optional(), // Preview image URL (scraped_link type)
-    image_width: z.number().int().optional(), // Preview image width (scraped_link type)
-    media_type: z.string().optional(), // Media type (media type)
-    name: z.string().optional(), // Media name (media type)
-    object: z.record(z.unknown()).optional(), // Embedded object (task, action types)
-    title: z.string().optional(), // Title (scraped_link, artifact, task types)
-    type: z.string(), // Attachment type: file, scraped_link, artifact, task, media, action
-    url: z.string().optional(), // URL to the resource (file, scraped_link, artifact, media types)
-    variants: z.array(mediaVariantSchema).optional(), // Media variants (media type)
-    version: z.number().int().optional(), // Artifact version number (artifact type)
-    width: z.number().int().optional(), // Media width (media type)
-});
-/** API schema for authentication token responses. */
+    /** MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise. */
+    content_type: z.string().optional().describe("MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise."),
+    /** Short description. The page meta-description for `scraped_link`, the artifact description for `artifact`, and the task description for `task` types. `null` on other types. */
+    description: z.string().optional().describe("Short description. The page meta-description for `scraped_link`, the artifact description for `artifact`, and the task description for `task` types. `null` on other types."),
+    /** Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise. */
+    filename: z.string().optional().describe("Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise."),
+    /** Height in pixels of the media item. Present on `media` type only. `null` otherwise. */
+    height: z.number().int().optional().describe("Height in pixels of the media item. Present on `media` type only. `null` otherwise."),
+    /** Unique identifier for this attachment within the message. */
+    id: z.string().describe("Unique identifier for this attachment within the message."),
+    /** Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise. */
+    image_height: z.number().int().optional().describe("Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise."),
+    /** Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise. */
+    image_source: imageSourceSchema.optional().describe("Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise."),
+    /** URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise. */
+    image_url: z.string().optional().describe("URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise."),
+    /** Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise. */
+    image_width: z.number().int().optional().describe("Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise."),
+    /** The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise. */
+    media_type: z.string().optional().describe("The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise."),
+    /** Display name of the media item. Present on `media` type only. `null` otherwise. */
+    name: z.string().optional().describe("Display name of the media item. Present on `media` type only. `null` otherwise."),
+    /** The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. `null` on other types. */
+    object: z.record(z.unknown()).optional().describe("The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. `null` on other types."),
+    /** Display title. The page title for `scraped_link`, the artifact name for `artifact`, and the task title for `task` types. `null` on other types. */
+    title: z.string().optional().describe("Display title. The page title for `scraped_link`, the artifact name for `artifact`, and the task title for `task` types. `null` on other types."),
+    /** The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, or `"action"`. Determines which additional fields are present. */
+    type: z.string().describe("The attachment type. One of `\"file\"`, `\"scraped_link\"`, `\"artifact\"`, `\"task\"`, `\"media\"`, or `\"action\"`. Determines which additional fields are present."),
+    /** URL to access the resource. A signed download URL for `file` and `artifact` types; the original URL for `scraped_link`; a media playback URL for `media`. `null` on `task` and `action` types. */
+    url: z.string().optional().describe("URL to access the resource. A signed download URL for `file` and `artifact` types; the original URL for `scraped_link`; a media playback URL for `media`. `null` on `task` and `action` types."),
+    /** Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise. */
+    variants: z.array(mediaVariantSchema).optional().describe("Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise."),
+    /** Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise. */
+    version: z.number().int().optional().describe("Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise."),
+    /** Width in pixels of the media item. Present on `media` type only. `null` otherwise. */
+    width: z.number().int().optional().describe("Width in pixels of the media item. Present on `media` type only. `null` otherwise."),
+}).describe("A rich attachment associated with a message, such as a file, scraped link, artifact, task, media item, or inline action.");
+/** Runtime validator for {@link AuthTokens}. */
 export const authTokensSchema = z.object({
-    expires_in: z.number().int(), // Token TTL in seconds
-    metadata: z.record(z.unknown()).optional(), // Additional metadata (e.g., onboarding_job_id)
-    refresh_token: z.string(), // Refresh token
-    token: z.string(), // Access token (JWT)
-    token_type: z.string(), // Token type (Bearer)
-    user: userSchema, // Authenticated user
-});
-/** An individual tool within a builtin tool catalog entry. */
+    /** Number of seconds until `token` expires. After this period, use `refresh_token` to obtain a new access token. */
+    expires_in: z.number().int().describe("Number of seconds until `token` expires. After this period, use `refresh_token` to obtain a new access token."),
+    /** Optional auxiliary data associated with this authentication event, such as `onboarding_job_id` when the user is completing onboarding. `null` when no extra context is present. */
+    metadata: z.record(z.unknown()).optional().describe("Optional auxiliary data associated with this authentication event, such as `onboarding_job_id` when the user is completing onboarding. `null` when no extra context is present."),
+    /** Long-lived opaque refresh token. Use this to obtain a new access token when `token` expires. */
+    refresh_token: z.string().describe("Long-lived opaque refresh token. Use this to obtain a new access token when `token` expires."),
+    /** Short-lived JWT access token. Include this value in the `Authorization: Bearer <token>` header for all authenticated API requests. */
+    token: z.string().describe("Short-lived JWT access token. Include this value in the `Authorization: Bearer <token>` header for all authenticated API requests."),
+    /** Token scheme. Always `"Bearer"`. */
+    token_type: z.string().describe("Token scheme. Always `\"Bearer\"`."),
+    /** The user who authenticated. Contains the user's profile and account details. */
+    user: userSchema.describe("The user who authenticated. Contains the user's profile and account details."),
+}).describe("Credential bundle returned after a successful authentication exchange. Contains the access token, refresh token, and the authenticated user.");
+/** Runtime validator for {@link BugReport}. */
+export const bugReportSchema = z.object({
+    /** App ID (`dap_...`) of the developer app through which the report was submitted. */
+    app: z.string().optional().describe("App ID (`dap_...`) of the developer app through which the report was submitted."),
+    /** The client application that submitted this report. One of `"agent_network_web"`, `"cli"`, or `"developer_portal"`. */
+    client: z.string().describe("The client application that submitted this report. One of `\"agent_network_web\"`, `\"cli\"`, or `\"developer_portal\"`."),
+    /** Version string of the submitting client at the time of submission, e.g. `"1.4.2"`. */
+    client_version: z.string().describe("Version string of the submitting client at the time of submission, e.g. `\"1.4.2\"`."),
+    /** Optional free-form JSON object providing additional context captured by the client (e.g. viewport size, active route). `null` when no context was provided. Maximum 5 KB when serialized. */
+    context: z.record(z.unknown()).optional().describe("Optional free-form JSON object providing additional context captured by the client (e.g. viewport size, active route). `null` when no context was provided. Maximum 5 KB when serialized."),
+    /** When the bug report was submitted (ISO 8601). */
+    created_at: z.string().optional().describe("When the bug report was submitted (ISO 8601)."),
+    /** Freeform text describing the issue or feedback, as entered by the user. Up to 10,000 characters. */
+    description: z.string().describe("Freeform text describing the issue or feedback, as entered by the user. Up to 10,000 characters."),
+    /** Bug report ID (`bgr_...`). */
+    id: z.string().describe("Bug report ID (`bgr_...`)."),
+    /** Organization ID (`org_...`) scoping this report. `null` when the user's account is not part of an organization. */
+    org: z.string().optional().describe("Organization ID (`org_...`) scoping this report. `null` when the user's account is not part of an organization."),
+    /** Sandbox ID (`dsb_...`) active at submission time. `null` when the report was not submitted from a sandbox context. */
+    sandbox: z.string().optional().describe("Sandbox ID (`dsb_...`) active at submission time. `null` when the report was not submitted from a sandbox context."),
+    /** Team ID (`tem_...`) of the team the submitting user belonged to at submission time. `null` when the user had no active team. */
+    team: z.string().optional().describe("Team ID (`tem_...`) of the team the submitting user belonged to at submission time. `null` when the user had no active team."),
+    /** When the bug report record was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When the bug report record was last modified (ISO 8601)."),
+}).describe("A bug report or freeform feedback submission from any ArchAstro client. Bug reports are write-only for the submitting user and are not returned by any public list or show endpoint.");
+/** Runtime validator for {@link BuiltinTool}. */
 export const builtinToolSchema = z.object({
-    description: z.string().optional(), // Tool description
-    name: z.string(), // Tool name
-});
-/** A builtin tool catalog entry describing an available tool category. */
+    /** Human-readable explanation of what the tool does. Surfaced to the agent as part of tool selection context. `null` when no description has been defined. */
+    description: z.string().optional().describe("Human-readable explanation of what the tool does. Surfaced to the agent as part of tool selection context. `null` when no description has been defined."),
+    /** Machine-readable name of the tool as it is registered with the agent runtime, e.g. `"web_search"` or `"github_create_issue"`. */
+    name: z.string().describe("Machine-readable name of the tool as it is registered with the agent runtime, e.g. `\"web_search\"` or `\"github_create_issue\"`."),
+}).describe("A single callable tool within a builtin tool catalog entry. Represents one discrete function an agent can invoke.");
+/** Runtime validator for {@link BuiltinToolCatalogEntry}. */
 export const builtinToolCatalogEntrySchema = z.object({
-    config_schema: z.record(z.unknown()).optional(), // JSON schema for tool configuration
-    description: z.string().optional(), // Tool description
-    instruction: z.string().optional(), // Tool instruction
-    key: z.string(), // Unique tool key
-    label: z.string().optional(), // Display label
-    providers: z.array(z.string()).optional(), // Supported providers
-    requires_integration: z.boolean().optional(), // Whether an integration is required
-    server_tool_type: z.string().optional(), // Server tool type identifier
-    tools: z.array(builtinToolSchema).optional(), // List of individual tools
-});
-/** Result of executing a command on an agent computer. */
+    /** JSON Schema object describing the configuration options for this tool category. Clients should use this schema to render and validate configuration forms before submitting. `null` when no configuration is needed. */
+    config_schema: z.record(z.unknown()).optional().describe("JSON Schema object describing the configuration options for this tool category. Clients should use this schema to render and validate configuration forms before submitting. `null` when no configuration is needed."),
+    /** Short prose description of what this tool category does. Suitable for display in setup UIs. `null` when no description has been defined. */
+    description: z.string().optional().describe("Short prose description of what this tool category does. Suitable for display in setup UIs. `null` when no description has been defined."),
+    /** Additional guidance surfaced to the agent at runtime when this tool category is enabled. `null` when no custom instruction is set. */
+    instruction: z.string().optional().describe("Additional guidance surfaced to the agent at runtime when this tool category is enabled. `null` when no custom instruction is set."),
+    /** Unique slug identifying this tool category, e.g. `"web_search"` or `"github"`. */
+    key: z.string().describe("Unique slug identifying this tool category, e.g. `\"web_search\"` or `\"github\"`."),
+    /** Human-readable display name for the tool category, e.g. `"Web Search"`. `null` when no label has been assigned. */
+    label: z.string().optional().describe("Human-readable display name for the tool category, e.g. `\"Web Search\"`. `null` when no label has been assigned."),
+    /** Controls whether multiple instances of this tool category may be enabled simultaneously. `"namespaced"` — multiple instances allowed; each must carry a `name_prefix` to distinguish them. `"passthrough"` — multiple instances allowed without a `name_prefix`; names are derived from the underlying source. `null` — single-instance only. */
+    multi_instance_mode: z.string().optional().describe("Controls whether multiple instances of this tool category may be enabled simultaneously. `\"namespaced\"` — multiple instances allowed; each must carry a `name_prefix` to distinguish them. `\"passthrough\"` — multiple instances allowed without a `name_prefix`; names are derived from the underlying source. `null` — single-instance only."),
+    /** List of integration provider slugs that can back this tool category, e.g. `["github", "gitlab"]`. Empty when the tool is provider-agnostic. */
+    providers: z.array(z.string()).optional().describe("List of integration provider slugs that can back this tool category, e.g. `[\"github\", \"gitlab\"]`. Empty when the tool is provider-agnostic."),
+    /** Whether enabling this tool category requires the user to connect a third-party integration. `true` means at least one active integration of the appropriate type must exist before the tool can be used. */
+    requires_integration: z.boolean().optional().describe("Whether enabling this tool category requires the user to connect a third-party integration. `true` means at least one active integration of the appropriate type must exist before the tool can be used."),
+    /** Internal type identifier used by the platform server when registering these tools. `null` for client-side-only tool categories. */
+    server_tool_type: z.string().optional().describe("Internal type identifier used by the platform server when registering these tools. `null` for client-side-only tool categories."),
+    /** Array of individual tool definitions included in this category. Each entry describes a single callable tool with its own name and description. */
+    tools: z.array(builtinToolSchema).optional().describe("Array of individual tool definitions included in this category. Each entry describes a single callable tool with its own name and description."),
+}).describe("A catalog entry describing a category of platform-provided (builtin) tools that can be enabled for an agent. Each entry groups one or more individual tools under a shared key, label, and configuration schema.");
+/** Runtime validator for {@link ChannelAck}. */
+export const channelAckSchema = z.object({}).describe("Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{\"status\": \"ok\", \"response\": {}}`.");
+/** Runtime validator for {@link MessageReaction}. */
+export const messageReactionSchema = z.object({
+    /** Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `"👍"`). */
+    payload: z.record(z.unknown()).optional().describe("Type-specific reaction data. For `\"emoji_reaction\"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `\"👍\"`)."),
+    /** Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions. */
+    type: z.string().describe("Reaction type identifier. Currently always `\"emoji_reaction\"` for emoji-based reactions."),
+    /** Public ID of the user who added the reaction (`usr_...`). */
+    user: z.string().optional().describe("Public ID of the user who added the reaction (`usr_...`)."),
+}).describe("A compact reaction record embedded in a message's `reactions` array, representing a single user's reaction to a message.");
+/** Runtime validator for {@link Message}. */
+export const messageSchema = z.object({
+    /** Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry. */
+    actors: z.array(actorSchema).optional().describe("Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry."),
+    /** ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users. */
+    agent: z.string().optional().describe("ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users."),
+    /** Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments. */
+    attachments: z.array(attachmentSchema).optional().describe("Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments."),
+    /** ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread. */
+    branched_thread: z.string().optional().describe("ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread."),
+    /** Text content of the message. `null` for messages that contain only attachments. */
+    content: z.string().optional().describe("Text content of the message. `null` for messages that contain only attachments."),
+    /** When the message was posted (ISO 8601). */
+    created_at: z.string().optional().describe("When the message was posted (ISO 8601)."),
+    /** Whether this message has at least one reply. Only present when explicitly requested or computed by the server. */
+    has_replies: z.boolean().optional().describe("Whether this message has at least one reply. Only present when explicitly requested or computed by the server."),
+    /** Message ID (`msg_...`). */
+    id: z.string().describe("Message ID (`msg_...`)."),
+    /** Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one. */
+    idempotency_key: z.string().optional().describe("Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one."),
+    /** Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users. */
+    legacy_agent: z.string().optional().describe("Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users."),
+    /** Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set."),
+    /** ID of the organization that owns this message (`org_...`). */
+    org: z.string().optional().describe("ID of the organization that owns this message (`org_...`)."),
+    /** Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded. */
+    reactions: z.array(messageReactionSchema).optional().describe("Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded."),
+    /** Display hint for how the message should be rendered. One of `"reply"`, `"direct"`, or `"inline"`. `null` for user-authored messages, which are always rendered as standard replies. */
+    rendering_mode: z.string().optional().describe("Display hint for how the message should be rendered. One of `\"reply\"`, `\"direct\"`, or `\"inline\"`. `null` for user-authored messages, which are always rendered as standard replies."),
+    /** Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message. */
+    replies: z.array(z.record(z.unknown())).optional().describe("Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message."),
+    /** Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response. */
+    replies_after_cursor: z.string().optional().describe("Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response."),
+    /** Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response. */
+    replies_before_cursor: z.string().optional().describe("Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response."),
+    /** Total number of direct replies to this message. Only present when explicitly requested or computed by the server. */
+    reply_count: z.number().int().optional().describe("Total number of direct replies to this message. Only present when explicitly requested or computed by the server."),
+    /** The parent message this message is a reply to, expanded as a full message object when loaded. `null` if this is a top-level message or the association is not preloaded. */
+    reply_to: z.record(z.unknown()).optional().describe("The parent message this message is a reply to, expanded as a full message object when loaded. `null` if this is a top-level message or the association is not preloaded."),
+    /** ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages. */
+    sandbox: z.string().optional().describe("ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages."),
+    /** ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped. */
+    team: z.string().optional().describe("ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped."),
+    /** ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread. */
+    thread: z.string().optional().describe("ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread."),
+    /** The human user who sent this message. Returns a public ID string (`usr_...`) when the association is not preloaded, or an expanded user object when it is. `null` for messages sent by agents. */
+    user: z.string().optional().describe("The human user who sent this message. Returns a public ID string (`usr_...`) when the association is not preloaded, or an expanded user object when it is. `null` for messages sent by agents."),
+}).describe("A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata.");
+/** Runtime validator for {@link ComputerExecResult}. */
 export const computerExecResultSchema = z.object({
-    exit_code: z.number().int().optional(), // Process exit code
-    output: z.string().optional(), // Command output
-});
-/** API schema for a custom object. */
+    /** The UNIX exit code returned by the process. `0` indicates success; any non-zero value indicates an error. `null` if the process did not terminate normally. */
+    exit_code: z.number().int().optional().describe("The UNIX exit code returned by the process. `0` indicates success; any non-zero value indicates an error. `null` if the process did not terminate normally."),
+    /** The combined stdout and stderr output produced by the command. `null` if the command produced no output. */
+    output: z.string().optional().describe("The combined stdout and stderr output produced by the command. `null` if the command produced no output."),
+}).describe("The result of executing a shell command on an agent's computer environment. Contains the captured output and the process exit code.");
+/** Runtime validator for {@link ContextDocument}. */
+export const contextDocumentSchema = z.object({
+    /** ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team. */
+    agent: z.string().optional().describe("ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team."),
+    /** When the document was created (ISO 8601). */
+    created_at: z.string().optional().describe("When the document was created (ISO 8601)."),
+    /** ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents. */
+    file: z.string().optional().describe("ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents."),
+    /** Context document ID (`cdo_...`). */
+    id: z.string().describe("Context document ID (`cdo_...`)."),
+    /** Arbitrary key-value metadata attached to the document. Shape varies by source type. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata attached to the document. Shape varies by source type."),
+    /** ID of the context source this document belongs to (`cso_...`). */
+    source: z.string().optional().describe("ID of the context source this document belongs to (`cso_...`)."),
+    /** ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent. */
+    team: z.string().optional().describe("ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent."),
+    /** Human-readable display title of the document. `null` if no title has been set. */
+    title: z.string().optional().describe("Human-readable display title of the document. `null` if no title has been set."),
+    /** Total number of lines in the document's text content. `0` if the document has no content. */
+    total_lines: z.number().int().optional().describe("Total number of lines in the document's text content. `0` if the document has no content."),
+    /** Total byte size of the document's text content. `0` if the document has no content. */
+    total_size: z.number().int().optional().describe("Total byte size of the document's text content. `0` if the document has no content."),
+    /** When the document was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When the document was last modified (ISO 8601)."),
+    /** ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent. */
+    user: z.string().optional().describe("ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent."),
+}).describe("A context document stored within a context source. Carries metadata and size information only; retrieve the full text content via the `/content` endpoint.");
+/** Runtime validator for {@link ContextDocumentContent}. */
+export const contextDocumentContentSchema = z.object({
+    /** Text of the document. Contains the full content when no `offset`/`limit` was requested, or only the requested slice otherwise. */
+    content: z.string().describe("Text of the document. Contains the full content when no `offset`/`limit` was requested, or only the requested slice otherwise."),
+    /** Zero-based exclusive index of the last byte in `content` (i.e. the slice covers bytes `start_byte..end_byte-1`). Populated only when `unit` is `"bytes"`; `null` otherwise. */
+    end_byte: z.number().int().optional().describe("Zero-based exclusive index of the last byte in `content` (i.e. the slice covers bytes `start_byte..end_byte-1`). Populated only when `unit` is `\"bytes\"`; `null` otherwise."),
+    /** 1-indexed line number of the last line included in `content` (i.e. the slice covers lines `start_line` through `end_line` inclusive). Populated only when `unit` is `"lines"`; `null` otherwise. */
+    end_line: z.number().int().optional().describe("1-indexed line number of the last line included in `content` (i.e. the slice covers lines `start_line` through `end_line` inclusive). Populated only when `unit` is `\"lines\"`; `null` otherwise."),
+    /** Context document ID (`cdo_...`). */
+    id: z.string().describe("Context document ID (`cdo_...`)."),
+    /** The `limit` value echoed from the request. `null` when no limit was requested. */
+    limit: z.number().int().optional().describe("The `limit` value echoed from the request. `null` when no limit was requested."),
+    /** Arbitrary key-value metadata attached to the document, such as source URL or author. `null` if no metadata was recorded. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata attached to the document, such as source URL or author. `null` if no metadata was recorded."),
+    /** The `offset` value echoed from the request. `null` when no offset was requested. */
+    offset: z.number().int().optional().describe("The `offset` value echoed from the request. `null` when no offset was requested."),
+    /** Zero-based index of the first byte included in `content`. Populated only when `unit` is `"bytes"`; `null` otherwise. */
+    start_byte: z.number().int().optional().describe("Zero-based index of the first byte included in `content`. Populated only when `unit` is `\"bytes\"`; `null` otherwise."),
+    /** 1-indexed line number of the first line included in `content`. Populated only when `unit` is `"lines"`; `null` otherwise. */
+    start_line: z.number().int().optional().describe("1-indexed line number of the first line included in `content`. Populated only when `unit` is `\"lines\"`; `null` otherwise."),
+    /** Human-readable display title of the document. `null` if the document has no title set. */
+    title: z.string().optional().describe("Human-readable display title of the document. `null` if the document has no title set."),
+    /** Total number of lines in the document's full content, regardless of any slice. */
+    total_lines: z.number().int().describe("Total number of lines in the document's full content, regardless of any slice."),
+    /** Total byte size of the document's full content, regardless of any slice. */
+    total_size: z.number().int().describe("Total byte size of the document's full content, regardless of any slice."),
+    /** Slice unit used when `offset` and `limit` were provided. One of `"lines"` (default) or `"bytes"`. `null` when no slice was requested. */
+    unit: z.string().optional().describe("Slice unit used when `offset` and `limit` were provided. One of `\"lines\"` (default) or `\"bytes\"`. `null` when no slice was requested."),
+}).describe("The text content of a context document, optionally sliced by line or byte range. Includes totals and slice boundary fields for the requested unit.");
+/** Runtime validator for {@link ContextIngestion}. */
+export const contextIngestionSchema = z.object({
+    /** ID of the agent that initiated this ingestion (`agi_...`). `null` if initiated by a user. */
+    agent: z.string().optional().describe("ID of the agent that initiated this ingestion (`agi_...`). `null` if initiated by a user."),
+    /** When the ingestion job finished, either successfully or with a failure. `null` if still in progress. */
+    completed_at: z.string().optional().describe("When the ingestion job finished, either successfully or with a failure. `null` if still in progress."),
+    /** When the ingestion was submitted (ISO 8601). */
+    created_at: z.string().optional().describe("When the ingestion was submitted (ISO 8601)."),
+    /** Structured error details when the ingestion has `status: "failed"`. `null` for any other status. */
+    error: z.record(z.unknown()).optional().describe("Structured error details when the ingestion has `status: \"failed\"`. `null` for any other status."),
+    /** Context ingestion ID (`cig_...`). */
+    id: z.string().describe("Context ingestion ID (`cig_...`)."),
+    /** Arbitrary key-value metadata associated with this ingestion run. Shape is caller-defined. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata associated with this ingestion run. Shape is caller-defined."),
+    /** ID of the context source being ingested (`cso_...`). `null` if the source has been deleted. */
+    source: z.string().optional().describe("ID of the context source being ingested (`cso_...`). `null` if the source has been deleted."),
+    /** When the ingestion job began processing. `null` if the job is still pending. */
+    started_at: z.string().optional().describe("When the ingestion job began processing. `null` if the job is still pending."),
+    /** Current processing status. One of `"pending"`, `"running"`, `"awaiting_callback"`, `"succeeded"`, or `"failed"`. */
+    status: z.string().describe("Current processing status. One of `\"pending\"`, `\"running\"`, `\"awaiting_callback\"`, `\"succeeded\"`, or `\"failed\"`."),
+    /** ID of the team that owns this ingestion (`tem_...`). `null` if owned by a user or agent. */
+    team: z.string().optional().describe("ID of the team that owns this ingestion (`tem_...`). `null` if owned by a user or agent."),
+    /** When the ingestion record was last updated (ISO 8601). */
+    updated_at: z.string().optional().describe("When the ingestion record was last updated (ISO 8601)."),
+    /** ID of the user that initiated this ingestion (`usr_...`). `null` if initiated by an agent. */
+    user: z.string().optional().describe("ID of the user that initiated this ingestion (`usr_...`). `null` if initiated by an agent."),
+}).describe("A context ingestion job that processes a context source and populates its documents. Tracks status and timing from submission through completion or failure.");
+/** Runtime validator for {@link CustomObject}. */
 export const customObjectSchema = z.object({
-    created_at: z.string().optional(), // Created timestamp
-    fields: z.record(z.unknown()).optional(), // Object field values
-    id: z.string(), // Public ID (cobj_...)
-    org: z.string().optional(), // Organization
-    row_key: z.string().optional(), // Row key
-    sandbox: z.string().optional(), // Sandbox identifier
-    schema_type: z.string().optional(), // Schema type (lookup_key)
-    team: z.string().optional(), // Owning team
-    updated_at: z.string().optional(), // Updated timestamp
-    user: z.string().optional(), // Owning user
-    version: z.number().int().optional(), // Aggregate version for OCC
-});
-/** API schema for OAuth device authorization responses. */
+    /** When the custom object was created (ISO 8601). */
+    created_at: z.string().optional().describe("When the custom object was created (ISO 8601)."),
+    /** Map of field names to their current values as defined by the object's schema type. */
+    fields: z.record(z.unknown()).optional().describe("Map of field names to their current values as defined by the object's schema type."),
+    /** Unique identifier for the custom object (`cobj_...`). */
+    id: z.string().describe("Unique identifier for the custom object (`cobj_...`)."),
+    /** ID of the organization this object belongs to (`org_...`). */
+    org: z.string().optional().describe("ID of the organization this object belongs to (`org_...`)."),
+    /** An optional stable key used to identify this object by a caller-controlled string rather than its generated ID. `null` if not set. */
+    row_key: z.string().optional().describe("An optional stable key used to identify this object by a caller-controlled string rather than its generated ID. `null` if not set."),
+    /** ID of the sandbox environment this object is scoped to (`dsb_...`). `null` for production objects. */
+    sandbox: z.string().optional().describe("ID of the sandbox environment this object is scoped to (`dsb_...`). `null` for production objects."),
+    /** The lookup key of the schema type that defines this object's field structure. `null` if the schema type has not been set. */
+    schema_type: z.string().optional().describe("The lookup key of the schema type that defines this object's field structure. `null` if the schema type has not been set."),
+    /** ID of the team that owns this object (`tem_...`). `null` if the object is not team-scoped. */
+    team: z.string().optional().describe("ID of the team that owns this object (`tem_...`). `null` if the object is not team-scoped."),
+    /** When the custom object was last modified (ISO 8601). `null` if the object has never been updated after creation. */
+    updated_at: z.string().optional().describe("When the custom object was last modified (ISO 8601). `null` if the object has never been updated after creation."),
+    /** ID of the user that owns this object (`usr_...`). `null` if the object is not user-scoped. */
+    user: z.string().optional().describe("ID of the user that owns this object (`usr_...`). `null` if the object is not user-scoped."),
+    /** Optimistic concurrency version of the object. Increments with each successful update; pass this value in write operations to detect conflicting changes. */
+    version: z.number().int().optional().describe("Optimistic concurrency version of the object. Increments with each successful update; pass this value in write operations to detect conflicting changes."),
+}).describe("A custom object belonging to an organization. Custom objects store arbitrary structured data defined by a schema type and are scoped to an org, team, or user.");
+/** Runtime validator for {@link CustomObjectListResponse}. */
+export const customObjectListResponseSchema = z.object({
+    /** Array of custom objects for the current page. */
+    data: z.array(customObjectSchema).describe("Array of custom objects for the current page."),
+    /** `true` if a subsequent page of results exists; `false` if this is the last page. */
+    has_next: z.boolean().describe("`true` if a subsequent page of results exists; `false` if this is the last page."),
+    /** `true` if a preceding page of results exists; `false` if this is the first page. */
+    has_prev: z.boolean().describe("`true` if a preceding page of results exists; `false` if this is the first page."),
+    /** The current page number (1-indexed). */
+    page: z.number().int().describe("The current page number (1-indexed)."),
+    /** Maximum number of results returned per page. */
+    page_size: z.number().int().describe("Maximum number of results returned per page."),
+    /** Total number of custom objects matching the query across all pages. */
+    total_entries: z.number().int().describe("Total number of custom objects matching the query across all pages."),
+    /** Total number of pages available for the current query. */
+    total_pages: z.number().int().describe("Total number of pages available for the current query."),
+}).describe("A paginated page of custom objects returned by a list operation. Use the pagination fields to navigate through result sets.");
+/** Runtime validator for {@link CustomObjectUpdateFieldsResponse}. */
+export const customObjectUpdateFieldsResponseSchema = z.object({
+    /** Map of field names to their new values as applied during the update. Only the fields that were included in the update request are present. */
+    fields: z.record(z.unknown()).describe("Map of field names to their new values as applied during the update. Only the fields that were included in the update request are present."),
+    /** ID of the custom object that was updated (`cobj_...`). */
+    id: z.string().describe("ID of the custom object that was updated (`cobj_...`)."),
+}).describe("Response returned after updating one or more fields on a custom object. Confirms the object that was modified and the field values that were applied.");
+/** Runtime validator for {@link DeviceAuthorizationResponse}. */
 export const deviceAuthorizationResponseSchema = z.object({
-    device_code: z.string(), // Device verification code
-    expires_in: z.number().int(), // TTL in seconds
-    interval: z.number().int(), // Polling interval in seconds
-    user_code: z.string(), // User-facing verification code
-    verification_uri: z.string(), // Base verification URI
-    verification_uri_complete: z.string(), // Full verification URI with code
-});
-/** API schema for OAuth device authorization approval and denial responses. */
+    /** Opaque code identifying this device authorization session. Pass this value when polling the token endpoint; do not display it to the user. */
+    device_code: z.string().describe("Opaque code identifying this device authorization session. Pass this value when polling the token endpoint; do not display it to the user."),
+    /** Number of seconds until the `device_code` and `user_code` expire. After expiry the user must restart the authorization flow. */
+    expires_in: z.number().int().describe("Number of seconds until the `device_code` and `user_code` expire. After expiry the user must restart the authorization flow."),
+    /** Minimum number of seconds to wait between polling attempts on the token endpoint. Polling more frequently will result in a `slow_down` error. */
+    interval: z.number().int().describe("Minimum number of seconds to wait between polling attempts on the token endpoint. Polling more frequently will result in a `slow_down` error."),
+    /** Short alphanumeric code the user must enter at `verification_uri` to authorize the device. */
+    user_code: z.string().describe("Short alphanumeric code the user must enter at `verification_uri` to authorize the device."),
+    /** URL the user visits to enter the `user_code` and approve the authorization request. */
+    verification_uri: z.string().describe("URL the user visits to enter the `user_code` and approve the authorization request."),
+    /** Full verification URL with the `user_code` pre-filled as a query parameter. Display this as a QR code or deep link to reduce manual entry. */
+    verification_uri_complete: z.string().describe("Full verification URL with the `user_code` pre-filled as a query parameter. Display this as a QR code or deep link to reduce manual entry."),
+}).describe("The initial response from an OAuth 2.0 Device Authorization Grant request, containing the codes and URIs needed to complete device authentication.");
+/** Runtime validator for {@link DeviceAuthorizationStatusResponse}. */
 export const deviceAuthorizationStatusResponseSchema = z.object({
-    status: z.string(), // Authorization status (approved or denied)
-});
-/** API schema for an installation. */
+    /** Outcome of the device authorization request. One of `"approved"` (the user granted access) or `"denied"` (the user rejected or cancelled the request). */
+    status: z.string().describe("Outcome of the device authorization request. One of `\"approved\"` (the user granted access) or `\"denied\"` (the user rejected or cancelled the request)."),
+}).describe("The result of a completed OAuth 2.0 Device Authorization flow, indicating whether the user approved or denied the device's access request.");
+/** Runtime validator for {@link AgentHealthAction}. */
+export const agentHealthActionSchema = z.object({
+    /** ID of the agent this action is scoped to (`agt_...`). `null` for org-level actions. */
+    agent: z.string().optional().describe("ID of the agent this action is scoped to (`agt_...`). `null` for org-level actions."),
+    /** ID of the application this action is associated with (`app_...`). `null` when not app-scoped. */
+    app: z.string().optional().describe("ID of the application this action is associated with (`app_...`). `null` when not app-scoped."),
+    /** When this health action was first created (ISO 8601). */
+    created_at: z.string().optional().describe("When this health action was first created (ISO 8601)."),
+    /** IDs of other health actions that must reach `"completed"` status before this action can be started. Empty array when there are no dependencies. */
+    depends_on: z.array(z.string()).optional().describe("IDs of other health actions that must reach `\"completed\"` status before this action can be started. Empty array when there are no dependencies."),
+    /** Longer Markdown-formatted explanation of what the action requires and why. `null` if not provided. */
+    description: z.string().optional().describe("Longer Markdown-formatted explanation of what the action requires and why. `null` if not provided."),
+    /** Health action ID (`aha_...`). */
+    id: z.string().describe("Health action ID (`aha_...`)."),
+    /** Category of action to take. One of `"env_var"` (set a secret), `"install"` (complete an agent installation, e.g. a GitHub App), `"custom"` (agent-defined step), or `"integration"` (authorize an OAuth-backed MCP server integration). */
+    kind: z.string().describe("Category of action to take. One of `\"env_var\"` (set a secret), `\"install\"` (complete an agent installation, e.g. a GitHub App), `\"custom\"` (agent-defined step), or `\"integration\"` (authorize an OAuth-backed MCP server integration)."),
+    /** When the verifier last ran for this action (ISO 8601). `null` until the verifier has been invoked at least once. */
+    last_verified_at: z.string().optional().describe("When the verifier last ran for this action (ISO 8601). `null` until the verifier has been invoked at least once."),
+    /** Human-readable output from the most recent verifier run. `null` if the verifier has not run yet. */
+    last_verifier_message: z.string().optional().describe("Human-readable output from the most recent verifier run. `null` if the verifier has not run yet."),
+    /** ID of the organization this action is associated with (`org_...`). `null` when not org-scoped. */
+    org: z.string().optional().describe("ID of the organization this action is associated with (`org_...`). `null` when not org-scoped."),
+    /** Kind-specific structured data used to construct the deep-link for this action. For `"env_var"` actions includes `key` and `scope`; for `"install"` actions includes `installation_kind`; for `"integration"` actions includes `mcp_server_ref`, and when resolvable also includes `provider` and `integration_id` for OAuth handoff. Empty object `{}` when no additional parameters are needed. */
+    params: z.record(z.unknown()).optional().describe("Kind-specific structured data used to construct the deep-link for this action. For `\"env_var\"` actions includes `key` and `scope`; for `\"install\"` actions includes `installation_kind`; for `\"integration\"` actions includes `mcp_server_ref`, and when resolvable also includes `provider` and `integration_id` for OAuth handoff. Empty object `{}` when no additional parameters are needed."),
+    /** `true` if this action must be completed before the agent is considered fully operational and counts toward the blocking checklist progress bar. */
+    required: z.boolean().describe("`true` if this action must be completed before the agent is considered fully operational and counts toward the blocking checklist progress bar."),
+    /** Display order within the same `source` group. Lower values appear first. */
+    sort_order: z.number().int().describe("Display order within the same `source` group. Lower values appear first."),
+    /** Lifecycle stage that produced this action. One of `"setup"` (post-install checklist item) or `"health"` (probe-detected issue). */
+    source: z.string().describe("Lifecycle stage that produced this action. One of `\"setup\"` (post-install checklist item) or `\"health\"` (probe-detected issue)."),
+    /** Current resolution state. One of `"pending"` (not yet completed), `"completed"` (resolved), `"skipped"` (dismissed by the user), or `"degraded"` (completed but the verifier is reporting a warning). */
+    status: z.string().describe("Current resolution state. One of `\"pending\"` (not yet completed), `\"completed\"` (resolved), `\"skipped\"` (dismissed by the user), or `\"degraded\"` (completed but the verifier is reporting a warning)."),
+    /** Short display label for this action, intended for use as a checklist item heading. */
+    title: z.string().describe("Short display label for this action, intended for use as a checklist item heading."),
+    /** When this health action was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When this health action was last modified (ISO 8601)."),
+    /** Configuration for the action's verifier step. Contains at minimum a `type` field that indicates which verification affordance to render. Server-internal fields are stripped before this is returned. */
+    verify_config: z.record(z.unknown()).optional().describe("Configuration for the action's verifier step. Contains at minimum a `type` field that indicates which verification affordance to render. Server-internal fields are stripped before this is returned."),
+}).describe("A single actionable item in an agent's health or setup checklist, carrying the structured data needed to render the item and deep-link to the resolution flow.");
+/** Runtime validator for {@link HealthActionListResponse}. */
+export const healthActionListResponseSchema = z.object({
+    /** Array of agent health action objects representing setup checklist items and probe-detected issues. */
+    data: z.array(agentHealthActionSchema).describe("Array of agent health action objects representing setup checklist items and probe-detected issues."),
+}).describe("List response containing agent health actions for a given agent or organization.");
+/** Runtime validator for {@link Installation}. */
 export const installationSchema = z.object({
-    agent: z.string().optional(), // Owning agent
-    config: z.record(z.unknown()).optional(), // Configuration
-    created_at: z.string().optional(), // Creation timestamp
-    id: z.string(), // Installation ID (cin_...)
-    kind: z.string().optional(), // Installation kind
-    shared_integration: z.string().optional(), // Bound shared integration
-    state: z.string().optional(), // Installation state
-    status_payload: z.record(z.unknown()).optional(), // Status payload
-    updated_at: z.string().optional(), // Last update timestamp
-});
-/** API schema for an installation kind. */
+    /** ID of the agent that owns this installation (`agi_...`). `null` if the installation has no agent owner. */
+    agent: z.string().optional().describe("ID of the agent that owns this installation (`agi_...`). `null` if the installation has no agent owner."),
+    /** Kind-specific configuration object for this installation. Shape depends on the `kind` value. `null` if the kind requires no configuration. */
+    config: z.record(z.unknown()).optional().describe("Kind-specific configuration object for this installation. Shape depends on the `kind` value. `null` if the kind requires no configuration."),
+    /** When the installation was created (ISO 8601). */
+    created_at: z.string().optional().describe("When the installation was created (ISO 8601)."),
+    /** Installation ID (`cin_...`). */
+    id: z.string().describe("Installation ID (`cin_...`)."),
+    /** Slug identifying the type of external service this installation connects to, e.g. `"enablement/github_app"` or `"integration/gmail"`. `null` if not set. */
+    kind: z.string().optional().describe("Slug identifying the type of external service this installation connects to, e.g. `\"enablement/github_app\"` or `\"integration/gmail\"`. `null` if not set."),
+    /** Caller-assigned stable identifier for this installation, used to reference it in knowledge search `source_refs`. `null` if no lookup key was provided at creation time. */
+    lookup_key: z.string().optional().describe("Caller-assigned stable identifier for this installation, used to reference it in knowledge search `source_refs`. `null` if no lookup key was provided at creation time."),
+    /** ID of the shared org- or app-level integration bound to this installation (`int_...`). `null` if no integration has been bound. */
+    shared_integration: z.string().optional().describe("ID of the shared org- or app-level integration bound to this installation (`int_...`). `null` if no integration has been bound."),
+    /** Current lifecycle state of the installation. One of `"pending"`, `"active"`, `"paused"`, or `"error"`. `"error"` indicates the installation was suspended due to a policy or compliance issue and requires attention. */
+    state: z.string().optional().describe("Current lifecycle state of the installation. One of `\"pending\"`, `\"active\"`, `\"paused\"`, or `\"error\"`. `\"error\"` indicates the installation was suspended due to a policy or compliance issue and requires attention."),
+    /** Provider-supplied status detail for this installation, set during activation or event processing. `null` if no status has been reported. */
+    status_payload: z.record(z.unknown()).optional().describe("Provider-supplied status detail for this installation, set during activation or event processing. `null` if no status has been reported."),
+    /** When the installation record was last updated (ISO 8601). */
+    updated_at: z.string().optional().describe("When the installation record was last updated (ISO 8601)."),
+}).describe("An installation representing a connection between an agent and an external service or enablement channel. Tracks configuration, lifecycle state, and any bound integration.");
+/** Runtime validator for {@link InstallationKind}. */
 export const installationKindSchema = z.object({
-    accepts_sources: z.boolean().optional(), // Whether this kind accepts sources
-    category: z.string().optional(), // Category
-    config_schema: z.record(z.unknown()).optional(), // JSON schema for configuration
-    description: z.string().optional(), // Description
-    kind: z.string(), // Installation kind identifier
-    label: z.string().optional(), // Display label
-    provider: z.string().optional(), // Integration provider
-    requires_integration: z.boolean().optional(), // Whether this kind requires an integration
-});
-/** List response for installation kinds. */
+    /** When `true`, sources can be attached to installations of this kind to supply additional context to the agent. */
+    accepts_sources: z.boolean().optional().describe("When `true`, sources can be attached to installations of this kind to supply additional context to the agent."),
+    /** Grouping category for UI display purposes, e.g. `"enablement"` or `"integration"`. `null` if uncategorized. */
+    category: z.string().optional().describe("Grouping category for UI display purposes, e.g. `\"enablement\"` or `\"integration\"`. `null` if uncategorized."),
+    /** JSON Schema object describing the shape of the `config` parameter accepted when creating or updating an installation of this kind. `null` if the kind accepts no configuration. */
+    config_schema: z.record(z.unknown()).optional().describe("JSON Schema object describing the shape of the `config` parameter accepted when creating or updating an installation of this kind. `null` if the kind accepts no configuration."),
+    /** Short prose description of what this kind connects to and how it is used. `null` if no description is defined. */
+    description: z.string().optional().describe("Short prose description of what this kind connects to and how it is used. `null` if no description is defined."),
+    /** Unique slug identifying this installation kind, e.g. `"enablement/github_app"`, `"integration/gmail"`, or `"web/site"`. Pass this value as `kind` when creating an installation. */
+    kind: z.string().describe("Unique slug identifying this installation kind, e.g. `\"enablement/github_app\"`, `\"integration/gmail\"`, or `\"web/site\"`. Pass this value as `kind` when creating an installation."),
+    /** Human-readable display name for this kind, e.g. `"GitHub App"`. `null` if the kind has no label defined. */
+    label: z.string().optional().describe("Human-readable display name for this kind, e.g. `\"GitHub App\"`. `null` if the kind has no label defined."),
+    /** Identifier of the external provider this kind connects to, e.g. `"github"` or `"slack"`. `null` for kinds with no specific provider. */
+    provider: z.string().optional().describe("Identifier of the external provider this kind connects to, e.g. `\"github\"` or `\"slack\"`. `null` for kinds with no specific provider."),
+    /** When `true`, this kind requires an integration to be provided (either inline or via `shared_integration`) before the installation can be activated. */
+    requires_integration: z.boolean().optional().describe("When `true`, this kind requires an integration to be provided (either inline or via `shared_integration`) before the installation can be activated."),
+}).describe("A supported installation kind describing a category of external service or enablement channel an agent can be connected to.");
+/** Runtime validator for {@link InstallationKindListResponse}. */
 export const installationKindListResponseSchema = z.object({
-    data: z.array(installationKindSchema), // List of installation kinds
-});
-/** List response for installations. */
+    /** Array of installation kind objects describing the available integration types and their configuration requirements. */
+    data: z.array(installationKindSchema).describe("Array of installation kind objects describing the available integration types and their configuration requirements."),
+}).describe("List response containing all available installation kinds that can be used when configuring an agent installation.");
+/** Runtime validator for {@link InstallationListResponse}. */
 export const installationListResponseSchema = z.object({
-    data: z.array(installationSchema), // List of installations
-});
-/** API schema for an installation source. */
+    /** Array of installation objects returned for the current page. */
+    data: z.array(installationSchema).describe("Array of installation objects returned for the current page."),
+}).describe("Paginated list response containing installation objects for an agent.");
+/** Runtime validator for {@link InstallationSource}. */
 export const installationSourceSchema = z.object({
-    agent: z.string().optional(), // Owning agent
-    context_installation: z.string().optional(), // Installation ID
-    created_at: z.string().optional(), // Creation timestamp
-    id: z.string(), // Source ID (cso_...)
-    metadata: z.record(z.unknown()).optional(), // Arbitrary metadata
-    parent_source: z.string().optional(), // Parent source ID
-    payload: z.record(z.unknown()).optional(), // Source payload
-    state: z.string().optional(), // Source state
-    team: z.string().optional(), // Team ID
-    thread: z.string().optional(), // Thread ID
-    type: z.string().optional(), // Source type
-    updated_at: z.string().optional(), // Last update timestamp
-    user: z.string().optional(), // User ID
-});
-/** List response for installation sources. */
+    /** ID of the agent that owns this source (`agi_...`). `null` if the source is not agent-owned. */
+    agent: z.string().optional().describe("ID of the agent that owns this source (`agi_...`). `null` if the source is not agent-owned."),
+    /** ID of the installation this source belongs to (`cin_...`). `null` if the source is not attached to an installation. */
+    context_installation: z.string().optional().describe("ID of the installation this source belongs to (`cin_...`). `null` if the source is not attached to an installation."),
+    /** When the source was created (ISO 8601). */
+    created_at: z.string().optional().describe("When the source was created (ISO 8601)."),
+    /** Source ID (`cso_...`). */
+    id: z.string().describe("Source ID (`cso_...`)."),
+    /** Arbitrary key-value metadata associated with this source. Shape is caller-defined. `null` if no metadata was set. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata associated with this source. Shape is caller-defined. `null` if no metadata was set."),
+    /** ID of the parent source (`cso_...`) when this source was derived from another source. `null` for top-level sources. */
+    parent_source: z.string().optional().describe("ID of the parent source (`cso_...`) when this source was derived from another source. `null` for top-level sources."),
+    /** Type-specific payload provided when the source was created. The shape depends on the `type` value. `null` if no payload was supplied. */
+    payload: z.record(z.unknown()).optional().describe("Type-specific payload provided when the source was created. The shape depends on the `type` value. `null` if no payload was supplied."),
+    /** Current lifecycle state of this source. One of `"active"` (ingestion running normally) or `"paused"` (ingestion suspended). Note that per-run ingestion progress is tracked separately and is not exposed on this field. */
+    state: z.string().optional().describe("Current lifecycle state of this source. One of `\"active\"` (ingestion running normally) or `\"paused\"` (ingestion suspended). Note that per-run ingestion progress is tracked separately and is not exposed on this field."),
+    /** ID of the team associated with this source (`tem_...`). `null` if the source has no team association. */
+    team: z.string().optional().describe("ID of the team associated with this source (`tem_...`). `null` if the source has no team association."),
+    /** ID of the conversation thread linked to this source (`thr_...`). `null` if the source is not thread-scoped. */
+    thread: z.string().optional().describe("ID of the conversation thread linked to this source (`thr_...`). `null` if the source is not thread-scoped."),
+    /** Slug identifying the kind of content this source provides, e.g. `"file/document"` or `"web/link"`. `null` if the type is not set. */
+    type: z.string().optional().describe("Slug identifying the kind of content this source provides, e.g. `\"file/document\"` or `\"web/link\"`. `null` if the type is not set."),
+    /** When the source record was last updated (ISO 8601). */
+    updated_at: z.string().optional().describe("When the source record was last updated (ISO 8601)."),
+    /** ID of the user associated with this source (`usr_...`). `null` if the source has no user association. */
+    user: z.string().optional().describe("ID of the user associated with this source (`usr_...`). `null` if the source has no user association."),
+}).describe("A source attached to an installation that supplies content for the agent's context. Sources are processed asynchronously after creation.");
+/** Runtime validator for {@link InstallationSourceListResponse}. */
 export const installationSourceListResponseSchema = z.object({
-    data: z.array(installationSourceSchema), // List of installation sources
-});
-/** Schema for a key-value storage entry.
-
-Maps exactly to render_entry/1 output in ApiStorageController.
- */
+    /** Array of installation source objects returned for the current page. */
+    data: z.array(installationSourceSchema).describe("Array of installation source objects returned for the current page."),
+}).describe("Paginated list response containing installation source objects attached to an installation.");
+/** Runtime validator for {@link KeyValueStorageEntry}. */
 export const keyValueStorageEntrySchema = z.object({
-    created_at: z.string().optional(), // Creation timestamp
-    key: z.string(), // Storage key
-    updated_at: z.string().optional(), // Last update timestamp
-    user: z.string(), // User
-    value: z.string(), // Stored value
-});
-/** Schema for a key-value storage entry, optionally enriched with a summary of
-the owning user.
-
-Used by the dual-mode list endpoint: user-JWT callers omit the user_email /
-user_name fields (they know who they are); developer / S2S callers populate
-them so the portal can render an owner column without a per-row lookup.
- */
+    /** When this storage entry was first created (ISO 8601). `null` if not yet persisted. */
+    created_at: z.string().optional().describe("When this storage entry was first created (ISO 8601). `null` if not yet persisted."),
+    /** The string key used to store and look up this entry. */
+    key: z.string().describe("The string key used to store and look up this entry."),
+    /** When this storage entry was last updated (ISO 8601). `null` if not yet persisted. */
+    updated_at: z.string().optional().describe("When this storage entry was last updated (ISO 8601). `null` if not yet persisted."),
+    /** ID of the user who owns this storage entry (`usr_...`). */
+    user: z.string().describe("ID of the user who owns this storage entry (`usr_...`)."),
+    /** The string value stored under `key` for this user. */
+    value: z.string().describe("The string value stored under `key` for this user."),
+}).describe("A single key-value storage entry belonging to a user. Represents one key/value pair written to a user's isolated storage namespace within an app.");
+/** Runtime validator for {@link KeyValueStorageEntryWithUser}. */
 export const keyValueStorageEntryWithUserSchema = z.object({
-    created_at: z.string(), // Creation timestamp
-    key: z.string(), // Storage key
-    updated_at: z.string(), // Last update timestamp
-    user: z.string(), // User ID
-    user_email: z.string().optional(), // User email (developer / S2S only)
-    user_name: z.string().optional(), // User display name (developer / S2S only)
-    value: z.string(), // Stored value
-});
-/** Response envelope for the dual-mode key-value list endpoint.
-
-User-JWT callers receive `%{data: [...]}` (no pagination fields).
-Developer / S2S callers receive `%{data: [...]}` plus pagination metadata.
- */
+    /** When this storage entry was first created (ISO 8601). */
+    created_at: z.string().describe("When this storage entry was first created (ISO 8601)."),
+    /** The string key used to store and look up this entry. */
+    key: z.string().describe("The string key used to store and look up this entry."),
+    /** When this storage entry was last updated (ISO 8601). */
+    updated_at: z.string().describe("When this storage entry was last updated (ISO 8601)."),
+    /** ID of the user who owns this storage entry (`usr_...`). */
+    user: z.string().describe("ID of the user who owns this storage entry (`usr_...`)."),
+    /** Email address of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers. */
+    user_email: z.string().optional().describe("Email address of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers."),
+    /** Display name of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers. */
+    user_name: z.string().optional().describe("Display name of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers."),
+    /** The string value stored under `key` for this user. */
+    value: z.string().describe("The string value stored under `key` for this user."),
+}).describe("A key-value storage entry enriched with owner information. Developer and server-to-server callers receive `user_email` and `user_name` populated; end-user (user-JWT) callers receive those fields as `null`.");
+/** Runtime validator for {@link KeyValueStorageEntryPage}. */
 export const keyValueStorageEntryPageSchema = z.object({
-    data: z.array(keyValueStorageEntryWithUserSchema), // Storage entries on this page
-    has_next: z.boolean().optional(), // Whether a next page exists (developer / S2S only)
-    has_prev: z.boolean().optional(), // Whether a previous page exists (developer / S2S only)
-    page: z.number().int().optional(), // Current page number (developer / S2S only)
-    page_size: z.number().int().optional(), // Results per page (developer / S2S only)
-    total_entries: z.number().int().optional(), // Total entries matching the filters (developer / S2S only)
-    total_pages: z.number().int().optional(), // Total number of pages (developer / S2S only)
-});
-/** Schema for inline message reactions.
-
-This is the compact format used in Message.reactions[], which differs from
-the full Reaction schema used in standalone reaction endpoints.
-Maps to format_reactions_for_client/1 output.
- */
-export const messageReactionSchema = z.object({
-    payload: z.record(z.unknown()).optional(), // Reaction payload (e.g., {emoji: '👍'})
-    type: z.string(), // Reaction type (e.g., emoji_reaction)
-    user: z.string().optional(), // User who added the reaction
-});
-/** API schema for a chat message. */
-export const messageSchema = z.object({
-    actors: z.array(actorSchema).optional(), // Message actors
-    agent: z.string().optional(), // Agent if sent by an agent user
-    attachments: z.array(attachmentSchema).optional(), // Message attachments
-    branched_thread: z.string().optional(), // Branched thread (if message spawned a thread)
-    content: z.string().optional(), // Message content
-    created_at: z.string().optional(), // Creation timestamp
-    has_replies: z.boolean().optional(), // Whether message has replies
-    id: z.string(), // Message ID (msg_...)
-    idempotency_key: z.string().optional(), // Client-provided idempotency key
-    legacy_agent: z.string().optional(), // Legacy agent if sent by legacy chat agent
-    metadata: z.record(z.unknown()).optional(), // Message metadata
-    org: z.string().optional(), // Organization
-    reactions: z.array(messageReactionSchema).optional(), // Message reactions
-    rendering_mode: z.string().optional(), // Rendering mode hint
-    replies: z.array(z.record(z.unknown())).optional(), // Inline replies (if loaded)
-    replies_after_cursor: z.string().optional(), // Cursor for replies pagination
-    replies_before_cursor: z.string().optional(), // Cursor for replies pagination
-    reply_count: z.number().int().optional(), // Number of replies
-    reply_to: z.record(z.unknown()).optional(), // Parent message object (if loaded)
-    sandbox: z.string().optional(), // Sandbox identifier
-    team: z.string().optional(), // Team
-    thread: z.string().optional(), // Parent thread
-    user: z.string().optional(), // Author user (public ID or expanded object when loaded)
-});
-/** API schema for OAuth token endpoint responses. */
+    /** Array of key-value storage entries for the current page. */
+    data: z.array(keyValueStorageEntryWithUserSchema).describe("Array of key-value storage entries for the current page."),
+    /** Whether a subsequent page exists. `false` when the current page is the last page. Present only for developer and server-to-server callers. */
+    has_next: z.boolean().optional().describe("Whether a subsequent page exists. `false` when the current page is the last page. Present only for developer and server-to-server callers."),
+    /** Whether a preceding page exists. `false` when the current page is the first page. Present only for developer and server-to-server callers. */
+    has_prev: z.boolean().optional().describe("Whether a preceding page exists. `false` when the current page is the first page. Present only for developer and server-to-server callers."),
+    /** Current page number (1-indexed). Present only for developer and server-to-server callers. */
+    page: z.number().int().optional().describe("Current page number (1-indexed). Present only for developer and server-to-server callers."),
+    /** Maximum number of results returned per page. Present only for developer and server-to-server callers. */
+    page_size: z.number().int().optional().describe("Maximum number of results returned per page. Present only for developer and server-to-server callers."),
+    /** Total number of storage entries matching the applied filters across all pages. Present only for developer and server-to-server callers. */
+    total_entries: z.number().int().optional().describe("Total number of storage entries matching the applied filters across all pages. Present only for developer and server-to-server callers."),
+    /** Total number of pages available given the current `page_size`. Present only for developer and server-to-server callers. */
+    total_pages: z.number().int().optional().describe("Total number of pages available given the current `page_size`. Present only for developer and server-to-server callers."),
+}).describe("Paginated response envelope for the dual-mode key-value storage list endpoint. End-user (user-JWT) callers receive only `data`; developer and server-to-server callers also receive pagination metadata fields.");
+/** Runtime validator for {@link KnowledgeSource}. */
+export const knowledgeSourceSchema = z.object({
+    /** ID of the agent that owns this source (`agt_...`). `null` if owned by a human user or team. */
+    agent: z.string().optional().describe("ID of the agent that owns this source (`agt_...`). `null` if owned by a human user or team."),
+    /** ID of the context installation that provisioned this source (`cin_...`). `null` when the source was created directly rather than through an installation. */
+    context_installation: z.string().optional().describe("ID of the context installation that provisioned this source (`cin_...`). `null` when the source was created directly rather than through an installation."),
+    /** When this knowledge source was created (ISO 8601). */
+    created_at: z.string().optional().describe("When this knowledge source was created (ISO 8601)."),
+    /** Knowledge source ID (`cso_...`). */
+    id: z.string().describe("Knowledge source ID (`cso_...`)."),
+    /** Arbitrary key-value metadata attached to this source. Useful for storing caller-defined labels or references. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata attached to this source. Useful for storing caller-defined labels or references."),
+    /** ID of the organization this source belongs to (`org_...`). `null` if not scoped to an org. */
+    org: z.string().optional().describe("ID of the organization this source belongs to (`org_...`). `null` if not scoped to an org."),
+    /** ID of the parent knowledge source (`cso_...`) when this source was derived from another. `null` for top-level sources. */
+    parent_source: z.string().optional().describe("ID of the parent knowledge source (`cso_...`) when this source was derived from another. `null` for top-level sources."),
+    /** Type-specific configuration object. The keys depend on the source `type`; see the create endpoint for the expected shape per type. */
+    payload: z.record(z.unknown()).optional().describe("Type-specific configuration object. The keys depend on the source `type`; see the create endpoint for the expected shape per type."),
+    /** ID of the developer sandbox this source is scoped to (`sbx_...`). `null` outside sandbox contexts. */
+    sandbox: z.string().optional().describe("ID of the developer sandbox this source is scoped to (`sbx_...`). `null` outside sandbox contexts."),
+    /** Current lifecycle state of the source. One of `"active"` (ingestion running normally) or `"paused"` (ingestion suspended). */
+    state: z.string().describe("Current lifecycle state of the source. One of `\"active\"` (ingestion running normally) or `\"paused\"` (ingestion suspended)."),
+    /** ID of the team that owns this source (`tea_...`). `null` if owned by a user, agent, or org. */
+    team: z.string().optional().describe("ID of the team that owns this source (`tea_...`). `null` if owned by a user, agent, or org."),
+    /** ID of the chat thread this source is associated with (`thr_...`). `null` when not thread-scoped. */
+    thread: z.string().optional().describe("ID of the chat thread this source is associated with (`thr_...`). `null` when not thread-scoped."),
+    /** Source type identifier (e.g. `"gmail"`, `"github_activity"`). Determines the shape of `payload` and the ingestion behavior. */
+    type: z.string().describe("Source type identifier (e.g. `\"gmail\"`, `\"github_activity\"`). Determines the shape of `payload` and the ingestion behavior."),
+    /** When this knowledge source was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When this knowledge source was last modified (ISO 8601)."),
+    /** ID of the user that owns this source (`usr_...`). `null` if owned by a team, agent, or org. */
+    user: z.string().optional().describe("ID of the user that owns this source (`usr_...`). `null` if owned by a team, agent, or org."),
+}).describe("A knowledge source that ingests content into the knowledge base. Sources connect to external systems (e.g. Gmail, GitHub) and continuously or on-demand index items for search.");
+/** Runtime validator for {@link KnowledgeSourceKind}. */
+export const knowledgeSourceKindSchema = z.object({
+    /** Short description of what this source kind ingests and how it is used. */
+    description: z.string().optional().describe("Short description of what this source kind ingests and how it is used."),
+    /** Human-readable display name for this source kind, suitable for showing in a UI. */
+    label: z.string().optional().describe("Human-readable display name for this source kind, suitable for showing in a UI."),
+    /** Machine-readable type identifier for this source kind (e.g. `"gmail"`, `"github_activity"`). Pass this value as `type` when creating a knowledge source. */
+    type: z.string().describe("Machine-readable type identifier for this source kind (e.g. `\"gmail\"`, `\"github_activity\"`). Pass this value as `type` when creating a knowledge source."),
+}).describe("Describes a single knowledge source kind that can be created through the public API. Use the `type` value when creating a new knowledge source.");
+/** Runtime validator for {@link KnowledgeSourceKindListResponse}. */
+export const knowledgeSourceKindListResponseSchema = z.object({
+    /** Array of knowledge source kind objects describing each creatable source type. */
+    data: z.array(knowledgeSourceKindSchema).describe("Array of knowledge source kind objects describing each creatable source type."),
+}).describe("List response containing the knowledge source kinds available for creation via the API.");
+/** Runtime validator for {@link OAuthTokenResponse}. */
 export const oAuthTokenResponseSchema = z.object({
-    access_token: z.string(), // OAuth access token
-    expires_in: z.number().int(), // Token TTL in seconds
-    refresh_token: z.string().optional(), // OAuth refresh token
-    scope: z.string().optional(), // Granted scopes (space-separated)
-    token_type: z.string(), // Token type (Bearer)
-    user: userSchema.optional(), // Authenticated user
-});
-/** Schema for paginated message replies response.
-
-Used by message replies list endpoints.
-Note: This response is NOT wrapped in a "data" field.
- */
+    /** Bearer token used to authenticate API requests. Include this value in the `Authorization: Bearer <token>` header. */
+    access_token: z.string().describe("Bearer token used to authenticate API requests. Include this value in the `Authorization: Bearer <token>` header."),
+    /** Number of seconds until the access token expires. */
+    expires_in: z.number().int().describe("Number of seconds until the access token expires."),
+    /** Token that can be exchanged for a new access token once the current one expires. `null` if the grant type does not issue refresh tokens. */
+    refresh_token: z.string().optional().describe("Token that can be exchanged for a new access token once the current one expires. `null` if the grant type does not issue refresh tokens."),
+    /** Space-separated list of scopes granted to the access token. `null` if scope was not included in the grant request. */
+    scope: z.string().optional().describe("Space-separated list of scopes granted to the access token. `null` if scope was not included in the grant request."),
+    /** Token type. Always `"Bearer"`. */
+    token_type: z.string().describe("Token type. Always `\"Bearer\"`."),
+    /** The authenticated user associated with this token. `null` when the token is not tied to a specific user (e.g. client-credentials grants). */
+    user: userSchema.optional().describe("The authenticated user associated with this token. `null` when the token is not tied to a specific user (e.g. client-credentials grants)."),
+}).describe("A successful OAuth 2.0 token response. Issued by the token endpoint after a completed authorization or device-flow grant.");
+/** Runtime validator for {@link PaginatedReplies}. */
 export const paginatedRepliesSchema = z.object({
-    after_cursor: z.string().optional(), // Cursor for fetching items after this point
-    before_cursor: z.string().optional(), // Cursor for fetching items before this point
-    has_more: z.boolean().optional(), // Whether more replies exist beyond the current page
-    replies: z.array(messageSchema), // List of reply message objects
-    total_count: z.number().int().optional(), // Total number of replies
-});
-/** A routine preset entry in the preset listing endpoint. Describes *what*
-a preset is, not a per-routine configuration — that's `PresetConfig`.
- */
+    /** Opaque cursor to pass as the pagination cursor to retrieve the page of replies that follow this one. `null` when no further pages exist. */
+    after_cursor: z.string().optional().describe("Opaque cursor to pass as the pagination cursor to retrieve the page of replies that follow this one. `null` when no further pages exist."),
+    /** Opaque cursor to pass as the pagination cursor to retrieve the page of replies that precede this one. `null` when no earlier pages exist. */
+    before_cursor: z.string().optional().describe("Opaque cursor to pass as the pagination cursor to retrieve the page of replies that precede this one. `null` when no earlier pages exist."),
+    /** Whether additional reply pages exist beyond the current page. */
+    has_more: z.boolean().optional().describe("Whether additional reply pages exist beyond the current page."),
+    /** Array of reply message objects for the current page. */
+    replies: z.array(messageSchema).describe("Array of reply message objects for the current page."),
+    /** Total number of replies in the thread across all pages. */
+    total_count: z.number().int().optional().describe("Total number of replies in the thread across all pages."),
+}).describe("A paginated list of reply messages for a thread. The reply array is returned directly, not nested inside a `data` wrapper.");
+/** Runtime validator for {@link RoutinePreset}. */
 export const routinePresetSchema = z.object({
-    applicable_events: z.array(z.string()), // Event types this preset accepts. `["*"]` means any event. Other event types are rejected at routine validation time.
-    chainable: z.boolean(), // Whether this preset may appear as a step inside a `:chain` routine. Presets with session or async execution models are not chainable.
-    description: z.string(), // Preset description
-    label: z.string(), // Display label
-    name: z.string(), // Preset name (e.g. do_task)
-    sessionable: z.boolean(), // Whether this preset maintains a persistent chatroom session across turns (e.g. `participate`). Sessionable presets don't expose instructions or session-mode fields at the routine level.
-    unique: z.boolean(), // Whether only one routine with this preset may exist per agent. Enforced at the AgentRoutine unique-index layer.
-});
-/** Schema for config validation result.
- */
+    /** Event types that routines using this preset may be triggered by. `["*"]` means the preset accepts any event type. Routines assigned to this preset will be rejected at creation time if their trigger event is not in this list. */
+    applicable_events: z.array(z.string()).describe("Event types that routines using this preset may be triggered by. `[\"*\"]` means the preset accepts any event type. Routines assigned to this preset will be rejected at creation time if their trigger event is not in this list."),
+    /** Whether routines using this preset can be composed as a step inside a chain routine. Presets with sessionable or asynchronous execution models are not chainable. */
+    chainable: z.boolean().describe("Whether routines using this preset can be composed as a step inside a chain routine. Presets with sessionable or asynchronous execution models are not chainable."),
+    /** Human-readable description of what the preset does and when to use it. */
+    description: z.string().describe("Human-readable description of what the preset does and when to use it."),
+    /** Human-readable display name for the preset, suitable for use in UIs. */
+    label: z.string().describe("Human-readable display name for the preset, suitable for use in UIs."),
+    /** Stable machine identifier for the preset, e.g. `"do_task"`. Used when assigning a preset to a routine. */
+    name: z.string().describe("Stable machine identifier for the preset, e.g. `\"do_task\"`. Used when assigning a preset to a routine."),
+    /** Whether routines using this preset maintain a persistent conversation session across invocations. Sessionable presets do not expose instruction or session-mode configuration on individual routines. */
+    sessionable: z.boolean().describe("Whether routines using this preset maintain a persistent conversation session across invocations. Sessionable presets do not expose instruction or session-mode configuration on individual routines."),
+    /** Whether at most one routine with this preset may exist per agent. Attempting to create a second routine with a unique preset on the same agent will be rejected. */
+    unique: z.boolean().describe("Whether at most one routine with this preset may exist per agent. Attempting to create a second routine with a unique preset on the same agent will be rejected."),
+}).describe("A named preset that defines the execution model and constraints for a routine. Presets are shared definitions; individual routines reference a preset by name.");
+/** Runtime validator for {@link SlackChannelBinding}. */
+export const slackChannelBindingSchema = z.object({
+    /** IDs of the agents attached to this binding. Empty array when no agents are assigned. */
+    agents: z.array(z.string()).optional().describe("IDs of the agents attached to this binding. Empty array when no agents are assigned."),
+    /** Slack channel ID (e.g. `C01234ABCDE`) that this binding targets. */
+    channel: z.string().optional().describe("Slack channel ID (e.g. `C01234ABCDE`) that this binding targets."),
+    /** Human-readable label identifying the customer, derived from the binding's embedded config. `null` when not set. */
+    customer_label: z.string().optional().describe("Human-readable label identifying the customer, derived from the binding's embedded config. `null` when not set."),
+    /** Unique identifier for this Slack channel binding. */
+    id: z.string().describe("Unique identifier for this Slack channel binding."),
+    /** ID of the Slack integration that owns this binding. */
+    integration: z.string().optional().describe("ID of the Slack integration that owns this binding."),
+    /** Cached value of Slack's `is_ext_shared` flag for this channel. May be stale relative to Slack's current state. */
+    is_ext_shared_cached: z.boolean().optional().describe("Cached value of Slack's `is_ext_shared` flag for this channel. May be stale relative to Slack's current state."),
+    /** ID of the ArchAstro team this channel is bound to. */
+    team: z.string().optional().describe("ID of the ArchAstro team this channel is bound to."),
+}).describe("A binding that connects a Slack channel to an ArchAstro team and one or more agents, enabling those agents to receive and respond to messages in that channel.");
+/** Runtime validator for {@link SlackChannelBindingListResponse}. */
+export const slackChannelBindingListResponseSchema = z.object({
+    /** Array of Slack channel binding objects for the current page. */
+    data: z.array(slackChannelBindingSchema).describe("Array of Slack channel binding objects for the current page."),
+    /** Current page number (1-indexed). */
+    page: z.number().int().describe("Current page number (1-indexed)."),
+    /** Maximum number of bindings returned per page. */
+    per_page: z.number().int().describe("Maximum number of bindings returned per page."),
+    /** Total number of Slack channel bindings matching the query across all pages. */
+    total_count: z.number().int().describe("Total number of Slack channel bindings matching the query across all pages."),
+    /** Total number of pages available at the current `per_page` size. */
+    total_pages: z.number().int().describe("Total number of pages available at the current `per_page` size."),
+}).describe("Paginated list of Slack channel bindings for the requested integration or team. Use the `page` and `per_page` fields to navigate pages of results.");
+/** Runtime validator for {@link StorageFile}. */
+export const storageFileSchema = z.object({
+    /** MIME type of the file, e.g. `"image/png"` or `"application/pdf"`. */
+    content_type: z.string().optional().describe("MIME type of the file, e.g. `\"image/png\"` or `\"application/pdf\"`."),
+    /** When the file was uploaded (ISO 8601). */
+    created_at: z.string().optional().describe("When the file was uploaded (ISO 8601)."),
+    /** Original filename as provided at upload time. */
+    filename: z.string().optional().describe("Original filename as provided at upload time."),
+    /** File ID (`fil_...`). */
+    id: z.string().describe("File ID (`fil_...`)."),
+    /** Image display metadata. Present only when `content_type` is an image type; `null` otherwise. */
+    image_source: imageSourceSchema.optional().describe("Image display metadata. Present only when `content_type` is an image type; `null` otherwise."),
+    /** ID of the organization that owns this file (`org_...`). */
+    org: z.string().optional().describe("ID of the organization that owns this file (`org_...`)."),
+    /** ID of the sandbox this file is scoped to (`sbx_...`). `null` for files not associated with a sandbox. */
+    sandbox: z.string().optional().describe("ID of the sandbox this file is scoped to (`sbx_...`). `null` for files not associated with a sandbox."),
+    /** Size of the file in bytes. */
+    size: z.number().int().optional().describe("Size of the file in bytes."),
+    /** When the file record was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When the file record was last modified (ISO 8601)."),
+    /** Short-lived signed URL for downloading the file. `null` if a URL could not be generated. */
+    url: z.string().optional().describe("Short-lived signed URL for downloading the file. `null` if a URL could not be generated."),
+}).describe("A file stored in the platform's object storage, with metadata and a signed URL for downloading its contents.");
+/** Runtime validator for {@link ValidationResult}. */
 export const validationResultSchema = z.object({
-    errors: z.array(z.string()).optional(), // List of validation errors
-    valid: z.boolean(), // Whether the config is valid
-    warnings: z.array(z.string()).optional(), // Optional warnings emitted during validation
-});
-/** API schema for a working memory entry. */
+    /** List of human-readable error messages describing why validation failed. Empty or absent when `valid` is `true`. */
+    errors: z.array(z.string()).optional().describe("List of human-readable error messages describing why validation failed. Empty or absent when `valid` is `true`."),
+    /** `true` if the configuration passed all validation checks, `false` if one or more errors were found. */
+    valid: z.boolean().describe("`true` if the configuration passed all validation checks, `false` if one or more errors were found."),
+    /** List of human-readable warning messages emitted during validation. Warnings do not cause `valid` to be `false` but indicate potentially problematic configuration. */
+    warnings: z.array(z.string()).optional().describe("List of human-readable warning messages emitted during validation. Warnings do not cause `valid` to be `false` but indicate potentially problematic configuration."),
+}).describe("The result of a configuration validation check, indicating whether the config is valid and listing any errors or warnings.");
+/** Runtime validator for {@link WorkingMemoryEntry}. */
 export const workingMemoryEntrySchema = z.object({
-    agent: z.string().optional(), // Owning agent
-    created_at: z.string().optional(), // Creation timestamp
-    expires_at: z.string().optional(), // Expiration timestamp
-    id: z.string(), // Memory entry ID (amm_...)
-    key: z.string().optional(), // Memory key
-    updated_at: z.string().optional(), // Last update timestamp
-    value: z.string().optional(), // Memory value
-});
-/** Paginated list response for working memory entries. */
+    /** ID of the agent that owns this memory entry (`agt_...`). */
+    agent: z.string().optional().describe("ID of the agent that owns this memory entry (`agt_...`)."),
+    /** When this memory entry was first written (ISO 8601). */
+    created_at: z.string().optional().describe("When this memory entry was first written (ISO 8601)."),
+    /** When this entry will be automatically deleted. `null` if the entry does not expire. */
+    expires_at: z.string().optional().describe("When this entry will be automatically deleted. `null` if the entry does not expire."),
+    /** Working memory entry ID (`amm_...`). */
+    id: z.string().describe("Working memory entry ID (`amm_...`)."),
+    /** The string key used to look up this memory entry within the agent's memory namespace. */
+    key: z.string().optional().describe("The string key used to look up this memory entry within the agent's memory namespace."),
+    /** When this memory entry was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When this memory entry was last modified (ISO 8601)."),
+    /** The string value stored under `key`. May be any serialized content the agent wrote. */
+    value: z.string().optional().describe("The string value stored under `key`. May be any serialized content the agent wrote."),
+}).describe("A key-value memory record stored for an agent, optionally scoped to a user. Memory entries persist across invocations and may carry an expiration time.");
+/** Runtime validator for {@link WorkingMemoryEntryListResponse}. */
 export const workingMemoryEntryListResponseSchema = z.object({
-    data: z.array(workingMemoryEntrySchema), // List of working memory entries
-    has_next: z.boolean().optional(), // Whether a next page exists
-    has_prev: z.boolean().optional(), // Whether a previous page exists
-    page: z.number().int().optional(), // Current page number
-    page_size: z.number().int().optional(), // Results per page
-    total_entries: z.number().int().optional(), // Total number of entries
-    total_pages: z.number().int().optional(), // Total number of pages
-});
+    /** Array of working memory entry objects for the current page. */
+    data: z.array(workingMemoryEntrySchema).describe("Array of working memory entry objects for the current page."),
+    /** `true` if a subsequent page exists and can be fetched by incrementing the page number. */
+    has_next: z.boolean().optional().describe("`true` if a subsequent page exists and can be fetched by incrementing the page number."),
+    /** `true` if a previous page exists and can be fetched by decrementing the page number. */
+    has_prev: z.boolean().optional().describe("`true` if a previous page exists and can be fetched by decrementing the page number."),
+    /** The current page number, starting at `1`. */
+    page: z.number().int().optional().describe("The current page number, starting at `1`."),
+    /** Maximum number of entries returned per page. */
+    page_size: z.number().int().optional().describe("Maximum number of entries returned per page."),
+    /** Total number of working memory entries matching the query across all pages. */
+    total_entries: z.number().int().optional().describe("Total number of working memory entries matching the query across all pages."),
+    /** Total number of pages given the current `page_size`. */
+    total_pages: z.number().int().optional().describe("Total number of pages given the current `page_size`."),
+}).describe("Paginated list of working memory entries stored for an agent. Includes page metadata to support sequential page traversal.");
+/** Runtime validator for {@link SolutionTemplateSummary}. */
+export const solutionTemplateSummarySchema = z.object({
+    /** Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel. */
+    description: z.string().optional().describe("Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel."),
+    /** Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`. */
+    display_name: z.string().optional().describe("Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`."),
+    /** Template config ID (`cfg_...`). `null` for inline-only templates. */
+    id: z.string().optional().describe("Template config ID (`cfg_...`). `null` for inline-only templates."),
+    /** Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved. */
+    kind: z.string().describe("Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved."),
+    /** Lookup key stamped on the template config at import time. `null` when no lookup key was assigned. */
+    lookup_key: z.string().optional().describe("Lookup key stamped on the template config at import time. `null` when no lookup key was assigned."),
+    /** Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`. */
+    name: z.string().optional().describe("Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`."),
+    /** Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`. */
+    readme_url: z.string().optional().describe("Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`."),
+    /** Stable virtual path assigned to the template config. `null` when no virtual path was set. */
+    virtual_path: z.string().optional().describe("Stable virtual path assigned to the template config. `null` when no virtual path was set."),
+}).describe("Identity and display metadata for a single template bundled by a Solution, used to represent each wrapped or sibling template at template granularity.");
+/** Runtime validator for {@link SolutionSummary}. */
+export const solutionSummarySchema = z.object({
+    /** Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none. */
+    category_keys: z.array(z.string()).optional().describe("Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none."),
+    /** When the Solution config was first imported (ISO 8601). */
+    created_at: z.string().optional().describe("When the Solution config was first imported (ISO 8601)."),
+    /** Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one. */
+    description: z.string().optional().describe("Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one."),
+    /** Solution config ID (`cfg_...`). */
+    id: z.string().describe("Solution config ID (`cfg_...`)."),
+    /** Resource type. Always `"Solution"`. */
+    kind: z.string().describe("Resource type. Always `\"Solution\"`."),
+    /** When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise. */
+    latest_solution: z.string().optional().describe("When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise."),
+    /** When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise. */
+    latest_version: z.string().optional().describe("When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise."),
+    /** The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set. */
+    lookup_key: z.string().optional().describe("The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set."),
+    /** Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none."),
+    /** Human-facing display name declared in the Solution body. `null` when the Solution body does not set one. */
+    name: z.string().optional().describe("Human-facing display name declared in the Solution body. `null` when the Solution body does not set one."),
+    /** Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions. */
+    org: z.string().optional().describe("Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions."),
+    /** Canonical image-source object for the resolved `org`'s logo, used as the principal category section glyph. Carries the signed `url` plus a `refresh_url`. `null` when `org_slug` is `null` or the org has no logo. */
+    org_logo: imageSourceSchema.optional().describe("Canonical image-source object for the resolved `org`'s logo, used as the principal category section glyph. Carries the signed `url` plus a `refresh_url`. `null` when `org_slug` is `null` or the org has no logo."),
+    /** Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`. */
+    org_name: z.string().optional().describe("Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`."),
+    /** Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key — clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve. */
+    org_slug: z.string().optional().describe("Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key — clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve."),
+    /** Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer's org scope). */
+    owners: z.array(z.string()).describe("Owner scopes this Solution appears under. Members: `\"system\"` (app-level system scope) and/or `\"org\"` (viewer's org scope)."),
+    /** Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`. */
+    readme_url: z.string().optional().describe("Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`."),
+    /** Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it. */
+    solution_id: z.string().optional().describe("Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it."),
+    /** Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version. */
+    solution_version: z.string().optional().describe("Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version."),
+    /** Freeform tag keys declared in the Solution body. An empty array when the body declares none. */
+    tag_keys: z.array(z.string()).optional().describe("Freeform tag keys declared in the Solution body. An empty array when the body declares none."),
+    /** Wrapped template kind — `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles. */
+    template_kind: z.string().optional().describe("Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles."),
+    /** Template configs bundled by this Solution, in declaration order — the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references. */
+    templates: z.array(solutionTemplateSummarySchema).describe("Template configs bundled by this Solution, in declaration order — the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references."),
+    /** When the Solution config was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When the Solution config was last modified (ISO 8601)."),
+    /** `true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows. */
+    upgrade_available: z.boolean().describe("`true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows."),
+    /** The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset. */
+    virtual_path: z.string().optional().describe("The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset."),
+}).describe("A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information.");
+/** Runtime validator for {@link AgentSourceSolution}. */
+export const agentSourceSolutionSchema = z.object({
+    /** Summary of the parent Solution, including `upgrade_available`, `latest_version`, and `latest_solution` when a newer system-scoped version is available for the agent's org-scoped Solution. */
+    solution: solutionSummarySchema.describe("Summary of the parent Solution, including `upgrade_available`, `latest_version`, and `latest_solution` when a newer system-scoped version is available for the agent's org-scoped Solution."),
+    /** Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from. */
+    template: upgradeTemplateSummarySchema.describe("Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from."),
+}).describe("Summary of the Solution and AgentTemplate that an agent was last provisioned from. Returned on single-agent responses; `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted.");
+/** Runtime validator for {@link Agent}. */
+export const agentSchema = z.object({
+    /** Access control list for the agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the agent is accessible to all members of its scope. */
+    acl: aclSchema.optional().describe("Access control list for the agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the agent is accessible to all members of its scope."),
+    /** ID of the application that owns this agent (`dap_...`). */
+    app: z.string().optional().describe("ID of the application that owns this agent (`dap_...`)."),
+    /** When the agent was created (ISO 8601). */
+    created_at: z.string().optional().describe("When the agent was created (ISO 8601)."),
+    /** Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`). */
+    default_model: z.string().optional().describe("Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`)."),
+    /** Email address provisioned for this agent. `null` if email delivery is not configured. */
+    email: z.string().optional().describe("Email address provisioned for this agent. `null` if email delivery is not configured."),
+    /** Agent ID (`agi_...`). */
+    id: z.string().describe("Agent ID (`agi_...`)."),
+    /** System-level identity prompt that shapes the agent's persona and behavior. */
+    identity: z.string().optional().describe("System-level identity prompt that shapes the agent's persona and behavior."),
+    /** ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents. */
+    last_applied_template_config: z.string().optional().describe("ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents."),
+    /** Stable, user-defined identifier for this agent within the application. Unique per app. */
+    lookup_key: z.string().optional().describe("Stable, user-defined identifier for this agent within the application. Unique per app."),
+    /** Arbitrary key-value metadata attached to the agent. Not interpreted by the platform. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata attached to the agent. Not interpreted by the platform."),
+    /** Human-readable display name for the agent. `null` if not set. */
+    name: z.string().optional().describe("Human-readable display name for the agent. `null` if not set."),
+    /** ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped. */
+    org: z.string().optional().describe("ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped."),
+    /** Display name of the organization this agent belongs to. `null` when the agent is not org-scoped or when the org association was not preloaded. */
+    org_name: z.string().optional().describe("Display name of the organization this agent belongs to. `null` when the agent is not org-scoped or when the org association was not preloaded."),
+    /** Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name). */
+    originator: z.string().optional().describe("Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name)."),
+    /** Phone number provisioned for this agent. `null` if SMS is not configured. */
+    phone_number: z.string().optional().describe("Phone number provisioned for this agent. `null` if SMS is not configured."),
+    /** ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments. */
+    sandbox: z.string().optional().describe("ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments."),
+    /** Source Solution and AgentTemplate summary for agents provisioned from a Solution. Includes `upgrade_available`, `latest_version`, and `latest_solution` so you can render an upgrade badge without a separate dry-run call. `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. Populated only on single-agent GET responses, never on list endpoints. */
+    source_solution: agentSourceSolutionSchema.optional().describe("Source Solution and AgentTemplate summary for agents provisioned from a Solution. Includes `upgrade_available`, `latest_version`, and `latest_solution` so you can render an upgrade badge without a separate dry-run call. `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. Populated only on single-agent GET responses, never on list endpoints."),
+    /** ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped. */
+    team: z.string().optional().describe("ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped."),
+    /** When the agent was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When the agent was last modified (ISO 8601)."),
+    /** ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped. */
+    user: z.string().optional().describe("ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped."),
+}).describe("An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or tasks.");
+/** Runtime validator for {@link AgentComputer}. */
+export const agentComputerSchema = z.object({
+    /** ID of the agent that owns this computer (`agi_...`). `null` if the computer is not yet assigned to an agent. */
+    agent: z.string().optional().describe("ID of the agent that owns this computer (`agi_...`). `null` if the computer is not yet assigned to an agent."),
+    /** ID of the app this computer belongs to (`dap_...`). */
+    app: z.string().optional().describe("ID of the app this computer belongs to (`dap_...`)."),
+    /** Provider-specific configuration key-value pairs for the computer. Structure depends on the underlying compute provider. */
+    config: z.record(z.unknown()).optional().describe("Provider-specific configuration key-value pairs for the computer. Structure depends on the underlying compute provider."),
+    /** When the computer was created (ISO 8601). */
+    created_at: z.string().optional().describe("When the computer was created (ISO 8601)."),
+    /** Human-readable error description when `status` is `"error"`. `null` otherwise. */
+    error_message: z.string().optional().describe("Human-readable error description when `status` is `\"error\"`. `null` otherwise."),
+    /** Computer ID (`cmp_...`). */
+    id: z.string().describe("Computer ID (`cmp_...`)."),
+    /** When the computer last reported activity or received a command. `null` if the computer has never been active. */
+    last_active_at: z.string().optional().describe("When the computer last reported activity or received a command. `null` if the computer has never been active."),
+    /** Unique, stable identifier you assign to this computer within its app. `null` if not set. */
+    lookup_key: z.string().optional().describe("Unique, stable identifier you assign to this computer within its app. `null` if not set."),
+    /** Arbitrary key-value metadata you attached to the computer. `null` if none was provided. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata you attached to the computer. `null` if none was provided."),
+    /** Human-readable display name for the computer. `null` if not set. */
+    name: z.string().optional().describe("Human-readable display name for the computer. `null` if not set."),
+    /** Cloud region where the computer is hosted, e.g. `"us-east-1"`. `null` if not yet assigned. */
+    region: z.string().optional().describe("Cloud region where the computer is hosted, e.g. `\"us-east-1\"`. `null` if not yet assigned."),
+    /** URL of the live screenshot sprite used to render a real-time preview of the computer's screen. `null` when no sprite is available. */
+    sprite_url: z.string().optional().describe("URL of the live screenshot sprite used to render a real-time preview of the computer's screen. `null` when no sprite is available."),
+    /** Current lifecycle state of the computer. Common values include `"provisioning"`, `"ready"`, `"error"`, and `"terminated"`. */
+    status: z.string().optional().describe("Current lifecycle state of the computer. Common values include `\"provisioning\"`, `\"ready\"`, `\"error\"`, and `\"terminated\"`."),
+    /** When the computer record was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When the computer record was last modified (ISO 8601)."),
+}).describe("A cloud computer resource provisioned for an agent to use for browser and desktop automation tasks.");
+/** Runtime validator for {@link AgentComputerListResponse}. */
+export const agentComputerListResponseSchema = z.object({
+    /** Array of agent computer objects matching the query. */
+    data: z.array(agentComputerSchema).describe("Array of agent computer objects matching the query."),
+}).describe("A list of agent computers returned by a list query.");
+/** Runtime validator for {@link AgentCreateResponse}. */
+export const agentCreateResponseSchema = z.object({
+    /** Access control list governing who can interact with this agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied. */
+    acl: aclSchema.optional().describe("Access control list governing who can interact with this agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied."),
+    /** ID of the app this agent belongs to (`dap_...`). */
+    app: z.string().optional().describe("ID of the app this agent belongs to (`dap_...`)."),
+    /** When the agent was created (ISO 8601). */
+    created_at: z.string().optional().describe("When the agent was created (ISO 8601)."),
+    /** Default AI model the agent uses when no model is specified at runtime, e.g. `"claude-3-5-sonnet-20241022"`. `null` if not configured. */
+    default_model: z.string().optional().describe("Default AI model the agent uses when no model is specified at runtime, e.g. `\"claude-3-5-sonnet-20241022\"`. `null` if not configured."),
+    /** Email address assigned to this agent for inbound email handling. `null` if not configured. */
+    email: z.string().optional().describe("Email address assigned to this agent for inbound email handling. `null` if not configured."),
+    /** Agent ID (`agi_...`). */
+    id: z.string().describe("Agent ID (`agi_...`)."),
+    /** System prompt or persona description that shapes the agent's behavior. `null` if not set. */
+    identity: z.string().optional().describe("System prompt or persona description that shapes the agent's behavior. `null` if not set."),
+    /** List of config records created as part of this request's `template_bundle` install. One entry per persisted config, sorted by `key`. Omitted entirely when the request did not include a `template_bundle`. */
+    installed_configs: z.array(installedConfigEntrySchema).optional().describe("List of config records created as part of this request's `template_bundle` install. One entry per persisted config, sorted by `key`. Omitted entirely when the request did not include a `template_bundle`."),
+    /** Unique, stable identifier for the agent within its app. `null` if not set. */
+    lookup_key: z.string().optional().describe("Unique, stable identifier for the agent within its app. `null` if not set."),
+    /** Arbitrary key-value metadata attached to the agent. `null` if none was provided. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata attached to the agent. `null` if none was provided."),
+    /** Human-readable display name for the agent. `null` if not set. */
+    name: z.string().optional().describe("Human-readable display name for the agent. `null` if not set."),
+    /** ID of the organization this agent belongs to (`org_...`). `null` for agents outside an org. */
+    org: z.string().optional().describe("ID of the organization this agent belongs to (`org_...`). `null` for agents outside an org."),
+    /** Free-form label identifying the source or author of the agent, e.g. a username or service name. `null` if not set. */
+    originator: z.string().optional().describe("Free-form label identifying the source or author of the agent, e.g. a username or service name. `null` if not set."),
+    /** Phone number assigned to this agent for inbound SMS or voice handling. `null` if not configured. */
+    phone_number: z.string().optional().describe("Phone number assigned to this agent for inbound SMS or voice handling. `null` if not configured."),
+    /** ID of the sandbox environment this agent is scoped to (`sbx_...`). `null` for agents not scoped to a sandbox. */
+    sandbox: z.string().optional().describe("ID of the sandbox environment this agent is scoped to (`sbx_...`). `null` for agents not scoped to a sandbox."),
+    /** ID of the team that owns this agent (`tea_...`). `null` if owned by a user rather than a team. */
+    team: z.string().optional().describe("ID of the team that owns this agent (`tea_...`). `null` if owned by a user rather than a team."),
+    /** When the agent record was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When the agent record was last modified (ISO 8601)."),
+    /** ID of the user that owns this agent (`usr_...`). `null` if owned by a team. */
+    user: z.string().optional().describe("ID of the user that owns this agent (`usr_...`). `null` if owned by a team."),
+}).describe("The response returned by `POST /api/v1/agents`. Contains all agent fields plus an optional `installed_configs` array when a `template_bundle` was supplied in the request.");
+/** Runtime validator for {@link AgentEnvVarMasked}. */
+export const agentEnvVarMaskedSchema = z.object({
+    /** ID of the agent this environment variable belongs to (`agt_...`). */
+    agent: z.string().describe("ID of the agent this environment variable belongs to (`agt_...`)."),
+    /** When the environment variable was created (ISO 8601). */
+    created_at: z.string().optional().describe("When the environment variable was created (ISO 8601)."),
+    /** Optional human-readable note describing the purpose of this variable. `null` if not set. */
+    description: z.string().optional().describe("Optional human-readable note describing the purpose of this variable. `null` if not set."),
+    /** Environment variable ID (`anv_...`). */
+    id: z.string().describe("Environment variable ID (`anv_...`)."),
+    /** Name of the environment variable as it appears in the agent's runtime. */
+    key: z.string().describe("Name of the environment variable as it appears in the agent's runtime."),
+    /** Redacted representation of the secret value. The last four characters are preserved; all preceding characters are replaced with `****`. Returns `****` when the value is absent or four characters or fewer. */
+    masked_value: z.string().describe("Redacted representation of the secret value. The last four characters are preserved; all preceding characters are replaced with `****`. Returns `****` when the value is absent or four characters or fewer."),
+    /** When the environment variable was last updated (ISO 8601). */
+    updated_at: z.string().optional().describe("When the environment variable was last updated (ISO 8601)."),
+}).describe("An agent environment variable with its secret value masked for safe display in list and show responses.");
+/** Runtime validator for {@link AgentEnvVarMaskedList}. */
+export const agentEnvVarMaskedListSchema = z.object({
+    /** Array of masked environment variable objects for the agent. */
+    data: z.array(agentEnvVarMaskedSchema).describe("Array of masked environment variable objects for the agent."),
+}).describe("Flat list of masked environment variables belonging to an agent.");
+/** Runtime validator for {@link AgentExport}. */
+export const agentExportSchema = z.object({
+    /** Ordered list of config file objects that the agent depends on. Included in full so the import can recreate all dependencies without additional requests. */
+    configs: z.array(configSchema).describe("Ordered list of config file objects that the agent depends on. Included in full so the import can recreate all dependencies without additional requests."),
+    /** The agent template definition as a structured map. Pass this directly to the import endpoint to recreate the agent. */
+    template: z.record(z.unknown()).describe("The agent template definition as a structured map. Pass this directly to the import endpoint to recreate the agent."),
+}).describe("A portable export bundle for an agent, containing everything needed to re-deploy it in another workspace or environment.");
+/** Runtime validator for {@link AgentHealth}. */
+export const agentHealthSchema = z.object({
+    /** Timestamps for the agent's most recent and next scheduled activity, used to surface last-run and upcoming-run information. */
+    activity: z.record(z.unknown()).describe("Timestamps for the agent's most recent and next scheduled activity, used to surface last-run and upcoming-run information."),
+    /** The agent this health profile describes. */
+    agent: agentSchema.describe("The agent this health profile describes."),
+    /** When the health profile was last computed (ISO 8601). */
+    checked_at: z.string().describe("When the health profile was last computed (ISO 8601)."),
+    /** Renderable health check results. Each object includes at minimum `key`, `label`, `status`, and `summary` fields. */
+    checks: z.array(z.record(z.unknown())).describe("Renderable health check results. Each object includes at minimum `key`, `label`, `status`, and `summary` fields."),
+    /** Action counts broken down by dependency area and resolution status, used to render progress indicators per category. */
+    counts: z.record(z.unknown()).describe("Action counts broken down by dependency area and resolution status, used to render progress indicators per category."),
+    /** All actionable items tracked for this agent, including both `"setup"` items (post-install checklist) and `"health"` items (probe-detected issues). Sorted by `(source, sort_order, id)`. Use each item's `params` field to construct deep-links that route the user to the correct resolution flow. */
+    health_actions: z.array(agentHealthActionSchema).describe("All actionable items tracked for this agent, including both `\"setup\"` items (post-install checklist) and `\"health\"` items (probe-detected issues). Sorted by `(source, sort_order, id)`. Use each item's `params` field to construct deep-links that route the user to the correct resolution flow."),
+    /** Recent execution metrics for the agent, including run counts and failure counts over a recent time window. */
+    recent: z.record(z.unknown()).describe("Recent execution metrics for the agent, including run counts and failure counts over a recent time window."),
+    /** Normalized health score from `0` (fully degraded) to `100` (fully healthy), derived from the weight and status of all health actions. */
+    score: z.number().int().describe("Normalized health score from `0` (fully degraded) to `100` (fully healthy), derived from the weight and status of all health actions."),
+    /** Overall health status of the agent. One of `"ok"`, `"warning"`, or `"critical"`. */
+    status: z.string().describe("Overall health status of the agent. One of `\"ok\"`, `\"warning\"`, or `\"critical\"`."),
+}).describe("Aggregate health profile for an agent, summarizing its current operational status, score, and the full list of setup and health actions.");
+/** Runtime validator for {@link AgentListResponse}. */
+export const agentListResponseSchema = z.object({
+    /** Array of agent objects for the current page. */
+    data: z.array(agentSchema).describe("Array of agent objects for the current page."),
+    /** `true` when a subsequent page of results exists. */
+    has_next: z.boolean().optional().describe("`true` when a subsequent page of results exists."),
+    /** `true` when a previous page of results exists. */
+    has_prev: z.boolean().optional().describe("`true` when a previous page of results exists."),
+    /** Current page number, starting at 1. */
+    page: z.number().int().optional().describe("Current page number, starting at 1."),
+    /** Maximum number of agents returned per page. */
+    page_size: z.number().int().optional().describe("Maximum number of agents returned per page."),
+    /** Total number of agents matching the query across all pages. */
+    total_entries: z.number().int().optional().describe("Total number of agents matching the query across all pages."),
+    /** Total number of pages available given the current `page_size`. */
+    total_pages: z.number().int().optional().describe("Total number of pages available given the current `page_size`."),
+}).describe("Paginated list of agent objects. Use the pagination fields to traverse multiple pages of results.");
+/** Runtime validator for {@link AgentRoutine}. */
+export const agentRoutineSchema = z.object({
+    /** Access control list for the routine. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the routine is accessible to all members of its scope. */
+    acl: aclSchema.optional().describe("Access control list for the routine. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the routine is accessible to all members of its scope."),
+    /** ID of the agent that owns this routine (`agi_...`). */
+    agent: z.string().optional().describe("ID of the agent that owns this routine (`agi_...`)."),
+    /** Application that scopes this routine (`dap_...`). */
+    app: z.string().optional().describe("Application that scopes this routine (`dap_...`)."),
+    /** ID of the Config record that backs this routine's configuration (`cfg_...`). `null` when the routine is not config-backed. */
+    config: z.string().optional().describe("ID of the Config record that backs this routine's configuration (`cfg_...`). `null` when the routine is not config-backed."),
+    /** When this routine was created (ISO 8601). */
+    created_at: z.string().optional().describe("When this routine was created (ISO 8601)."),
+    /** Optional description of what this routine does. `null` when not set. */
+    description: z.string().optional().describe("Optional description of what this routine does. `null` when not set."),
+    /** Additional configuration controlling how the event trigger is matched or filtered. Shape depends on `event_type`. `null` when not configured. */
+    event_config: z.record(z.unknown()).optional().describe("Additional configuration controlling how the event trigger is matched or filtered. Shape depends on `event_type`. `null` when not configured."),
+    /** Platform event type that triggers this routine, e.g. `"agentroutine.invoked"`. `null` for schedule-only routines. */
+    event_type: z.string().optional().describe("Platform event type that triggers this routine, e.g. `\"agentroutine.invoked\"`. `null` for schedule-only routines."),
+    /** Execution strategy for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. */
+    handler_type: z.string().optional().describe("Execution strategy for this routine. One of `\"workflow_graph\"`, `\"script\"`, `\"preset\"`, or `\"chain\"`."),
+    /** Routine ID (`arn_...`). */
+    id: z.string().describe("Routine ID (`arn_...`)."),
+    /** ID of the AgentRoutineTemplate Config this routine was last provisioned or updated from (`cfg_...`). `null` for hand-built routines. */
+    last_applied_template_config: z.string().optional().describe("ID of the AgentRoutineTemplate Config this routine was last provisioned or updated from (`cfg_...`). `null` for hand-built routines."),
+    /** Unique human-readable key used to look up this routine without knowing its ID. `null` when not set. */
+    lookup_key: z.string().optional().describe("Unique human-readable key used to look up this routine without knowing its ID. `null` when not set."),
+    /** Arbitrary key-value metadata attached to this routine. `null` when not set. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata attached to this routine. `null` when not set."),
+    /** Human-readable name for the routine. */
+    name: z.string().optional().describe("Human-readable name for the routine."),
+    /** Resolved preset configuration when `handler_type` is `"preset"`. `null` for other handler types. */
+    preset_config: presetConfigSchema.optional().describe("Resolved preset configuration when `handler_type` is `\"preset\"`. `null` for other handler types."),
+    /** Name of the preset invoked when `handler_type` is `"preset"`. `null` for other handler types. */
+    preset_name: z.string().optional().describe("Name of the preset invoked when `handler_type` is `\"preset\"`. `null` for other handler types."),
+    /** Cron expression controlling when the routine fires on a schedule. `null` for event-only routines. */
+    schedule: z.string().optional().describe("Cron expression controlling when the routine fires on a schedule. `null` for event-only routines."),
+    /** Inline script body executed when `handler_type` is `"script"`. `null` for other handler types. */
+    script: z.string().optional().describe("Inline script body executed when `handler_type` is `\"script\"`. `null` for other handler types."),
+    /** Lifecycle status of the routine. One of `"draft"`, `"active"`, or `"paused"`. Only `"active"` routines respond to triggers. */
+    status: z.string().optional().describe("Lifecycle status of the routine. One of `\"draft\"`, `\"active\"`, or `\"paused\"`. Only `\"active\"` routines respond to triggers."),
+    /** Ordered list of chain steps (present when handler_type is "chain"). Each step is a plain map with handler_type, optional body fields (preset_name / preset_config / script / config), and step-local plumbing (name, inputs, output_key, on_error). */
+    steps: z.array(z.record(z.unknown())).optional().describe("Ordered list of chain steps (present when handler_type is \"chain\"). Each step is a plain map with handler_type, optional body fields (preset_name / preset_config / script / config), and step-local plumbing (name, inputs, output_key, on_error)."),
+    /** Execution context in which runs are created. One of `"event"` (background job) or `"chat_session"` (interactive session). Defaults to `"event"`. */
+    trigger_context: z.string().optional().describe("Execution context in which runs are created. One of `\"event\"` (background job) or `\"chat_session\"` (interactive session). Defaults to `\"event\"`."),
+    /** When this routine was last updated (ISO 8601). */
+    updated_at: z.string().optional().describe("When this routine was last updated (ISO 8601)."),
+}).describe("An agent routine defines a reusable handler — script, preset, or chain — that runs in response to events or on a schedule.");
+/** Runtime validator for {@link AgentRoutineListResponse}. */
+export const agentRoutineListResponseSchema = z.object({
+    /** Array of agent routine objects. */
+    data: z.array(agentRoutineSchema).describe("Array of agent routine objects."),
+}).describe("List of agent routine objects belonging to a given agent.");
+/** Runtime validator for {@link AgentRoutineRun}. */
+export const agentRoutineRunSchema = z.object({
+    /** Access control list for the run. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the run is accessible to all members of its scope. */
+    acl: aclSchema.optional().describe("Access control list for the run. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the run is accessible to all members of its scope."),
+    /** ID of the agent that owns the parent routine (`agi_...`). */
+    agent: z.string().optional().describe("ID of the agent that owns the parent routine (`agi_...`)."),
+    /** Application that scopes this run (`dap_...`). */
+    app: z.string().optional().describe("Application that scopes this run (`dap_...`)."),
+    /** When this run was created (ISO 8601). */
+    created_at: z.string().optional().describe("When this run was created (ISO 8601)."),
+    /** Total wall-clock time the run took to execute, in milliseconds. `null` while the run is still in progress. */
+    duration_ms: z.number().int().optional().describe("Total wall-clock time the run took to execute, in milliseconds. `null` while the run is still in progress."),
+    /** Identifier of the platform event that triggered this run. `null` for manually invoked runs. */
+    event_id: z.string().optional().describe("Identifier of the platform event that triggered this run. `null` for manually invoked runs."),
+    /** Routine run ID (`arr_...`). */
+    id: z.string().describe("Routine run ID (`arr_...`)."),
+    /** Arbitrary key-value metadata attached to this run. Empty object when no metadata was set. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata attached to this run. Empty object when no metadata was set."),
+    /** Input payload delivered to the routine when this run was triggered. Empty object when no payload was provided. */
+    payload: z.record(z.unknown()).optional().describe("Input payload delivered to the routine when this run was triggered. Empty object when no payload was provided."),
+    /** Output produced by the routine after execution. `null` while the run has not yet completed. */
+    result: z.record(z.unknown()).optional().describe("Output produced by the routine after execution. `null` while the run has not yet completed."),
+    /** ID of the parent routine that produced this run (`arn_...`). */
+    routine: z.string().optional().describe("ID of the parent routine that produced this run (`arn_...`)."),
+    /** Current execution status. One of `"pending"`, `"running"`, `"completed"`, `"failed"`, `"skipped"`, or `"cancelled"`. */
+    status: z.string().optional().describe("Current execution status. One of `\"pending\"`, `\"running\"`, `\"completed\"`, `\"failed\"`, `\"skipped\"`, or `\"cancelled\"`."),
+    /** Validated structured output extracted from `result` when the routine uses an AgentMessageSchema. `null` if the routine does not use a schema or the run has not completed. */
+    structured_response: z.record(z.unknown()).optional().describe("Validated structured output extracted from `result` when the routine uses an AgentMessageSchema. `null` if the routine does not use a schema or the run has not completed."),
+    /** When this run was last updated (ISO 8601). */
+    updated_at: z.string().optional().describe("When this run was last updated (ISO 8601)."),
+    /** Background worker status. `null` when no worker job is associated with this run. */
+    worker: workerStatusSchema.optional().describe("Background worker status. `null` when no worker job is associated with this run."),
+}).describe("A single execution of an agent routine, capturing its status, inputs, outputs, and timing.");
+/** Runtime validator for {@link AgentRoutineRunListResponse}. */
+export const agentRoutineRunListResponseSchema = z.object({
+    /** Opaque cursor to pass as the after-cursor parameter to fetch the next page of runs. `null` when no later results exist. */
+    after_cursor: z.string().optional().describe("Opaque cursor to pass as the after-cursor parameter to fetch the next page of runs. `null` when no later results exist."),
+    /** Opaque cursor to pass as the before-cursor parameter to fetch the page of runs that precede this one. `null` when no earlier results exist. */
+    before_cursor: z.string().optional().describe("Opaque cursor to pass as the before-cursor parameter to fetch the page of runs that precede this one. `null` when no earlier results exist."),
+    /** Array of agent routine run objects for the current page. */
+    data: z.array(agentRoutineRunSchema).describe("Array of agent routine run objects for the current page."),
+}).describe("Cursor-paginated list of agent routine run objects, ordered by creation time descending.");
+/** Runtime validator for {@link AgentSchedule}. */
+export const agentScheduleSchema = z.object({
+    /** ID of the agent that owns this schedule (`agi_...`). */
+    agent: z.string().optional().describe("ID of the agent that owns this schedule (`agi_...`)."),
+    /** ID of the application the schedule belongs to (`dap_...`). */
+    app: z.string().optional().describe("ID of the application the schedule belongs to (`dap_...`)."),
+    /** When the schedule was created (ISO 8601). */
+    created_at: z.string().optional().describe("When the schedule was created (ISO 8601)."),
+    /** Standard cron expression defining the recurrence pattern (e.g. `"0 9 * * 1"`). Present only when `schedule_type` is `"recurring"`. `null` for one-time schedules. */
+    cron_expression: z.string().optional().describe("Standard cron expression defining the recurrence pattern (e.g. `\"0 9 * * 1\"`). Present only when `schedule_type` is `\"recurring\"`. `null` for one-time schedules."),
+    /** Schedule ID (`asc_...`). */
+    id: z.string().describe("Schedule ID (`asc_...`)."),
+    /** The task description the agent will execute when this schedule fires. */
+    instructions: z.string().optional().describe("The task description the agent will execute when this schedule fires."),
+    /** UTC datetime of the most recent successful execution. `null` if the schedule has never run. */
+    last_run_at: z.string().optional().describe("UTC datetime of the most recent successful execution. `null` if the schedule has never run."),
+    /** Maximum number of times a recurring schedule may fire before automatically transitioning to `"completed"`. `null` means no limit. */
+    max_runs: z.number().int().optional().describe("Maximum number of times a recurring schedule may fire before automatically transitioning to `\"completed\"`. `null` means no limit."),
+    /** Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform."),
+    /** UTC datetime of the next planned execution. `null` if the schedule has completed, been cancelled, or has not yet been computed. */
+    next_run_at: z.string().optional().describe("UTC datetime of the next planned execution. `null` if the schedule has completed, been cancelled, or has not yet been computed."),
+    /** Total number of times this schedule has fired. */
+    run_count: z.number().int().optional().describe("Total number of times this schedule has fired."),
+    /** Determines how the schedule repeats. `"once"` fires a single time at `scheduled_at` then transitions to `"completed"`. `"recurring"` fires on the `cron_expression` and reschedules automatically. */
+    schedule_type: z.string().optional().describe("Determines how the schedule repeats. `\"once\"` fires a single time at `scheduled_at` then transitions to `\"completed\"`. `\"recurring\"` fires on the `cron_expression` and reschedules automatically."),
+    /** The exact UTC datetime at which a one-time schedule fires. Present only when `schedule_type` is `"once"`. `null` for recurring schedules. */
+    scheduled_at: z.string().optional().describe("The exact UTC datetime at which a one-time schedule fires. Present only when `schedule_type` is `\"once\"`. `null` for recurring schedules."),
+    /** Current lifecycle status of the schedule. One of `"active"` (will fire as planned), `"paused"` (temporarily suspended), `"completed"` (has run its last execution), `"cancelled"` (manually stopped), or `"expired"` (past its valid window). */
+    status: z.string().optional().describe("Current lifecycle status of the schedule. One of `\"active\"` (will fire as planned), `\"paused\"` (temporarily suspended), `\"completed\"` (has run its last execution), `\"cancelled\"` (manually stopped), or `\"expired\"` (past its valid window)."),
+    /** Thread ID (`thr_...`) this schedule is bound to. When set, the scheduled task is delivered into the thread rather than creating a new session. `null` for session-based schedules. */
+    thread: z.string().optional().describe("Thread ID (`thr_...`) this schedule is bound to. When set, the scheduled task is delivered into the thread rather than creating a new session. `null` for session-based schedules."),
+    /** IANA timezone name used to interpret the cron expression or `scheduled_at` (e.g. `"America/New_York"`). Defaults to `"Etc/UTC"`. */
+    timezone: z.string().optional().describe("IANA timezone name used to interpret the cron expression or `scheduled_at` (e.g. `\"America/New_York\"`). Defaults to `\"Etc/UTC\"`."),
+    /** When the schedule was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When the schedule was last modified (ISO 8601)."),
+}).describe("A scheduled task created by an agent. Supports one-time and recurring (cron-based) execution patterns.");
+/** Runtime validator for {@link AgentSession}. */
+export const agentSessionSchema = z.object({
+    /** ID of the agent that owns this session (`agi_...`). */
+    agent: z.string().optional().describe("ID of the agent that owns this session (`agi_...`)."),
+    /** When the session reached a terminal state (`"completed"`, `"failed"`, or `"cancelled"`). `null` if still in progress. */
+    completed_at: z.string().optional().describe("When the session reached a terminal state (`\"completed\"`, `\"failed\"`, or `\"cancelled\"`). `null` if still in progress."),
+    /** When the session was created (ISO 8601). */
+    created_at: z.string().optional().describe("When the session was created (ISO 8601)."),
+    /** Human-readable error message describing why the session failed. `null` unless `status` is `"failed"`. */
+    error: z.string().optional().describe("Human-readable error message describing why the session failed. `null` unless `status` is `\"failed\"`."),
+    /** Session ID (`ase_...`). */
+    id: z.string().describe("Session ID (`ase_...`)."),
+    /** Ordered list of messages delivered to the session's inbox while it was in the `"waiting"` state. Each entry includes `id`, `role`, `content`, `sender_id`, `sender_type`, `sent_at`, and `metadata`. */
+    inbox: z.array(z.record(z.unknown())).optional().describe("Ordered list of messages delivered to the session's inbox while it was in the `\"waiting\"` state. Each entry includes `id`, `role`, `content`, `sender_id`, `sender_type`, `sent_at`, and `metadata`."),
+    /** The task the agent is instructed to perform in this session. */
+    instructions: z.string().optional().describe("The task the agent is instructed to perform in this session."),
+    /** `true` if this session was created by the platform internally (e.g. by a schedule or health action) rather than by a user or API caller. */
+    is_system_session: z.boolean().optional().describe("`true` if this session was created by the platform internally (e.g. by a schedule or health action) rather than by a user or API caller."),
+    /** Maximum number of tool calls the agent may make within a single turn. Defaults to `25`. */
+    max_runs_per_turn: z.number().int().optional().describe("Maximum number of tool calls the agent may make within a single turn. Defaults to `25`."),
+    /** Maximum number of tokens the session may consume across all turns before being terminated. Defaults to `20000`. */
+    max_tokens: z.number().int().optional().describe("Maximum number of tokens the session may consume across all turns before being terminated. Defaults to `20000`."),
+    /** Maximum number of agent turns (LLM calls) allowed before the session is forcibly terminated. Defaults to `100`. */
+    max_turns: z.number().int().optional().describe("Maximum number of agent turns (LLM calls) allowed before the session is forcibly terminated. Defaults to `100`."),
+    /** Arbitrary key-value pairs attached to the session. Not interpreted by the platform. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value pairs attached to the session. Not interpreted by the platform."),
+    /** Optional human-readable label for the session. `null` when not set. */
+    name: z.string().optional().describe("Optional human-readable label for the session. `null` when not set."),
+    /** Structured output produced by the session on successful completion. Shape is agent-defined. `null` while the session is still running or if it failed. */
+    result: z.record(z.unknown()).optional().describe("Structured output produced by the session on successful completion. Shape is agent-defined. `null` while the session is still running or if it failed."),
+    /** When the session began executing. `null` if still `"pending"`. */
+    started_at: z.string().optional().describe("When the session began executing. `null` if still `\"pending\"`."),
+    /** Current execution status. One of `"pending"` (queued, not yet started), `"running"` (actively executing), `"waiting"` (paused for an inbox message or external event), `"completed"` (finished successfully), `"failed"` (terminated with an error), or `"cancelled"` (manually stopped). */
+    status: z.string().optional().describe("Current execution status. One of `\"pending\"` (queued, not yet started), `\"running\"` (actively executing), `\"waiting\"` (paused for an inbox message or external event), `\"completed\"` (finished successfully), `\"failed\"` (terminated with an error), or `\"cancelled\"` (manually stopped)."),
+    /** ID of the trajectory that records the full message history for this session (`trj_...`). `null` until the session has started. */
+    trajectory: z.string().optional().describe("ID of the trajectory that records the full message history for this session (`trj_...`). `null` until the session has started."),
+}).describe("A durable agent session record representing a single AI task execution. Tracks status, trajectory, result, and any inbox messages delivered to the session.");
+/** Runtime validator for {@link AgentSessionListResponse}. */
+export const agentSessionListResponseSchema = z.object({
+    /** Array of agent session objects for the current page. */
+    data: z.array(agentSessionSchema).describe("Array of agent session objects for the current page."),
+}).describe("Paginated list response containing an array of agent session objects.");
+/** Runtime validator for {@link AgentSkill}. */
+export const agentSkillSchema = z.object({
+    /** ID of the agent this skill is attached to (`agi_...`). */
+    agent: z.string().optional().describe("ID of the agent this skill is attached to (`agi_...`)."),
+    /** ID of the application this skill belongs to (`dap_...`). */
+    app: z.string().optional().describe("ID of the application this skill belongs to (`dap_...`)."),
+    /** ID of the root skill config record that defines this skill's behavior (`cfg_...`). */
+    config: z.string().optional().describe("ID of the root skill config record that defines this skill's behavior (`cfg_...`)."),
+    /** When the skill was added to the agent (ISO 8601). */
+    created_at: z.string().optional().describe("When the skill was added to the agent (ISO 8601)."),
+    /** Skill ID (`ask_...`). */
+    id: z.string().describe("Skill ID (`ask_...`)."),
+    /** Optional instruction text that overrides the default skill instructions for this specific agent. `null` when no override is set. */
+    instruction: z.string().optional().describe("Optional instruction text that overrides the default skill instructions for this specific agent. `null` when no override is set."),
+    /** ID of the agent template config from which this skill was last provisioned or updated (`cfg_...`). `null` if the skill was not provisioned from a template. */
+    last_applied_template_config: z.string().optional().describe("ID of the agent template config from which this skill was last provisioned or updated (`cfg_...`). `null` if the skill was not provisioned from a template."),
+    /** Arbitrary key-value pairs attached to the skill. Not interpreted by the platform. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value pairs attached to the skill. Not interpreted by the platform."),
+    /** Whether the skill is currently in use. `"active"` means the agent will use this skill during sessions. `"inactive"` means it is disabled but not deleted. */
+    status: z.string().optional().describe("Whether the skill is currently in use. `\"active\"` means the agent will use this skill during sessions. `\"inactive\"` means it is disabled but not deleted."),
+    /** When the skill was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When the skill was last modified (ISO 8601)."),
+}).describe("A skill enabled on an agent, linking the agent to a skill configuration. Controls which capabilities the agent has access to.");
+/** Runtime validator for {@link AgentSkillList}. */
+export const agentSkillListSchema = z.object({
+    /** Array of agent skill objects for the current page. */
+    data: z.array(agentSkillSchema).describe("Array of agent skill objects for the current page."),
+}).describe("Paginated list response containing an array of agent skill objects.");
+/** Runtime validator for {@link AgentTool}. */
+export const agentToolSchema = z.object({
+    /** ID of the agent this tool belongs to (`agi_...`). */
+    agent: z.string().optional().describe("ID of the agent this tool belongs to (`agi_...`)."),
+    /** ID of the application that owns this tool (`dap_...`). */
+    app: z.string().optional().describe("ID of the application that owns this tool (`dap_...`)."),
+    /** `true` when the tool executes asynchronously and returns a task handle rather than an immediate result. */
+    async: z.boolean().optional().describe("`true` when the tool executes asynchronously and returns a task handle rather than an immediate result."),
+    /** Provider-specific configuration for the built-in tool. Present only when `kind` is `"builtin"`. Shape varies by `builtin_tool_key`. */
+    builtin_tool_config: z.record(z.unknown()).optional().describe("Provider-specific configuration for the built-in tool. Present only when `kind` is `\"builtin\"`. Shape varies by `builtin_tool_key`."),
+    /** Registry key identifying the built-in tool implementation. Present only when `kind` is `"builtin"`. */
+    builtin_tool_key: z.string().optional().describe("Registry key identifying the built-in tool implementation. Present only when `kind` is `\"builtin\"`."),
+    /** ID of the config record (`cfg_...`) containing this tool's full configuration. `null` for inline-only tools. */
+    config: z.string().optional().describe("ID of the config record (`cfg_...`) containing this tool's full configuration. `null` for inline-only tools."),
+    /** When the tool was created (ISO 8601). */
+    created_at: z.string().optional().describe("When the tool was created (ISO 8601)."),
+    /** Description of what the tool does, passed to the LLM as part of the tool definition. Resolved from the built-in registry for `kind: "builtin"` tools. */
+    description: z.string().optional().describe("Description of what the tool does, passed to the LLM as part of the tool definition. Resolved from the built-in registry for `kind: \"builtin\"` tools."),
+    /** Execution handler type. One of `"http"`, `"script"`, or `"builtin"`. */
+    handler_type: z.string().optional().describe("Execution handler type. One of `\"http\"`, `\"script\"`, or `\"builtin\"`."),
+    /** Tool ID (`atl_...`). */
+    id: z.string().describe("Tool ID (`atl_...`)."),
+    /** Optional system-level instruction appended to the agent prompt when this tool is active. */
+    instruction: z.string().optional().describe("Optional system-level instruction appended to the agent prompt when this tool is active."),
+    /** Tool kind. One of `"builtin"`, `"custom"`, or `"mcp"`. */
+    kind: z.string().optional().describe("Tool kind. One of `\"builtin\"`, `\"custom\"`, or `\"mcp\"`."),
+    /** ID of the AgentToolTemplate config (`cfg_...`) this tool was last provisioned or updated from. `null` for manually created tools. */
+    last_applied_template_config: z.string().optional().describe("ID of the AgentToolTemplate config (`cfg_...`) this tool was last provisioned or updated from. `null` for manually created tools."),
+    /** Stable, user-defined identifier for this tool within the agent. Unique per agent. */
+    lookup_key: z.string().optional().describe("Stable, user-defined identifier for this tool within the agent. Unique per agent."),
+    /** Arbitrary key-value metadata attached to the tool. Not interpreted by the platform. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata attached to the tool. Not interpreted by the platform."),
+    /** Human-readable name of the tool as exposed to the LLM. Resolved from the built-in registry for `kind: "builtin"` tools. */
+    name: z.string().optional().describe("Human-readable name of the tool as exposed to the LLM. Resolved from the built-in registry for `kind: \"builtin\"` tools."),
+    /** Per-instance namespace prepended to LLM-facing tool names for built-in tools that support multiple instances per agent. `null` when not applicable. */
+    name_prefix: z.string().optional().describe("Per-instance namespace prepended to LLM-facing tool names for built-in tools that support multiple instances per agent. `null` when not applicable."),
+    /** JSON Schema object describing the tool's input parameters as presented to the LLM. */
+    parameters: z.record(z.unknown()).optional().describe("JSON Schema object describing the tool's input parameters as presented to the LLM."),
+    /** ID of the config record (`cfg_...`) storing the tool's parameter schema. `null` when parameters are defined inline. */
+    parameters_config: z.string().optional().describe("ID of the config record (`cfg_...`) storing the tool's parameter schema. `null` when parameters are defined inline."),
+    /** Current status of the tool. One of `"active"` or `"disabled"`. */
+    status: z.string().optional().describe("Current status of the tool. One of `\"active\"` or `\"disabled\"`."),
+    /** When the tool was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When the tool was last modified (ISO 8601)."),
+}).describe("A tool attached to an agent, defining a capability the agent can invoke during a conversation or task run.");
+/** Runtime validator for {@link AgentToolListResponse}. */
+export const agentToolListResponseSchema = z.object({
+    /** Array of agent tool objects returned for the current request. */
+    data: z.array(agentToolSchema).describe("Array of agent tool objects returned for the current request."),
+}).describe("Paginated list response containing the tools attached to an agent.");
+/** Runtime validator for {@link AgentUpgradeFieldChange}. */
+export const agentUpgradeFieldChangeSchema = z.object({
+    /** Value that was set by the last-applied template version (pinned baseline). Populated only on `agent_base` field changes. `null` when no baseline is available (legacy agent or deleted version). */
+    baseline: z.unknown().optional().describe("Value that was set by the last-applied template version (pinned baseline). Populated only on `agent_base` field changes. `null` when no baseline is available (legacy agent or deleted version)."),
+    /** Name of the field that will change, e.g. `"name"` or `"identity"`. */
+    field: z.string().describe("Name of the field that will change, e.g. `\"name\"` or `\"identity\"`."),
+    /** `true` when the agent's current value differs from `baseline`, indicating a local edit that this upgrade will overwrite. `false` when the current value matches the baseline. `null` when `baseline` is unavailable. Populated only on `agent_base` field changes. */
+    locally_edited: z.boolean().optional().describe("`true` when the agent's current value differs from `baseline`, indicating a local edit that this upgrade will overwrite. `false` when the current value matches the baseline. `null` when `baseline` is unavailable. Populated only on `agent_base` field changes."),
+    /** Incoming value the field will be set to after the upgrade (string, number, boolean, or `null`). */
+    new: z.unknown().optional().describe("Incoming value the field will be set to after the upgrade (string, number, boolean, or `null`)."),
+    /** Current value of the field before the upgrade (string, number, boolean, or `null`). */
+    old: z.unknown().optional().describe("Current value of the field before the upgrade (string, number, boolean, or `null`)."),
+}).describe("One field-level diff entry within an agent upgrade change, describing how a single field will change. `baseline` and `locally_edited` are populated only for `agent_base` entries; child resource entries (tools, routines, skills, computers) carry only `field`, `old`, and `new`.");
+/** Runtime validator for {@link AgentUpgradeChange}. */
+export const agentUpgradeChangeSchema = z.object({
+    /** The operation that will be performed. One of `"add"`, `"update"`, `"remove"`, or `"noop"`. */
+    action: z.string().describe("The operation that will be performed. One of `\"add\"`, `\"update\"`, `\"remove\"`, or `\"noop\"`."),
+    /** Description of the child resource this change touches, when one is set. `null` when no description is available. */
+    description: z.string().optional().describe("Description of the child resource this change touches, when one is set. `null` when no description is available."),
+    /** Field-level diff entries for this change. Populated only when `action` is `"update"`; empty or absent for `add`, `remove`, and `noop` entries. */
+    field_changes: z.array(agentUpgradeFieldChangeSchema).optional().describe("Field-level diff entries for this change. Populated only when `action` is `\"update\"`; empty or absent for `add`, `remove`, and `noop` entries."),
+    /** Public ID of the existing resource being updated or removed (e.g. `atl_...`, `arn_...`). `null` for `add` entries. */
+    id: z.string().optional().describe("Public ID of the existing resource being updated or removed (e.g. `atl_...`, `arn_...`). `null` for `add` entries."),
+    /** Lookup key of the resource derived from its source template. `null` when the template has no lookup key. */
+    key: z.string().optional().describe("Lookup key of the resource derived from its source template. `null` when the template has no lookup key."),
+    /** Human-facing name of the child resource this change touches (tool/routine/skill/computer name, or builtin tool key for unnamed builtin tools). Falls back to the source template's name. `null` for the synthetic `agent_base` entry. */
+    name: z.string().optional().describe("Human-facing name of the child resource this change touches (tool/routine/skill/computer name, or builtin tool key for unnamed builtin tools). Falls back to the source template's name. `null` for the synthetic `agent_base` entry."),
+    /** Summary of the parent AgentTemplate config (`cfg_...`) being applied in this upgrade. */
+    parent_template_config: upgradeTemplateSummarySchema.describe("Summary of the parent AgentTemplate config (`cfg_...`) being applied in this upgrade."),
+    /** Resource-type-specific identity details. Tools: `tool_type`, `builtin_tool_key`, `name_prefix`, `handler_type`, `instruction`. Routines: `handler_type`, `preset_name`, `event_type`, `schedule`, `trigger_context`. Skills: `instruction`. Computers: `region`. Only populated keys are present; `null` when nothing is known. */
+    resource: z.record(z.unknown()).optional().describe("Resource-type-specific identity details. Tools: `tool_type`, `builtin_tool_key`, `name_prefix`, `handler_type`, `instruction`. Routines: `handler_type`, `preset_name`, `event_type`, `schedule`, `trigger_context`. Skills: `instruction`. Computers: `region`. Only populated keys are present; `null` when nothing is known."),
+    /** Type of the child resource being changed. One of `"agent"`, `"tool"`, `"routine"`, `"skill"`, or `"computer"`. */
+    resource_type: z.string().describe("Type of the child resource being changed. One of `\"agent\"`, `\"tool\"`, `\"routine\"`, `\"skill\"`, or `\"computer\"`."),
+    /** Summary of the specific child template config (`cfg_...`) that defines this resource. `null` when no source template is resolvable. */
+    source_template_config: upgradeTemplateSummarySchema.optional().describe("Summary of the specific child template config (`cfg_...`) that defines this resource. `null` when no source template is resolvable."),
+}).describe("One child-resource change produced by an agent upgrade, describing the action to be taken on a single resource.");
+/** Runtime validator for {@link AgentUpgradeSummary}. */
+export const agentUpgradeSummarySchema = z.object({
+    /** Number of child resources that will be created by this upgrade. */
+    adds: z.number().int().describe("Number of child resources that will be created by this upgrade."),
+    /** Number of child resources with no changes in this upgrade. */
+    noops: z.number().int().describe("Number of child resources with no changes in this upgrade."),
+    /** Number of child resources that will be removed by this upgrade. */
+    removes: z.number().int().describe("Number of child resources that will be removed by this upgrade."),
+    /** Number of child resources that will be updated by this upgrade. */
+    updates: z.number().int().describe("Number of child resources that will be updated by this upgrade."),
+}).describe("Aggregate counts of each change type produced by an agent upgrade diff.");
+/** Runtime validator for {@link AgentUpgradeResult}. */
+export const agentUpgradeResultSchema = z.object({
+    /** Ordered list of per-resource changes that will be (or were) applied by this upgrade. */
+    changes: z.array(agentUpgradeChangeSchema).describe("Ordered list of per-resource changes that will be (or were) applied by this upgrade."),
+    /** `true` when the request was a dry run and no changes were persisted to the agent. */
+    dry_run: z.boolean().describe("`true` when the request was a dry run and no changes were persisted to the agent."),
+    /** Upgrade mode that was used. One of `"full"` (apply all changes) or `"review"` (require fingerprint confirmation). */
+    mode: z.string().describe("Upgrade mode that was used. One of `\"full\"` (apply all changes) or `\"review\"` (require fingerprint confirmation)."),
+    /** Opaque fingerprint of the computed diff. Pass this value back as `review_fingerprint` to confirm and apply a `"review"` mode upgrade. */
+    review_fingerprint: z.string().optional().describe("Opaque fingerprint of the computed diff. Pass this value back as `review_fingerprint` to confirm and apply a `\"review\"` mode upgrade."),
+    /** Outcome of the upgrade. `"ready"` for a dry-run (no changes applied); `"upgraded"` when the upgrade was committed. */
+    status: z.string().describe("Outcome of the upgrade. `\"ready\"` for a dry-run (no changes applied); `\"upgraded\"` when the upgrade was committed."),
+    /** Aggregate counts of adds, updates, removes, and noops across all child resources. */
+    summary: agentUpgradeSummarySchema.describe("Aggregate counts of adds, updates, removes, and noops across all child resources."),
+}).describe("The computed diff and outcome of an agent upgrade operation, including the full list of per-resource changes.");
+/** Runtime validator for {@link AgentUpgradeResponse}. */
+export const agentUpgradeResponseSchema = z.object({
+    /** The agent after the upgrade has been applied. `null` for dry-run requests where no changes were persisted. */
+    agent: agentSchema.optional().describe("The agent after the upgrade has been applied. `null` for dry-run requests where no changes were persisted."),
+    /** Summary of the parent Solution the agent was upgraded from. */
+    solution: solutionSummarySchema.describe("Summary of the parent Solution the agent was upgraded from."),
+    /** Summary of the AgentTemplate config (`cfg_...`) that was selected for this upgrade. */
+    template: upgradeTemplateSummarySchema.describe("Summary of the AgentTemplate config (`cfg_...`) that was selected for this upgrade."),
+    /** Full upgrade diff including status, mode, dry-run flag, summary counts, and per-resource change list. */
+    upgrade_result: agentUpgradeResultSchema.describe("Full upgrade diff including status, mode, dry-run flag, summary counts, and per-resource change list."),
+}).describe("Response returned by the agent upgrade endpoint, combining the updated agent, its source Solution and template, and the full upgrade diff.");
+/** Runtime validator for {@link SolutionCategorySummary}. */
+export const solutionCategorySummarySchema = z.object({
+    /** When this category was first created (ISO 8601). `null` for system-built-in categories. */
+    created_at: z.string().optional().describe("When this category was first created (ISO 8601). `null` for system-built-in categories."),
+    /** Short prose description of what solutions in this category do. `null` when not configured. */
+    description: z.string().optional().describe("Short prose description of what solutions in this category do. `null` when not configured."),
+    /** Solution category config ID (`cfg_...`). */
+    id: z.string().describe("Solution category config ID (`cfg_...`)."),
+    /** Stable, human-readable key for this category, referenced by solutions via `category_keys`. */
+    key: z.string().describe("Stable, human-readable key for this category, referenced by solutions via `category_keys`."),
+    /** Resource type identifier. Always `"SolutionCategory"`. */
+    kind: z.string().describe("Resource type identifier. Always `\"SolutionCategory\"`."),
+    /** Lookup key of the underlying config record. `null` when not set. */
+    lookup_key: z.string().optional().describe("Lookup key of the underlying config record. `null` when not set."),
+    /** Arbitrary key-value metadata attached to this category by the publisher. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata attached to this category by the publisher."),
+    /** Display name shown to users. `null` when not configured. */
+    name: z.string().optional().describe("Display name shown to users. `null` when not configured."),
+    /** Organization ID (`org_...`) that owns this category. `null` for system-scoped categories. */
+    org: z.string().optional().describe("Organization ID (`org_...`) that owns this category. `null` for system-scoped categories."),
+    /** Scopes under which this category is visible. Possible values are `"system"` (available to all apps) and `"org"` (scoped to the viewer's organization). */
+    owners: z.array(z.string()).describe("Scopes under which this category is visible. Possible values are `\"system\"` (available to all apps) and `\"org\"` (scoped to the viewer's organization)."),
+    /** Key of the parent `SolutionCategory`, enabling a hierarchy. `null` for top-level categories. */
+    parent_key: z.string().optional().describe("Key of the parent `SolutionCategory`, enabling a hierarchy. `null` for top-level categories."),
+    /** Numeric hint for ordering categories in a list. Lower values sort first. `null` when not configured. */
+    sort_order: z.number().int().optional().describe("Numeric hint for ordering categories in a list. Lower values sort first. `null` when not configured."),
+    /** When this category was last modified (ISO 8601). `null` for system-built-in categories. */
+    updated_at: z.string().optional().describe("When this category was last modified (ISO 8601). `null` for system-built-in categories."),
+    /** Virtual path of the underlying config record. `null` when not set. */
+    virtual_path: z.string().optional().describe("Virtual path of the underlying config record. `null` when not set."),
+}).describe("A solution category that organizes solutions in the catalog, identified by a stable key and optionally nested under a parent category.");
+/** Runtime validator for {@link SolutionCategoryListResponse}. */
+export const solutionCategoryListResponseSchema = z.object({
+    /** Array of solution category summary objects for the current page. */
+    data: z.array(solutionCategorySummarySchema).describe("Array of solution category summary objects for the current page."),
+    /** `true` when a subsequent page of results exists. */
+    has_next: z.boolean().describe("`true` when a subsequent page of results exists."),
+    /** `true` when a previous page of results exists. */
+    has_prev: z.boolean().describe("`true` when a previous page of results exists."),
+    /** Current page number (1-indexed). */
+    page: z.number().int().describe("Current page number (1-indexed)."),
+    /** Maximum number of entries returned per page. */
+    page_size: z.number().int().describe("Maximum number of entries returned per page."),
+    /** Total number of distinct solution categories across all pages. */
+    total_entries: z.number().int().describe("Total number of distinct solution categories across all pages."),
+    /** Total number of pages available at the current `page_size`. */
+    total_pages: z.number().int().describe("Total number of pages available at the current `page_size`."),
+}).describe("Paginated list of solution category summaries. Use `page` and `page_size` to navigate pages of results.");
+/** Runtime validator for {@link SolutionDependentAgent}. */
+export const solutionDependentAgentSchema = z.object({
+    /** Agent ID (`agi_...`). */
+    id: z.string().describe("Agent ID (`agi_...`)."),
+    /** Human-readable display name of the agent. `null` when no name has been set. */
+    name: z.string().optional().describe("Human-readable display name of the agent. `null` when no name has been set."),
+}).describe("A brief representation of an agent that references at least one config bundled by a Solution, included in the dependents preview response.");
+/** Runtime validator for {@link SolutionDependentsResponse}. */
+export const solutionDependentsResponseSchema = z.object({
+    /** Total number of distinct agents that reference at least one config bundled by this Solution. Use this count in the confirmation message; `dependent_agents` may be a shorter sample. */
+    dependent_agent_count: z.number().int().describe("Total number of distinct agents that reference at least one config bundled by this Solution. Use this count in the confirmation message; `dependent_agents` may be a shorter sample."),
+    /** A representative sample of the dependent agents, suitable for displaying in a warning list. May contain fewer entries than `dependent_agent_count` when there are many dependents. */
+    dependent_agents: z.array(solutionDependentAgentSchema).describe("A representative sample of the dependent agents, suitable for displaying in a warning list. May contain fewer entries than `dependent_agent_count` when there are many dependents."),
+    /** Number of bundled configs that would be detached and preserved rather than deleted, because at least one live agent still references them. */
+    preserved_config_count: z.number().int().describe("Number of bundled configs that would be detached and preserved rather than deleted, because at least one live agent still references them."),
+}).describe("A preview of the agents and configs that would be affected by deleting a Solution, returned before any deletion occurs so the caller can display a confirmation warning.");
+/** Runtime validator for {@link SolutionDiffReference}. */
+export const solutionDiffReferenceSchema = z.object({
+    /** ID of the referencing config (`cfg_...`). */
+    id: z.string().describe("ID of the referencing config (`cfg_...`)."),
+    /** Object type of the referencing config, e.g. `"Automation"` or `"Template"`. */
+    kind: z.string().describe("Object type of the referencing config, e.g. `\"Automation\"` or `\"Template\"`."),
+    /** Human-readable stable identifier of the referencing config. `null` if not assigned. */
+    lookup_key: z.string().optional().describe("Human-readable stable identifier of the referencing config. `null` if not assigned."),
+    /** Explanation of how the referencing config depends on the orphaned entry. */
+    reason: z.string().describe("Explanation of how the referencing config depends on the orphaned entry."),
+}).describe("A reference from another config to an orphaned entry in a solution upgrade diff, explaining why the orphan cannot be safely removed.");
+/** Runtime validator for {@link SolutionDiffEntry}. */
+export const solutionDiffEntrySchema = z.object({
+    /** Planned action for this entry. One of `"add"` (new config), `"update"` (existing config changes), `"noop"` (no change needed), `"orphan"` (config no longer in the solution), or `"delete"` (config to be removed). */
+    action: z.string().describe("Planned action for this entry. One of `\"add\"` (new config), `\"update\"` (existing config changes), `\"noop\"` (no change needed), `\"orphan\"` (config no longer in the solution), or `\"delete\"` (config to be removed)."),
+    /** `true` if the config content differs between the existing and incoming solution versions. */
+    content_changed: z.boolean().describe("`true` if the config content differs between the existing and incoming solution versions."),
+    /** Config ID (`cfg_...`) if this entry corresponds to an existing config record. `null` for new additions. */
+    id: z.string().optional().describe("Config ID (`cfg_...`) if this entry corresponds to an existing config record. `null` for new additions."),
+    /** Stable string key identifying this config entry within the solution. */
+    key: z.string().describe("Stable string key identifying this config entry within the solution."),
+    /** Config object type, e.g. `"Automation"` or `"Template"`. `null` if not yet known. */
+    kind: z.string().optional().describe("Config object type, e.g. `\"Automation\"` or `\"Template\"`. `null` if not yet known."),
+    /** Human-readable stable identifier for this config. `null` if not assigned. */
+    lookup_key: z.string().optional().describe("Human-readable stable identifier for this config. `null` if not assigned."),
+    /** `true` if the MIME type of the config changed between versions. */
+    mime_type_changed: z.boolean().describe("`true` if the MIME type of the config changed between versions."),
+    /** List of other configs that reference this entry. Populated for orphaned configs that cannot be safely removed. Empty array when there are no references. */
+    referenced_by: z.array(solutionDiffReferenceSchema).optional().describe("List of other configs that reference this entry. Populated for orphaned configs that cannot be safely removed. Empty array when there are no references."),
+    /** `true` if the relative path of the config within the solution changed between versions. */
+    relative_path_changed: z.boolean().describe("`true` if the relative path of the config within the solution changed between versions."),
+    /** Role of this config within the solution. Indicates whether it is a primary config or a dependency. */
+    role: z.string().describe("Role of this config within the solution. Indicates whether it is a primary config or a dependency."),
+    /** Hierarchical path of this config in the config tree. `null` if not assigned. */
+    virtual_path: z.string().optional().describe("Hierarchical path of this config in the config tree. `null` if not assigned."),
+}).describe("A single config entry in a solution upgrade diff, describing what action will be taken on a specific config key.");
+/** Runtime validator for {@link SolutionDiffSummary}. */
+export const solutionDiffSummarySchema = z.object({
+    /** Number of config entries that will be newly created by this upgrade. */
+    adds: z.number().int().describe("Number of config entries that will be newly created by this upgrade."),
+    /** Number of config entries that will be deleted as part of the upgrade. */
+    deletes: z.number().int().describe("Number of config entries that will be deleted as part of the upgrade."),
+    /** Number of config entries that are already up to date and require no changes. */
+    noops: z.number().int().describe("Number of config entries that are already up to date and require no changes."),
+    /** Number of config entries present in the existing solution that are absent from the incoming version and have no external references blocking removal. */
+    orphans: z.number().int().describe("Number of config entries present in the existing solution that are absent from the incoming version and have no external references blocking removal."),
+    /** Number of orphaned config entries that cannot be removed because other configs still reference them. */
+    referenced_orphans: z.number().int().describe("Number of orphaned config entries that cannot be removed because other configs still reference them."),
+    /** Number of config entries that exist and will be updated with new content. */
+    updates: z.number().int().describe("Number of config entries that exist and will be updated with new content."),
+}).describe("Aggregate counts of each action type across all entries in a solution upgrade diff.");
+/** Runtime validator for {@link SolutionImportResult}. */
+export const solutionImportResultSchema = z.object({
+    /** Machine-readable conflict code present when `status` is `"conflict"`, identifying the specific conflict reason. `null` when `status` is `"ready"`. */
+    code: z.string().optional().describe("Machine-readable conflict code present when `status` is `\"conflict\"`, identifying the specific conflict reason. `null` when `status` is `\"ready\"`."),
+    /** Whether this result was produced by a dry-run check. `true` when the import was validated without persisting any changes. */
+    dry_run: z.boolean().describe("Whether this result was produced by a dry-run check. `true` when the import was validated without persisting any changes."),
+    /** Semver string of the Solution version already present in the library. `null` when no prior version exists. */
+    existing_solution_version: z.string().optional().describe("Semver string of the Solution version already present in the library. `null` when no prior version exists."),
+    /** Semver string of the Solution version in the bundle being imported. `null` when the bundle does not declare a version. */
+    incoming_solution_version: z.string().optional().describe("Semver string of the Solution version in the bundle being imported. `null` when the bundle does not declare a version."),
+    /** Human-readable description of the import status or conflict reason, suitable for display in a confirmation dialog. `null` when no detail is available. */
+    message: z.string().optional().describe("Human-readable description of the import status or conflict reason, suitable for display in a confirmation dialog. `null` when no detail is available."),
+    /** Outcome of the import check. `"ready"` means the import can proceed as a normal create or update. `"conflict"` means a version conflict was detected and the upgrade flow must be used instead. */
+    status: z.string().describe("Outcome of the import check. `\"ready\"` means the import can proceed as a normal create or update. `\"conflict\"` means a version conflict was detected and the upgrade flow must be used instead."),
+    /** Whether the caller must invoke the dedicated upgrade flow to complete the import. Mirrors `status == "conflict"` as a convenience boolean. */
+    upgrade_required: z.boolean().describe("Whether the caller must invoke the dedicated upgrade flow to complete the import. Mirrors `status == \"conflict\"` as a convenience boolean."),
+}).describe("The machine-readable outcome of a Solution import attempt, indicating whether the import succeeded or requires an upgrade flow to resolve a version conflict.");
+/** Runtime validator for {@link SolutionImportResponse}. */
+export const solutionImportResponseSchema = z.object({
+    /** When the Solution config record was first created (ISO 8601). */
+    created_at: z.string().optional().describe("When the Solution config record was first created (ISO 8601)."),
+    /** Solution config ID (`cfg_...`). */
+    id: z.string().describe("Solution config ID (`cfg_...`)."),
+    /** Structured outcome of the import, including status, conflict details, and version information. */
+    import_result: solutionImportResultSchema.describe("Structured outcome of the import, including status, conflict details, and version information."),
+    /** Deprecated legacy field. One entry per persisted config in the import (including the Solution itself), defaulting to an empty array. Callers should prefer `solution` plus follow-up APIs instead. `key` echoes the caller-supplied input identifier (original lookup_key for top-level configs; `<skill_lookup_key>:<relative_path>` for skill / solution-file children). Order is stable: sorted by `key`. */
+    installed_configs: z.array(installedConfigEntrySchema).optional().describe("Deprecated legacy field. One entry per persisted config in the import (including the Solution itself), defaulting to an empty array. Callers should prefer `solution` plus follow-up APIs instead. `key` echoes the caller-supplied input identifier (original lookup_key for top-level configs; `<skill_lookup_key>:<relative_path>` for skill / solution-file children). Order is stable: sorted by `key`."),
+    /** Resource type. Always `"Solution"`. */
+    kind: z.string().describe("Resource type. Always `\"Solution\"`."),
+    /** The `lookup_key` stored on the Solution config after the import's suffix normalization. `null` when the Solution was not given a lookup key. */
+    lookup_key: z.string().optional().describe("The `lookup_key` stored on the Solution config after the import's suffix normalization. `null` when the Solution was not given a lookup key."),
+    /** Full summary of the imported Solution, in the same shape as the individual Solution retrieval endpoint. */
+    solution: solutionSummarySchema.describe("Full summary of the imported Solution, in the same shape as the individual Solution retrieval endpoint."),
+    /** When the Solution config record was last modified (ISO 8601). */
+    updated_at: z.string().optional().describe("When the Solution config record was last modified (ISO 8601)."),
+    /** The `virtual_path` stored on the Solution config, used as the stable dedupe key across owner scopes. `null` when no virtual path was assigned. */
+    virtual_path: z.string().optional().describe("The `virtual_path` stored on the Solution config, used as the stable dedupe key across owner scopes. `null` when no virtual path was assigned."),
+}).describe("The result of importing a Solution bundle into the library, including the Solution config record, a structured import result, and the list of all configs persisted during the transaction.");
+/** Runtime validator for {@link SolutionInstallResponse}. */
+export const solutionInstallResponseSchema = z.object({
+    /** Public ID of the provisioned resource. The prefix reflects the resource kind: `agi_...` for Agent, `aut_...` for Automation, `art_...` for AgentRoutine, `att_...` for AgentTool, `ask_...` for AgentSkill, `cmp_...` for AgentComputer. */
+    id: z.string().describe("Public ID of the provisioned resource. The prefix reflects the resource kind: `agi_...` for Agent, `aut_...` for Automation, `art_...` for AgentRoutine, `att_...` for AgentTool, `ask_...` for AgentSkill, `cmp_...` for AgentComputer."),
+    /** Type of the provisioned resource. One of `"Agent"`, `"Automation"`, `"AgentRoutine"`, `"AgentTool"`, `"AgentSkill"`, or `"AgentComputer"`. */
+    kind: z.string().describe("Type of the provisioned resource. One of `\"Agent\"`, `\"Automation\"`, `\"AgentRoutine\"`, `\"AgentTool\"`, `\"AgentSkill\"`, or `\"AgentComputer\"`."),
+    /** The `lookup_key` stamped on the provisioned resource. `null` for `AgentSkill`, which is a join record and does not carry a lookup key. */
+    lookup_key: z.string().optional().describe("The `lookup_key` stamped on the provisioned resource. `null` for `AgentSkill`, which is a join record and does not carry a lookup key."),
+    /** Solution config ID (`cfg_...`) that was used as the source for this install. */
+    solution: z.string().describe("Solution config ID (`cfg_...`) that was used as the source for this install."),
+}).describe("The runtime resource provisioned by installing a Solution, along with a reference back to the source Solution config.");
+/** Runtime validator for {@link SolutionListResponse}. */
+export const solutionListResponseSchema = z.object({
+    /** Array of Solution summary objects for the current page, in the order returned by the query. */
+    data: z.array(solutionSummarySchema).describe("Array of Solution summary objects for the current page, in the order returned by the query."),
+    /** `true` when a subsequent page exists; `false` when this is the last page. */
+    has_next: z.boolean().describe("`true` when a subsequent page exists; `false` when this is the last page."),
+    /** `true` when a preceding page exists; `false` when this is the first page. */
+    has_prev: z.boolean().describe("`true` when a preceding page exists; `false` when this is the first page."),
+    /** 1-based index of the current page. */
+    page: z.number().int().describe("1-based index of the current page."),
+    /** Maximum number of results included per page. */
+    page_size: z.number().int().describe("Maximum number of results included per page."),
+    /** Total number of Solutions matching the query after deduplication by `solution_id` across owner scopes. */
+    total_entries: z.number().int().describe("Total number of Solutions matching the query after deduplication by `solution_id` across owner scopes."),
+    /** Total number of pages available at the current `page_size`. */
+    total_pages: z.number().int().describe("Total number of pages available at the current `page_size`."),
+}).describe("A paginated collection of Solution summaries, with page metadata for navigating the result set.");
+/** Runtime validator for {@link SolutionTagSummary}. */
+export const solutionTagSummarySchema = z.object({
+    /** When the solution tag was first created (ISO 8601). `null` if unavailable. */
+    created_at: z.string().optional().describe("When the solution tag was first created (ISO 8601). `null` if unavailable."),
+    /** Short prose explanation of what the tag represents. `null` if not provided. */
+    description: z.string().optional().describe("Short prose explanation of what the tag represents. `null` if not provided."),
+    /** Solution tag config ID (`cfg_...`). */
+    id: z.string().describe("Solution tag config ID (`cfg_...`)."),
+    /** Stable string key for this tag, referenced by `Solution.tag_keys` to associate solutions with this tag. */
+    key: z.string().describe("Stable string key for this tag, referenced by `Solution.tag_keys` to associate solutions with this tag."),
+    /** Object type discriminator. Always `"SolutionTag"`. */
+    kind: z.string().describe("Object type discriminator. Always `\"SolutionTag\"`."),
+    /** Human-readable stable identifier for this tag config, used for lookups and imports. `null` if not assigned. */
+    lookup_key: z.string().optional().describe("Human-readable stable identifier for this tag config, used for lookups and imports. `null` if not assigned."),
+    /** Arbitrary key-value metadata attached to this tag. Empty object `{}` when no metadata is present. */
+    metadata: z.record(z.unknown()).optional().describe("Arbitrary key-value metadata attached to this tag. Empty object `{}` when no metadata is present."),
+    /** Human-readable display name for the tag. `null` if not yet set. */
+    name: z.string().optional().describe("Human-readable display name for the tag. `null` if not yet set."),
+    /** ID of the organization that owns this tag (`org_...`). `null` for system-scoped tags. */
+    org: z.string().optional().describe("ID of the organization that owns this tag (`org_...`). `null` for system-scoped tags."),
+    /** Scopes under which this tag is visible to the caller. One or both of `"system"` (platform-level tag available to all orgs) and `"org"` (tag scoped to the viewer's org). */
+    owners: z.array(z.string()).describe("Scopes under which this tag is visible to the caller. One or both of `\"system\"` (platform-level tag available to all orgs) and `\"org\"` (tag scoped to the viewer's org)."),
+    /** Optional integer hint for ordering tags in UI lists. Lower values sort first. `null` if not set. */
+    sort_order: z.number().int().optional().describe("Optional integer hint for ordering tags in UI lists. Lower values sort first. `null` if not set."),
+    /** When the solution tag was last modified (ISO 8601). `null` if unavailable. */
+    updated_at: z.string().optional().describe("When the solution tag was last modified (ISO 8601). `null` if unavailable."),
+    /** Hierarchical path used to organize this tag in the config tree. `null` if not assigned. */
+    virtual_path: z.string().optional().describe("Hierarchical path used to organize this tag in the config tree. `null` if not assigned."),
+}).describe("A single solution tag definition, representing a named classification label that can be applied to solutions.");
+/** Runtime validator for {@link SolutionTagListResponse}. */
+export const solutionTagListResponseSchema = z.object({
+    /** Array of solution tag objects for the current page. */
+    data: z.array(solutionTagSummarySchema).describe("Array of solution tag objects for the current page."),
+    /** `true` if a subsequent page exists; `false` when this is the last page. */
+    has_next: z.boolean().describe("`true` if a subsequent page exists; `false` when this is the last page."),
+    /** `true` if a preceding page exists; `false` when this is the first page. */
+    has_prev: z.boolean().describe("`true` if a preceding page exists; `false` when this is the first page."),
+    /** Current page number (1-indexed). */
+    page: z.number().int().describe("Current page number (1-indexed)."),
+    /** Maximum number of results returned per page. */
+    page_size: z.number().int().describe("Maximum number of results returned per page."),
+    /** Total number of distinct solution tags across all pages, after deduplication by key. */
+    total_entries: z.number().int().describe("Total number of distinct solution tags across all pages, after deduplication by key."),
+    /** Total number of pages available at the current `page_size`. */
+    total_pages: z.number().int().describe("Total number of pages available at the current `page_size`."),
+}).describe("Paginated list of solution tag summaries returned by the list solution tags endpoint.");
+/** Runtime validator for {@link SolutionUpgradeResult}. */
+export const solutionUpgradeResultSchema = z.object({
+    /** Ordered list of individual config change entries representing every add, update, noop, orphan, and delete in the diff. */
+    changes: z.array(solutionDiffEntrySchema).describe("Ordered list of individual config change entries representing every add, update, noop, orphan, and delete in the diff."),
+    /** Machine-readable conflict code when `status` is `"conflict"`, e.g. `"review_required"`. `null` when there is no conflict. */
+    code: z.string().optional().describe("Machine-readable conflict code when `status` is `\"conflict\"`, e.g. `\"review_required\"`. `null` when there is no conflict."),
+    /** `true` when the upgrade was computed without writing any changes; `false` when changes were committed. */
+    dry_run: z.boolean().describe("`true` when the upgrade was computed without writing any changes; `false` when changes were committed."),
+    /** Version string of the currently installed solution, as declared in its manifest. `null` if no prior version is installed. */
+    existing_solution_version: z.string().optional().describe("Version string of the currently installed solution, as declared in its manifest. `null` if no prior version is installed."),
+    /** Version string of the incoming solution to be installed, as declared in its manifest. `null` if the incoming manifest omits a version. */
+    incoming_solution_version: z.string().optional().describe("Version string of the incoming solution to be installed, as declared in its manifest. `null` if the incoming manifest omits a version."),
+    /** Human-readable description of the conflict or error. `null` when there is no conflict. */
+    message: z.string().optional().describe("Human-readable description of the conflict or error. `null` when there is no conflict."),
+    /** Opaque fingerprint that uniquely identifies this diff. Pass this value as `review_fingerprint` on a subsequent non-dry-run upgrade call to confirm you have reviewed the diff. `null` if not applicable. */
+    review_fingerprint: z.string().optional().describe("Opaque fingerprint that uniquely identifies this diff. Pass this value as `review_fingerprint` on a subsequent non-dry-run upgrade call to confirm you have reviewed the diff. `null` if not applicable."),
+    /** Overall result of the upgrade. `"ready"` means the upgrade can proceed; `"conflict"` means a blocking issue was detected and the upgrade was not applied. */
+    status: z.string().describe("Overall result of the upgrade. `\"ready\"` means the upgrade can proceed; `\"conflict\"` means a blocking issue was detected and the upgrade was not applied."),
+    /** Aggregate counts of each action type across all diff entries. */
+    summary: solutionDiffSummarySchema.describe("Aggregate counts of each action type across all diff entries."),
+    /** Describes the nature of the version transition. One of `"upgrade"`, `"downgrade"`, `"same"`, or `"unknown"`. */
+    version_change: z.string().describe("Describes the nature of the version transition. One of `\"upgrade\"`, `\"downgrade\"`, `\"same\"`, or `\"unknown\"`."),
+}).describe("The outcome of a solution upgrade operation, including the computed diff and conflict status.");
+/** Runtime validator for {@link SolutionUpgradeResponse}. */
+export const solutionUpgradeResponseSchema = z.object({
+    /** When the solution config record was first created (ISO 8601). `null` if unavailable. */
+    created_at: z.string().optional().describe("When the solution config record was first created (ISO 8601). `null` if unavailable."),
+    /** Config ID of the solution record (`cfg_...`). */
+    id: z.string().describe("Config ID of the solution record (`cfg_...`)."),
+    /** List of config entries that were installed or updated as part of this upgrade. Empty when `dry_run` is `true` or when no configs changed. */
+    installed_configs: z.array(installedConfigEntrySchema).optional().describe("List of config entries that were installed or updated as part of this upgrade. Empty when `dry_run` is `true` or when no configs changed."),
+    /** Object type discriminator. Always `"Solution"`. */
+    kind: z.string().describe("Object type discriminator. Always `\"Solution\"`."),
+    /** Human-readable stable identifier for this solution config. `null` if not assigned. */
+    lookup_key: z.string().optional().describe("Human-readable stable identifier for this solution config. `null` if not assigned."),
+    /** Summary of the solution being upgraded, including its name, manifest metadata, and tag keys. */
+    solution: solutionSummarySchema.describe("Summary of the solution being upgraded, including its name, manifest metadata, and tag keys."),
+    /** When the solution config record was last modified (ISO 8601). `null` if unavailable. */
+    updated_at: z.string().optional().describe("When the solution config record was last modified (ISO 8601). `null` if unavailable."),
+    /** Detailed result of the upgrade operation, including the computed diff and any conflict information. */
+    upgrade_result: solutionUpgradeResultSchema.describe("Detailed result of the upgrade operation, including the computed diff and any conflict information."),
+    /** Hierarchical path of the solution in the config tree. `null` if not assigned. */
+    virtual_path: z.string().optional().describe("Hierarchical path of the solution in the config tree. `null` if not assigned."),
+}).describe("Response returned by the solution upgrade endpoint, containing the solution record, the full upgrade diff, and the resulting installed configs.");
 //# sourceMappingURL=common.js.map