@openscout/protocol 0.2.104 → 0.2.106

package/dist/broker-routes.d.ts

@@ -16,6 +16,8 @@ export declare const scoutBrokerPaths: {
         readonly machines: "/v1/machines";
         readonly machinesScan: "/v1/machines/scan";
         readonly messages: "/v1/messages";
+        readonly messageReactions: "/v1/message-reactions";
+        readonly messageReactionsRemove: "/v1/message-reactions/remove";
         readonly brokerMessages: "/v1/broker/messages";
         readonly eventsStream: "/v1/events/stream";
         readonly commands: "/v1/commands";

package/dist/broker-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-routes.d.ts","sourceRoot":"","sources":["../src/broker-routes.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CnB,CAAC;AAEX,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAG3E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAKvE;AAED,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEjE"}
+{"version":3,"file":"broker-routes.d.ts","sourceRoot":"","sources":["../src/broker-routes.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CnB,CAAC;AAEX,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAG3E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAKvE;AAED,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEjE"}

package/dist/broker-routes.js

@@ -22,6 +22,8 @@ export const scoutBrokerPaths = {
         machines: "/v1/machines",
         machinesScan: "/v1/machines/scan",
         messages: "/v1/messages",
+        messageReactions: "/v1/message-reactions",
+        messageReactionsRemove: "/v1/message-reactions/remove",
         brokerMessages: "/v1/broker/messages",
         eventsStream: "/v1/events/stream",
         commands: "/v1/commands",

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export * from "./assigned-roles.js";
 export * from "./orchestrator-prompt.js";
 export * from "./orchestration-provider-map.js";
 export * from "./messages.js";
+export * from "./message-reactions.js";
 export * from "./read-receipts.js";
 export * from "./invocations.js";
 export * from "./agent-runs.js";
@@ -54,6 +55,7 @@ export * from "./permission-policy.js";
 export * from "./cursor-transport.js";
 export * from "./terminal-surface-id.js";
 export * from "./terminal-sessions.js";
+export * from "./terminal-session-resolve.js";
 export * from "./terminal-workspaces.js";
 export * from "./terminal-host-topology.js";
 export * from "./herdr-workspace-digest.js";

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,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"}
+{"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,wBAAwB,CAAC;AACvC,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,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -18,6 +18,7 @@ export * from "./assigned-roles.js";
 export * from "./orchestrator-prompt.js";
 export * from "./orchestration-provider-map.js";
 export * from "./messages.js";
+export * from "./message-reactions.js";
 export * from "./read-receipts.js";
 export * from "./invocations.js";
 export * from "./agent-runs.js";
@@ -54,6 +55,7 @@ export * from "./permission-policy.js";
 export * from "./cursor-transport.js";
 export * from "./terminal-surface-id.js";
 export * from "./terminal-sessions.js";
+export * from "./terminal-session-resolve.js";
 export * from "./terminal-workspaces.js";
 export * from "./terminal-host-topology.js";
 export * from "./herdr-workspace-digest.js";

package/dist/message-reactions.d.ts

@@ -0,0 +1,29 @@
+/** Hover strip. Unknown emoji is `400 invalid_emoji`. */
+export declare const REACTION_EMOJI_QUICK: readonly ["👍", "❤️", "😂", "👀", "🎉"];
+/** Extra row, opened from “more” on the strip. */
+export declare const REACTION_EMOJI_MORE: readonly ["🔥", "🙏", "👏", "😢", "😮", "🚀", "✅", "💯", "🤔", "💡", "🙌", "✨"];
+export declare const REACTION_EMOJI_ALLOWLIST: readonly ["👍", "❤️", "😂", "👀", "🎉", "🔥", "🙏", "👏", "😢", "😮", "🚀", "✅", "💯", "🤔", "💡", "🙌", "✨"];
+export type ReactionEmoji = (typeof REACTION_EMOJI_ALLOWLIST)[number];
+export declare const REACTION_EMOJI_ALLOWLIST_SET: ReadonlySet<string>;
+export declare function isAllowedReactionEmoji(value: string): value is ReactionEmoji;
+/** One chip on a message, as the feed projects it for the authenticated viewer. */
+export interface MessageReactionChip {
+    emoji: string;
+    count: number;
+    me: boolean;
+}
+/** One stored row. Canonical identity is `(messageId, actorId, emoji)`. */
+export interface MessageReactionRecord {
+    messageId: string;
+    actorId: string;
+    emoji: string;
+    createdAt: number;
+}
+/**
+ * Project stored rows onto the feed shape.
+ *
+ * Order is first time that emoji appeared, then allowlist index as a tie-break,
+ * so a count change never reshuffles the row under the cursor.
+ */
+export declare function projectMessageReactionChips(rows: readonly MessageReactionRecord[], viewerActorId: string): MessageReactionChip[];
+//# sourceMappingURL=message-reactions.d.ts.map

package/dist/message-reactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-reactions.d.ts","sourceRoot":"","sources":["../src/message-reactions.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,yCAA0C,CAAC;AAE5E,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,iFAatB,CAAC;AAEX,eAAO,MAAM,wBAAwB,+GAG3B,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,MAAM,CAAqC,CAAC;AAEnG,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa,CAE5E;AAED,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;CACb;AAED,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,SAAS,qBAAqB,EAAE,EACtC,aAAa,EAAE,MAAM,GACpB,mBAAmB,EAAE,CA2BvB"}

package/dist/message-reactions.js

@@ -0,0 +1,63 @@
+/** Hover strip. Unknown emoji is `400 invalid_emoji`. */
+export const REACTION_EMOJI_QUICK = ["👍", "❤️", "😂", "👀", "🎉"];
+/** Extra row, opened from “more” on the strip. */
+export const REACTION_EMOJI_MORE = [
+    "🔥",
+    "🙏",
+    "👏",
+    "😢",
+    "😮",
+    "🚀",
+    "✅",
+    "💯",
+    "🤔",
+    "💡",
+    "🙌",
+    "✨",
+];
+export const REACTION_EMOJI_ALLOWLIST = [
+    ...REACTION_EMOJI_QUICK,
+    ...REACTION_EMOJI_MORE,
+];
+export const REACTION_EMOJI_ALLOWLIST_SET = new Set(REACTION_EMOJI_ALLOWLIST);
+export function isAllowedReactionEmoji(value) {
+    return REACTION_EMOJI_ALLOWLIST_SET.has(value);
+}
+/**
+ * Project stored rows onto the feed shape.
+ *
+ * Order is first time that emoji appeared, then allowlist index as a tie-break,
+ * so a count change never reshuffles the row under the cursor.
+ */
+export function projectMessageReactionChips(rows, viewerActorId) {
+    const byEmoji = new Map();
+    for (const row of rows) {
+        const current = byEmoji.get(row.emoji);
+        if (current) {
+            current.count += 1;
+            if (row.actorId === viewerActorId)
+                current.me = true;
+            if (row.createdAt < current.firstAt)
+                current.firstAt = row.createdAt;
+        }
+        else {
+            byEmoji.set(row.emoji, {
+                count: 1,
+                me: row.actorId === viewerActorId,
+                firstAt: row.createdAt,
+            });
+        }
+    }
+    const allowlistIndex = (emoji) => {
+        const index = REACTION_EMOJI_ALLOWLIST.indexOf(emoji);
+        return index === -1 ? REACTION_EMOJI_ALLOWLIST.length : index;
+    };
+    return [...byEmoji.entries()]
+        .sort((left, right) => {
+        const time = left[1].firstAt - right[1].firstAt;
+        if (time !== 0)
+            return time;
+        return allowlistIndex(left[0]) - allowlistIndex(right[0]);
+    })
+        .map(([emoji, value]) => ({ emoji, count: value.count, me: value.me }));
+}

package/dist/terminal-session-resolve.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Session → terminal surface resolution.
+ *
+ * "Hop into terminal" needs one answer from any surface that shows an agent or
+ * session: which live terminal surface, if any, is running it. This module is
+ * that resolver, shared by the web server (`/api/terminal-sessions/resolve`),
+ * the web client (hop menus), and thin clients such as the macOS HUD that ask
+ * the server instead of shipping the matching rules.
+ *
+ * Matching is deliberately conservative — a false positive drops the operator
+ * into someone else's terminal, which is worse than offering no hop at all.
+ * The binds, strongest first:
+ *
+ * 1. A registered record's `sourceSessionId` — the harness-native id `scout
+ *    session intake` stored when the session got its terminal home.
+ * 2. A registered record's session metadata refs (thread id, conversation id,
+ *    runtime/external session id) — same session, different spelling.
+ * 3. A surface's `sessionName` equal to a ref — how discovered multiplexer
+ *    sessions (`tmux-…`, `session-…`, harness-prefixed names) resolve.
+ *
+ * `agentId` contributes one weak candidate: its leading `session-…` segment —
+ * the definition id Scout agents embed (`session-xxx.host.node`). Nothing else
+ * binds an agent id to a terminal record, and a bare non-`session-` leading
+ * segment is deliberately not trusted.
+ */
+import type { TerminalSessionRecord, TerminalSurface } from "./terminal-sessions.js";
+export type SessionTerminalHints = {
+    /** Scout agent id, when the caller knows which agent owns the session. */
+    agentId?: string | null;
+    /** Session references: harness session ids, transcript ids, route refs. */
+    sessionRefs?: readonly (string | null | undefined)[];
+};
+export type SessionTerminalResolution = {
+    session: TerminalSessionRecord;
+    surface: TerminalSurface;
+    /** Which rule bound the session to the surface. */
+    via: "sourceSessionId" | "metadata" | "sessionName";
+};
+/**
+ * One ref becomes a small set of match candidates. Besides the cleaned ref
+ * itself, a leading short `prefix:` token (a harness or `session:` namespace
+ * marker, e.g. `claude:abc123`) contributes its suffix, since callers hand over
+ * refs in both bare and scoped spellings.
+ */
+export declare function sessionRefCandidates(value: string | null | undefined): string[];
+/** All match candidates for a hints bag, deduplicated, order preserved. */
+export declare function sessionHintCandidates(hints: SessionTerminalHints): string[];
+/**
+ * The surface a hop should land on for a matched record. Session-level beats
+ * pane-level (a hop into a multiplexer session wants its own layout, not a
+ * pinned pane), and live beats detached or exited.
+ */
+export declare function preferredHopSurface(session: TerminalSessionRecord): TerminalSurface | null;
+/**
+ * Resolve session/agent hints to a live terminal target, or null when nothing
+ * provably matches. `sessions` should be the reconciled inventory — registered
+ * records plus discovered host sessions (`/api/terminal-sessions` with
+ * `includeDiscovered=1`).
+ */
+export declare function resolveSessionTerminalSurface(sessions: readonly TerminalSessionRecord[], hints: SessionTerminalHints): SessionTerminalResolution | null;
+//# sourceMappingURL=terminal-session-resolve.d.ts.map

package/dist/terminal-session-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-session-resolve.d.ts","sourceRoot":"","sources":["../src/terminal-session-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAErF,MAAM,MAAM,oBAAoB,GAAG;IACjC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,OAAO,EAAE,eAAe,CAAC;IACzB,mDAAmD;IACnD,GAAG,EAAE,iBAAiB,GAAG,UAAU,GAAG,aAAa,CAAC;CACrD,CAAC;AAWF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAiB/E;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAU3E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,GAAG,IAAI,CAU1F;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,SAAS,qBAAqB,EAAE,EAC1C,KAAK,EAAE,oBAAoB,GAC1B,yBAAyB,GAAG,IAAI,CAuDlC"}

package/dist/terminal-session-resolve.js

@@ -0,0 +1,157 @@
+/**
+ * Session → terminal surface resolution.
+ *
+ * "Hop into terminal" needs one answer from any surface that shows an agent or
+ * session: which live terminal surface, if any, is running it. This module is
+ * that resolver, shared by the web server (`/api/terminal-sessions/resolve`),
+ * the web client (hop menus), and thin clients such as the macOS HUD that ask
+ * the server instead of shipping the matching rules.
+ *
+ * Matching is deliberately conservative — a false positive drops the operator
+ * into someone else's terminal, which is worse than offering no hop at all.
+ * The binds, strongest first:
+ *
+ * 1. A registered record's `sourceSessionId` — the harness-native id `scout
+ *    session intake` stored when the session got its terminal home.
+ * 2. A registered record's session metadata refs (thread id, conversation id,
+ *    runtime/external session id) — same session, different spelling.
+ * 3. A surface's `sessionName` equal to a ref — how discovered multiplexer
+ *    sessions (`tmux-…`, `session-…`, harness-prefixed names) resolve.
+ *
+ * `agentId` contributes one weak candidate: its leading `session-…` segment —
+ * the definition id Scout agents embed (`session-xxx.host.node`). Nothing else
+ * binds an agent id to a terminal record, and a bare non-`session-` leading
+ * segment is deliberately not trusted.
+ */
+import { AGENT_HARNESSES } from "./actors.js";
+/** Metadata keys a registered record may carry that name the same session. */
+const SESSION_REF_METADATA_KEYS = [
+    "threadId",
+    "externalSessionId",
+    "conversationId",
+    "runtimeSessionId",
+    "sessionId",
+];
+/**
+ * One ref becomes a small set of match candidates. Besides the cleaned ref
+ * itself, a leading short `prefix:` token (a harness or `session:` namespace
+ * marker, e.g. `claude:abc123`) contributes its suffix, since callers hand over
+ * refs in both bare and scoped spellings.
+ */
+export function sessionRefCandidates(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return [];
+    const leaf = trimmed.split(/[\\/]/u).filter(Boolean).at(-1) ?? trimmed;
+    const cleaned = leaf.endsWith(".jsonl") ? leaf.slice(0, -".jsonl".length) : leaf;
+    if (!cleaned)
+        return [];
+    const candidates = new Set([cleaned]);
+    const scoped = /^([A-Za-z][A-Za-z0-9_-]{0,15}):(.+)$/u.exec(cleaned);
+    if (scoped?.[2]) {
+        candidates.add(scoped[2]);
+        if (scoped[1] === "session") {
+            const harnessScoped = /^([A-Za-z][A-Za-z0-9_-]{0,15}):(.+)$/u.exec(scoped[2]);
+            if (harnessScoped?.[2])
+                candidates.add(harnessScoped[2]);
+        }
+    }
+    return [...candidates];
+}
+/** All match candidates for a hints bag, deduplicated, order preserved. */
+export function sessionHintCandidates(hints) {
+    const seen = new Set();
+    const agentRef = hints.agentId?.trim().split(".", 1)[0];
+    if (agentRef?.startsWith("session-"))
+        seen.add(agentRef);
+    for (const ref of hints.sessionRefs ?? []) {
+        for (const candidate of sessionRefCandidates(ref)) {
+            seen.add(candidate);
+        }
+    }
+    return [...seen];
+}
+/**
+ * The surface a hop should land on for a matched record. Session-level beats
+ * pane-level (a hop into a multiplexer session wants its own layout, not a
+ * pinned pane), and live beats detached or exited.
+ */
+export function preferredHopSurface(session) {
+    const surfaces = session.surfaces.filter((surface) => surface.state !== "exited");
+    if (surfaces.length === 0)
+        return null;
+    return (surfaces.find((surface) => !surface.paneId && surface.state === "live")
+        ?? surfaces.find((surface) => !surface.paneId)
+        ?? surfaces.find((surface) => surface.state === "live")
+        ?? surfaces[0]
+        ?? null);
+}
+/**
+ * Resolve session/agent hints to a live terminal target, or null when nothing
+ * provably matches. `sessions` should be the reconciled inventory — registered
+ * records plus discovered host sessions (`/api/terminal-sessions` with
+ * `includeDiscovered=1`).
+ */
+export function resolveSessionTerminalSurface(sessions, hints) {
+    const refs = new Set(sessionHintCandidates(hints));
+    if (refs.size === 0)
+        return null;
+    const canonicalHarness = (value) => {
+        const normalized = value.trim().toLowerCase().replace(/_/gu, "-");
+        const alias = normalized === "claude-code" || normalized === "claude-stream-json" ? "claude"
+            : normalized === "codex-app-server" || normalized === "codex-exec" ? "codex"
+                : normalized === "pi-rpc" ? "pi" : normalized;
+        return AGENT_HARNESSES.includes(alias) ? alias : null;
+    };
+    const qualifiedHarnesses = new Set();
+    for (const ref of hints.sessionRefs ?? []) {
+        const scoped = /^(?:session:)?([^:/\\]+):/u.exec(ref?.trim() ?? "");
+        const harness = scoped ? canonicalHarness(scoped[1]) : null;
+        if (harness)
+            qualifiedHarnesses.add(harness);
+    }
+    // Conflicting scope hints cannot prove one target. Unknown/discovered
+    // harnesses are eligible only for unqualified lookups.
+    if (qualifiedHarnesses.size > 1)
+        return null;
+    const requestedHarness = [...qualifiedHarnesses][0];
+    const eligible = sessions.filter((session) => !requestedHarness
+        || canonicalHarness(session.harness) === requestedHarness);
+    const registered = eligible.filter((session) => session.origin !== "discovered");
+    const bySource = [];
+    for (const session of registered) {
+        if (!session.sourceSessionId || !refs.has(session.sourceSessionId))
+            continue;
+        const surface = preferredHopSurface(session);
+        if (surface)
+            bySource.push({ session, surface, via: "sourceSessionId" });
+    }
+    if (bySource.length > 0)
+        return bySource.length === 1 ? bySource[0] : null;
+    const byMetadata = [];
+    for (const session of registered) {
+        const metadata = session.metadata;
+        if (!metadata)
+            continue;
+        const matched = SESSION_REF_METADATA_KEYS.some((key) => {
+            const value = metadata[key];
+            return typeof value === "string" && refs.has(value);
+        });
+        if (!matched)
+            continue;
+        const surface = preferredHopSurface(session);
+        if (surface)
+            byMetadata.push({ session, surface, via: "metadata" });
+    }
+    if (byMetadata.length > 0)
+        return byMetadata.length === 1 ? byMetadata[0] : null;
+    const byName = [];
+    for (const session of eligible) {
+        const matches = session.surfaces.filter((candidate) => candidate.state !== "exited" && refs.has(candidate.sessionName));
+        const sessionLevel = matches.filter((candidate) => !candidate.paneId);
+        const preferred = sessionLevel.length > 0 ? sessionLevel : matches;
+        for (const surface of preferred)
+            byName.push({ session, surface, via: "sessionName" });
+    }
+    return byName.length === 1 ? byName[0] : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openscout/protocol",
-  "version": "0.2.104",
+  "version": "0.2.106",
   "description": "Typed protocol for the OpenScout local control plane",
   "license": "Apache-2.0",
   "type": "module",
@@ -57,5 +57,5 @@
   "devDependencies": {
     "typescript": "^5"
   },
-  "gitHead": "ccfe6c5bb412f1f40a85858b25acfea34060bc5e"
+  "gitHead": "02db44c5ccdacb0dddbd4647e36da5d7d8f630bf"
 }

package/src/broker-routes.ts

@@ -23,6 +23,8 @@ export const scoutBrokerPaths = {
     machines: "/v1/machines",
     machinesScan: "/v1/machines/scan",
     messages: "/v1/messages",
+    messageReactions: "/v1/message-reactions",
+    messageReactionsRemove: "/v1/message-reactions/remove",
     brokerMessages: "/v1/broker/messages",
     eventsStream: "/v1/events/stream",
     commands: "/v1/commands",

package/src/index.ts

@@ -18,6 +18,7 @@ export * from "./assigned-roles.js";
 export * from "./orchestrator-prompt.js";
 export * from "./orchestration-provider-map.js";
 export * from "./messages.js";
+export * from "./message-reactions.js";
 export * from "./read-receipts.js";
 export * from "./invocations.js";
 export * from "./agent-runs.js";
@@ -54,6 +55,7 @@ export * from "./permission-policy.js";
 export * from "./cursor-transport.js";
 export * from "./terminal-surface-id.js";
 export * from "./terminal-sessions.js";
+export * from "./terminal-session-resolve.js";
 export * from "./terminal-workspaces.js";
 export * from "./terminal-host-topology.js";
 export * from "./herdr-workspace-digest.js";

package/src/message-reactions.ts

@@ -0,0 +1,84 @@
+/** Hover strip. Unknown emoji is `400 invalid_emoji`. */
+export const REACTION_EMOJI_QUICK = ["👍", "❤️", "😂", "👀", "🎉"] as const;
+
+/** Extra row, opened from “more” on the strip. */
+export const REACTION_EMOJI_MORE = [
+  "🔥",
+  "🙏",
+  "👏",
+  "😢",
+  "😮",
+  "🚀",
+  "✅",
+  "💯",
+  "🤔",
+  "💡",
+  "🙌",
+  "✨",
+] as const;
+
+export const REACTION_EMOJI_ALLOWLIST = [
+  ...REACTION_EMOJI_QUICK,
+  ...REACTION_EMOJI_MORE,
+] as const;
+
+export type ReactionEmoji = (typeof REACTION_EMOJI_ALLOWLIST)[number];
+
+export const REACTION_EMOJI_ALLOWLIST_SET: ReadonlySet<string> = new Set(REACTION_EMOJI_ALLOWLIST);
+
+export function isAllowedReactionEmoji(value: string): value is ReactionEmoji {
+  return REACTION_EMOJI_ALLOWLIST_SET.has(value);
+}
+
+/** One chip on a message, as the feed projects it for the authenticated viewer. */
+export interface MessageReactionChip {
+  emoji: string;
+  count: number;
+  me: boolean;
+}
+
+/** One stored row. Canonical identity is `(messageId, actorId, emoji)`. */
+export interface MessageReactionRecord {
+  messageId: string;
+  actorId: string;
+  emoji: string;
+  createdAt: number;
+}
+
+/**
+ * Project stored rows onto the feed shape.
+ *
+ * Order is first time that emoji appeared, then allowlist index as a tie-break,
+ * so a count change never reshuffles the row under the cursor.
+ */
+export function projectMessageReactionChips(
+  rows: readonly MessageReactionRecord[],
+  viewerActorId: string,
+): MessageReactionChip[] {
+  const byEmoji = new Map<string, { count: number; me: boolean; firstAt: number }>();
+  for (const row of rows) {
+    const current = byEmoji.get(row.emoji);
+    if (current) {
+      current.count += 1;
+      if (row.actorId === viewerActorId) current.me = true;
+      if (row.createdAt < current.firstAt) current.firstAt = row.createdAt;
+    } else {
+      byEmoji.set(row.emoji, {
+        count: 1,
+        me: row.actorId === viewerActorId,
+        firstAt: row.createdAt,
+      });
+    }
+  }
+  const allowlistIndex = (emoji: string): number => {
+    const index = REACTION_EMOJI_ALLOWLIST.indexOf(emoji as ReactionEmoji);
+    return index === -1 ? REACTION_EMOJI_ALLOWLIST.length : index;
+  };
+  return [...byEmoji.entries()]
+    .sort((left, right) => {
+      const time = left[1].firstAt - right[1].firstAt;
+      if (time !== 0) return time;
+      return allowlistIndex(left[0]) - allowlistIndex(right[0]);
+    })
+    .map(([emoji, value]) => ({ emoji, count: value.count, me: value.me }));
+}

package/src/terminal-session-resolve.ts

@@ -0,0 +1,172 @@
+/**
+ * Session → terminal surface resolution.
+ *
+ * "Hop into terminal" needs one answer from any surface that shows an agent or
+ * session: which live terminal surface, if any, is running it. This module is
+ * that resolver, shared by the web server (`/api/terminal-sessions/resolve`),
+ * the web client (hop menus), and thin clients such as the macOS HUD that ask
+ * the server instead of shipping the matching rules.
+ *
+ * Matching is deliberately conservative — a false positive drops the operator
+ * into someone else's terminal, which is worse than offering no hop at all.
+ * The binds, strongest first:
+ *
+ * 1. A registered record's `sourceSessionId` — the harness-native id `scout
+ *    session intake` stored when the session got its terminal home.
+ * 2. A registered record's session metadata refs (thread id, conversation id,
+ *    runtime/external session id) — same session, different spelling.
+ * 3. A surface's `sessionName` equal to a ref — how discovered multiplexer
+ *    sessions (`tmux-…`, `session-…`, harness-prefixed names) resolve.
+ *
+ * `agentId` contributes one weak candidate: its leading `session-…` segment —
+ * the definition id Scout agents embed (`session-xxx.host.node`). Nothing else
+ * binds an agent id to a terminal record, and a bare non-`session-` leading
+ * segment is deliberately not trusted.
+ */
+
+import { AGENT_HARNESSES } from "./actors.js";
+import type { TerminalSessionRecord, TerminalSurface } from "./terminal-sessions.js";
+
+export type SessionTerminalHints = {
+  /** Scout agent id, when the caller knows which agent owns the session. */
+  agentId?: string | null;
+  /** Session references: harness session ids, transcript ids, route refs. */
+  sessionRefs?: readonly (string | null | undefined)[];
+};
+
+export type SessionTerminalResolution = {
+  session: TerminalSessionRecord;
+  surface: TerminalSurface;
+  /** Which rule bound the session to the surface. */
+  via: "sourceSessionId" | "metadata" | "sessionName";
+};
+
+/** Metadata keys a registered record may carry that name the same session. */
+const SESSION_REF_METADATA_KEYS = [
+  "threadId",
+  "externalSessionId",
+  "conversationId",
+  "runtimeSessionId",
+  "sessionId",
+] as const;
+
+/**
+ * One ref becomes a small set of match candidates. Besides the cleaned ref
+ * itself, a leading short `prefix:` token (a harness or `session:` namespace
+ * marker, e.g. `claude:abc123`) contributes its suffix, since callers hand over
+ * refs in both bare and scoped spellings.
+ */
+export function sessionRefCandidates(value: string | null | undefined): string[] {
+  const trimmed = value?.trim();
+  if (!trimmed) return [];
+  const leaf = trimmed.split(/[\\/]/u).filter(Boolean).at(-1) ?? trimmed;
+  const cleaned = leaf.endsWith(".jsonl") ? leaf.slice(0, -".jsonl".length) : leaf;
+  if (!cleaned) return [];
+
+  const candidates = new Set<string>([cleaned]);
+  const scoped = /^([A-Za-z][A-Za-z0-9_-]{0,15}):(.+)$/u.exec(cleaned);
+  if (scoped?.[2]) {
+    candidates.add(scoped[2]);
+    if (scoped[1] === "session") {
+      const harnessScoped = /^([A-Za-z][A-Za-z0-9_-]{0,15}):(.+)$/u.exec(scoped[2]);
+      if (harnessScoped?.[2]) candidates.add(harnessScoped[2]);
+    }
+  }
+  return [...candidates];
+}
+
+/** All match candidates for a hints bag, deduplicated, order preserved. */
+export function sessionHintCandidates(hints: SessionTerminalHints): string[] {
+  const seen = new Set<string>();
+  const agentRef = hints.agentId?.trim().split(".", 1)[0];
+  if (agentRef?.startsWith("session-")) seen.add(agentRef);
+  for (const ref of hints.sessionRefs ?? []) {
+    for (const candidate of sessionRefCandidates(ref)) {
+      seen.add(candidate);
+    }
+  }
+  return [...seen];
+}
+
+/**
+ * The surface a hop should land on for a matched record. Session-level beats
+ * pane-level (a hop into a multiplexer session wants its own layout, not a
+ * pinned pane), and live beats detached or exited.
+ */
+export function preferredHopSurface(session: TerminalSessionRecord): TerminalSurface | null {
+  const surfaces = session.surfaces.filter((surface) => surface.state !== "exited");
+  if (surfaces.length === 0) return null;
+  return (
+    surfaces.find((surface) => !surface.paneId && surface.state === "live")
+    ?? surfaces.find((surface) => !surface.paneId)
+    ?? surfaces.find((surface) => surface.state === "live")
+    ?? surfaces[0]
+    ?? null
+  );
+}
+
+/**
+ * Resolve session/agent hints to a live terminal target, or null when nothing
+ * provably matches. `sessions` should be the reconciled inventory — registered
+ * records plus discovered host sessions (`/api/terminal-sessions` with
+ * `includeDiscovered=1`).
+ */
+export function resolveSessionTerminalSurface(
+  sessions: readonly TerminalSessionRecord[],
+  hints: SessionTerminalHints,
+): SessionTerminalResolution | null {
+  const refs = new Set(sessionHintCandidates(hints));
+  if (refs.size === 0) return null;
+
+  const canonicalHarness = (value: string) => {
+    const normalized = value.trim().toLowerCase().replace(/_/gu, "-");
+    const alias = normalized === "claude-code" || normalized === "claude-stream-json" ? "claude"
+      : normalized === "codex-app-server" || normalized === "codex-exec" ? "codex"
+      : normalized === "pi-rpc" ? "pi" : normalized;
+    return (AGENT_HARNESSES as readonly string[]).includes(alias) ? alias : null;
+  };
+  const qualifiedHarnesses = new Set<string>();
+  for (const ref of hints.sessionRefs ?? []) {
+    const scoped = /^(?:session:)?([^:/\\]+):/u.exec(ref?.trim() ?? "");
+    const harness = scoped ? canonicalHarness(scoped[1]!) : null;
+    if (harness) qualifiedHarnesses.add(harness);
+  }
+  // Conflicting scope hints cannot prove one target. Unknown/discovered
+  // harnesses are eligible only for unqualified lookups.
+  if (qualifiedHarnesses.size > 1) return null;
+  const requestedHarness = [...qualifiedHarnesses][0];
+  const eligible = sessions.filter((session) => !requestedHarness
+    || canonicalHarness(session.harness) === requestedHarness);
+  const registered = eligible.filter((session) => session.origin !== "discovered");
+
+  const bySource: SessionTerminalResolution[] = [];
+  for (const session of registered) {
+    if (!session.sourceSessionId || !refs.has(session.sourceSessionId)) continue;
+    const surface = preferredHopSurface(session);
+    if (surface) bySource.push({ session, surface, via: "sourceSessionId" });
+  }
+  if (bySource.length > 0) return bySource.length === 1 ? bySource[0]! : null;
+
+  const byMetadata: SessionTerminalResolution[] = [];
+  for (const session of registered) {
+    const metadata = session.metadata;
+    if (!metadata) continue;
+    const matched = SESSION_REF_METADATA_KEYS.some((key) => {
+      const value = metadata[key];
+      return typeof value === "string" && refs.has(value);
+    });
+    if (!matched) continue;
+    const surface = preferredHopSurface(session);
+    if (surface) byMetadata.push({ session, surface, via: "metadata" });
+  }
+  if (byMetadata.length > 0) return byMetadata.length === 1 ? byMetadata[0]! : null;
+
+  const byName: SessionTerminalResolution[] = [];
+  for (const session of eligible) {
+    const matches = session.surfaces.filter((candidate) => candidate.state !== "exited" && refs.has(candidate.sessionName));
+    const sessionLevel = matches.filter((candidate) => !candidate.paneId);
+    const preferred = sessionLevel.length > 0 ? sessionLevel : matches;
+    for (const surface of preferred) byName.push({ session, surface, via: "sessionName" });
+  }
+  return byName.length === 1 ? byName[0]! : null;
+}