@openscout/protocol 0.2.98 → 0.2.104

package/dist/channel-invites.js

@@ -0,0 +1,166 @@
+/**
+ * Channel invitations: a portable, scoped, revocable capability that lets a
+ * teammate bring an agent session they are *already running* into a Scout
+ * channel.
+ *
+ * Three boundaries shape this module.
+ *
+ * 1. **The secret never lands in a record.** Only `tokenHash` is persisted, so
+ *    a snapshot, a journal line, or a log dump cannot be replayed into channel
+ *    membership. The raw token exists in the invitation URL and nowhere else.
+ * 2. **Membership is not reception.** Redeeming an invitation makes an actor a
+ *    channel participant. Whether that actor can actually *receive* is a
+ *    separate, live judgement made from endpoint evidence — see
+ *    {@link deriveChannelReception}.
+ * 3. **Reachability is stated, not assumed.** A loopback route is recorded as
+ *    `local_only` so a surface can say plainly that the link will not work for
+ *    a teammate on another machine.
+ *
+ * Invites live in the owning conversation's metadata under
+ * {@link CHANNEL_INVITES_METADATA_KEY}; the broker remains the only writer.
+ */
+export const CHANNEL_INVITES_METADATA_KEY = "channelInvites";
+export const CHANNEL_INVITE_SCOPE = "channel_participation";
+export function channelInviteState(invite, nowMs) {
+    if (invite.revokedAt !== undefined)
+        return "revoked";
+    if (invite.expiresAt !== null && invite.expiresAt <= nowMs)
+        return "expired";
+    if (invite.maxRedemptions !== null
+        && invite.redemptions.length >= invite.maxRedemptions) {
+        return "exhausted";
+    }
+    return "active";
+}
+/**
+ * Decide whether one redemption attempt may proceed.
+ *
+ * Retries are first-class: an identity that already redeemed this invitation
+ * is accepted again with its original redemption, even once the invitation is
+ * exhausted. Re-running an agent's join command must never mint a second
+ * identity, burn a second slot, or replace a live session.
+ */
+export function evaluateChannelInviteRedemption(input) {
+    const { invite, request, nowMs } = input;
+    const actorId = request.actorId?.trim();
+    if (!actorId) {
+        return {
+            ok: false,
+            rejection: {
+                reason: "missing_identity",
+                message: "Redemption needs the actor id of the agent session that is joining.",
+            },
+        };
+    }
+    if (request.channelId?.trim() && request.channelId.trim() !== invite.channelId) {
+        return {
+            ok: false,
+            rejection: {
+                reason: "channel_mismatch",
+                message: "This invitation does not belong to the requested channel.",
+            },
+        };
+    }
+    if (request.scope?.trim() && request.scope.trim() !== invite.scope) {
+        return {
+            ok: false,
+            rejection: {
+                reason: "scope_mismatch",
+                message: `This invitation grants ${invite.scope} only.`,
+            },
+        };
+    }
+    const existing = findChannelInviteRedemption(invite, request);
+    if (existing) {
+        // Revocation still bites: a revoked invitation stops being a usable
+        // capability even for an identity that once held it.
+        if (invite.revokedAt !== undefined) {
+            return { ok: false, rejection: channelInviteRejection("revoked") };
+        }
+        return { ok: true, existing };
+    }
+    const state = channelInviteState(invite, nowMs);
+    if (state !== "active") {
+        return { ok: false, rejection: channelInviteRejection(state) };
+    }
+    return { ok: true, existing: null };
+}
+/**
+ * The redemption already recorded for this identity, if any.
+ *
+ * **Session identity is decisive.** When a request carries a session id, only a
+ * redemption for that exact session counts as the same joiner. A durable agent
+ * running two concrete sessions is two distinct attachments: this feature
+ * exists to attach *the exact session* a teammate is already working in, so
+ * letting a second session inherit the first one's membership through a shared
+ * agent id would hand it the wrong context and silently skip a use of the
+ * invitation.
+ *
+ * Only when no session is carried does the durable actor or agent id decide.
+ */
+export function findChannelInviteRedemption(invite, request) {
+    const sessionId = request.sessionId?.trim();
+    if (sessionId) {
+        return invite.redemptions.find((redemption) => redemption.sessionId?.trim() === sessionId) ?? null;
+    }
+    const actorId = request.actorId?.trim();
+    const agentId = request.agentId?.trim();
+    return invite.redemptions.find((redemption) => {
+        if (actorId && redemption.actorId === actorId)
+            return true;
+        return Boolean(agentId) && redemption.agentId?.trim() === agentId;
+    }) ?? null;
+}
+function channelInviteRejection(state) {
+    switch (state) {
+        case "expired":
+            return { reason: "expired", message: "This invitation has expired. Ask for a new one." };
+        case "revoked":
+            return { reason: "revoked", message: "This invitation was revoked." };
+        case "exhausted":
+            return {
+                reason: "exhausted",
+                message: "This invitation has already been used the maximum number of times.",
+            };
+    }
+}
+export function unknownChannelInviteRejection() {
+    // Deliberately identical for a malformed, unknown, and deleted token: a
+    // probe must not learn which invitations exist.
+    return { reason: "unknown_token", message: "This invitation link is not valid." };
+}
+/** Read the invitations stored on a conversation record. */
+export function readChannelInvites(metadata) {
+    const raw = metadata?.[CHANNEL_INVITES_METADATA_KEY];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((entry) => Boolean(entry)
+        && typeof entry === "object"
+        && typeof entry.id === "string"
+        && typeof entry.tokenHash === "string"
+        && Array.isArray(entry.redemptions));
+}
+/** Match a presented token against stored invitations by its digest. */
+export function findChannelInviteByTokenHash(invites, tokenHash) {
+    const normalized = tokenHash.trim().toLowerCase();
+    if (!normalized)
+        return null;
+    return invites.find((invite) => invite.tokenHash.toLowerCase() === normalized) ?? null;
+}
+export function channelInvitePublicView(invite, nowMs) {
+    return {
+        id: invite.id,
+        channelId: invite.channelId,
+        createdByActorId: invite.createdByActorId,
+        scope: invite.scope,
+        state: channelInviteState(invite, nowMs),
+        tokenHint: invite.tokenHint,
+        createdAt: invite.createdAt,
+        expiresAt: invite.expiresAt,
+        maxRedemptions: invite.maxRedemptions,
+        redemptionCount: invite.redemptions.length,
+        ...(invite.invitee ? { invitee: invite.invitee } : {}),
+        route: invite.route,
+        redemptions: invite.redemptions,
+    };
+}

