@adhdev/mesh-shared 1.0.60-rc.7 → 1.0.60-rc.71

package/dist/types.d.ts

@@ -136,4 +136,15 @@ export interface RepoMeshSessionStatus {
     startedAt?: string | null;
     lastActivityAt?: string | null;
     isCached?: boolean;
+    /**
+     * Worker MCP delivery outcome for this session's launch (present only for a
+     * mesh-delegated launch). `reason` is a short enum code, never free text —
+     * see `WORKER_MCP_DELIVERY_REASONS` (daemon-core's `mesh/worker-mcp-isolation.ts`,
+     * the source of the vocabulary this field's values are drawn from; not
+     * re-exported here so mesh-shared stays a dependency-free leaf).
+     */
+    workerMcp?: {
+        delivered: boolean;
+        reason?: string;
+    };
 }

package/dist/worker-protocol.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 { type MissionBrief } from './mission-brief';
+export declare const WORKER_TOOLS: readonly ["report_completion", "progress_update", "peer_context_pull", "git_status", "git_log", "git_diff"];
+export type WorkerTool = typeof WORKER_TOOLS[number];
+export declare function isWorkerTool(value: unknown): value is WorkerTool;
+/** Stable marker line so a body is never footered twice and tests can find it. */
+export declare 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 declare function hasWorkerProtocolFooter(body: string): boolean;
+/**
+ * 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 declare function renderWorkerProtocolFooter(input?: WorkerProtocolFooterInput): string;
+/**
+ * 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 declare function stripWorkerProtocolFooter(body: string): string;
+/**
+ * Append the footer to a body that does not carry one yet. Idempotent.
+ */
+export declare function appendWorkerProtocolFooter(body: string, input?: WorkerProtocolFooterInput): string;
+/**
+ * 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 declare function renderCoordinatorWorkerSection(): string;

package/dist/ws-protocol.d.ts

@@ -1,50 +1,78 @@
 /**
- * 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'
+import { type DaemonToServerType, type ServerToDaemonControlType, type P2PSignalType, type MeshP2PSignalType, type DashboardToDaemonP2PType, type DaemonToDashboardP2PType } from './protocol';
+/** Messages the daemon sends UP to the Workers server over the WS bridge (see protocol/daemon-server.ts). */
+export type DaemonToServerWsMsg = DaemonToServerType;
 /**
- * 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.
+ * 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.
  */
- | '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'
+export type ServerToDaemonWsMsg = ServerToDaemonControlType;
+/** P2P signaling relayed through the server WS — the `p2p_`/`mesh_p2p_` spellings the wire actually uses. */
+export type P2PSignalingWsMsg = P2PSignalType | MeshP2PSignalType;
+/** Every dashboard↔daemon P2P DataChannel JSON kind, both directions (see protocol/dashboard-daemon-p2p.ts). */
+export type DashboardP2PMessageKind = DashboardToDaemonP2PType | DaemonToDashboardP2PType;
+export declare const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[];
+export declare const SERVER_TO_DAEMON_WS_MSGS: readonly ServerToDaemonWsMsg[];
 /**
- * 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.
+ * `auth_ok.payload.limits` — the plan-limit contract the server sends DOWN to
+ * the daemon for client-side enforcement.
+ *
+ * WHY THIS EXISTS: the wire spelling is `maxP2Pconnections` (lowercase `c`),
+ * inherited from `PlanLimits` in the proprietary server's plan-limits.ts. The
+ * daemon-cloud consumer independently declared the same field as
+ * `maxP2PConnections` (capital `C`) and assigned it from a `payload as any`
+ * cast — so the two spellings NEVER met under a type, TypeScript had nothing
+ * to compare, and the limit arrived as `undefined` at every comparison site.
+ * `undefined !== -1` passes the "is it unlimited?" guard, then every
+ * `count >= undefined` is false: enforcement silently degraded to unlimited on
+ * all plans, in production, for months.
+ *
+ * The lesson is NOT "pick a spelling" — it is that a cross-package wire
+ * contract asserted by hand on both ends with an `any` in between cannot fail
+ * loudly. Both producer (server) and consumer (daemon-cloud) must now import
+ * THIS symbol, so a rename breaks the build on both sides instead of silently
+ * disabling a paid-plan limit. Use `normalizeAuthOkLimits()` at the parse
+ * boundary; never re-spell these fields locally.
  */
