/** * Typed REST client for the TeamShare API (contract: docs/agent-tasks/ * agent-hub-connection.md). Envelope-aware, retrying, timeout-bound. * * Split (1200-line-per-file rule): transport lives in api-core.ts, DTOs in * api-types.ts and the endpoint groups in api-agents.ts / api-tasks.ts / * api-content.ts; this file keeps the TeamshareApi class itself. */ import { AgentConfig } from './config'; import { ContentEndpoints } from './api-content'; import type { BlogGenerationContext, BuildQueue, Document, OrchestratorWorkItem, ToolRun } from './api-types'; export { ApiError, DEFAULT_API_URL, DEFAULT_WS_URL } from './api-core'; export * from './api-types'; export declare class TeamshareApi extends ContentEndpoints { /** Reuses a config agent's credentials. Resolves key from secret store. */ static forAgent(baseUrl: string, agent: AgentConfig): TeamshareApi; /** * Everything a `blog.generate` session needs in one call: the brief, plus the * post's CURRENT title/excerpt/content/tags. * * The current content is what makes a REFINE run safe - the agent rewrites * what the human actually has on the page, not what it last produced, so * manual edits survive the rewrite. Agent-key auth (scope `blog:write`). */ getBlogGeneration(generationId: string): Promise; /** * Streams progress for the web's generation panel. The first call is what * flips the run from `pending` to `running` on the hub, so a replayed wake * cannot resurrect a generation a human cancelled. * * Best-effort by design: a failed progress call must never fail the run, so * every caller wraps this in `.catch(() => undefined)`. */ reportBlogGenerationProgress(generationId: string, lines: Array<{ stream: string; text: string; }>, extra?: { phase?: string; sessionId?: string; model?: string; }): Promise<{ accepted: boolean; status: string; }>; /** * Delivers the finished post. The hub writes it into the DRAFT - status and * author are untouched, so a generated post is always a draft until a human * submits it. `ok: false` settles the run as failed and leaves the draft * exactly as it was. * * Markdown is already final: charts were rendered locally by * `lib/blog/charts.ts`, so the hub stores plain markdown. */ completeBlogGeneration(generationId: string, body: { ok: boolean; title?: string; excerpt?: string; content?: string; tags?: string[]; model?: string; sessionId?: string; error?: string; }): Promise<{ applied: boolean; status: string; postId: string | null; }>; /** * Everything an `insight.narrate` session needs in one call: scope, kind * and the frozen deterministic facts to narrate. Agent-key auth (scope * `insight:write`). No server-side provider key is involved. */ getInsightRun(runId: string): Promise; /** * Streams progress for the run. The first call flips the run from `pending` * to `running` on the hub. Best-effort: never fails the run. */ reportInsightProgress(runId: string, lines: Array<{ stream: string; text: string; }>, extra?: { phase?: string; sessionId?: string; model?: string; }): Promise<{ accepted: boolean; status: string; }>; /** * Delivers the finished narrative. The hub validates it, writes the * insights aiCache and a zero-cost usage row. `ok: false` settles as failed. */ completeInsightRun(runId: string, body: { ok: boolean; narrative?: { summary: string; risks?: string[]; recommendations?: Array<{ title: string; detail: string; impact: 'high' | 'medium' | 'low'; }>; } | null; model?: string; sessionId?: string; error?: string; }): Promise<{ applied: boolean; status: string; }>; /** * Everything a `workflow.run` session needs in one call: frozen * definition, resolved inputs, step list with live statuses and * credential KEYS (never values). Agent-key auth (scope * `workflows:write`). */ getWorkflowRun(runId: string): Promise; /** * Streams progress for the run. The first call flips the run from `pending` * to `running` on the hub. Best-effort: never fails the run. */ reportWorkflowProgress(runId: string, lines: Array<{ stream: string; text: string; }>, extra?: { phase?: string; stepIndex?: number; sessionId?: string; model?: string; }): Promise<{ accepted: boolean; status: string; }>; /** * Advances one step on the run timeline. Terminal runs refuse. * Best-effort: never fails the run. */ reportWorkflowStep(runId: string, body: { stepIndex: number; status: string; note?: string; }): Promise<{ accepted: boolean; status: string; }>; /** * Delivers the finished run. The hub settles completed/failed, moves the * backing task, links output documents and notifies the creator. * `ok: false` settles as failed. */ completeWorkflowRun(runId: string, body: { ok: boolean; summary?: string; error?: string; outputDocumentIds?: string[]; model?: string; sessionId?: string; }): Promise<{ applied: boolean; status: string; }>; /** * Decrypts the packed per-run env-var values. ONLY the run's own agent may * call this; the hub refuses terminal runs. Never logged. */ getWorkflowSecrets(runId: string): Promise<{ secrets: Record; keys: string[]; }>; /** * The next node an ADVANCED run wants executed (the worker's work loop). * Returns `{ state: 'bridge', node }`, `{ state: 'waiting' }` or a terminal * verdict. Agent-key auth (scope `workflows:write`). */ getNextWorkflowNode(runId: string): Promise; /** * Reports an ADVANCED node's outcome; the hub persists artifacts, advances * the graph and returns the next node (or a terminal/waiting verdict). */ completeWorkflowNode(runId: string, nodeId: string, body: { ok: boolean; output?: unknown; error?: string; artifacts?: Array<{ name: string; mime: string; dataBase64: string; }>; log?: Array<{ stream: string; text: string; }>; }): Promise; /** * The build queue of a project: pending ready-for-dev tasks in strict * order (sortOrder asc, createdAt asc), blocked tasks awaiting an answer * to an agent question, and the build agent (agentId + status). */ getBuildQueue(projectId: string): Promise; /** * Progress of the build run on this machine. Mirrors the whole run onto * the backend (bridge state kind 'build' + AgentLog transitions) so the * frontend can render live status from any device (IMP-630 pattern). */ pushBuildProgress(agentId: string, body: { projectId: string; status: 'running' | 'finished' | 'stopped' | 'blocked'; total: number; done: number; remaining: number; currentTaskId?: string; currentTitle?: string; skippedTaskId?: string; }): Promise<{ ok: true; }>; /** * The task's OPEN agent question, or null when answered/none (thread + * #agent-questions channel aware). The build loop polls this to detect * answered questions and resume skipped build tasks (IMP-700). */ getTaskQuestions(taskId: string): Promise<{ open: { commentId: string; body: string; askedBy: { id: string; name: string; }; askedAt: string; } | null; }>; getOrchestratorWork(agentId: string): Promise; mergeOrchestratorTask(otId: string): Promise<{ success: boolean; conflictFiles?: string[]; }>; /** IMP-919: worker self-report - this run died without completing the task. */ reportOrchestratorWorkerFailed(otId: string, reason: string): Promise<{ ok: boolean; status: string; }>; /** * Claim the orchestrator task behind a source Task (stranded sweep). * `{ blocked: "group_sequencing" }` = an earlier sibling of a sequential * group holds the turn; `{ blocked: "parent_planning" }` = the batch's * planner has not finished deciding this batch's units yet. Both mean the * same thing to the caller — do NOT wake, retry on a later poll cycle. */ claimOrchestratorBySourceTask(sourceTaskId: string): Promise<{ otId: string; } | { blocked: 'group_sequencing' | 'parent_planning'; } | null>; listToolCatalog(): Promise<{ tools: Array<{ key: string; title: string; description: string; category: string; outputs: string[]; estSeconds: number; }>; }>; createToolRun(projectId: string, toolKey: string, params: Record): Promise; getToolRun(runId: string): Promise; /** * Lightweight status probe (2026-11). The research/auto-answer runner polls * this every few seconds to detect cancellation; fetching the full run pulled * the whole log each time, which is exactly the egress this endpoint exists * to avoid. */ getToolRunStatus(runId: string): Promise<{ id: string; status: string; endedAt: string | null; errorSummary: string | null; logCursor: number; }>; /** * Per-run ephemeral secrets (browser auto-answer): the browser agent key + * optional provider key / base URL supplied on the run form. Agent-key auth * only; returns null when none were provided or they expired. */ getToolRunSecrets(runId: string): Promise<{ browserKey: string | null; providerKey: string | null; provider: string | null; baseUrl: string | null; /** QA-login credentials (browser-agent), when supplied on the run form. */ username: string | null; password: string | null; /** Named test accounts for this run (2026-11): decrypted for the run's agent only. */ actors?: Array<{ label: string; labelKey?: string; role?: string | null; username?: string | null; password?: string | null; email?: string | null; hasMailbox?: boolean; isPrimary?: boolean; }> | null; expiresAt: string; } | null>; /** Validate a superadmin-issued browser agent key before a browse session. */ validateBrowserAgentKey(key: string): Promise<{ valid: boolean; user: { id: string; name: string | null; email: string | null; }; agent: { id: string; userId: string; }; label: string; remainingUses: number | null; expiresAt: string | null; }>; listToolRuns(projectId: string, page?: number, pageSize?: number): Promise; cancelToolRun(runId: string): Promise<{ cancelled: boolean; }>; appendToolLog(runId: string, lines: Array<{ stream: string; text: string; }>, progress?: Record): Promise<{ ok: boolean; }>; uploadToolOutput(runId: string, fileBuffer: Buffer, fileName: string, mime: string): Promise; /** * Marks an agent-driven (harness/self) tool run terminal — or PAUSED when the * harness stopped to ask a human. `completed` moves the backing task to * in_review; `paused` keeps it in_progress so the answer can resume the run. */ completeToolRun(runId: string, body: { status?: 'completed' | 'failed' | 'paused'; progress?: Record; errorSummary?: string; /** The agent this machine actually ran as (the bridge's --agent flag). */ executorAgentId?: string; /** This machine's id, for history and future routing. */ executorMachineId?: string; }): Promise; plannerComplete(body: { planTaskId: string; mode: string; tasks: unknown[]; orderedTaskIds: string[]; dependencies: unknown[]; /** Overview mode: planner-decided combined-run grouping (partition). */ groups?: Array<{ name?: string; taskIds: string[]; mode?: 'combined' | 'parallel'; dependsOn?: string[]; workers?: number; }>; /** Overview mode: the planner's ordered barrier plan (2026-11). */ stages?: Array<{ key?: string; name?: string; groups: Array<{ key?: string; name?: string; taskIds: string[]; mode?: 'combined' | 'parallel'; workerAgentId?: string; workerHint?: string; workers?: number; }>; maxWorkers?: number; failurePolicy?: 'halt' | 'continue'; }>; /** Extra edges beyond the stage barrier (earlier group → later group). */ edges?: Array<{ fromGroup: string; toGroup: string; }>; planMarkdown?: string; acceptanceCriteria?: string; planSummary?: string; planTitle?: string; }): Promise<{ delivered: boolean; }>; }