package/dist/channel-reception.d.ts

@@ -0,0 +1,78 @@
+import type { AgentState, DeliveryTransport } from "./common.js";
+/**
+ * Honest reception state for a channel member.
+ *
+ * Channel membership is a durable fact. Whether a member can actually receive
+ * a message right now is a live judgement, and the two must never be conflated
+ * — a roster that renders every member as "listening" because a row exists is
+ * the specific failure this module prevents.
+ *
+ * Two independent axes carry the truth:
+ *
+ * - {@link ChannelReceptionRouteKind} — what the attached transport *can* do.
+ *   A `claude_resume` or `codex_exec` endpoint has no persistent listener at
+ *   all: a delivery wakes a fresh run. That is a legitimate route, but calling
+ *   it "listening" would be a lie.
+ * - {@link ChannelReceptionState} — what the route is doing at this instant,
+ *   read from endpoint state and heartbeat freshness.
+ */
+export type ChannelReceptionState = 
+/** A member with no agent session attached yet — the invite is unredeemed. */
+"waiting_for_agent"
+/** An attached session that is still warming up or waking. */
+ | "connecting"
+/** A live route that will carry a message now. */
+ | "ready_to_receive"
+/** Attached, but no usable route exists — explain why, never imply delivery. */
+ | "unavailable"
+/** A route that existed and has since gone quiet or been stopped. */
+ | "disconnected";
+export type ChannelReceptionRouteKind = 
+/** The agent holds an open channel and sees a post without being started. */
+"persistent"
+/**
+ * Delivery reaches the invited session by resuming or steering it. Context is
+ * preserved and the session is never replaced, but nothing is watching
+ * between messages.
+ */
+ | "wake_on_delivery"
+/** No route at all. */
+ | "none";
+export declare function channelReceptionRouteKind(transport: DeliveryTransport | null | undefined): ChannelReceptionRouteKind;
+/** How long an idle persistent route may stay silent before we stop vouching for it. */
+export declare const CHANNEL_RECEPTION_STALE_AFTER_MS: number;
+export interface ChannelReceptionEndpointEvidence {
+    state: AgentState;
+    transport: DeliveryTransport;
+    sessionId?: string | null;
+    lastSeenAt?: number | null;
+}
+export interface ChannelReceptionEvidence {
+    /** The member's attached harness session, when the invite was redeemed. */
+    attachedSessionId?: string | null;
+    endpoint?: ChannelReceptionEndpointEvidence | null;
+    nowMs: number;
+    staleAfterMs?: number;
+}
+export interface ChannelReception {
+    state: ChannelReceptionState;
+    routeKind: ChannelReceptionRouteKind;
+    /** True only when a process is attached and watching right now. */
+    listening: boolean;
+    /** Badge-length label. */
+    summary: string;
+    /** One sentence a person can act on. Always populated. */
+    detail: string;
+    /** When the evidence behind this reading was last observed. */
+    evidenceAt: number | null;
+}
+/**
+ * Derive a member's reception state from live evidence only.
+ *
+ * Every branch returns a `detail` sentence, including the happy path: a
+ * surface should never have to invent an explanation, and a `wake_on_delivery`
+ * route always says so out loud.
+ */
+export declare function deriveChannelReception(evidence: ChannelReceptionEvidence): ChannelReception;
+export declare function channelReceptionStateLabel(state: ChannelReceptionState): string;
+//# sourceMappingURL=channel-reception.d.ts.map

