@adhdev/mesh-shared 1.0.58-rc.6 → 1.0.58-rc.7

package/dist/mesh-tool-names.d.ts

@@ -18,7 +18,7 @@
  * Order mirrors mcp-server `ALL_MESH_TOOLS` for easy visual diffing, but the consistency
  * checks are set-based (order-insensitive).
  */
-export declare const CANONICAL_MESH_TOOL_NAMES: readonly ["mesh_status", "mesh_list_nodes", "mesh_enqueue_batch", "mesh_enqueue_task", "mesh_view_queue", "mesh_graph_view", "mesh_graph_gate_claim", "mesh_graph_gate_release", "mesh_graph_gate_abandon", "mesh_queue_cancel", "mesh_queue_requeue", "mesh_send_task", "mesh_read_chat", "mesh_read_debug", "mesh_read_terminal", "mesh_send_keys", "mesh_launch_session", "mesh_git_status", "mesh_read_node_logs", "mesh_fast_forward_node", "mesh_restart_daemon", "mesh_checkpoint", "mesh_approve", "mesh_answer_question", "mesh_list_pending_approvals", "mesh_plan_onboarding", "mesh_create", "mesh_add_node", "mesh_clone_node", "mesh_remove_node", "mesh_cleanup_worktree_nodes", "mesh_refine_node", "mesh_refine_batch", "mesh_refine_config", "mesh_change_impact_config", "mesh_init", "mesh_reinit", "mesh_write_mesh_json_config", "mesh_refine_plan", "mesh_cleanup_sessions", "mesh_prune_stale_direct", "mesh_task_history", "mesh_ledger_query", "mesh_record_note", "mesh_forget_note", "mesh_reconcile_ledger", "mesh_requeue_held_events", "mesh_mission_upsert", "mesh_mission_list", "mesh_review_inbox", "mesh_magi_review", "mesh_magi_collect", "mesh_magi_kind_panel_set", "mesh_magi_kind_panel_list", "mesh_node_slots_set", "mesh_node_slots_list", "mesh_node_slots_propose", "mesh_coordinator_prompt_append_get", "mesh_coordinator_prompt_append_set"];
+export declare const CANONICAL_MESH_TOOL_NAMES: readonly ["mesh_status", "mesh_route_preview", "mesh_list_nodes", "mesh_enqueue_batch", "mesh_enqueue_task", "mesh_view_queue", "mesh_graph_view", "mesh_graph_gate_claim", "mesh_graph_gate_release", "mesh_graph_gate_abandon", "mesh_queue_cancel", "mesh_queue_requeue", "mesh_send_task", "mesh_read_chat", "mesh_read_debug", "mesh_read_terminal", "mesh_send_keys", "mesh_launch_session", "mesh_git_status", "mesh_read_node_logs", "mesh_fast_forward_node", "mesh_restart_daemon", "mesh_checkpoint", "mesh_approve", "mesh_answer_question", "mesh_list_pending_approvals", "mesh_plan_onboarding", "mesh_create", "mesh_add_node", "mesh_clone_node", "mesh_remove_node", "mesh_cleanup_worktree_nodes", "mesh_refine_node", "mesh_refine_batch", "mesh_refine_config", "mesh_change_impact_config", "mesh_init", "mesh_reinit", "mesh_write_mesh_json_config", "mesh_refine_plan", "mesh_cleanup_sessions", "mesh_prune_stale_direct", "mesh_task_history", "mesh_ledger_query", "mesh_record_note", "mesh_forget_note", "mesh_reconcile_ledger", "mesh_requeue_held_events", "mesh_mission_upsert", "mesh_mission_list", "mesh_review_inbox", "mesh_magi_review", "mesh_magi_collect", "mesh_magi_kind_panel_set", "mesh_magi_kind_panel_list", "mesh_node_slots_set", "mesh_node_slots_list", "mesh_node_slots_propose", "mesh_coordinator_prompt_append_get", "mesh_coordinator_prompt_append_set"];
 export type CanonicalMeshToolName = typeof CANONICAL_MESH_TOOL_NAMES[number];
 /** The count the `NN tools` barrel doc comments and consistency test assert against. */
