@adhdev/mesh-shared 1.0.60-rc.33 → 1.0.60-rc.35

package/src/worker-protocol.ts

@@ -0,0 +1,142 @@
+/**
+ * worker-protocol — what a delegated worker is told, and what it may call.
+ *
+ * Wiring-unification Phase F1 (docs/design/2026-09-23-wiring-unification.md §7b).
+ *
+ * Measured 2026-09-23 on the live preview ledger: 635 worker attempts in 14
+ * days, 3 `report_completion` calls. The worker MCP was delivered to every
+ * provider and never used, because nothing ever told the worker it existed —
+ * the dispatched task body carried no instruction and the coordinator prompt
+ * did not mention the worker tools at all. The only text a worker saw about
+ * its tools was the tool description.
+ *
+ * This module is the single source for BOTH sides of that contract:
+ *   - `WORKER_TOOLS` — exactly what `adhdev mcp --mode worker` advertises
+ *     (a parity test in mcp-server pins ListTools to this tuple);
+ *   - `renderWorkerProtocolFooter()` — the block appended to EVERY dispatched
+ *     task body, so a worker learns the protocol from the task itself;
+ *   - `renderCoordinatorWorkerSection()` — the matching paragraph the
+ *     coordinator prompt carries, so the coordinator expects structured reports
+ *     and stops polling for them.
+ *
+ * Wiring-unification Phase H2 adds an optional mission-brief block: when a
+ * dispatched task belongs to a mission that carries a `MissionBrief`
+ * (`./mission-brief.ts`), `renderWorkerProtocolFooter` renders it ABOVE the
+ * `WORKER_PROTOCOL_FOOTER_MARKER` line. This is deliberate placement, not an
+ * accident of insertion order: `hasWorkerProtocolFooter` / `stripWorkerProtocolFooter`
+ * both key off the marker line alone, so a body with a brief block strips
+ * identically to one without — the brief is authored content from the
+ * coordinator's point of view (like the task message itself), never part of
+ * the protocol contract the marker demarcates.
+ */
+
+import { renderMissionBriefBlock, type MissionBrief } from './mission-brief'
+
+export const WORKER_TOOLS = [
+    'report_completion',
+    'progress_update',
+    'peer_context_pull',
+    'git_status',
+    'git_log',
+    'git_diff',
+] as const
+
+export type WorkerTool = typeof WORKER_TOOLS[number]
+
+const WORKER_TOOL_SET: ReadonlySet<string> = new Set(WORKER_TOOLS)
+
+export function isWorkerTool(value: unknown): value is WorkerTool {
+    return typeof value === 'string' && WORKER_TOOL_SET.has(value)
+}
+
+/** Stable marker line so a body is never footered twice and tests can find it. */
+export const WORKER_PROTOCOL_FOOTER_MARKER = '--- adhdev worker protocol ---'
+
+export interface WorkerProtocolFooterInput {
+    taskId?: string
+    taskMode?: string
+    difficulty?: string
+    readonly?: boolean
+    /** Number of handoff notes enclosed above the footer, when any. */
+    enclosedHandoffNotes?: number
+    /** H2: the owning mission's brief, when this task belongs to one. Rendered above the marker line — see module doc. */
+    missionBrief?: MissionBrief
+}
+
+export function hasWorkerProtocolFooter(body: string): boolean {
+    return typeof body === 'string' && body.includes(WORKER_PROTOCOL_FOOTER_MARKER)
+}
+
+/**
+ * The protocol block appended to a dispatched task. Written for the model that
+ * receives it: imperative, short, and explicit about what is NOT available so
+ * the worker does not go looking for coordinator tools.
+ */
+export function renderWorkerProtocolFooter(input: WorkerProtocolFooterInput = {}): string {
+    const briefBlock = input.missionBrief ? renderMissionBriefBlock(input.missionBrief) : null
+    const lines: string[] = briefBlock ? [briefBlock, '', WORKER_PROTOCOL_FOOTER_MARKER] : [WORKER_PROTOCOL_FOOTER_MARKER]
+    const scope: string[] = []
+    if (input.taskId) scope.push(`task ${input.taskId}`)
+    if (input.taskMode) scope.push(`mode ${input.taskMode}`)
+    if (input.difficulty) scope.push(`difficulty ${input.difficulty}`)
+    if (input.readonly) scope.push('read-only')
+    if (scope.length) lines.push(`You are a delegated worker (${scope.join(', ')}).`)
+    else lines.push('You are a delegated worker.')
+    lines.push(
+        'When your work is finished, blocked, or has failed, call `report_completion` exactly once. '
+            + 'Its `summary` is recorded verbatim as the authoritative record of this task — your terminal is not '
+            + 'scraped for it — so state what you did, what you found, and where you left the branch.',
+        'For work that runs longer than a few minutes, call `progress_update` at natural checkpoints so the '
+            + 'coordinator can see you are alive without polling.',
+        '`peer_context_pull` shows what sibling tasks in this mission have reported; `git_status` / `git_diff` / '
+            + '`git_log` inspect your own workspace (pass its absolute path as `workspace`).',
+        'You have no coordinator tools (no `mesh_*`) by design: do not enqueue, dispatch, or restart anything. '
+            + 'If you need a decision from the coordinator, finish with `report_completion` and outcome `blocked`, '
+            + 'listing what you need in `blockers`.',
+    )
+    if (input.enclosedHandoffNotes && input.enclosedHandoffNotes > 0) {
+        lines.push(
+            `The ${input.enclosedHandoffNotes} handoff note(s) above were written by agents who touched this code before you; `
+                + 'honour their conflict guidance and add your own in `handoff_notes` when you report.',
+        )
+    }
+    return lines.join('\n')
+}
+
+/**
+ * The authored text of a dispatched body: everything before the footer marker.
+ * Ledger descriptors, replay fixtures and tests compare authored text, never
+ * the protocol block.
+ */
+export function stripWorkerProtocolFooter(body: string): string {
+    if (typeof body !== 'string') return body
+    const at = body.indexOf(WORKER_PROTOCOL_FOOTER_MARKER)
+    if (at < 0) return body
+    return body.slice(0, at).replace(/\s+$/, '')
+}
+
+/**
+ * Append the footer to a body that does not carry one yet. Idempotent.
+ */
+export function appendWorkerProtocolFooter(body: string, input: WorkerProtocolFooterInput = {}): string {
+    if (hasWorkerProtocolFooter(body)) return body
+    const trimmed = body.replace(/\s+$/, '')
+    return `${trimmed}\n\n${renderWorkerProtocolFooter(input)}`
+}
+
+/**
+ * The paragraph the COORDINATOR prompt carries about its workers. Kept next to
+ * the footer so the two halves of the protocol cannot drift apart.
+ */
+export function renderCoordinatorWorkerSection(): string {
+    return [
+        '## Workers',
+        '',
+        `Every task you dispatch is delivered with a worker protocol footer. Workers hold exactly these tools: ${WORKER_TOOLS.map((tool) => `\`${tool}\``).join(', ')} — and no \`mesh_*\` tools.`,
+        '- A worker finishes by calling `report_completion`; its structured report (outcome, summary, touched files, branch state, handoff notes) is what reaches you as the completion event. Read that report — do not re-derive the outcome from `mesh_read_chat` or the terminal unless the report is missing.',
+        '- `progress_update` from a worker arrives as a lightweight progress note. Do NOT poll `mesh_status`, `mesh_view_queue` or `mesh_read_chat` to check on a running worker; completion, progress, blocked and failure all arrive as events.',
+        '- To reach a busy worker mid-task use `mesh_notify_worker`: the memo is delivered on the worker\'s next tool call (or when it becomes idle). A worker that reports `blocked` is asking you for a decision — answer it with `mesh_send_task` to the same session.',
+        '- `mesh_status` is for node health and capacity before delegating, never for progress.',
+        '- A `code_change` task\'s declared `owned_paths` (H1) is enforced at claim time: a second `code_change` task whose `owned_paths` overlaps an already-claimed task\'s is refused rather than silently racing it. A worker\'s `report_completion.touched_files` is compared against its own task\'s declaration afterward and any mismatch is surfaced back to you as evidence — it is never a validation failure, since a worker often cannot know its exact final file list at enqueue time.',
+    ].join('\n')
+}