package/dist/channel-reception.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-reception.d.ts","sourceRoot":"","sources":["../src/channel-reception.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEjE;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,qBAAqB;AAC/B,8EAA8E;AAC5E,mBAAmB;AACrB,8DAA8D;GAC5D,YAAY;AACd,kDAAkD;GAChD,kBAAkB;AACpB,gFAAgF;GAC9E,aAAa;AACf,qEAAqE;GACnE,cAAc,CAAC;AAEnB,MAAM,MAAM,yBAAyB;AACnC,6EAA6E;AAC3E,YAAY;AACd;;;;GAIG;GACD,kBAAkB;AACpB,uBAAuB;GACrB,MAAM,CAAC;AAwBX,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,GAC9C,yBAAyB,CAG3B;AAED,wFAAwF;AACxF,eAAO,MAAM,gCAAgC,QAAiB,CAAC;AAE/D,MAAM,WAAW,gCAAgC;IAC/C,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,EAAE,gCAAgC,GAAG,IAAI,CAAC;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,qBAAqB,CAAC;IAC7B,SAAS,EAAE,yBAAyB,CAAC;IACrC,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;IACnB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,wBAAwB,GACjC,gBAAgB,CA8KlB;AAYD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAQ/E"}

package/dist/channel-reception.js

@@ -0,0 +1,219 @@
+/**
+ * Transports where a process is actually attached and watching. Everything
+ * else either spawns per delivery or injects into a surface with no listener
+ * contract, and is reported as `wake_on_delivery`.
+ */
+const PERSISTENT_RECEIVE_TRANSPORTS = new Set([
+    "local_socket",
+    "websocket",
+    "pairing_bridge",
+    "peer_broker",
+    "claude_channel",
+    "claude_stream_json",
+    "codex_app_server",
+    "pi_rpc",
+    "grok_acp",
+    "kimi_acp",
+    "cursor_acp",
+    "opencode_acp",
+    "devin_acp",
+    "cursor_sdk_local",
+]);
+export function channelReceptionRouteKind(transport) {
+    if (!transport)
+        return "none";
+    return PERSISTENT_RECEIVE_TRANSPORTS.has(transport) ? "persistent" : "wake_on_delivery";
+}
+/** How long an idle persistent route may stay silent before we stop vouching for it. */
+export const CHANNEL_RECEPTION_STALE_AFTER_MS = 10 * 60 * 1000;
+/**
+ * Derive a member's reception state from live evidence only.
+ *
+ * Every branch returns a `detail` sentence, including the happy path: a
+ * surface should never have to invent an explanation, and a `wake_on_delivery`
+ * route always says so out loud.
+ */
+export function deriveChannelReception(evidence) {
+    const endpoint = evidence.endpoint ?? null;
+    const attachedSessionId = evidence.attachedSessionId?.trim() || null;
+    const routeKind = channelReceptionRouteKind(endpoint?.transport);
+    const evidenceAt = endpoint?.lastSeenAt ?? null;
+    if (!endpoint) {
+        return attachedSessionId
+            ? {
+                state: "unavailable",
+                routeKind: "none",
+                listening: false,
+                summary: "No route",
+                detail: `Session ${attachedSessionId} is attached to this channel but the broker has no registered endpoint for it, so messages cannot be delivered.`,
+                evidenceAt,
+            }
+            : {
+                state: "waiting_for_agent",
+                routeKind: "none",
+                listening: false,
+                summary: "Waiting for agent",
+                detail: "This member has joined the channel but no agent session has redeemed the invitation yet.",
+                evidenceAt,
+            };
+    }
+    const base = { routeKind, evidenceAt };
+    // An endpoint is only evidence about *this* member when the channel knows
+    // which session it attached. Without that link there is a route on the
+    // machine but nothing tying it to this membership, so it cannot be read as
+    // this member being reachable.
+    if (!attachedSessionId) {
+        return {
+            ...base,
+            state: "waiting_for_agent",
+            listening: false,
+            summary: "Waiting for agent",
+            detail: `This member has not redeemed an invitation from a session yet. A ${endpoint.transport} route exists elsewhere for them, but nothing attaches it to this channel, so a message here has no session to arrive in.`,
+        };
+    }
+    // The invitation attached one concrete session. A live endpoint belonging to
+    // a different session is somebody else's evidence: reporting it as this
+    // member's readiness is exactly the false listening claim to avoid.
+    const endpointSessionId = endpoint.sessionId?.trim() || null;
+    if (endpointSessionId && endpointSessionId !== attachedSessionId) {
+        return {
+            ...base,
+            state: "disconnected",
+            listening: false,
+            summary: "Session replaced",
+            detail: `This channel attached session ${attachedSessionId}, but the live ${endpoint.transport} route now belongs to ${endpointSessionId}. Re-redeem the invitation from the session you want in the room.`,
+        };
+    }
+    switch (endpoint.state) {
+        case "attaching":
+        case "waking":
+            return {
+                ...base,
+                state: "connecting",
+                listening: false,
+                summary: "Connecting",
+                detail: `The ${endpoint.transport} route is ${endpoint.state}; messages sent now will be delivered once it settles.`,
+            };
+        case "registered":
+            // `registered` means the broker knows how to reach this endpoint, not
+            // that a session is attached and watching. Only the live states below
+            // are evidence of an active receive route.
+            return {
+                ...base,
+                state: "connecting",
+                listening: false,
+                summary: "Registered",
+                detail: `Session ${attachedSessionId} is registered over ${endpoint.transport} but has not been observed attached and watching, so it is not yet an active receive route.`,
+            };
+        case "offline":
+        case "stopped":
+            return {
+                ...base,
+                state: "disconnected",
+                listening: false,
+                summary: "Disconnected",
+                detail: `The attached session's ${endpoint.transport} route is ${endpoint.state}. Restart or re-attach the session to receive messages.`,
+            };
+        case "superseded":
+            return {
+                ...base,
+                state: "disconnected",
+                listening: false,
+                summary: "Superseded",
+                detail: "A newer route replaced this one. The member's membership stands, but this endpoint no longer receives.",
+            };
+        case "unreachable":
+        case "failed":
+            return {
+                ...base,
+                state: "unavailable",
+                listening: false,
+                summary: endpoint.state === "failed" ? "Failed" : "Unreachable",
+                detail: `The broker last saw this ${endpoint.transport} route as ${endpoint.state}; it cannot currently accept a delivery.`,
+            };
+        default:
+            break;
+    }
+    // Past this point every branch makes a positive claim about the attached
+    // session. An endpoint that does not say which session it serves cannot
+    // support one: the route may well be fine, but "session X is receiving" is a
+    // claim about a specific session and this is not evidence for it. The
+    // negative states above are unaffected -- a dead route is dead either way.
+    if (!endpointSessionId) {
+        return {
+            ...base,
+            state: "connecting",
+            listening: false,
+            summary: "Unconfirmed",
+            detail: `A ${endpoint.transport} route is registered for this member, but it does not identify which session it serves, so Scout cannot confirm that session ${attachedSessionId} is the one receiving.`,
+        };
+    }
+    if (routeKind === "wake_on_delivery") {
+        return {
+            ...base,
+            state: "ready_to_receive",
+            listening: false,
+            summary: "Wakes on delivery",
+            // Say what actually happens. These transports resume or steer the exact
+            // invited session, so context survives -- claiming a message "starts a
+            // new run" would misdescribe them. What they lack is a listener between
+            // messages, and that is the only claim being withheld here.
+            detail: `Messages reach this member by ${endpoint.transport === "tmux" ? "steering" : "resuming"} session ${attachedSessionId} over ${endpoint.transport}. That session keeps its context and is never replaced, but nothing is watching the channel between messages.`,
+        };
+    }
+    const staleAfterMs = evidence.staleAfterMs ?? CHANNEL_RECEPTION_STALE_AFTER_MS;
+    const lastSeenAt = endpoint.lastSeenAt ?? null;
+    // Registration is not observation. A persistent route claims a process is
+    // watching right now; with no timestamp the broker has never seen it do so,
+    // and an unobserved row is not grounds for telling a person their agent is
+    // listening. A wake-on-delivery route makes no such claim, so its
+    // registration alone remains sufficient.
+    if (lastSeenAt === null) {
+        return {
+            ...base,
+            state: "connecting",
+            listening: false,
+            summary: "Unconfirmed",
+            detail: `The ${endpoint.transport} route is registered for this session but has never been observed live, so Scout cannot yet confirm it is listening.`,
+        };
+    }
+    if (evidence.nowMs - lastSeenAt > staleAfterMs) {
+        return {
+            ...base,
+            state: "disconnected",
+            listening: false,
+            summary: "Silent",
+            detail: `The ${endpoint.transport} route is registered but has not been seen for ${formatDuration(evidence.nowMs - lastSeenAt)}, so it is no longer treated as listening.`,
+            evidenceAt: lastSeenAt,
+        };
+    }
+    return {
+        ...base,
+        state: "ready_to_receive",
+        listening: true,
+        summary: "Ready to receive",
+        detail: `An attached ${endpoint.transport} session is watching this channel and will see new messages without being started.`,
+        evidenceAt: lastSeenAt,
+    };
+}
+function formatDuration(ms) {
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 1)
+        return "under a minute";
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? "" : "s"}`;
+    const days = Math.floor(hours / 24);
+    return `${days} day${days === 1 ? "" : "s"}`;
+}
+export function channelReceptionStateLabel(state) {
+    switch (state) {
+        case "waiting_for_agent": return "Waiting for agent";
+        case "connecting": return "Connecting";
+        case "ready_to_receive": return "Ready to receive";
+        case "unavailable": return "Unavailable";
+        case "disconnected": return "Disconnected";
+    }
+}

package/dist/common.d.ts

@@ -6,7 +6,7 @@ export type DeliveryStatus = "accepted" | "peer_acked" | "running" | "completed"
 export type DeliveryFailureReason = "peer_unreachable" | "peer_rejected" | "agent_offline" | "timeout" | "harness_error" | "dispatch" | "cancelled";
 export type DeliveryPolicy = "best_effort" | "must_ack" | "durable" | "ephemeral";
 export type DeliveryTargetKind = "participant" | "agent" | "bridge" | "device" | "voice_session" | "webhook";
-export type DeliveryTransport = "local_socket" | "websocket" | "pairing_bridge" | "peer_broker" | "http" | "webhook" | "telegram" | "discord" | "sms" | "email" | "tts" | "native_voice" | "claude_channel" | "claude_stream_json" | "codex_app_server" | "codex_exec" | "claude_resume" | "pi_rpc" | "grok_acp" | "kimi_acp" | "cursor_acp" | "opencode_acp" | "tmux" | "cursor_exec" | "cursor_cli_text" | "cursor_cli_stream_json" | "cursor_sdk_local";
+export type DeliveryTransport = "local_socket" | "websocket" | "pairing_bridge" | "peer_broker" | "http" | "webhook" | "telegram" | "discord" | "sms" | "email" | "tts" | "native_voice" | "claude_channel" | "claude_stream_json" | "codex_app_server" | "codex_exec" | "claude_resume" | "pi_rpc" | "grok_acp" | "kimi_acp" | "cursor_acp" | "opencode_acp" | "devin_acp" | "tmux" | "cursor_exec" | "cursor_cli_text" | "cursor_cli_stream_json" | "cursor_sdk_local";
 export type DeliveryReason = "conversation_visibility" | "direct_message" | "mention" | "thread_reply" | "invocation" | "bridge_outbound" | "speech";
 export type AdvertiseScope = "local" | "mesh";
 export type ShareMode = "local" | "summary" | "shared";

package/dist/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,MAAM,UAAU,GAClB,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,SAAS,GACT,MAAM,GACN,QAAQ,GACR,SAAS,GACT,SAAS,GACT,aAAa,GACb,QAAQ,GACR,YAAY,GACZ,SAAS,CAAC;AAEd,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5E,MAAM,MAAM,cAAc,GAEtB,UAAU,GACV,YAAY,GACZ,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,GACR,WAAW,GAEX,SAAS,GACT,QAAQ,GACR,MAAM,GACN,cAAc,CAAC;AAEnB,MAAM,MAAM,qBAAqB,GAC7B,kBAAkB,GAClB,eAAe,GACf,eAAe,GACf,SAAS,GACT,eAAe,GACf,UAAU,GACV,WAAW,CAAC;AAEhB,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;AAElF,MAAM,MAAM,kBAAkB,GAC1B,aAAa,GACb,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,eAAe,GACf,SAAS,CAAC;AAEd,MAAM,MAAM,iBAAiB,GACzB,cAAc,GACd,WAAW,GACX,gBAAgB,GAChB,aAAa,GACb,MAAM,GACN,SAAS,GACT,UAAU,GACV,SAAS,GACT,KAAK,GACL,OAAO,GACP,KAAK,GACL,cAAc,GACd,gBAAgB,GAChB,oBAAoB,GACpB,kBAAkB,GAClB,YAAY,GACZ,eAAe,GACf,QAAQ,GACR,UAAU,GACV,UAAU,GACV,YAAY,GACZ,cAAc,GACd,MAAM,GACN,aAAa,GACb,iBAAiB,GACjB,wBAAwB,GACxB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,cAAc,GACtB,yBAAyB,GACzB,gBAAgB,GAChB,SAAS,GACT,cAAc,GACd,YAAY,GACZ,iBAAiB,GACjB,QAAQ,CAAC;AAEb,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,MAAM,UAAU,GAClB,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,SAAS,GACT,MAAM,GACN,QAAQ,GACR,SAAS,GACT,SAAS,GACT,aAAa,GACb,QAAQ,GACR,YAAY,GACZ,SAAS,CAAC;AAEd,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5E,MAAM,MAAM,cAAc,GAEtB,UAAU,GACV,YAAY,GACZ,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,GACR,WAAW,GAEX,SAAS,GACT,QAAQ,GACR,MAAM,GACN,cAAc,CAAC;AAEnB,MAAM,MAAM,qBAAqB,GAC7B,kBAAkB,GAClB,eAAe,GACf,eAAe,GACf,SAAS,GACT,eAAe,GACf,UAAU,GACV,WAAW,CAAC;AAEhB,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;AAElF,MAAM,MAAM,kBAAkB,GAC1B,aAAa,GACb,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,eAAe,GACf,SAAS,CAAC;AAEd,MAAM,MAAM,iBAAiB,GACzB,cAAc,GACd,WAAW,GACX,gBAAgB,GAChB,aAAa,GACb,MAAM,GACN,SAAS,GACT,UAAU,GACV,SAAS,GACT,KAAK,GACL,OAAO,GACP,KAAK,GACL,cAAc,GACd,gBAAgB,GAChB,oBAAoB,GACpB,kBAAkB,GAClB,YAAY,GACZ,eAAe,GACf,QAAQ,GACR,UAAU,GACV,UAAU,GACV,YAAY,GACZ,cAAc,GACd,WAAW,GACX,MAAM,GACN,aAAa,GACb,iBAAiB,GACjB,wBAAwB,GACxB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,cAAc,GACtB,yBAAyB,GACzB,gBAAgB,GAChB,SAAS,GACT,cAAc,GACd,YAAY,GACZ,iBAAiB,GACjB,QAAQ,CAAC;AAEb,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/dist/conversation-projection.d.ts

@@ -1,6 +1,6 @@
 import type { ConversationKind } from "./conversations.js";
 import type { ObservedActivity } from "./observed-status.js";
-export declare const CONVERSATION_PROJECTION_VERSION = 1;
+export declare const CONVERSATION_PROJECTION_VERSION = 2;
 export type ConversationProjectionEntityKind = "scout_conversation" | "observed_session";
 export type ConversationProjectionVisibility = "visible" | "hidden";
 export type ConversationProjectionItem = {

package/dist/conversation-projection.js

@@ -1,4 +1,4 @@
-export const CONVERSATION_PROJECTION_VERSION = 1;
+export const CONVERSATION_PROJECTION_VERSION = 2;
 export function scoutConversationFeedId(conversationId) {
     return `conv:${conversationId}`;
 }

package/dist/herdr-workspace-digest.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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.
+ */
+import type { HerdrAgentStatus, HerdrSessionTopology, HerdrTabLayout, HerdrTopologyUnavailableReason } from "./terminal-host-topology.js";
+/** Total emitted panes across every group before the digest declares truncation. */
+export declare const HERDR_DIGEST_PANE_CAP = 40;
+/** Ceiling on each of the two lead lists; attention is a shortlist, not an inventory. */
+export declare const HERDR_DIGEST_LEAD_CAP = 12;
+export type HerdrStatusCounts = Record<HerdrAgentStatus, number>;
+export type HerdrDigestPane = {
+    /**
+     * What `herdr agent <verb>` accepts as a target for this pane: the stable
+     * terminal id when herdr reported one, else the pane id. Null on a persisted
+     * projection, where neither is live — a pane you cannot address yet.
+     */
+    target: string | null;
+    paneId: string;
+    workspaceId: string;
+    tabId: string;
+    label: string | null;
+    /** Detected agent label ("claude", "codex"), or null for a plain shell. */
+    agent: string | null;
+    status: HerdrAgentStatus;
+    /** Working directory: the foreground process's when known, else the pane's. */
+    directory: string | null;
+    focused: boolean;
+    /**
+     * Scrollback backlog depth in lines. The cheapest activity signal a
+     * projection carries — a deep backlog on an idle pane is work that already
+     * happened, not work happening. Null when herdr did not report scroll state.
+     */
+    backlog: number | null;
+};
+export type HerdrDigestGroup = {
+    /** The panes' literal shared working directory; null when they report none. */
+    directory: string | null;
+    /** Last path segment — how an operator names the place. */
+    name: string;
+    counts: HerdrStatusCounts;
+    panes: HerdrDigestPane[];
+    /** Panes in this group dropped by the pane cap. */
+    omitted: number;
+    /**
+     * What was dropped, by status. A collapsed label has to carry its own scent:
+     * a reader decides whether the hidden rows matter from the label alone, so
+     * "2 idle not shown" is a usable label and "2 not shown" is not.
+     */
+    omittedCounts: HerdrStatusCounts;
+};
+export type HerdrDigestShape = {
+    workspaceId: string;
+    workspaceLabel: string;
+    tabId: string;
+    tabLabel: string;
+    paneCount: number;
+    /** One readable phrase for the arrangement, e.g. "2×2 grid". */
+    arrangement: string;
+    zoomed: boolean;
+    focused: boolean;
+};
+export type HerdrWorkspaceDigest = {
+    session: string;
+    /** True only for a projection read from a running herdr server. */
+    live: boolean;
+    observedAt: number;
+    /** Set when the projection is the persisted last-known state, not a live read. */
+    savedAt: number | null;
+    /**
+     * Why a non-live projection is not live. `unreadable` means a server for the
+     * session IS running and did not answer — the digest must not present that as
+     * a stopped session. Null on a live read.
+     */
+    unavailable: HerdrTopologyUnavailableReason | null;
+    totals: {
+        workspaces: number;
+        tabs: number;
+        panes: number;
+        /** Panes herdr recognized an agent in. The rest are plain shells. */
+        agents: number;
+    };
+    counts: HerdrStatusCounts;
+    /** Blocked panes — the only entries that represent something waiting on a person. */
+    needsYou: HerdrDigestPane[];
+    /** Panes herdr observed as working, bounded. */
+    working: HerdrDigestPane[];
+    groups: HerdrDigestGroup[];
+    shapes: HerdrDigestShape[];
+    truncated: boolean;
+    /** Caveats the reader must carry with the numbers. Never decorative. */
+    notes: string[];
+};
+export declare function herdrStatusRank(status: HerdrAgentStatus): number;
+/**
+ * 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 declare function describeHerdrArrangement(layout: HerdrTabLayout | null, paneCount: number): string;
+/**
+ * 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 declare function digestHerdrTopology(topology: HerdrSessionTopology, options?: {
+    paneCap?: number;
+    leadCap?: number;
+}): HerdrWorkspaceDigest;
+/**
+ * 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 declare function renderHerdrWorkspaceDigest(digest: HerdrWorkspaceDigest): string;
+//# sourceMappingURL=herdr-workspace-digest.d.ts.map

package/dist/herdr-workspace-digest.d.ts.map

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