/** Canonical UUID shape - a run session requires a real task id. */ export declare const UUID_RE: RegExp; /** * Wake dedupe (usage guard): the same wake (task/chat-message/document) * is only spawned once per cooldown window. Re-sync re-wakes on every * reconnect used to respawn the same task endlessly - each respawn burns * a full harness context. 60s is enough to prevent reconnect storms while * the agent lock + server-side claim guard already prevent double work. */ export declare const WAKE_COOLDOWN_MS: number; export declare const TASK_WAKE_COOLDOWN_MS: number; /** Stable dedupe key for a wake event (null = nothing to dedupe). */ export declare function wakeDedupeKey(event: WakeEvent): string | null; /** * In-flight wake marker key (2026-09): the same wake handed to `handleWake` * twice while the first copy is still resolving its task/folder must never * spawn twice. `wakeDedupeKey` alone misses this window - its cooldown stamp * lands only AFTER a spawn (and never at all for plan-branch spawns), and the * server-side `recordProcessed` marker is written after the spawn too, so a * stranded-sweep/WS pair arriving seconds apart both looked "unprocessed". * * Rule: any task-scoped event collapses to `task:` (the same identity * the sweep and cooldown already use); other events fall back to * `wakeDedupeKey`, and events with neither get no marker (nothing to race on). */ export declare function wakeInFlightKey(event: WakeEvent): string | null; /** * Shared task-scoped routing gate (2026-09): decides whether a wake must run * a PLANNING pass instead of the executing run session. Used by `spawnWake` * for `task.assigned`, `task.run` and task-comment `comment.mention`, so all * delivery paths (live WS, inbox poll, reconnect re-sync, busy-lock flush) * take the SAME decision from a freshly fetched task. * * Returns `'plan'` when the wake must spawn `teamshare-agent plan`, else null * (caller falls through to its existing behaviour). */ export declare function planModeRoute(event: { type: string; role?: string; orchestratorTaskId?: string; }, task: { kind?: string | null; workMode?: string | null; }): 'plan' | null; export interface WakeEvent { type: 'task.assigned' | 'task.run' | 'comment.mention' | 'chat.mention' | 'document.mention' | 'document.edit_request' | 'board.mention' | 'build.trigger' | 'build.stop' | 'question.answered' | 'question.expired' | 'plan.trigger' | 'tool.trigger' | 'tool.stop' | 'document.job' | 'blog.generate' | 'insight.narrate' | 'workflow.run' | 'workflow.mention' /** Manual interrupt (2026-08): kill the live harness for this agent. */ | 'session.stop'; taskId?: string; projectId?: string; /** * Chat channel scope (2026-10, chat.mention). The hub sends it on every chat * wake; the daemon forwards it to the chat session (`--channel`) so reads * and replies stay in the waking channel instead of defaulting to General. * Absent on wakes from an older hub - the session then runs unscoped, which * is exactly today's behaviour. */ channelId?: string; worktreePath?: string; /** * BRANCH CONTINUATION (2026-11-08): the branch this run must START from, * resolved by the hub from the plan (`unit.planContinuesFrom` → the previous * unit's `runBranch`). The isolation mirror bases on it, so a later stage * actually contains the code an earlier stage produced. Absent = the normal * derivation (task's own branch, then the project base). */ baseBranch?: string; documentId?: string; commentId?: string; messageId?: string; mention?: string; /** * AgentMention id (2026-09): the hub's deterministic record of "this agent was * asked". The daemon CLAIMS it before spawning, so a replayed wake cannot * start a second session on an already-answered question; the session CLOSES * it once its reply is delivered. */ mentionId?: string | null; /** Whiteboard id (board.mention). */ whiteboardId?: string; /** Workflow definition id (workflow.mention). */ workflowId?: string; /** ToolRun id / registry key (tool.trigger / tool.stop). */ runId?: string; toolKey?: string; /** DocumentJob id (document.job). */ jobId?: string; /** BlogGeneration id (blog.generate) - the run to author. */ blogGenerationId?: string; /** BlogPost id the generation writes into (blog.generate). */ blogPostId?: string; /** InsightNarrativeRun id (insight.narrate) - the run to narrate. */ insightRunId?: string; /** WorkflowRun id (workflow.run) - the run to execute. */ workflowRunId?: string; /** * Execution surface for this run (workflow.run): 'folder' (the linked * folder) | 'mirror' (an isolated worktree + branch + PR). Set by the hub * from Workflow.isolation; `preflightWake` routes `needsMirror` on it. */ isolation?: 'folder' | 'mirror'; by?: { id: string; name: string; }; /** * Manual trigger (2026-10): a HUMAN authored this wake (assigned the planner / * pressed Start build). Manual wakes bypass the automated-plan gate and are * the only thing that clears a sticky build stop. */ manual?: boolean; /** Present when the question was on an orchestrator-managed task. */ orchestratorTaskId?: string; /** * AgentQuestion id (question.answered / question.expired). The hub has always * sent it; the bridge type simply never declared it, so the only ids a * question resume had to log were the task and the answer comment. */ questionId?: string; /** IMP-810: 'worker' when the wake targets a multi-agent orchestrator subtask. */ role?: 'worker'; /** True when resuming a paused task - bypasses the wake cooldown. */ resume?: boolean; /** Internal retry counter for a re-enqueued wake that failed to spawn. */ _retryCount?: number; /** AI edit request metadata (document.edit_request only). */ editRequest?: { instruction: string; pageNumber?: number; quote: string; }; /** * Entity references attached to the chat message that woke us * (`#[task|doc|board:uuid:Label]` in the body). Sent by `chat.gateway` on * the WS wake; the inbox/re-sync paths rebuild the same shape from the * stored message body. A `type:'task'` entry turns the chat session into a * task-linked session (own branch + the standard git flow). */ references?: ChatReference[]; } /** One `#[type:id:label]` entity reference from a chat message. */ export interface ChatReference { type: 'task' | 'doc' | 'board'; id: string; label?: string; title?: string; } /** * Rebuild `references` from a raw chat message body. The inbox poll and the * reconnect re-sync only carry the stored message (the backend does not * duplicate `references` on `/agents/:id/inbox`), so the same structured * tokens the composer wrote are parsed here - identical to what * `chat.gateway.resolveChatReferences` resolves for the WS wake. */ export declare function chatReferencesFromBody(body: unknown): ChatReference[]; /** * Task id behind a `chat.mention` wake: the wake's `references[].type==='task'` * (WS payload or body rebuild) wins, a directly-set `event.taskId` is the * fallback. Returns undefined for a non-task chat mention - those keep the * legacy behavior (no branch, no stash, no commit). */ export declare function chatMentionTaskId(event: WakeEvent): string | undefined; /** * What happened to a wake handed to {@link handleWake}. Poll/resync callers * use this to decide whether to persist the processed-wake marker: * 'queued'/'deferred' wakes were NOT run and must stay unmarked so the next * pass retries them (previously they were marked done and silently dropped). * 'blocked' means the folder guard refused the session - it MUST also stay * unmarked so stranded-task sweeps retry once the user links a folder * (previously a blocked task.assigned was recorded as done forever). */ export type WakeOutcome = 'spawned' | 'queued' | 'deferred' | 'skipped' | 'blocked'; /** * Which session a wake will start. Decided BEFORE isolation so a wake that * cannot spawn never builds a mirror (2026-09 - see {@link preflightWake}). */ export type WakeKind = 'plan' | 'tool' | 'doc' | 'board' | 'build' | 'chat' | 'blog' | 'insight' | 'workflow' | 'workflow-author' | 'code' | 'stop' | 'none'; export interface PreflightInput { event: WakeEvent; /** Freshly fetched task for task-scoped wakes (null when not fetched). */ task?: { id?: string; kind?: string | null; /** * `task.type` — `qa` is run-only (2026-10) and must never spawn a plan or * code session. `kind` alone is not enough: a fresh QA task is `kind=tool` * with no `toolRunId` yet, which is exactly the shape that used to fall * through to a code session. */ type?: string | null; workMode?: string | null; planRunCount?: unknown; toolRunId?: string | null; /** * Frozen per-kind snapshot (the task's toolSpec column): workflow tasks * carry `{ workflowRunId, isolation }`. Typed `unknown` because each * kind freezes a different shape - read it via {@link workflowSpecOf}. */ toolSpec?: unknown; } | null; /** `hasHarnessSession(agentId, taskId, 'plan')` - the twin-spawn race guard. */ hasLocalPlanSession?: boolean; /** `hasHarnessSession(agentId, taskId, 'run')`. */ hasLocalRunSession?: boolean; /** `hasHarnessSession(agentId, taskId, 'build')`. */ hasLocalBuildSession?: boolean; /** `hasHarnessSession(agentId, generationId, 'blog')`. */ hasLocalBlogSession?: boolean; /** A build state file exists for this agent+project. */ hasBuildState?: boolean; /** Plain read-only chat mention (no `#task:` reference). */ plainChat?: boolean; } /** * The frozen workflow snapshot on a kind='workflow' task (the task's * toolSpec column, written by the hub at run creation). Read defensively: * a task from an older hub has no snapshot at all. */ export declare function workflowSpecOf(task: PreflightInput['task']): { workflowRunId: string | null; isolation: string | null; } | null; export interface PreflightResult { outcome: 'spawn' | 'skip' | 'stop'; kind: WakeKind; /** True when the session must work in a private mirror, not the linked folder. */ needsMirror: boolean; /** Why the wake is skipped (logged verbatim) - only for outcome 'skip'. */ reason?: string; /** Extra context for the skip log (planRuns=N etc). */ detail?: string; } /** * DECIDE, THEN BUILD (2026-09). * * `spawnWake` used to create the isolation mirror FIRST and validate/route * afterwards, so every `return 'skipped'` below the mirror block leaked 5 * worktrees until the sweeper noticed hours later. A live case: a duplicate * `task.assigned` wake built a full mirror, then the automated-plan gate said * "already-planned" and returned skipped - 45 MB of worktree for nothing. * * This hoists every decision that can end a wake without a session ABOVE the * mirror block. It relocates existing decisions only - it introduces no new * skip reason, so it can never strand work that would previously have run. * Deliberately NOT hoisted: the folder-serialization gate, which must keep * running on the EFFECTIVE cwd (a successful mirror has no presence, so the * gate stays a no-op for isolated runs and only guards the degraded path). */ export declare function preflightWake(input: PreflightInput): PreflightResult;