archastro.platform.types.tasks

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 3a75d35595f1
  4
  5from datetime import datetime
  6from typing import Any
  7
  8from pydantic import BaseModel, Field
  9
 10from .common import Actor
 11
 12
 13class TaskSessionLeaseSummary(BaseModel):
 14    """
 15    Viewer-safe details about a task's current coding-session lease.
 16    """
 17
 18    expires_at: datetime = Field(
 19        ..., description="Server-calculated lease expiry in ISO 8601 format."
 20    )
 21    harness: str = Field(..., description="Bounded harness identifier for the coding session.")
 22    session_name: str = Field(
 23        ..., description="Display name supplied by the coding session that holds the lease."
 24    )
 25
 26
 27class Task(BaseModel):
 28    """
 29    A task representing a unit of work, optionally assignable to a user or agent.
 30    """
 31
 32    agent: str | None = Field(
 33        default=None,
 34        description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.",
 35    )
 36    aggregate_version: int | None = Field(
 37        default=None,
 38        description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.",
 39    )
 40    blocked_by_count: int | None = Field(
 41        default=None,
 42        description="Number of readable tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.",
 43    )
 44    closed_at: datetime | None = Field(
 45        default=None,
 46        description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.",
 47    )
 48    comments_count: int | None = Field(
 49        default=None, description="Total number of comments posted on this task."
 50    )
 51    created_at: datetime | None = Field(
 52        default=None, description="When the task was created (ISO 8601)."
 53    )
 54    created_by_actor: Actor | None = Field(
 55        default=None,
 56        description="Resolved creator details including `id`, `name`, `alias`, and `profile_picture`. `null` if no creator is set or the creator cannot be resolved (e.g. creating agent was deleted).",
 57    )
 58    created_by_agent: str | None = Field(
 59        default=None,
 60        description="ID of the agent that created this task (`agi_...`). `null` if the task was created by a human user, or if the creating agent was later deleted.",
 61    )
 62    created_by_user: str | None = Field(
 63        default=None,
 64        description="ID of the user who created this task (`usr_...`). `null` if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.",
 65    )
 66    current_lease: TaskSessionLeaseSummary | None = Field(
 67        default=None,
 68        description="Viewer-safe live coding-session lease summary. `null` when the task is unleased or the projected lease has expired. Fencing identifiers are never included.",
 69    )
 70    description: str | None = Field(
 71        default=None,
 72        description="Long-form description or notes for the task. `null` if no description has been provided.",
 73    )
 74    due_date: datetime | None = Field(
 75        default=None,
 76        description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.",
 77    )
 78    epic: str | None = Field(
 79        default=None,
 80        description="Free-form grouping label. `null` when the task is not in an epic.",
 81    )
 82    id: str = Field(..., description="Task ID (`tsk_...`).")
 83    is_blocked: bool | None = Field(
 84        default=None,
 85        description="`true` while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.",
 86    )
 87    is_stalled: bool | None = Field(
 88        default=None,
 89        description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.",
 90    )
 91    links: dict[str, Any] | None = Field(
 92        default=None,
 93        description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.",
 94    )
 95    metadata: dict[str, Any] | None = Field(
 96        default=None,
 97        description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.",
 98    )
 99    name: str = Field(..., description="Human-readable title of the task.")