-export declare const CANONICAL_MESH_TOOL_COUNT: 59;
+export declare const CANONICAL_MESH_TOOL_COUNT: 60;

package/dist/semver-compare.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Semver precedence comparison — the single version-ordering primitive for the
+ * daemon's upgrade paths.
+ *
+ * Why this exists: the upgrade path used to decide "is this a no-op?" with a
+ * raw string equality check (`currentInstalled === latest`) and nothing else.
+ * Equality answers "is it the same version?" but never "which one is newer?",
+ * so any target that merely differed from the running build was installed —
+ * including one that is OLDER. That is how a node running `1.0.49-rc.2`
+ * silently got rolled back to `1.0.48`.
+ *
+ * String comparison cannot fix it either: `'1.0.49-rc.2' < '1.0.48'` is TRUE
+ * lexicographically (the '4' in "-rc.2"'s prefix never gets that far — '9' vs
+ * '8' at index 4 decides it, and even where it works `rc.10` sorts below
+ * `rc.9`). Only field-wise numeric comparison with semver §11 prerelease rules
+ * gives the right answer.
+ *
+ * This module is a PURE LEAF: zero imports, no I/O. It lives in mesh-shared
+ * (fragmentation audit) so BOTH the OSS daemon and the proprietary Workers
+ * server (`packages/server/src/utils/version-policy.ts`, previously a
+ * byte-identical independent copy) can consume ONE implementation — the two
+ * gate the same auto-update decision from opposite ends, and a drift between
+ * them can produce an unbreakable update-nag loop (server says behind, daemon
+ * gate refuses the "upgrade" as a rollback). daemon-core re-exports this from
+ * its original `version-compare.ts` path, so existing imports keep working.
+ *
+ * NOTE ON PRERELEASE SEMANTICS: this is STRICT semver §11 — `1.0.49-rc.2` is
+ * BELOW `1.0.49`, because a prerelease precedes its own release. That is the
+ * correct rule for "would installing this move me backwards?", which is the
+ * only question this module is used to answer. It deliberately differs from
+ * `oss/packages/web-core/src/utils/version-update.ts`, whose
+ * `isDaemonBehindTarget` treats an rc as up-to-date against its own base
+ * release so the dashboard does not nag preview users with an update banner.
+ * Those are two different questions; do not collapse them into one helper.
+ */
+/** Parsed semver fields. Build metadata (`+…`) is discarded: it never affects precedence (§10). */
+export interface ParsedSemver {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    /** Dot-separated prerelease identifiers; empty for a release build. */
+    readonly prerelease: readonly string[];
+}
+/**
+ * Parse a semver string, tolerating a leading `v` (npm/CLI output carries it
+ * inconsistently). Returns null for anything unparsable so callers can fail
+ * closed rather than guess.
+ */
+export declare function parseSemver(version: unknown): ParsedSemver | null;
+/**
+ * Compare two versions by semver precedence.
+ *
+ * @returns -1 when `a` precedes `b`, 0 when equal, 1 when `a` succeeds `b`, and
+ *   **null when either side is unparsable** — callers MUST treat null as
+ *   "direction unknown" and fail closed rather than coercing it to a number
+ *   (`null` compares as `0` in JS numeric contexts, which would read as "equal").
+ */
+export declare function compareSemver(a: unknown, b: unknown): number | null;
+/**
+ * Would installing `target` move a daemon currently on `current` BACKWARDS?
+ *
+ * Returns false when the direction cannot be established (either version
+ * unparsable) — an unknown direction must never block an upgrade, because the
+ * cost of a false block (the whole fleet can no longer be upgraded) is far
+ * higher than the cost of a missed downgrade guard. Equal versions are NOT a
+ * downgrade, so a same-version reinstall stays allowed.
+ */
+export declare function isDowngrade(current: unknown, target: unknown): boolean;

