/** * Task-centric endpoints of the TeamShare REST client: tasks, plan-run * tracking, claims, subtasks, checklist items, comments and whiteboards. * Split out of api.ts (1200-line-per-file rule). */ import { AgentEndpoints } from './api-agents'; import type { ChecklistItemRow, Comment, SubtaskNode, Task, TaskDocument, TaskAttachment } from './api-types'; export declare class TaskEndpoints extends AgentEndpoints { getTask(taskId: string): Promise; listTasks(params: { projectId?: string; status?: string; assigneeId?: string; page?: number; pageSize?: number; }): Promise; createTask(dto: { projectId: string; title: string; description?: string; status?: string; priority?: string; assigneeId?: string; dueDate?: string; tags?: string[]; readyForDev?: boolean; sortOrder?: number; documentIds?: string[]; }): Promise; listTaskDocuments(taskId: string): Promise; /** * Figma design references attached to a task (2026-12). Best-effort at the * call site: an older hub answers 404, which must never cost the brief. */ listTaskDesigns(taskId: string): Promise>; /** * Files uploaded directly to a task (the attachment system - separate from * project documents). Fails soft at call sites on older backends. */ listTaskAttachments(taskId: string): Promise; updateTask(taskId: string, dto: Record): Promise; /** * Reports that a planning pass has STARTED for the task. Increments the * task's plan-run counter + stamps the start time on the hub. Best-effort at * the call site; never changes the task status. */ startPlanRun(taskId: string, meta?: { harness?: string; model?: string; sessionId?: string; }): Promise<{ planRunCount: number; planLastRunAt: string | null; }>; /** * Reports a planning pass FINISHED. On success the hub sets the definitive * `plannedAt` marker; on failure it stores `planLastError`. */ finishPlanRun(taskId: string, result: { ok: boolean; summary?: string; error?: string; }): Promise<{ plannedAt: string | null; planRunCount: number; planLastError: string | null; }>; /** * Reports what the run's git pipeline delivered: whether the agent's naming * proposal was used or refused (and why), plus the delivered branch when a * guarded rename applied. The hub records `Task.deliveryBranch` from this, so * a retry continues on the renamed branch. * * Best-effort at the call site: the work is already committed and pushed, so * a failed report costs metadata, never the delivery. */ reportGitDelivery(taskId: string, dto: { naming: 'applied' | 'refused' | 'none'; reason?: string; branch?: string; sha?: string; prUrl?: string; prNumber?: number; repos?: Array<{ repo: string; branch: string; sha?: string; prUrl?: string; }>; }): Promise<{ recorded: boolean; deliveryBranch: string | null; }>; /** Claims the task (lease 10 min by default, renewed by heartbeat). Errors surface as thrown messages. * * `manual` is how a HUMAN says "work this task anyway": it is the ONLY thing * that lets a claim through on a task that is not open/in_progress, so it * must be set from a real human trigger (the `task.run` wake / the `--manual` * CLI flag) and never from an automated path. The backend refuses with * `TASK_NOT_OPEN` otherwise. */ claimTask(taskId: string, expiresMinutes?: number, manual?: boolean): Promise<{ claimed: boolean; claimedById: string; claimExpiresAt: string; }>; /** Releases the task claim (self-release or owner/admin takeover). */ releaseTask(taskId: string): Promise<{ released: boolean; claimedById: string | null; }>; /** Renews an active claim's lease without checking task status. */ renewClaim(taskId: string): Promise<{ renewed: boolean; claimExpiresAt: string; }>; /** * Session-scoped claim cleanup (2026-08-26): clears every claim THIS * session took. Called once when a chat/doc/run harness exits so an * agent forgetting release_task can never strand a lease. */ releaseSessionClaims(sessionId: string): Promise<{ released: number; }>; /** * Auto-run guard (2026-09): reports a harness-level failure (the run died * before producing work - provider outage, crashed CLI, missing binary) so * the hub can count consecutive failures and suspend the task instead of * letting the stranded-task sweep re-wake it forever. `suspended: true` means * no further automatic runs - a human must press "Run task". */ reportRunFailed(taskId: string, input?: { reason?: string; harness?: string; }): Promise<{ failures: number; suspended: boolean; cap: number; }>; listComments(taskId: string): Promise; /** Subtask tree of a task (nested, each node with checklist items). */ listSubtasks(taskId: string): Promise; createSubtask(dto: { taskId: string; title: string; parentId?: string | null; assigneeId?: string | null; dueDate?: string | null; }): Promise; /** Mark done / reopen, rename, reassign, move or re-due a subtask. */ updateSubtask(subtaskId: string, dto: Record): Promise; /** Lists checklist items on a task. */ listChecklistItems(taskId: string): Promise; /** Adds a checklist row to a task or a subtask (pass exactly one id). */ createChecklistItem(target: { taskId?: string; subtaskId?: string; }, title: string): Promise; /** Toggle done / rename a checklist row. */ updateChecklistItem(checklistItemId: string, dto: { title?: string; done?: boolean; }): Promise; /** Removes a checklist row. */ deleteChecklistItem(checklistItemId: string): Promise<{ id: string; deleted: boolean; }>; /** Document comment thread (Phase F document assistant). */ listDocumentComments(documentId: string): Promise; /** * Post a comment. * * `clientRequestId` is the IDEMPOTENCY KEY (2026-10). Every retry of one * logical notification must reuse the same value, and the server collapses * repeats onto the first row (`@@unique([authorId, clientRequestId])`, * returning the existing comment with 200 instead of creating a second). * * This is not theoretical: a stopped run posted the identical `[work stopped]` * comment eight times and the identical git notice three times, every one * tagged ETIMEDOUT. A request that times out AFTER the server committed it is * indistinguishable from one that never arrived, so any client-side "did I * already send this?" check is a guess. A key the server enforces is not. * * Derive it from something STABLE about the intent (never a timestamp or a * random value per attempt): e.g. * `git-unavailable::::`. */ addComment(dto: { taskId?: string; documentId?: string; whiteboardId?: string; workflowId?: string; /** Thread this comment under a parent (2026-11) - how an agent answers a reply. */ parentId?: string; body: string; clientRequestId?: string; }): Promise; /** Workflow authoring thread (2026-10): the definition conversation. */ listWorkflowComments(workflowId: string): Promise; /** Full authoring brief: definition + validation + runs + thread (dual auth). */ getWorkflowAuthoringContext(workflowId: string): Promise<{ workflow: { id: string; projectId: string | null; name: string; mode: string; steps?: unknown; graph?: unknown; params?: unknown; enabled: boolean; lockedFromAi?: boolean; validation?: unknown; updatedAt: string; }; validation: unknown; runs: Array<{ id: string; status: string; createdAt: string; }>; comments: Comment[]; }>; /** Board comment thread (board assistant / "Ask agent" on a board). */ listWhiteboardComments(whiteboardId: string): Promise; /** Board metadata + raw Excalidraw scene. */ getWhiteboard(whiteboardId: string): Promise<{ id: string; projectId: string; name: string; content?: unknown; updatedAt: string; }>; /** Agent-readable text extract of a board. */ extractWhiteboard(whiteboardId: string): Promise<{ text: string; truncated?: boolean; cached?: boolean; }>; /** Append a DiagramSpec to a board (deterministic server-side layout). */ drawOnWhiteboard(whiteboardId: string, spec: Record, expectedUpdatedAt?: string): Promise<{ id: string; updatedAt: string; applied: number; }>; }