@adhdev/mesh-shared 1.0.56-rc.8 → 1.0.56

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_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_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: 58;
+export declare const CANONICAL_MESH_TOOL_COUNT: 59;

package/dist/node-facts.d.ts

@@ -75,10 +75,42 @@ export interface MeshNodeFactsProviderQuota {
          * rather than presenting them as a freshly measured value.
          */
         lastGoodWindows?: boolean;
+        /**
+         * Unix ms when the reporting node last ATTEMPTED a refresh of this
+         * provider — deliberately distinct from `updatedAt`, which dates the
+         * DATA. They differ for file-source providers (claude-cli reports its
+         * statusline snapshot's capture time, codex-cli the rollout entry's),
+         * whose `updatedAt` does not move while the source file is unchanged
+         * however often it is successfully re-read.
+         *
+         * A reader judging FRESHNESS wants `updatedAt`. This field answers the
+         * different question "is that node still looking?", which is what makes
+         * "3h old but re-checked a minute ago" distinguishable from "3h old and
+         * nobody has looked since". Absent on entries written by daemons
+         * predating the field.
+         */
+        fetchedAt?: number;
         [extra: string]: unknown;
     };
     [extra: string]: unknown;
 }
+/**
+ * One provider's enablement state on the reporting machine — see
+ * `MeshNodeFacts.providerEnablement`.
+ *
+ * Both fields are REQUIRED booleans on the wire even though the underlying
+ * config defaults are asymmetric (`enabled` defaults false, `quotaEnabled`
+ * defaults true). The producer resolves those defaults before stamping, so a
+ * reader never re-derives them — a second copy of the default rules is exactly
+ * the drift this shape avoids. Absence is expressed by omitting the whole
+ * provider entry (or the whole bundle field), never by a missing sub-field.
+ */
+export interface MeshNodeFactsProviderEnablement {
+    /** "This machine uses provider X" — gates launching and mesh claims. */
+    enabled: boolean;
+    /** "...and its quota is probed here" — an independent user opt-out. */
+    quotaEnabled: boolean;
+}
 export interface MeshNodeFacts {
     schemaVersion: number;
     reportedAt: number;
@@ -118,6 +150,31 @@ export interface MeshNodeFacts {
      * rule: quotaSnapshotAgeMs in daemon-core mesh-quota-routing.ts).
      */
     quota?: Record<string, MeshNodeFactsProviderQuota>;
+    /**
+     * Per-provider ENABLEMENT state on the reporting machine, keyed the same
+     * way as `quota`. Exists because `quota` alone cannot answer "why is there
+     * no snapshot": a provider that is disabled — on either axis — is pruned
+     * from the quota cache entirely (daemon-core quota/refresh.ts drops it and
+     * refuses to restore it from disk), so a deliberate opt-out and a
+     * never-yet-measured provider both arrive as the SAME absent entry. On the
+     * node that owns the config that ambiguity is resolvable by reading the
+     * config; for every OTHER node in the mesh it was not resolvable at all,
+     * which is what this field fixes.
+     *
+     * The two axes mirror ProviderLoader exactly and are INDEPENDENT:
+     * `enabled` is "this machine uses provider X" (gates launching and mesh
+     * claims), `quotaEnabled` gates ONLY the quota probe — a machine can use a
+     * provider and still opt out of having its usage read.
+     *
+     * ★An ABSENT bundle field means "this node did not tell us" — a daemon too
+     * old to send it — and must NEVER be read as "disabled". The consumer
+     * (daemon-core mesh-quota-routing.ts classifyAbsentQuotaReason) keeps its
+     * unclassified fallback for exactly that case; treating absence as
+     * disabled would invent a fail-closed verdict out of a missing field.
+     *
+     * Booleans keyed by provider type only — no free text, no credentials.
+     */
+    providerEnablement?: Record<string, MeshNodeFactsProviderEnablement>;
     /** Future fields ride through opaquely — do not enumerate them in relays. */
     [extra: string]: unknown;
 }
@@ -159,11 +216,13 @@ export declare function normalizeMeshNodeFacts(raw: unknown): MeshNodeFacts | un
  * ★antigravity-cli was likewise twice judged impossible, from reading
  * `agy --help` where the usage view does not appear because it is a TUI view.
  * Its quota comes from the SHARED Gemini Code Assist backend
- * (`cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary`), and its
- * credential lives in the OS keyring, not the stale on-disk token file — see
- * the provenance note in daemon-core `quota/fetchers/antigravity.ts`. It is
- * macOS-only by design; other platforms report `unsupported` rather than guess
- * at a keyring backend nobody has verified.
+ * (`daily-cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary` —
+ * the host `agy` itself uses; the unprefixed `cloudcode-pa` host 429s Google
+ * AI Pro Antigravity accounts), and its credential lives in the OS keyring,
+ * not the stale on-disk token file — see the provenance note in daemon-core
+ * `quota/fetchers/antigravity.ts`. Supported on macOS and Windows; other
+ * platforms report `unsupported` rather than guess at a keyring backend
+ * nobody has verified.
  *
  * ★Adding a provider here without adding its fetcher to REFRESHERS re-creates
  * exactly the "switch that does nothing" this constant prevents.