package/dist/ws-protocol.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ws-protocol — shared string-literal unions for the daemon↔server WS surface
+ * and the daemon↔dashboard P2P DataChannel surface.
+ *
+ * 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.
+ */
+/** 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';
+/** 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';
+/** 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';
+/**
+ * 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).
+ */
+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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/mesh-shared",
-  "version": "1.0.58-rc.6",
+  "version": "1.0.58-rc.7",
   "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/index.ts

@@ -26,3 +26,5 @@ export * from './interpolation'
 export * from './mesh-tool-names'
 export * from './mesh-status-probe'
 export * from './rpc-chunking'
+export * from './semver-compare'
+export * from './ws-protocol'

package/src/mesh-tool-names.ts

@@ -20,6 +20,7 @@
  */
 export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_status',
+    'mesh_route_preview',
     'mesh_list_nodes',
     // GRAPH-ORCHESTRATION Phase F — batch before task, mirroring ALL_MESH_TOOLS.
     'mesh_enqueue_batch',

package/src/semver-compare.ts

@@ -0,0 +1,122 @@
+/**
+ * Semver precedence comparison — the single version-ordering primitive for the
+ * daemon's upgrade paths.
+ *
+ * Why this exists: the upgrade path used to decide "is this a no-op?" with a
+ * raw string equality check (`currentInstalled === latest`) and nothing else.
+ * Equality answers "is it the same version?" but never "which one is newer?",
+ * so any target that merely differed from the running build was installed —
+ * including one that is OLDER. That is how a node running `1.0.49-rc.2`
+ * silently got rolled back to `1.0.48`.
+ *
+ * String comparison cannot fix it either: `'1.0.49-rc.2' < '1.0.48'` is TRUE
+ * lexicographically (the '4' in "-rc.2"'s prefix never gets that far — '9' vs
+ * '8' at index 4 decides it, and even where it works `rc.10` sorts below
+ * `rc.9`). Only field-wise numeric comparison with semver §11 prerelease rules
+ * gives the right answer.
+ *
+ * This module is a PURE LEAF: zero imports, no I/O. It lives in mesh-shared
+ * (fragmentation audit) so BOTH the OSS daemon and the proprietary Workers
+ * server (`packages/server/src/utils/version-policy.ts`, previously a
+ * byte-identical independent copy) can consume ONE implementation — the two
+ * gate the same auto-update decision from opposite ends, and a drift between
+ * them can produce an unbreakable update-nag loop (server says behind, daemon
+ * gate refuses the "upgrade" as a rollback). daemon-core re-exports this from
+ * its original `version-compare.ts` path, so existing imports keep working.
+ *
+ * NOTE ON PRERELEASE SEMANTICS: this is STRICT semver §11 — `1.0.49-rc.2` is
+ * BELOW `1.0.49`, because a prerelease precedes its own release. That is the
+ * correct rule for "would installing this move me backwards?", which is the
+ * only question this module is used to answer. It deliberately differs from
+ * `oss/packages/web-core/src/utils/version-update.ts`, whose
+ * `isDaemonBehindTarget` treats an rc as up-to-date against its own base
+ * release so the dashboard does not nag preview users with an update banner.
+ * Those are two different questions; do not collapse them into one helper.
+ */
+
+/** Parsed semver fields. Build metadata (`+…`) is discarded: it never affects precedence (§10). */
+export interface ParsedSemver {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    /** Dot-separated prerelease identifiers; empty for a release build. */
+    readonly prerelease: readonly string[];
+}
+
+const SEMVER_PATTERN = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const NUMERIC_IDENTIFIER = /^\d+$/;
+
+/**
+ * Parse a semver string, tolerating a leading `v` (npm/CLI output carries it
+ * inconsistently). Returns null for anything unparsable so callers can fail
+ * closed rather than guess.
+ */
+export function parseSemver(version: unknown): ParsedSemver | null {
+    if (typeof version !== 'string') return null;
+    const match = version.trim().replace(/^v/, '').match(SEMVER_PATTERN);
+    if (!match) return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4] ? match[4].split('.') : [],
+    };
+}
+
+/**
+ * Semver §11 prerelease precedence: a release outranks its own prereleases;
+ * numeric identifiers compare numerically (so rc.10 > rc.9) and rank below
+ * alphanumeric ones; alphanumerics compare lexically; a shorter identifier
+ * list ranks below an otherwise-equal longer one.
+ */
+function comparePrerelease(a: readonly string[], b: readonly string[]): number {
+    if (a.length === 0 && b.length === 0) return 0;
+    // An empty prerelease list means "release build", which outranks any prerelease.
+    if (a.length === 0) return 1;
+    if (b.length === 0) return -1;
+    for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
+        const idA = a[i];
+        const idB = b[i];
+        if (idA === idB) continue;
+        const numA = NUMERIC_IDENTIFIER.test(idA);
+        const numB = NUMERIC_IDENTIFIER.test(idB);
+        if (numA && numB) return Number(idA) < Number(idB) ? -1 : 1;
+        if (numA) return -1;
+        if (numB) return 1;
+        return idA < idB ? -1 : 1;
+    }
+    return a.length === b.length ? 0 : (a.length < b.length ? -1 : 1);
+}
+
+/**
+ * Compare two versions by semver precedence.
+ *
+ * @returns -1 when `a` precedes `b`, 0 when equal, 1 when `a` succeeds `b`, and
+ *   **null when either side is unparsable** — callers MUST treat null as
+ *   "direction unknown" and fail closed rather than coercing it to a number
+ *   (`null` compares as `0` in JS numeric contexts, which would read as "equal").
+ */
+export function compareSemver(a: unknown, b: unknown): number | null {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (!pa || !pb) return null;
+    if (pa.major !== pb.major) return pa.major < pb.major ? -1 : 1;
+    if (pa.minor !== pb.minor) return pa.minor < pb.minor ? -1 : 1;
+    if (pa.patch !== pb.patch) return pa.patch < pb.patch ? -1 : 1;
+    return comparePrerelease(pa.prerelease, pb.prerelease);
+}
+
+/**
+ * Would installing `target` move a daemon currently on `current` BACKWARDS?
+ *
+ * Returns false when the direction cannot be established (either version
+ * unparsable) — an unknown direction must never block an upgrade, because the
+ * cost of a false block (the whole fleet can no longer be upgraded) is far
+ * higher than the cost of a missed downgrade guard. Equal versions are NOT a
+ * downgrade, so a same-version reinstall stays allowed.
+ */
+export function isDowngrade(current: unknown, target: unknown): boolean {
+    const direction = compareSemver(target, current);
+    if (direction === null) return false;
+    return direction < 0;
+}

package/src/ws-protocol.ts

@@ -0,0 +1,90 @@
+/**
+ * ws-protocol — shared string-literal unions for the daemon↔server WS surface
+ * and the daemon↔dashboard P2P DataChannel surface.
+ *
+ * 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.
+ */
+
+/** 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';
+
+/** 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';
+
+/** 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';
+
+/**
+ * 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).
+ */
+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 const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[] = [
+    'auth', 'status_report', 'status_heartbeat', 'status_event', 'command_result', 'error', 'agent_event', 'log',
+];
+
+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',
+];
+
+export function isDaemonToServerWsMsg(value: unknown): value is DaemonToServerWsMsg {
+    return typeof value === 'string' && (DAEMON_TO_SERVER_WS_MSGS as readonly string[]).includes(value);
+}
+
+export function isServerToDaemonWsMsg(value: unknown): value is ServerToDaemonWsMsg {
+    return typeof value === 'string' && (SERVER_TO_DAEMON_WS_MSGS as readonly string[]).includes(value);
+}