/** * WAKE LANES (2026-10) - MIRROR of the backend file. Do not diverge. * * Canonical source: `teamshare-backend/src/modules/agent-runtime/wake-lanes.ts` * * This file is a byte-for-byte copy apart from this header, and * `teamshare-bridge/tests/wake-lane-parity.test.mjs` asserts the two agree. They * live in different repositories, so nothing but that test stops them drifting. * * WHY THE MIRROR IS LOAD-BEARING: the bridge used to dedupe its restored offline * queue on `wakeDedupeKey`, which returns `null` for `comment.mention`, * `board.mention`, `tool.trigger`, `tool.stop` and `build.stop`. Two `null`s * compared EQUAL, so every queued wake of those types collapsed into one on * daemon restart - three commands in, one out, with no error anywhere. */ /** How many coalesced triggers `triggerMeta` keeps. Oldest-first, then trimmed. */ export declare const TRIGGER_META_MAX = 20; /** * How many ids a coalesced payload's `mentionIds` / `commentIds` keep. * * A separate cap from {@link TRIGGER_META_MAX} because they answer different * questions: `triggerMeta` is the AUDIT ("how many triggers, and roughly when"), * while these lists are the WORK ("exactly which comments must I answer?"). The * audit may be trimmed aggressively; the work list may not, because every id * dropped from it is a human request the agent will never read. */ export declare const PAYLOAD_ID_LIST_MAX = 20; /** * Drain priority, highest first. * * The old drain was `createdAt ASC, take 20`, which is a starvation bug: a * `session.stop` issued to an offline agent sat behind every stale chat mention * ever queued for it and could simply never be delivered inside the cap. */ export declare const WAKE_PRIORITY: { /** A human pressed "Stop work". Never starve these. */ readonly STOP: 100; /** A human pressed "Run task", or @mentioned an idle agent. */ readonly HUMAN: 50; /** `question.answered` / `question.expired` - a paused run is waiting on this. */ readonly RESUME: 40; /** A deterministic, uniquely-identified job: tool run, blog post, document job. */ readonly JOB: 30; /** Someone addressed the agent in a thread: chat, document, board. */ readonly MESSAGE: 20; /** `build.trigger` - idempotent, cheapest to lose a count on. */ readonly BUILD: 10; }; /** * The event fields a lane can be derived from, structurally typed so the bridge * can mirror this file against its own `WakeEvent` without importing backend * types (and so a payload that survived a JSON round-trip still typechecks). */ export interface WakeLaneInput { type: string; taskId?: string | null; documentId?: string | null; whiteboardId?: string | null; channelId?: string | null; messageId?: string | null; commentId?: string | null; mentionId?: string | null; insightRunId?: string | null; /** The exact @token that matched the agent (chat/comment/board mentions). */ mention?: string | null; /** * Every mention folded into this payload by coalescing, oldest first. * * Added 2026-10: a lane holds ONE payload, and the payload used to be * REPLACED wholesale on coalesce. A `task.run` (which carries no mention at * all) therefore erased the `commentId`/`mentionId` of a human @mention queued * moments earlier on the same task lane, and the delivered wake was "run this * task" with the request gone. This list is what survives instead. */ mentionIds?: string[] | null; /** Same, for the underlying comments. */ commentIds?: string[] | null; runId?: string | null; jobId?: string | null; blogGenerationId?: string | null; /** WorkflowRun id (workflow.run) - one lane per run, never coalesced. */ workflowRunId?: string | null; /** Workflow DEFINITION id (workflow.mention) - the authoring conversation. */ workflowId?: string | null; orchestratorTaskId?: string | null; projectId?: string | null; /** Who triggered it, for `triggerMeta`. */ by?: { id: string; name: string; } | null; } /** A workflow-definition lane (authoring conversation, not a run). */ export declare function workflowDefLane(workflowId: string): string; /** * Derive the coalescing lane for a wake. Returns `null` only when the event * carries no identity at all, in which case the caller must NOT coalesce (two * identity-less wakes are indistinguishable, and dropping one would lose real * work - the old code's `identityFilter` returned null here and then deduped on * type alone, which is how a second `build.trigger` could erase a first). */ export declare function wakeLane(event: WakeLaneInput): string | null; /** * The lane a LIVE session occupies, so a mention on the work already in flight * can be routed to an INSTRUCTION instead of a wake. * * A session is one of: a task run, a build loop, a plan pass, a chat reply, a * doc/board reply, or a blog generation. Return the lane in the SAME vocabulary * as {@link wakeLane} or the comparison silently never matches. */ export declare function laneOfLiveSession(session: { mode?: string | null; taskId?: string | null; projectId?: string | null; channelId?: string | null; documentId?: string | null; whiteboardId?: string | null; jobId?: string | null; blogGenerationId?: string | null; insightRunId?: string | null; workflowId?: string | null; } | null): string | null; /** Drain priority for a lane. Unknown lanes get the human band - never lowest. */ export declare function wakePriority(lane: string, eventType?: string): number; /** One entry of `PendingWake.triggerMeta`. */ export interface WakeTriggerMeta { type: string; /** The most specific identity on the trigger, for a human to act on. */ entityId?: string | null; /** * The SPECIFIC ids, when the trigger carried any. * * `entityId` deliberately stays `taskId` for a task-scoped trigger, because it * must agree with the lane (see {@link wakeTriggerMeta}). But that made the * audit useless for exactly the case that needed it: a `comment.mention` and a * `task.run` on one task both logged `entityId = `, so the * `wake_coalesced` row proved a trigger had been folded in and never said * WHICH comment. These two fields close that, additively - nothing reads * `entityId`, so nothing can disagree with the lane. */ commentId?: string | null; mentionId?: string | null; at: string; by?: { id: string; name: string; } | null; } /** * Summarize a trigger for `triggerMeta`. * * `entityId` picks the SAME identity `wakeLane` prefers, so the log reads * consistently with the lane ("2 more mentions on task X") rather than showing * an unrelated field. */ export declare function wakeTriggerMeta(event: WakeLaneInput, now?: Date): WakeTriggerMeta; /** * Append a trigger to a `triggerMeta` list, capped. * * Capped rather than counted alone because "3 mentions happened" only tells a * human something if they can see WHICH three. When the cap is exceeded the * OLDEST entries go, and the count on the row is what tells you how many were * dropped from the list. */ export declare function appendTriggerMeta(existing: unknown, incoming: WakeTriggerMeta, max?: number): WakeTriggerMeta[]; /** True when two wakes are the same lane and may coalesce. */ export declare function sameLane(a: string | null, b: string | null): boolean; /** * Coalesce two payloads for the SAME lane without losing either one's request. * * ── WHAT THIS FIXES (2026-10) ──────────────────────────────────────────────── * * A lane holds exactly one payload, and coalescing REPLACED it. That is correct * for "which instruction is newest" and catastrophic for "who asked me * something", because the two are not the same field. The real failure, reported * from production: * * 1. A human @mentions the agent in a task comment while it is offline. * Queued on lane `task:T` with `commentId` + `mentionId` set. * 2. The human then presses "Run task". `task.run` derives the SAME lane * (`taskId` outranks everything, rule 2 above). * 3. `task.run` carries NO comment identity at all, and it arrived last, so * last-write-wins handed the lane a payload with the request erased. * 4. The delivered wake was "run this task". The bridge's mention-claim gate * is `if (event.mentionId)`, so it never ran; nothing was claimed, nothing * was ever closed; the run's brief showed the last 3 comments as context * with no "unanswered" marker; the agent worked the task and the person was * never answered. Silence, start to finish. * * So the rule is: **scalars are last-write-wins, identity is cumulative.** * * - `type`, `by`, `editRequest`, `references`, `model`, `resume` etc. come from * `incoming`, because the newest instruction is the one the agent acts on. * - `mentionId` / `commentId` are newest-NON-NULL. A trigger with no mention * cannot erase one that had a mention - that single rule is the whole fix. * - `mentionIds` / `commentIds` are the union of both sides, oldest first, * capped. Several mentions coalesce into several obligations rather than one * obligation and a count. * * The cap is the one place information can still be lost, so it is the caller's * job to notice: {@link PAYLOAD_ID_LIST_MAX} entries survive, oldest dropped, and * `triggerCount` on the row says how many were folded in beyond them. */ export declare function mergeWakePayload(existing: T | null | undefined, incoming: T): T; /** * Every mention id a payload carries, newest last. * * The single place that reads "does this wake owe somebody an answer?", so the * sweeper, the claim gate and the brief cannot each invent their own answer. */ export declare function mentionIdsOf(event: WakeLaneInput | null | undefined): string[]; /** True when the event steers a running session rather than starting work. */ export declare function isResumeType(type: string): boolean; /** True when the event is a task-scoped wake. */ export declare function isTaskScoped(type: string): boolean;