package/dist/rpc-chunking.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Mesh RPC frame chunking — split/reassemble oversized mesh envelopes.
+ *
+ * WHY THIS EXISTS
+ * The mesh DataChannel path (`daemon-mesh-manager`) writes every RPC envelope as a
+ * SINGLE `dc.sendMessage(JSON.stringify(envelope))` frame. That was fine while every
+ * mesh arg was small text, but a coordinator dispatching an IMAGE to a worker puts a
+ * multi-MB base64 part inside `args` — far past what one DataChannel frame carries, so
+ * the send throws or the frame is dropped and the dispatch silently dies.
+ *
+ * The dashboard P2P path already solved exactly this problem and has been running in
+ * production: `packages/daemon-cloud/src/daemon-p2p/data-channel-router.ts` (send +
+ * reassemble) and `packages/web-cloud/src/p2p.ts` (browser side). This module is a PORT
+ * of that proven scheme onto the mesh envelope shape — deliberately NOT a new protocol.
+ * The boundary values are carried over unchanged (see the constants below for why each
+ * one is what it is).
+ *
+ * It lives in mesh-shared because it is pure string/JSON work with no transport, no
+ * Node API and no DOM API — the same reason the normalizers live here. `daemon-cloud`
+ * (sender/receiver) is the only current consumer, but keeping it in the pure leaf means
+ * the standalone side can reassemble with the identical code rather than a hand-synced
+ * copy, which is the drift bug class this package was created to kill.
+ *
+ * FAILURE POLICY (DoD): reassembly never degrades silently. A malformed, out-of-range,
+ * over-budget or unparseable chunk stream yields an explicit typed failure that the
+ * caller turns into an RPC error — never a partially-applied or truncated envelope.
+ */
+/**
+ * Inline ceiling: an envelope whose JSON is at or below this goes out as one frame,
+ * exactly as before this module existed. 60_000 (not 65_536) matches the dashboard
+ * path and leaves headroom under the common 64KiB SCTP message limit so the frame is
+ * never the thing that trips a transport-level cap.
+ */
+export declare const MESH_MAX_INLINE_FRAME_BYTES = 60000;
+/**
+ * Per-chunk payload slice, in CHARACTERS. Ported unchanged from the dashboard path.
+ *
+ * Why 16_000 chars is safe under a 60_000-BYTE ceiling, with ~3.75x of headroom:
+ * `splitMeshFrame` slices the ALREADY-SERIALIZED outer frame, so the text being cut
+ * is JSON output — control characters are pre-expanded to `\u00XX` ASCII before they
+ * ever reach the slicer. Re-escaping that slice inside the chunk envelope can at worst
+ * double the backslashes. Measured worst cases for a 16_000-char slice:
+ *   backslashes / astral emoji  → 32,073 bytes
+ *   Korean (3-byte, unescaped)  → 48,073 bytes   ← densest observed
+ *   plain ASCII                 → 16,073 bytes
+ * All are under MESH_MAX_INLINE_FRAME_BYTES. `splitMeshFrame` still MEASURES each
+ * envelope and shrinks on overflow, so the guarantee is enforced rather than assumed
+ * if either constant is ever retuned — but at these values that path is unreachable,
+ * which is exactly what `assertMeshChunkConstantsAreSafe` pins down.
+ */
+export declare const MESH_CHUNK_PAYLOAD_CHARS = 16000;
+/**
+ * Hard cap on chunk count for one frame. 1024 × ~16KB ≈ 16MB of transferable payload,
+ * which comfortably covers a screenshot while bounding what a single peer can make the
+ * receiver buffer. Exceeding it is an explicit refusal, never a truncated send.
+ */
+export declare const MESH_MAX_CHUNKS = 1024;
+/**
+ * Reassembly budget for one frame, in bytes. Bounds receiver memory independently of
+ * chunk count so a peer cannot send 1024 maximally-large chunks to force an oversized
+ * allocation. Mirrors the dashboard receiver's MAX_REASSEMBLED_JSON_BYTES.
+ */
+export declare const MESH_MAX_REASSEMBLED_BYTES = 16000000;
+/**
+ * How long a partially-received frame is retained. A sender that dies mid-stream must
+ * not pin receiver memory forever; the partial is swept and the frame simply never
+ * completes (the RPC's own deadline then reports it).
+ */
+export declare const MESH_CHUNK_TTL_MS = 60000;
+/** Envelope `kind` for a chunk of a larger mesh frame. */
+export declare const MESH_CHUNK_KIND = "rpc_chunk";
+export interface MeshChunkEnvelope {
+    v: number;
+    kind: typeof MESH_CHUNK_KIND;
+    /** Groups the chunks of one logical frame. */
+    chunkId: string;
+    /** 0-based position of this chunk. */
+    index: number;
+    /** Total chunk count for this frame; constant across the group. */
+    total: number;
+    /** The slice of the original envelope JSON. */
+    data: string;
+}
+export type MeshChunkSplitResult = {
+    ok: true;
+    chunks: MeshChunkEnvelope[];
+} | {
+    ok: false;
+    reason: 'too_many_chunks' | 'chunk_too_large';
+    detail: string;
+};
+export type MeshChunkAcceptResult = 
+/** Chunk stored; the frame is not complete yet. */
+{
+    status: 'partial';
+    received: number;
+    total: number;
+}
+/** Final chunk landed and the frame parsed cleanly. */
+ | {
+    status: 'complete';
+    frame: unknown;
+}
+/** Explicitly rejected — the caller must surface this, never ignore it. */
+ | {
+    status: 'failed';
+    reason: MeshChunkFailureReason;
+    detail: string;
+    chunkId: string;
+};
+export type MeshChunkFailureReason = 'malformed_chunk' | 'too_many_chunks' | 'inconsistent_total' | 'duplicate_chunk_mismatch' | 'budget_exceeded' | 'reassembled_parse_failed';
+/** UTF-8 byte length without assuming Buffer or TextEncoder is present. */
+export declare function meshUtf8ByteLength(value: string): number;
+/**
+ * Worst-case size of one chunk envelope at the current constants.
+ *
+ * Exported so the safety margin documented on MESH_CHUNK_PAYLOAD_CHARS is a CHECKED
+ * invariant rather than a comment that rots. The densest slice the splitter can produce
+ * is 3-byte unescaped text (JSON.stringify leaves non-ASCII as-is), so that is what this
+ * measures. If someone raises MESH_CHUNK_PAYLOAD_CHARS or lowers the frame ceiling past
+ * the safe point, the accompanying test fails loudly instead of the overflow only
+ * showing up as dropped frames on a live mesh.
+ */
+export declare function measureWorstCaseChunkEnvelopeBytes(): number;
+/** True when the serialized frame must be chunked rather than sent inline. */
+export declare function meshFrameNeedsChunking(json: string): boolean;
+/**
+ * Split a serialized mesh envelope into chunk envelopes.
+ *
+ * Each slice is measured AS ITS FINAL SERIALIZED ENVELOPE and shrunk (×0.8, as in the
+ * dashboard implementation) until it fits the inline ceiling — so multi-byte UTF-8 and
+ * the envelope overhead are both accounted for rather than assumed away. `total` is
+ * stamped only after the full split is known, so every chunk in a group agrees.
+ */
+export declare function splitMeshFrame(json: string, chunkId: string, version: number): MeshChunkSplitResult;
+/**
+ * Receiver-side reassembly buffer, one per peer connection.
+ *
+ * Keyed by chunkId only — callers construct one assembler per peer, so chunk groups
+ * from different peers can never collide in the same map.
+ */
+export declare class MeshChunkAssembler {
+    private readonly now;
+    private readonly buffers;
+    constructor(now?: () => number);
+    /** True when the frame is a chunk envelope this assembler should handle. */
+    static isChunkFrame(frame: unknown): boolean;
+    /** Drop partials older than the TTL so a dead sender cannot pin memory. */
+    private sweep;
+    /** Discard any partial state for a peer (call on disconnect). */
+    reset(): void;
+    /** Number of frames currently mid-reassembly — for tests and diagnostics. */
+    get pendingCount(): number;
+    /**
+     * Accept one chunk envelope.
+     *
+     * Never throws and never returns a partially-applied frame: the result is exactly one
+     * of partial / complete / failed, and `failed` carries a typed reason the transport
+     * turns into an explicit RPC error.
+     */
+    accept(frame: unknown): MeshChunkAcceptResult;
+}