package/src/ws-protocol.ts

@@ -1,110 +1,56 @@
 /**
- * ws-protocol — shared string-literal unions for the daemon↔server WS surface
- * and the daemon↔dashboard P2P DataChannel surface.
+ * ws-protocol — name-only aliases for the daemon↔server WS surface and the
+ * daemon↔dashboard P2P DataChannel surface, plus the `auth_ok.payload.limits`
+ * contract.
  *
- * Fragmentation audit: these message types existed as a TypeScript union in
- * exactly ONE package (the proprietary daemon-cloud's server-connection.ts),
- * which is a leaf CONSUMER — the other two participants (the Workers server
- * and OSS daemon-core, which is the primary `status_report` producer) matched
- * bare string literals by hand. Renaming `auth_ok` server-side would compile
- * everywhere and leave the daemon reconnecting forever. Pure literals, zero
- * runtime deps — the textbook mesh-shared leaf.
- *
- * SCOPE HONESTY: this file declares the OSS-visible protocol surface. The
- * proprietary repo's server-connection.ts remains the authority for the full
- * ServerToDaemon command set; it should adopt these unions and extend them
- * (`ServerToDaemonMsg | <proprietary extras>`) rather than re-declaring the
- * shared members. Members here are the ones OSS daemon-core itself produces
- * or matches.
+ * Wiring-unification Phase A2: the typed frame unions now live in ./protocol
+ * (one file per link, payloads included). This file keeps the symbols that
+ * pre-dated them — `DaemonToServerWsMsg`, `ServerToDaemonWsMsg`,
+ * `P2PSignalingWsMsg`, `DashboardP2PMessageKind` and the two name arrays —
+ * DERIVED from the protocol unions rather than re-declared, so they cannot
+ * drift again. Before this derivation the list here said `offer|answer|ice`
+ * while the wire said `p2p_offer|p2p_answer|p2p_ice`, declared a `log` frame
+ * nothing sent or handled, omitted `daemon_mesh_command` (sent by a raw
+ * `ws.send`), and listed 12 of the ~27 P2P kinds — and nothing imported the
+ * drifted members, so nothing noticed.
  */
 
