@openscout/protocol 0.2.98 → 0.2.104

package/dist/herdr-workspace-digest.js

@@ -0,0 +1,343 @@
+/**
+ * Herdr workspace digest — the presentation layer over {@link HerdrSessionTopology}.
+ *
+ * The raw projection is faithful but shapeless: a complex session is several
+ * workspaces × tabs × panes, and handing that whole tree to an operator (or to
+ * an assistant that has to answer for it) buries the one thing they came for.
+ * A digest ranks, groups, bounds, and describes it.
+ *
+ * Four commitments, in order of how much they matter:
+ *
+ * 1. **Attention leads.** A `blocked` pane is the only thing in a herdr session
+ *    that is actually waiting on a person. It comes first, always, before any
+ *    inventory. Everything else is context for it.
+ * 2. **Directory is the grouping axis, not the tab.** Operators think "which
+ *    repo", herdr thinks "which tab". Grouping is by the pane's literal working
+ *    directory — no repo-root inference, because a guessed grouping presented as
+ *    a fact is worse than an honest fragmented one.
+ * 3. **Shape is described, not dumped.** A tab's layout becomes one readable
+ *    phrase ("2×2 grid", "3 columns (2 · 1 · 1)") derived from the pane rects.
+ * 4. **Bounded and honest.** Panes are capped and truncation is declared;
+ *    `unknown` never collapses into `done`; a persisted projection is labeled
+ *    last-known rather than passed off as live.
+ *
+ * There are no mutation verbs here, for the same reason there are none in the
+ * topology projection: herdr owns workspaces, tabs and panes, and Scout's layer
+ * is coordination over whatever host is present. A digest pane carries the
+ * herdr `target` string so a caller can construct a handoff; performing it is
+ * the herdr client's job.
+ */
+/** Total emitted panes across every group before the digest declares truncation. */
+export const HERDR_DIGEST_PANE_CAP = 40;
+/** Ceiling on each of the two lead lists; attention is a shortlist, not an inventory. */
+export const HERDR_DIGEST_LEAD_CAP = 12;
+const EMPTY_COUNTS = { blocked: 0, working: 0, idle: 0, done: 0, unknown: 0 };
+/** Attention order. Blocked outranks working because it is the only state that waits on a person. */
+const STATUS_RANK = {
+    blocked: 5,
+    working: 4,
+    idle: 3,
+    done: 2,
+    unknown: 1,
+};
+export function herdrStatusRank(status) {
+    return STATUS_RANK[status];
+}
+function emptyCounts() {
+    return { ...EMPTY_COUNTS };
+}
+function totalCount(counts) {
+    return counts.blocked + counts.working + counts.idle + counts.done + counts.unknown;
+}
+function paneDirectory(pane) {
+    return pane.foregroundCwd ?? pane.cwd ?? null;
+}
+function directoryName(directory) {
+    if (!directory)
+        return "no directory";
+    const segments = directory.replace(/\/+$/, "").split("/").filter(Boolean);
+    return segments[segments.length - 1] ?? directory;
+}
+function toDigestPane(pane) {
+    return {
+        target: pane.terminalId ?? pane.paneId ?? null,
+        paneId: pane.paneId,
+        workspaceId: pane.workspaceId,
+        tabId: pane.tabId,
+        label: pane.label,
+        agent: pane.agent,
+        status: pane.agentStatus,
+        directory: paneDirectory(pane),
+        focused: pane.focused,
+        backlog: pane.scroll?.maxOffsetFromBottom ?? null,
+    };
+}
+/**
+ * Rank panes for a lead list: attention state, then the focused pane (where the
+ * operator's eyes already are), then the deepest backlog, then pane id so the
+ * order never wobbles between polls.
+ */
+function compareLeadPanes(left, right) {
+    const byStatus = STATUS_RANK[right.status] - STATUS_RANK[left.status];
+    if (byStatus !== 0)
+        return byStatus;
+    if (left.focused !== right.focused)
+        return left.focused ? -1 : 1;
+    const byBacklog = (right.backlog ?? -1) - (left.backlog ?? -1);
+    if (byBacklog !== 0)
+        return byBacklog;
+    return left.paneId.localeCompare(right.paneId, undefined, { numeric: true });
+}
+/**
+ * Describe a tab's arrangement from its pane rects.
+ *
+ * Panes sharing an x start a column; panes sharing a y start a row. A layout
+ * whose columns all hold the same number of panes is a grid and is named as
+ * one; anything else is named by its columns and their depths, which is both
+ * shorter and more truthful than inventing a name for an irregular split.
+ */
+export function describeHerdrArrangement(layout, paneCount) {
+    if (paneCount <= 0)
+        return "no panes";
+    if (paneCount === 1)
+        return "single pane";
+    const panes = layout?.panes ?? [];
+    if (panes.length !== paneCount)
+        return `${paneCount} panes (layout unavailable)`;
+    const columns = new Map();
+    const rows = new Map();
+    for (const pane of panes) {
+        columns.set(pane.rect.x, (columns.get(pane.rect.x) ?? 0) + 1);
+        rows.set(pane.rect.y, (rows.get(pane.rect.y) ?? 0) + 1);
+    }
+    if (columns.size === 1)
+        return `${paneCount} stacked rows`;
+    if (rows.size === 1)
+        return `${paneCount} side-by-side columns`;
+    const depths = [...columns.entries()]
+        .sort((left, right) => left[0] - right[0])
+        .map(([, count]) => count);
+    const first = depths[0] ?? 0;
+    if (depths.every((depth) => depth === first) && first * columns.size === paneCount) {
+        return `${first}×${columns.size} grid`;
+    }
+    return `${columns.size} columns (${depths.join(" · ")})`;
+}
+/**
+ * Build the digest for one herdr session topology.
+ *
+ * Pure: the same topology always digests to the same value, so the whole
+ * presentation is testable without a herdr server.
+ */
+export function digestHerdrTopology(topology, options = {}) {
+    const paneCap = options.paneCap ?? HERDR_DIGEST_PANE_CAP;
+    const leadCap = options.leadCap ?? HERDR_DIGEST_LEAD_CAP;
+    const counts = emptyCounts();
+    const shapes = [];
+    const all = [];
+    let tabTotal = 0;
+    let agentTotal = 0;
+    for (const workspace of topology.workspaces) {
+        const workspaceLabel = workspace.label ?? (workspace.number != null ? `workspace ${workspace.number}` : workspace.workspaceId);
+        for (const tab of workspace.tabs) {
+            tabTotal += 1;
+            shapes.push({
+                workspaceId: workspace.workspaceId,
+                workspaceLabel,
+                tabId: tab.tabId,
+                tabLabel: tab.label ?? (tab.number != null ? `tab ${tab.number}` : tab.tabId),
+                paneCount: tab.panes.length,
+                arrangement: describeHerdrArrangement(tab.layout, tab.panes.length),
+                zoomed: tab.layout?.zoomed ?? false,
+                focused: workspace.focused && tab.focused,
+            });
+            for (const pane of tab.panes) {
+                const digestPane = toDigestPane(pane);
+                counts[digestPane.status] += 1;
+                if (digestPane.agent)
+                    agentTotal += 1;
+                all.push(digestPane);
+            }
+        }
+    }
+    // Groups are filled in rank order so the pane cap spends its budget on the
+    // panes that matter, not on whichever directory herdr happened to list first.
+    const ranked = [...all].sort(compareLeadPanes);
+    const kept = ranked.slice(0, paneCap);
+    const droppedByDirectory = new Map();
+    for (const pane of ranked.slice(paneCap)) {
+        const key = pane.directory ?? "";
+        let dropped = droppedByDirectory.get(key);
+        if (!dropped) {
+            dropped = emptyCounts();
+            droppedByDirectory.set(key, dropped);
+        }
+        dropped[pane.status] += 1;
+    }
+    const groupsByDirectory = new Map();
+    for (const pane of all) {
+        const key = pane.directory ?? "";
+        let group = groupsByDirectory.get(key);
+        if (!group) {
+            group = {
+                directory: pane.directory,
+                name: directoryName(pane.directory),
+                counts: emptyCounts(),
+                panes: [],
+                omitted: totalCount(droppedByDirectory.get(key) ?? EMPTY_COUNTS),
+                omittedCounts: { ...(droppedByDirectory.get(key) ?? EMPTY_COUNTS) },
+            };
+            groupsByDirectory.set(key, group);
+        }
+        group.counts[pane.status] += 1;
+    }
+    const keptIds = new Set(kept.map((pane) => `${pane.workspaceId}/${pane.paneId}`));
+    for (const pane of all) {
+        if (!keptIds.has(`${pane.workspaceId}/${pane.paneId}`))
+            continue;
+        groupsByDirectory.get(pane.directory ?? "")?.panes.push(pane);
+    }
+    const groups = [...groupsByDirectory.values()];
+    for (const group of groups)
+        group.panes.sort(compareLeadPanes);
+    // Groups sort by what is waiting, then what is moving, then size — the same
+    // precedence the lead lists use, applied one level up.
+    groups.sort((left, right) => right.counts.blocked - left.counts.blocked
+        || right.counts.working - left.counts.working
+        || (right.panes.length + right.omitted) - (left.panes.length + left.omitted)
+        || left.name.localeCompare(right.name, undefined, { numeric: true }));
+    const notes = [];
+    if (!topology.running) {
+        // "Last known" is only useful with a when: a layout saved an hour ago and
+        // one saved in March are the same claim with very different weight.
+        const saved = topology.savedAt ? ` Last saved ${new Date(topology.savedAt).toISOString()}.` : "";
+        notes.push(topology.unavailable === "unreadable"
+            // The session IS running; herdr just would not answer. Saying "stopped"
+            // here would be the one thing a digest must never do — state, of live
+            // work, that it is not live.
+            ? `A herdr server for this session is running but did not answer, so this is the persisted last-known layout, not what is on screen. The usual cause is a protocol skew between the installed herdr client and a long-lived server; restarting that session's server (which exits its pane processes) is what clears it.${saved}`
+            : `Not live: this is the persisted last-known layout. Agent status, terminal ids and geometry are absent from it — no pane here is claimed to be running.${saved}`);
+    }
+    if (counts.unknown > 0) {
+        notes.push(`${counts.unknown} ${counts.unknown === 1 ? "pane reports" : "panes report"} unknown: herdr sees an agent it cannot classify. Unknown is the absence of a signal, not completion.`);
+    }
+    return {
+        session: topology.session,
+        live: topology.running,
+        observedAt: topology.observedAt,
+        savedAt: topology.savedAt ?? null,
+        unavailable: topology.running ? null : topology.unavailable ?? "not_running",
+        totals: {
+            workspaces: topology.workspaces.length,
+            tabs: tabTotal,
+            panes: all.length,
+            agents: agentTotal,
+        },
+        counts,
+        needsYou: ranked.filter((pane) => pane.status === "blocked").slice(0, leadCap),
+        working: ranked.filter((pane) => pane.status === "working").slice(0, leadCap),
+        groups,
+        shapes,
+        truncated: all.length > paneCap,
+        notes,
+    };
+}
+/**
+ * One row, led by whatever is most specific to this pane.
+ *
+ * Rows that all begin `term-w1:p1`, `term-w1:p2` share a long prefix, and a
+ * scanning reader learns to skip the opening of every line — so the identity
+ * column becomes the one column nobody reads. The lead is therefore the pane's
+ * label when it has one, and its pane id when it does not, since a short id
+ * differs within the first couple of characters where a terminal id does not.
+ *
+ * The pane id is enough to act on: `herdr agent <verb>` accepts the pane
+ * currently hosting an agent as a target. The directory is the basename only —
+ * the full path is carried once, in the grouped section, and repeating it on
+ * every row buys nothing.
+ */
+function paneLine(pane) {
+    const parts = pane.label
+        ? [pane.label, pane.agent ?? "shell", pane.paneId]
+        : [pane.paneId, pane.agent ?? "shell"];
+    if (pane.directory)
+        parts.push(directoryName(pane.directory));
+    if (pane.focused)
+        parts.push("focused");
+    return `  ${parts.join("  ")}`;
+}
+/** "2 idle not shown" — a collapsed label a reader can decide from. */
+function omittedLabel(counts) {
+    const total = totalCount(counts);
+    if (total === 0)
+        return null;
+    const order = ["blocked", "working", "idle", "done", "unknown"];
+    const present = order.filter((status) => counts[status] > 0);
+    if (present.length === 1)
+        return `+${total} ${present[0]} not shown`;
+    return `+${total} not shown (${present.map((status) => `${counts[status]} ${status}`).join(" · ")})`;
+}
+function countsLine(counts) {
+    const order = ["blocked", "working", "idle", "done", "unknown"];
+    const parts = order.filter((status) => counts[status] > 0).map((status) => `${counts[status]} ${status}`);
+    return parts.length ? parts.join(" · ") : "no panes";
+}
+/**
+ * Render a digest as the text an operator should actually read.
+ *
+ * Ordering is the whole design: what is waiting, then what is moving, then
+ * where things live, then how the screen is arranged. A reader who stops after
+ * the first section has still got the answer that mattered.
+ *
+ * Section heads are verb phrases rather than bare nouns, and there is no
+ * trailing caveat block: a qualifier that changes how a count should be read
+ * sits directly under that count, because a scanning reader reaches the top of
+ * the output and not the bottom of it.
+ */
+export function renderHerdrWorkspaceDigest(digest) {
+    const lines = [];
+    const state = digest.live
+        ? "live"
+        : digest.unavailable === "unreadable" ? "running, not readable" : "not running";
+    const { workspaces, tabs, panes } = digest.totals;
+    lines.push(`herdr · ${digest.session} — ${state} · ${workspaces} workspace${workspaces === 1 ? "" : "s"}, ${tabs} tab${tabs === 1 ? "" : "s"}, ${panes} pane${panes === 1 ? "" : "s"} (${countsLine(digest.counts)})`);
+    // Caveats sit under the counts they qualify, not in a block at the bottom.
+    // A qualifier that changes how a number should be read is body text; a
+    // scanning reader never reaches a footnote, and these are the lines that stop
+    // someone believing `unknown` meant done or that a stale layout was current.
+    for (const note of digest.notes)
+        lines.push(`  ${note}`);
+    if (digest.needsYou.length) {
+        lines.push("", "Waiting on you");
+        for (const pane of digest.needsYou)
+            lines.push(paneLine(pane));
+    }
+    if (digest.working.length) {
+        lines.push("", "Working now");
+        for (const pane of digest.working)
+            lines.push(paneLine(pane));
+    }
+    if (digest.groups.length) {
+        lines.push("", "Grouped by directory");
+        for (const group of digest.groups) {
+            const total = totalCount(group.counts);
+            const where = group.directory ? ` (${group.directory})` : "";
+            const hidden = omittedLabel(group.omittedCounts);
+            lines.push(`  ${group.name}${where} — ${total} pane${total === 1 ? "" : "s"} · ${countsLine(group.counts)}${hidden ? ` · ${hidden}` : ""}`);
+        }
+    }
+    if (digest.shapes.length) {
+        lines.push("", "Arranged like this");
+        for (const shape of digest.shapes) {
+            const marks = [shape.arrangement];
+            if (shape.zoomed)
+                marks.push("zoomed");
+            if (shape.focused)
+                marks.push("focused");
+            // The tab id leads because two workspaces can carry the same label, and
+            // a label can itself contain the separator — the id cannot do either.
+            lines.push(`  ${shape.tabId}  ${shape.workspaceLabel} / ${shape.tabLabel} — ${marks.join(" · ")}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -7,9 +7,12 @@ export * from "./a2a.js";
 export * from "./scout-agent-card.js";
 export * from "./relay-agent-card.js";
 export * from "./mesh.js";
+export * from "./machines.js";
 export * from "./conversations.js";
 export * from "./conversation-projection.js";
 export * from "./channel-identity.js";
+export * from "./channel-invites.js";
+export * from "./channel-reception.js";
 export * from "./collaboration.js";
 export * from "./assigned-roles.js";
 export * from "./orchestrator-prompt.js";
@@ -53,6 +56,7 @@ export * from "./terminal-surface-id.js";
 export * from "./terminal-sessions.js";
 export * from "./terminal-workspaces.js";
 export * from "./terminal-host-topology.js";
+export * from "./herdr-workspace-digest.js";
 export * from "./broker-routes.js";
 export * from "./rendezvous.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -7,9 +7,12 @@ export * from "./a2a.js";
 export * from "./scout-agent-card.js";
 export * from "./relay-agent-card.js";
 export * from "./mesh.js";
+export * from "./machines.js";
 export * from "./conversations.js";
 export * from "./conversation-projection.js";
 export * from "./channel-identity.js";
+export * from "./channel-invites.js";
+export * from "./channel-reception.js";
 export * from "./collaboration.js";
 export * from "./assigned-roles.js";
 export * from "./orchestrator-prompt.js";
@@ -53,5 +56,6 @@ export * from "./terminal-surface-id.js";
 export * from "./terminal-sessions.js";
 export * from "./terminal-workspaces.js";
 export * from "./terminal-host-topology.js";
+export * from "./herdr-workspace-digest.js";
 export * from "./broker-routes.js";
 export * from "./rendezvous.js";

package/dist/machines.d.ts

@@ -0,0 +1,233 @@
+import type { AdvertiseScope, MetadataMap, ScoutId } from "./common.js";
+/**
+ * Machines — the physical (or virtual) boxes Scout knows about.
+ *
+ * A machine is NOT a node. A node is a Scout broker runtime; a machine is the
+ * computer it runs on. The distinction matters because most machines Scout can
+ * see are not running Scout at all: a tailnet peer, a Mac advertising itself on
+ * the LAN, a Linux box that only answers ARP. Modelling them as nodes would
+ * either invent fake nodes or make them invisible, and both were wrong.
+ *
+ * A machine record is assembled from **evidence**, never asserted. Four
+ * channels report independently and none of them is authoritative:
+ *
+ * | channel   | tells us                                        |
+ * | --------- | ----------------------------------------------- |
+ * | `scout`   | a broker node lives here (id, mesh, urls)       |
+ * | `tailnet` | reachable over Tailscale (stable peer id, IPs)  |
+ * | `lan`     | seen on this network (mDNS advert, ARP neighbor)|
+ * | `host`    | terminal hosts present (herdr, tmux, zellij)    |
+ *
+ * The join between them is `machineIdentityKeys` + `groupMachineEvidence`.
+ * Everything else in this module is a pure derivation over a group, so the
+ * whole model is testable without a network, a broker, or a database.
+ */
+export declare const MACHINE_ID_PREFIX = "mach-";
+export type MachineEvidenceKind = "scout" | "tailnet" | "lan" | "host";
+export type MachinePlatform = "macos" | "linux" | "windows" | "ios" | "android" | "unknown";
+/**
+ * What a machine can do *for Scout*, as observed — never as configured. A
+ * capability is present because something answered, so an operator reading
+ * `herdr` on a row knows a herdr probe actually succeeded there.
+ */
+export type MachineCapability = "scout-broker" | "scout-web" | "scout-pairing" | "herdr" | "tmux" | "zellij" | "ssh" | "vnc" | "smb" | "http";
+export type MachineRouteKind = "loopback" | "lan" | "tailnet" | "mesh" | "relay";
+/** One way to reach a machine. Ordered by preference in `deriveMachineRoutes`. */
+export interface MachineRoute {
+    kind: MachineRouteKind;
+    host: string;
+    port?: number;
+    url?: string;
+    lastSeenAt?: number;
+}
+export type MachineTerminalHost = "herdr" | "tmux" | "zellij";
+export type LanDiscoveryMethod = "mdns" | "arp";
+interface MachineEvidenceBase {
+    kind: MachineEvidenceKind;
+    observedAt: number;
+}
+/** A Scout broker node registered with, or discovered by, this broker. */
+export interface ScoutMachineEvidence extends MachineEvidenceBase {
+    kind: "scout";
+    nodeId: ScoutId;
+    meshId?: ScoutId;
+    nodeName: string;
+    hostName?: string;
+    brokerUrl?: string;
+    webUrl?: string;
+    /** The node's named web doorway (`m1.scout.local`) — see NodeDefinition.webHost. */
+    webHost?: string;
+    advertiseScope?: AdvertiseScope;
+    tailnetName?: string;
+    isSelf?: boolean;
+}
+/** A `tailscale status` peer (or self). Present whether or not it runs Scout. */
+export interface TailnetMachineEvidence extends MachineEvidenceBase {
+    kind: "tailnet";
+    peerId: string;
+    hostName?: string;
+    dnsName?: string;
+    tailnetName?: string;
+    addresses: string[];
+    online: boolean;
+    os?: string;
+    tags?: string[];
+    isSelf?: boolean;
+}
+/** A local-network sighting: an mDNS service instance or an ARP neighbor. */
+export interface LanMachineEvidence extends MachineEvidenceBase {
+    kind: "lan";
+    method: LanDiscoveryMethod;
+    hostName?: string;
+    instanceName?: string;
+    /** Full service type as browsed, e.g. `_openscout._tcp`. */
+    serviceType?: string;
+    addresses: string[];
+    port?: number;
+    macAddress?: string;
+    /** Best-effort OUI vendor. Null whenever the prefix is not in the table. */
+    vendor?: string;
+    interfaceName?: string;
+    txt?: MetadataMap;
+}
+/** A terminal host observed on a machine Scout can probe. */
+export interface HostMachineEvidence extends MachineEvidenceBase {
+    kind: "host";
+    host: MachineTerminalHost;
+    /** Machine this was probed on — host probes are never self-identifying. */
+    hostName?: string;
+    nodeId?: ScoutId;
+    sessionCount: number;
+    runningSessionCount?: number;
+    version?: string;
+}
+export type MachineEvidence = ScoutMachineEvidence | TailnetMachineEvidence | LanMachineEvidence | HostMachineEvidence;
+/**
+ * Identity keys, split by how long they stay true.
+ *
+ * `durable` keys name the machine itself — a Tailscale node id, a MAC, a Scout
+ * node id, a hostname. They are persisted with the record and re-join evidence
+ * across passes, days apart.
+ *
+ * `transient` keys are only true right now. A LAN IP is the important one: it
+ * is what joins an ARP row to an mDNS advert *inside one scan*, and it is
+ * exactly what DHCP hands to a different machine next week. Persisting it
+ * would silently fuse two machines, so it never leaves the pass that saw it.
+ */
+export interface MachineIdentityKeys {
+    durable: string[];
+    transient: string[];
+}
+/** mDNS service types Scout browses, and what each one proves. */
+export declare const MACHINE_SERVICE_CAPABILITIES: Readonly<Record<string, MachineCapability>>;
+/** Browsed for inventory. `_workstation._tcp` proves nothing but presence. */
+export declare const MACHINE_LAN_SERVICE_TYPES: readonly string[];
+export declare function normalizeMachineHostName(value: string | null | undefined): string;
+/**
+ * Lowercase colon-form MAC. Returns "" for entries that identify nothing —
+ * broadcast, all-zero, or an incomplete ARP row.
+ *
+ * BSD `arp` drops leading zeros (`3c:22:fb:1:2:3`), so octets are padded
+ * rather than the string being scrubbed of separators: scrubbing turns that
+ * nine-character form into a rejected MAC instead of a valid one.
+ */
+export declare function normalizeMacAddress(value: string | null | undefined): string;
+export declare function normalizeMachineAddress(value: string | null | undefined): string;
+export declare function isLoopbackAddress(value: string): boolean;
+/** Tailscale's CGNAT range (100.64.0.0/10) and its IPv6 ULA prefix. */
+export declare function isTailnetAddress(value: string): boolean;
+/**
+ * The keys one piece of evidence claims. Two pieces of evidence describe the
+ * same machine when they share any key — see `groupMachineEvidence`.
+ */
+export declare function machineIdentityKeys(evidence: MachineEvidence): MachineIdentityKeys;
+export interface MachineEvidenceGroup {
+    /** Durable keys only — what gets persisted so the next pass re-joins here. */
+    identityKeys: string[];
+    evidence: MachineEvidence[];
+    /**
+     * Indices of every seed this group attached to, ascending. More than one
+     * means fresh evidence proved two records were always the same machine —
+     * the first is the survivor, the rest are absorbed by the caller.
+     */
+    seedIndices: number[];
+}
+/**
+ * Union-find over identity keys. Evidence lands in the same group when it
+ * shares any key, directly or through a chain — an ARP row and an mDNS advert
+ * share an IP; the advert and a tailnet peer share a hostname; so all three
+ * describe one machine even though ARP and Tailscale share nothing at all.
+ *
+ * `seeds` are the durable key sets of machines already on record. They enter
+ * the union as members, which is what lets a machine seen only by ARP today
+ * and only by Tailscale tomorrow stay one record: the seed bridges the passes.
+ */
+export declare function groupMachineEvidence(evidence: readonly MachineEvidence[], seeds?: readonly (readonly string[])[]): MachineEvidenceGroup[];
+/**
+ * Deterministic id from a group's durable keys, so two brokers observing the
+ * same machine mint the same id and a restart never renumbers the fleet.
+ * FNV-1a ×2, matching `stableChannelId`.
+ */
+export declare function stableMachineId(identityKeys: readonly string[]): ScoutId;
+/**
+ * The name to show. Scout's own name for the node wins because the operator
+ * chose it; then the tailnet hostname, then whatever the LAN advertised. A
+ * machine known only by MAC gets its MAC, never a fabricated label.
+ */
+export declare function deriveMachineName(evidence: readonly MachineEvidence[]): string;
+export declare function deriveMachinePlatform(evidence: readonly MachineEvidence[]): MachinePlatform;
+export declare function deriveMachineCapabilities(evidence: readonly MachineEvidence[]): MachineCapability[];
+/**
+ * Routes, best first: loopback (it's this machine), then LAN (no hop), then
+ * tailnet, then whatever the mesh advertised. This is the order a caller
+ * should dial, and it mirrors the LAN-first preference iOS already uses.
+ */
+/**
+ * Every way we know to reach this machine, best first. `isSelf` decides whether
+ * loopback belongs at all: a peer advertising `http://127.0.0.1:43120` is
+ * describing its own loopback, which is not a route to it from here.
+ */
+export declare function deriveMachineRoutes(evidence: readonly MachineEvidence[], isSelf?: boolean): MachineRoute[];
+export type MachinePresence = "online" | "recent" | "offline";
+/** Anything seen inside this window counts as present. */
+export declare const MACHINE_ONLINE_WINDOW_MS: number;
+export declare const MACHINE_RECENT_WINDOW_MS: number;
+export interface MachineRecord {
+    id: ScoutId;
+    /** Operator-set name. Null means "use `name`". */
+    displayName: string | null;
+    /** Derived from the strongest evidence — recomputed every pass. */
+    name: string;
+    platform: MachinePlatform;
+    /** Durable keys, sorted. The join key set for the next pass. */
+    identityKeys: string[];
+    isSelf: boolean;
+    scoutNodeId?: ScoutId;
+    meshId?: ScoutId;
+    tailnetId?: string;
+    tailnetName?: string;
+    hostNames: string[];
+    addresses: string[];
+    macAddresses: string[];
+    capabilities: MachineCapability[];
+    routes: MachineRoute[];
+    evidence: MachineEvidence[];
+    /** Operator marked it worth keeping even when nothing has seen it in weeks. */
+    pinned: boolean;
+    notes?: string;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    metadata?: MetadataMap;
+}
+export declare function machineLabel(machine: Pick<MachineRecord, "displayName" | "name">): string;
+export declare function machinePresence(machine: Pick<MachineRecord, "lastSeenAt">, now?: number): MachinePresence;
+/**
+ * Build (or rebuild) a record from a group. `previous` carries the parts an
+ * operator owns — id, chosen name, notes, pin, first-seen — which no amount of
+ * fresh evidence may overwrite.
+ */
+export declare function buildMachineRecord(group: MachineEvidenceGroup, previous?: Partial<MachineRecord> | null): MachineRecord;
+/** Sort for display: this machine, then present ones, then by name. */
+export declare function compareMachines(a: MachineRecord, b: MachineRecord): number;
+export {};
+//# sourceMappingURL=machines.d.ts.map

package/dist/machines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machines.d.ts","sourceRoot":"","sources":["../src/machines.ts"],"names":[],"mappings":"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"}