package/package.json

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

@@ -25,3 +25,4 @@ export * from './slot-proposal'
 export * from './interpolation'
 export * from './mesh-tool-names'
 export * from './mesh-status-probe'
+export * from './rpc-chunking'

package/src/mesh-tool-names.ts

@@ -29,6 +29,7 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_graph_view',
     'mesh_graph_gate_claim',
     'mesh_graph_gate_release',
+    'mesh_graph_gate_abandon',
     'mesh_queue_cancel',
     'mesh_queue_requeue',
     'mesh_send_task',

package/src/node-facts.ts

@@ -78,11 +78,44 @@ export interface MeshNodeFactsProviderQuota {
          * rather than presenting them as a freshly measured value.
          */
         lastGoodWindows?: boolean
+        /**
+         * Unix ms when the reporting node last ATTEMPTED a refresh of this
+         * provider — deliberately distinct from `updatedAt`, which dates the
+         * DATA. They differ for file-source providers (claude-cli reports its
+         * statusline snapshot's capture time, codex-cli the rollout entry's),
+         * whose `updatedAt` does not move while the source file is unchanged
+         * however often it is successfully re-read.
+         *
+         * A reader judging FRESHNESS wants `updatedAt`. This field answers the
+         * different question "is that node still looking?", which is what makes
+         * "3h old but re-checked a minute ago" distinguishable from "3h old and
+         * nobody has looked since". Absent on entries written by daemons
+         * predating the field.
+         */
+        fetchedAt?: number
         [extra: string]: unknown
     }
     [extra: string]: unknown
 }
 