100    org: str | None = Field(
101        default=None,
102        description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.",
103    )
104    owner_actor: Actor | None = Field(
105        default=None,
106        description="Resolved owner details including `id`, `name`, `alias`, and `profile_picture`. `null` if the task is unassigned or the owner cannot be resolved (e.g. assigned agent was deleted).",
107    )
108    owner_agent: str | None = Field(
109        default=None,
110        description="ID of the agent assigned as owner (`agi_...`). `null` if the owner is a human user, the task is unassigned, or the assigned agent was deleted.",
111    )
112    owner_user: str | None = Field(
113        default=None,
114        description="ID of the user assigned as owner (`usr_...`). `null` if the owner is an agent, the task is unassigned, or the assigned agent was deleted.",
115    )
116    parent: str | None = Field(
117        default=None,
118        description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.",
119    )
120    priority: int | None = Field(
121        default=None,
122        description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.",
123    )
124    project_id: str | None = Field(
125        default=None,
126        description="Optional project ID (`prj_...`). Membership does not change task visibility.",
127    )
128    sandbox: str | None = Field(
129        default=None,
130        description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.",
131    )
132    source_id: str | None = Field(
133        default=None,
134        description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.",
135    )
136    source_scope: str | None = Field(
137        default=None,
138        description="Container of the work this task is about (for example `github.com`). `null` when the task has no source. Set together with `source_type` and `source_id`.",
139    )
140    source_type: str | None = Field(
141        default=None,
142        description="Kind of source object (for example `repository`). `null` when the task has no source.",
143    )
144    stalled_since: datetime | None = Field(
145        default=None,
146        description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.",
147    )
148    status: str = Field(
149        ...,
150        description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.',
151    )
152    subtasks_count: int | None = Field(
153        default=None,
154        description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.",
155    )
156    tags: list[str] | None = Field(
157        default=None,
158        description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.",
159    )
160    target_binary: str | None = Field(
161        default=None,
162        description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.",
163    )
164    target_version: str | None = Field(
165        default=None,
166        description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.",
167    )
168    team: str | None = Field(
169        default=None,
170        description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.",
171    )
172    thread: str | None = Field(
173        default=None,
174        description="ID of the thread this task is bound to (`thr_...`) - the conversation it was filed from, or the thread passed at creation. `null` for tasks not tied to a thread.",
175    )
176    updated_at: datetime | None = Field(
177        default=None, description="When the task was last modified (ISO 8601)."
178    )
179    user: str | None = Field(
180        default=None,
181        description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.",
182    )
183
184
185class TaskComment(BaseModel):
186    """
187    A comment posted on a task by a user or an agent, including resolved author information.
188    """
189
190    author_actor: Actor | None = Field(
191        default=None,
192        description="Resolved author details including `id`, `name`, `alias`, and `profile_picture`. `null` if no author is set or the author cannot be resolved (e.g. authoring agent was deleted).",
193    )
194    author_agent: str | None = Field(
195        default=None,
196        description="ID of the agent that posted this comment (`agi_...`). `null` if the author is a human user, or if the authoring agent was later deleted.",
197    )
198    author_user: str | None = Field(
199        default=None,
200        description="ID of the user who posted this comment (`usr_...`). `null` if the author is an agent, or if author provenance was cleared after the authoring agent was deleted.",
201    )
202    body: str = Field(..., description="Plain-text body of the comment.")
203    created_at: datetime | None = Field(
204        default=None, description="When this comment was posted (ISO 8601)."
205    )
206    id: str = Field(..., description="Comment ID (`tcmt_...`).")
207    org: str | None = Field(
208        default=None, description="ID of the organization that owns this comment (`org_...`)."
209    )
210    sandbox: str | None = Field(
211        default=None,
212        description="Sandbox ID this comment is scoped to. `null` for comments outside a sandbox environment.",
213    )
214    task: str | None = Field(
215        default=None, description="ID of the task this comment belongs to (`tsk_...`)."
216    )
217    team: str | None = Field(
218        default=None,
219        description="ID of the team the task belongs to (`tem_...`). `null` if not scoped to a team.",
220    )
221    updated_at: datetime | None = Field(
222        default=None, description="When this comment was last edited (ISO 8601)."
223    )
224
225
226class TaskEnsureResult(BaseModel):
227    """
228    The current source task and whether this request created it.
229    """
230
231    created: bool = Field(..., description="Whether this request created the task.")
232    task: Task = Field(..., description="The current task.")
233
234
235class TaskExternalLink(BaseModel):
236    """
237    An indexed external object linked to a task.
238    """
239
240    external_scope: str = Field(..., description="External container identity.")
241    object_id: str = Field(..., description="Object identity within that container.")
242    object_type: str = Field(..., description="External object kind.")
243
244
245class TaskOwnershipJob(BaseModel):
246    """
247    The background job accepted for a task ownership conversion.
248    """
249
250    job_id: int = Field(..., description="Background job ID.")
251    projection_pending: bool | None = Field(
252        default=None, description="Completed transfers are still reaching task read models."
253    )
254    status: str = Field(..., description="Current background job state.")
255
256
257class TaskSessionLease(BaseModel):
258    """
259    A task-session lease returned only to its matching holder.
260    """
261
262    expires_at: datetime = Field(
263        ..., description="Server-calculated lease expiry in ISO 8601 format."
264    )
265    harness: str = Field(
266        ..., description="Bounded harness identifier for the matching coding session."
267    )
268    lease_id: str = Field(
269        ..., description="Caller-generated fencing token required for renewal and release."
270    )
271    lease_remaining_ms: int = Field(
272        ...,
273        description="Milliseconds of lease left when the response was built, clamped at zero. A renewal made while more than half the lease remains appends no event and leaves the expiry unchanged, so clients derive their deadline from this value.",
274    )
275    renewed_at: datetime = Field(
276        ..., description="Server timestamp for the most recent claim, reclaim, or renewal."
277    )
278    session_id: str = Field(..., description="Opaque caller-generated coding-session identifier.")
279    session_name: str = Field(
280        ..., description="Display name supplied by the matching coding session."
281    )
282    task_aggregate_version: int = Field(
283        ..., description="Task aggregate version including the claim, reclaim, or renewal event."
284    )
285    task_status: str = Field(..., description="Native task status after the lease event.")