-/** Messages the daemon sends UP to the Workers server over the WS bridge. */
-export type DaemonToServerWsMsg =
-    | 'auth'
-    | 'status_report'
-    | 'status_heartbeat'
-    | 'status_event'
-    | 'command_result'
-    | 'error'
-    | 'agent_event'
-    | 'log'
-    /**
-     * seqscribe Beacon vectors (design §7.1). ONE daemon-initiated frame carries
-     * both directions — `op: 'put'` stores this node's content-free vector
-     * report, `op: 'get'` asks for the board — because the server has no way to
-     * wake itself: `DaemonConnectionDO` has neither an alarm nor a timer, and
-     * adding one would hit the most request-quota-pressured axis in the system.
-     */
-    | 'beacon_vectors';
-
-/** Server→daemon control messages the OSS engine reacts to. */
-export type ServerToDaemonWsMsg =
-    | 'auth_ok'
-    | 'auth_error'
-    | 'machine_evicted'
-    | 'force_disconnect'
-    | 'token_revoked'
-    | 'version_mismatch'
-    | 'force_update_required'
-    | 'command'
-    | 'agent_command'
-    | 'resolve_action'
-    /**
-     * Reply to a `beacon_vectors` GET, correlated by `requestId`. A PUT is
-     * fire-and-forget and gets no reply at all — the beacon is advisory, so a
-     * lost report costs one debounce cycle of prediction accuracy and nothing
-     * else, which is not worth an ack round trip.
-     */
-    | 'beacon_vectors_result';
+import {
+    DAEMON_TO_SERVER_TYPES,
+    SERVER_TO_DAEMON_CONTROL_TYPES,
+    isDaemonToServerType,
+    isServerToDaemonControlType,
+    type DaemonToServerType,
+    type ServerToDaemonControlType,
+    type P2PSignalType,
+    type MeshP2PSignalType,
+    type DashboardToDaemonP2PType,
+    type DaemonToDashboardP2PType,
+} from './protocol';
 