+/**
+ * One provider's enablement state on the reporting machine — see
+ * `MeshNodeFacts.providerEnablement`.
+ *
+ * Both fields are REQUIRED booleans on the wire even though the underlying
+ * config defaults are asymmetric (`enabled` defaults false, `quotaEnabled`
+ * defaults true). The producer resolves those defaults before stamping, so a
+ * reader never re-derives them — a second copy of the default rules is exactly
+ * the drift this shape avoids. Absence is expressed by omitting the whole
+ * provider entry (or the whole bundle field), never by a missing sub-field.
+ */
+export interface MeshNodeFactsProviderEnablement {
+    /** "This machine uses provider X" — gates launching and mesh claims. */
+    enabled: boolean
+    /** "...and its quota is probed here" — an independent user opt-out. */
+    quotaEnabled: boolean
+}
+
 export interface MeshNodeFacts {
     schemaVersion: number
     reportedAt: number
@@ -122,6 +155,31 @@ export interface MeshNodeFacts {
      * rule: quotaSnapshotAgeMs in daemon-core mesh-quota-routing.ts).
      */
     quota?: Record<string, MeshNodeFactsProviderQuota>
+    /**
+     * Per-provider ENABLEMENT state on the reporting machine, keyed the same
+     * way as `quota`. Exists because `quota` alone cannot answer "why is there
+     * no snapshot": a provider that is disabled — on either axis — is pruned
+     * from the quota cache entirely (daemon-core quota/refresh.ts drops it and
+     * refuses to restore it from disk), so a deliberate opt-out and a
+     * never-yet-measured provider both arrive as the SAME absent entry. On the
+     * node that owns the config that ambiguity is resolvable by reading the
+     * config; for every OTHER node in the mesh it was not resolvable at all,
+     * which is what this field fixes.
+     *
+     * The two axes mirror ProviderLoader exactly and are INDEPENDENT:
+     * `enabled` is "this machine uses provider X" (gates launching and mesh
+     * claims), `quotaEnabled` gates ONLY the quota probe — a machine can use a
+     * provider and still opt out of having its usage read.
+     *
+     * ★An ABSENT bundle field means "this node did not tell us" — a daemon too
+     * old to send it — and must NEVER be read as "disabled". The consumer
+     * (daemon-core mesh-quota-routing.ts classifyAbsentQuotaReason) keeps its
+     * unclassified fallback for exactly that case; treating absence as
+     * disabled would invent a fail-closed verdict out of a missing field.
+     *
+     * Booleans keyed by provider type only — no free text, no credentials.
+     */
+    providerEnablement?: Record<string, MeshNodeFactsProviderEnablement>
     /** Future fields ride through opaquely — do not enumerate them in relays. */
     [extra: string]: unknown
 }
@@ -173,11 +231,13 @@ export function normalizeMeshNodeFacts(raw: unknown): MeshNodeFacts | undefined
  * ★antigravity-cli was likewise twice judged impossible, from reading
  * `agy --help` where the usage view does not appear because it is a TUI view.
  * Its quota comes from the SHARED Gemini Code Assist backend
- * (`cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary`), and its
- * credential lives in the OS keyring, not the stale on-disk token file — see
- * the provenance note in daemon-core `quota/fetchers/antigravity.ts`. It is
- * macOS-only by design; other platforms report `unsupported` rather than guess
- * at a keyring backend nobody has verified.
+ * (`daily-cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary` —
+ * the host `agy` itself uses; the unprefixed `cloudcode-pa` host 429s Google
+ * AI Pro Antigravity accounts), and its credential lives in the OS keyring,
+ * not the stale on-disk token file — see the provenance note in daemon-core
+ * `quota/fetchers/antigravity.ts`. Supported on macOS and Windows; other
+ * platforms report `unsupported` rather than guess at a keyring backend
+ * nobody has verified.
  *
  * ★Adding a provider here without adding its fetcher to REFRESHERS re-creates
  * exactly the "switch that does nothing" this constant prevents.