/** * Shared DTO interfaces of the TeamShare REST client (ToolRun, Task, * Document, Comment, BuildQueue, ...). Split out of api.ts - re-exported * from api.ts so the public surface is unchanged. */ /** * Blog generation context (IMP-9xx) - `GET /blog/generations/:id/context`. * * `post` carries the draft's CURRENT content, which is what makes a refine run * safe: the agent rewrites what the human actually has on the page, so manual * edits made since the last run are preserved rather than discarded. */ /** * Insight narrative context (2026-10) - `GET /insights/narratives/:id/context`. * * `facts` is the frozen deterministic snapshot the harness narrates. The * harness never computes numbers - it only explains them. */ export interface InsightNarrativeContext { id: string; scope: 'personal' | 'company' | 'project'; companyId: string | null; projectId: string | null; kind: 'overview' | 'performance' | 'teams' | 'recommendations'; trigger: 'manual' | 'weekly' | 'refresh'; status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'; facts: unknown; } /** * Workflow run context (2026-10) - `GET /workflows/runs/:id/context`. * * Everything a `workflow.run` session needs in one call: the frozen * definition, resolved inputs, the step list with live statuses and the * credential KEYS (never values - those ride the secrets endpoint). */ export interface WorkflowRunContext { id: string; workflowId: string; workflowName: string; projectId: string; taskId: string | null; status: 'pending' | 'running' | 'waiting_answer' | 'completed' | 'failed' | 'cancelled'; isolation: 'folder' | 'mirror'; /** 'basic' (ordered steps) or 'advanced' (node graph). */ mode: 'basic' | 'advanced'; /** The node graph for an advanced workflow (empty for basic). */ graph: WorkflowGraph | null; params: Record; paramContract: Array>; steps: Array<{ index: number; id: string; title: string; instruction: string; type: 'instruction' | 'command' | 'checkpoint' | 'ask_human'; expect: string | null; status: 'pending' | 'running' | 'done' | 'skipped' | 'failed'; note: string | null; }>; credentialKeys: Array<{ key: string; tier: string; }>; hasSecrets: boolean; outputContract: unknown; requiredCapabilities: string[]; } export interface WorkflowGraphNode { id: string; kind: 'input' | 'agent' | 'tool' | 'http' | 'media' | 'browser' | 'transform' | 'condition' | 'loop' | 'merge' | 'human' | 'deliver'; label: string; position: { x: number; y: number; }; config: Record; note?: string; } export interface WorkflowGraphEdge { id: string; source: string; target: string; sourceHandle?: string; targetHandle?: string; } export interface WorkflowGraph { nodes: WorkflowGraphNode[]; edges: WorkflowGraphEdge[]; viewport?: { x: number; y: number; zoom: number; }; } /** One node the engine wants the bridge to execute. */ export interface WorkflowNodeTask { nodeId: string; kind: string; label: string; config: Record; } /** * The verdict from `GET /workflows/runs/:id/next-node` (and from the * `complete` call): `bridge` = execute the node; `waiting` = a human gate the * worker should exit on; `done`/`failed` = terminal. */ export type WorkflowAdvance = { state: 'bridge'; node: WorkflowNodeTask; } | { state: 'waiting'; nodeId: string; question: string; } | { state: 'done'; status: string; } | { state: 'failed'; error?: string; }; export interface WorkflowNodeArtifact { name: string; mime: string; dataBase64: string; } export interface BlogGenerationContext { id: string; kind: 'generate' | 'refine'; topic: string; instruction: string | null; tone: string | null; length: string | null; status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'; post: { id: string; title: string; excerpt: string | null; content: string; tags: string[]; slug: string; } | null; } export interface ToolRun { id: string; projectId: string; toolKey: string; execution: string; status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'; params?: Record | null; agentId?: string | null; createdBy: string; outputDocumentIds: string[]; chainedFromId?: string | null; log?: Array<{ stream: string; text: string; at: string; }> | null; errorSummary?: string | null; durationMs?: number | null; costCents?: number | null; /** Tools-as-tasks: task kind / tool key / back-link + live progress. */ kind?: string | null; taskId?: string | null; progress?: Record | null; /** Originating recurring schedule id, when run by the scheduler. */ scheduleId?: string | null; /** Typed Tool Task spec snapshot (joined from the backing task). */ spec?: ToolTaskSpec | null; /** Backing task title (joined server-side). */ taskTitle?: string | null; /** Live task progress mirrored from the backing task. */ toolProgress?: Record | null; startedAt: string; endedAt?: string | null; createdAt: string; updatedAt: string; } /** Declared column in a data-collection contract. */ export interface ToolColumnSpec { key: string; label: string; type: 'string' | 'number' | 'date' | 'url' | 'email' | 'boolean'; required?: boolean; citationRequired?: boolean; example?: string; } /** Frozen spec snapshot attached to a tool run (from the backing task). */ export interface ToolTaskSpec { toolKey: string; toolTitle: string; /** Short Subject for deliverable file names (task title minus tool prefix). */ baseName?: string; execution: string; kind: 'tool' | 'research'; /** * Tool category ('document' | 'data' | 'chart' | 'images' | 'research' | * 'board' | 'browser'…). Decides WHERE deliverables go (2026-10): research * tools write under the per-task `research/` folder, every other tool into * its declared output-contract folders. Absent on specs frozen before the * field existed — those keep the old behaviour. */ category?: string; recipe: { id: string; version: number; steps: string[]; }; outputContract: { folders: string[]; documents: Array<{ type: string; name: string; label?: string; required?: boolean; }>; manifest: boolean; }; columns: ToolColumnSpec[]; requiredCapabilities: string[]; requiredMcpTools: string[]; /** Outreach delivery: recipients are read from these deliverable columns. */ supportsEmailDelivery?: boolean; emailRecipientColumns?: string[]; emailNameColumns?: string[]; /** * The run form's answers (2026-10), composed backend-side with human labels. * Rendered as the `## Inputs` block — before this existed the prompt carried * only a fixed allow-list of param keys, so a CV run was authored without the * candidate's name, experience or chosen template. */ inputs?: Array<{ key: string; label: string; value: string; }>; /** * Composed style guidance (2026-10) — currently the CV template style guide: * the chosen template, its section order and the markdown format contract. * Rendered as the `## Style guide` block. */ styleGuide?: string; /** * The anti-AI-tell writing rules (2026-10), frozen into the spec by the * backend. Rendered as a `## Writing style` block. Older specs (created * before the field existed) fall back to the bridge's own copy. */ writingStyle?: string; capabilityCheck: { ok: boolean; missing: string[]; reason: string | null; }; specVersion: number; createdAt: string; } /** * One compact similarity hit from `/search/similar|related/*` (pg_trgm). * No content — fetch it with read_document / get_task. */ export interface SimilarRow { kind: 'task' | 'document'; id: string; title: string; /** 0-1 pg_trgm score. */ score: number; status?: string; folderPath?: string | null; createdAt: string; } export interface Task { id: string; title: string; description?: string | null; status: string; priority: string; projectId: string; assigneeId?: string | null; dueDate?: string | null; tags?: string[]; readyForDev?: boolean; sortOrder?: number; /** Plan mode: acceptance criteria (markdown), maintained by the planner. */ acceptanceCriteria?: string | null; /** Nested sub-task of a plan task (orchestrator planning). */ parentTaskId?: string | null; /** * Combined runs (2026-09): non-null = THIS task is folded into the combined * run named by the id (only ever set on members; a combined task itself has * `combinedMembers` instead). */ combinedIntoId?: string | null; /** * Combined runs: on the combined (group) task — every member it covers, with * full detail so a working session never has to guess what is in its run. */ combinedMembers?: Array<{ id: string; title: string; description?: string | null; acceptanceCriteria?: string | null; status: string; priority: string; readyForDev?: boolean; }>; workMode?: 'plan' | 'build'; /** * Delivery naming (2026-12): the branch this task's work ACTUALLY lives on. * Set by the hub after a guarded rename to a name the agent proposed, and the * only branch authority a retry reads - without it a retry would derive a * clean branch and re-implement the delivered work. */ deliveryBranch?: string | null; /** * The agent's proposed delivery naming (commit message, PR title/body, * optional branch). `status` is `pending` while the pipeline may still use it; * `applied`/`refused` once a delivery reported back. */ gitNaming?: { branchName?: string | null; commitSubject?: string | null; commitBody?: string | null; prTitle?: string | null; prBody?: string | null; status?: string; statusReason?: string | null; updatedAt?: string; appliedAt?: string | null; } | null; /** * Figma design references attached to the task (2026-12): context for a * normal task, verification baselines for a QA task. Each carries the human * note, frame identity and a stored preview document id. */ designs?: Array<{ id: string; label: string; purpose: 'verification' | 'reference'; description?: string | null; sourceUrl: string; fileKey: string; nodeId: string; nodeName?: string | null; baselineStatus?: string; baselineDocumentId?: string | null; thumbnailDocumentId?: string | null; metaSummary?: { nodeType?: string; layoutMode?: string | null; width?: number | null; height?: number | null; colors?: string[]; fonts?: Array<{ family: string; weight: number; }>; textNodes?: number; componentName?: string | null; /** Full-layer JSON spec document written at capture time. */ specDocumentId?: string | null; } | null; }>; /** * Exclusive claim held by an agent working this task. `claimExpiresAt` is the * lease end - an EXPIRED claim is not held (2026-08-26 incident: a stale lease * made every other agent treat the task as taken and refuse it). */ claimedById?: string | null; claimExpiresAt?: string | null; /** Plan-run tracking (2026-09): definitive planned marker + run count. */ plannedAt?: string | null; planRunCount?: number; planLastRunAt?: string | null; planLastError?: string | null; /** * QA test brief (2026-10): first-class fields for automated QA testing. * All null when the task has no brief. Older tasks may still carry a * `## QA test brief` markdown section inside `description` instead. */ qaWebsite?: string | null; qaWhatToTest?: string | null; qaSteps?: string | null; qaExpectation?: string | null; /** Typed Tool Task fields (kind = tool|research). */ kind?: 'code' | 'tool' | 'research' | 'workflow'; toolKey?: string | null; toolParams?: Record | null; toolSpec?: ToolTaskSpec | null; toolProgress?: Record | null; toolRunId?: string | null; /** Custom workflows (2026-10): the WorkflowRun id (kind = 'workflow'). */ workflowRunId?: string | null; createdAt: string; updatedAt?: string; project?: { id: string; name: string; /** Project-wide base branch (2026-12); null = the linked folder's branch. */ gitBaseBranch?: string | null; } | null; comments?: Comment[]; } export interface TaskDocument { id: string; name: string; type: string; folderPath?: string | null; mime?: string | null; size?: number | null; createdAt: string; uploader?: { id: string; name: string; avatarUrl?: string | null; } | null; } /** * A file uploaded directly to a task or one of its comments (the separate * attachment system - distinct from project documents). */ export interface TaskAttachment { id: string; taskId?: string | null; commentId?: string | null; fileKey?: string; url?: string | null; name: string; mime: string | null; sizeBytes?: number | null; target?: 'task' | 'comment'; uploadedBy?: string; createdAt: string; uploader?: { id: string; name: string; avatarUrl?: string | null; kind?: string; } | null; } export interface Comment { id: string; taskId?: string | null; documentId?: string | null; whiteboardId?: string | null; workflowId?: string | null; /** Parent comment id when this comment is a threaded reply (2026-11). */ parentId?: string | null; body: string; author?: { id: string; name: string; kind?: string; } | null; authorId?: string; createdAt: string; } export interface ChecklistItemRow { id: string; title: string; done: boolean; sortOrder?: number; } export interface SubtaskNode { id: string; taskId: string; parentId?: string | null; title: string; done: boolean; assigneeId?: string | null; dueDate?: string | null; sortOrder: number; createdBy: string; createdAt: string; updatedAt: string; assignee?: { id: string; name: string; kind?: string; } | null; creator?: { id: string; name: string; kind?: string; } | null; children?: SubtaskNode[]; checklistItems?: ChecklistItemRow[]; } export interface Document { id: string; projectId: string; type: 'link' | 'file' | 'note'; urlOrKey: string; name: string; mime?: string | null; /** Virtual folder path (IMP-601); "/" is the root. */ folderPath?: string; createdAt: string; } /** One node of the virtual folder tree (IMP-601). */ export interface DocumentFolderNode { path: string; name: string; children: DocumentFolderNode[]; documentCount: number; } /** * A deterministic file-processing job for the document editing pipeline * (2026-09). The bridge claims it, converts with LibreOffice WASM, uploads the * result and completes it - no model calls anywhere. */ export interface DocumentJob { id: string; documentId: string; projectId: string; kind: 'docx_to_html' | 'html_to_docx' | 'text_commit' | 'sheet_commit' | 'export'; purpose: 'prepare' | 'commit' | 'download'; status: 'queued' | 'claimed' | 'processing' | 'succeeded' | 'failed' | 'superseded' | 'cancelled'; targetFormat?: string | null; sourceFormat?: string | null; baseVersionNumber?: number | null; attempts: number; error?: string | null; /** Only present on the claim response - the converter's full input. */ payload?: { sourceUrl?: string | null; sourceMime?: string | null; fileName?: string | null; html?: string; targetFormat?: string; [key: string]: unknown; }; } /** Build-mode queue snapshot (IMP-700): strict order + blocked + agent. */ export interface BuildQueue { project: { id: string; name: string; }; buildAgent: { id: string; name: string; status: string; } | null; pending: Array<{ position: number; task: Task; }>; blocked: Array<{ task: Task; question: { commentId: string; body: string; askedBy: { id: string; name: string; }; askedAt: string; }; }>; /** Orchestrator flow config per task (model + escalation + verification + worktree). */ flows?: Record; } export interface BuildProgressBody { projectId: string; status: 'running' | 'finished' | 'stopped' | 'blocked'; total: number; done: number; remaining: number; currentTaskId?: string; currentTitle?: string; skippedTaskId?: string; } export interface OrchestratorWorkItem { orchestratorTaskId: string; taskId: string | null; title: string; description: string | null; projectId: string; worktreePath: string | null; branchName: string | null; /** chainMode: previous completed group task's branch to build on. */ baseBranch: string | null; integrationBranch: string | null; preferredModel: string | null; verificationSteps: string[]; attemptCount: number; maxAttempts: number; localMode: boolean; } /** A durable "@agent, please answer" record (2026-09). */ export interface AgentMention { id: string; projectId: string; kind: 'chat' | 'comment' | 'document' | 'board'; /** Chat message id, or comment id - the deterministic target. */ targetId: string; channelId: string | null; body: string; mention: string | null; authorId: string; /** A session STARTED working it; null = nobody is on it. */ triggeredAt: string | null; /** The reply was delivered - closed for good. */ answeredAt: string | null; answerMessageId: string | null; createdAt: string; }