-/** P2P signaling relayed through the server WS. */
-export type P2PSignalingWsMsg =
-    | 'p2p_ready'
-    | 'offer'
-    | 'answer'
-    | 'ice'
-    | 'mesh_p2p_ready'
-    | 'mesh_p2p_offer'
-    | 'mesh_p2p_answer'
-    | 'mesh_p2p_ice';
+/** Messages the daemon sends UP to the Workers server over the WS bridge (see protocol/daemon-server.ts). */
+export type DaemonToServerWsMsg = DaemonToServerType;
 
 /**
- * Dashboard↔daemon P2P DataChannel JSON message kinds. Previously matched as
- * hand-synced literals on both ends with NO shared symbol anywhere —
- * `p2p_evicted` had exactly two occurrences repo-wide (emit + handle).
+ * Server→daemon CONTROL messages (see protocol/daemon-server.ts). The server
+ * additionally relays an open command namespace as the frame `type`
+ * (`ServerDirectCommandMsg`), which is deliberately not a member here.
  */
-export type DashboardP2PMessageKind =
-    | 'ping'
-    | 'pong'
-    | 'status_report'
-    | 'status_event'
-    | 'p2p_evicted'
-    | 'command'
-    | 'command_result'
-    | 'command_result_chunk'
-    | 'screenshot_start'
-    | 'screenshot_stop'
-    | 'pty_input'
-    | 'pty_resize';
+export type ServerToDaemonWsMsg = ServerToDaemonControlType;
 
-export const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[] = [
-    'auth', 'status_report', 'status_heartbeat', 'status_event', 'command_result', 'error', 'agent_event', 'log',
-    'beacon_vectors',
-];
+/** P2P signaling relayed through the server WS — the `p2p_`/`mesh_p2p_` spellings the wire actually uses. */
+export type P2PSignalingWsMsg = P2PSignalType | MeshP2PSignalType;
 
-export const SERVER_TO_DAEMON_WS_MSGS: readonly ServerToDaemonWsMsg[] = [
-    'auth_ok', 'auth_error', 'machine_evicted', 'force_disconnect', 'token_revoked',
-    'version_mismatch', 'force_update_required', 'command', 'agent_command', 'resolve_action',
-    'beacon_vectors_result',
-];
+/** Every dashboard↔daemon P2P DataChannel JSON kind, both directions (see protocol/dashboard-daemon-p2p.ts). */
+export type DashboardP2PMessageKind = DashboardToDaemonP2PType | DaemonToDashboardP2PType;
 
-export function isDaemonToServerWsMsg(value: unknown): value is DaemonToServerWsMsg {
-    return typeof value === 'string' && (DAEMON_TO_SERVER_WS_MSGS as readonly string[]).includes(value);
-}
+export const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[] = DAEMON_TO_SERVER_TYPES;
 
-export function isServerToDaemonWsMsg(value: unknown): value is ServerToDaemonWsMsg {
-    return typeof value === 'string' && (SERVER_TO_DAEMON_WS_MSGS as readonly string[]).includes(value);
-}
+export const SERVER_TO_DAEMON_WS_MSGS: readonly ServerToDaemonWsMsg[] = SERVER_TO_DAEMON_CONTROL_TYPES;
+
+export const isDaemonToServerWsMsg: (value: unknown) => value is DaemonToServerWsMsg = isDaemonToServerType;
+
+export const isServerToDaemonWsMsg: (value: unknown) => value is ServerToDaemonWsMsg = isServerToDaemonControlType;
 
 /**
  * `auth_ok.payload.limits` — the plan-limit contract the server sends DOWN to