- | 'beacon_vectors_result';
-/** 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';
+export interface AuthOkPlanLimits {
+    /** P2P concurrent connection count (-1 = unlimited). WIRE SPELLING — lowercase `c`. */
+    maxP2Pconnections: number;
+    /** Screenshot send interval floor (seconds). 0 = real-time. */
+    screenshotIntervalSeconds: number;
+    /** Daily screenshot usage budget (minutes). -1 = unlimited. */
+    dailyScreenshotMinutes: number;
+    /** Max connectable machines/daemons (-1 = unlimited). */
+    maxMachines: number;
+}
 /**
- * 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).
+ * Parse-boundary normalizer for `auth_ok.payload.limits`.
+ *
+ * Returns `null` when the payload carries no usable limits object, so callers
+ * keep their existing "no limits known yet" branch. Individual non-numeric or
+ * missing fields fall back to the UNLIMITED sentinel (-1) for count-style
+ * limits and 0 for the interval floor, matching how each consumer already
+ * treats "no constraint" — a malformed field must never be coerced to a
+ * MORE restrictive value than the server intended, or a server-side schema
+ * change would start throttling paying users.
+ *
+ * Accepts the capital-`C` misspelling as an input alias ONLY so a daemon
+ * talking to a mixed-version fleet cannot regress; output is always the
+ * canonical wire spelling.
  */
-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 declare const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[];
-export declare const SERVER_TO_DAEMON_WS_MSGS: readonly ServerToDaemonWsMsg[];
-export declare function isDaemonToServerWsMsg(value: unknown): value is DaemonToServerWsMsg;
-export declare function isServerToDaemonWsMsg(value: unknown): value is ServerToDaemonWsMsg;
+export declare function normalizeAuthOkLimits(raw: unknown): AuthOkPlanLimits | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/mesh-shared",
-  "version": "1.0.60-rc.7",
+  "version": "1.0.60-rc.71",
   "description": "ADHDev mesh-shared — pure mesh/git status normalizers shared by daemon-core and web-core",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/brain-routing.ts

@@ -66,7 +66,7 @@ export function isMeshTaskDifficulty(value: unknown): value is MeshTaskDifficult
  *      a value that should never have been stamped provider-blind.
  *
  *   2. IT FOUGHT THE SLOTS. Operators express model choice per node via
- *      capability slots (`mesh_node_slots_set`), which know the provider. A
+ *      capability slots (`mesh_node_slots` action "set"), which know the provider. A
  *      mesh-wide preset that also picks a model duplicated that decision from a
  *      position with strictly less information, and needed the modelSource
  *      ('explicit' vs 'preset') precedence machinery plus a fail-closed
@@ -112,7 +112,7 @@ export function normalizeDifficultyBrainMap(raw: unknown): DifficultyBrainMap {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Node capability slots (ORCHESTRATION_NODE_SLOTS.md)
+// Node capability slots (node capability slots design, 2026-07-09)
 //
 // A node's "Preferred AI tools" list is redefined as an ordered array of
 // capability slots. Each slot bundles what used to be scattered across
@@ -252,7 +252,7 @@ export function deriveSlotsFromLegacy(input: {
  * The reverse direction of deriveSlotsFromLegacy: derive the legacy
  * `providerPriority` order from capability slots — each slot's provider, in
  * first-appearance order, de-duplicated. Slot order = preference is the settled
- * slots semantics (ORCHESTRATION_NODE_SLOTS.md), so this is what readers of the
+ * slots semantics (node capability slots design, 2026-07-09), so this is what readers of the
  * legacy `policy.providerPriority` field must fall back to when a node declares
  * slots but no explicit providerPriority (otherwise such a node reads as
  * unlaunchable even though its slots fully determine the preference order).

package/src/index.ts

@@ -29,3 +29,14 @@ export * from './rpc-chunking'
 export * from './semver-compare'
 export * from './ws-protocol'
 export * from './interactive-prompt-constants'
+export * from './session-status'
+export * from './mesh-vocabulary'
+export * from './outbound-message'
+export * from './worker-protocol'
+export * from './protocol'
+export * from './turn-evidence'
+export * from './session-launch'
+export * from './turn-ipc'
+export * from './path-ownership'
+export * from './mission-brief'
+export * from './keyed-doc-delta'

package/src/interpolation.ts

@@ -1,21 +1,3 @@
-/**
- * Pure {{key}} template interpolation shared by the mesh command paths.
- *
- * Hoisted from packages/daemon-cloud/src/mesh/mesh-interpolation.ts — the
- * substitution is transport-agnostic (plain string/object work), so it belongs
- * in the dependency-free mesh-shared leaf where standalone can reuse it too.
- * The substitution semantics are byte-for-byte identical to the prior cloud copy.
- */
-export function interpolateArgs(
-  args: Record<string, unknown>,
-  context: Record<string, unknown>,
-): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(args)) {
-    result[k] = typeof v === 'string' ? interpolateString(v, context) : v;
-  }
-  return result;
-}
 
 export function interpolateString(template: string, ctx: Record<string, unknown>): string {
   return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {