@openscout/protocol 0.2.98 → 0.2.104

package/src/channel-invites.ts

@@ -0,0 +1,343 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+
+/**
+ * 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";
+
+/**
+ * The only scope this pilot grants. It permits posting, reading, and replying
+ * inside one channel — never project, shell, or filesystem authority.
+ */
+export type ChannelInviteScope = "channel_participation";
+
+export const CHANNEL_INVITE_SCOPE: ChannelInviteScope = "channel_participation";
+
+/** How far the recorded route actually reaches. */
+export type ChannelInviteReachability =
+  /** Loopback only: useless to anybody not on the authority machine. */
+  | "local_only"
+  /** A LAN/mDNS doorway name or address on the local network. */
+  | "lan"
+  /** A tailnet/mesh route that survives leaving the LAN. */
+  | "mesh"
+  /** No evidence either way; do not claim it works. */
+  | "unknown";
+
+export interface ChannelInviteRoute {
+  /** The broker node that owns the channel and must accept the redemption. */
+  authorityNodeId: ScoutId;
+  /** Host an invited agent should dial. */
+  host: string;
+  /** Absolute base URL the invitation document points at. */
+  baseUrl: string;
+  reachability: ChannelInviteReachability;
+  /**
+   * Why this route may not reach the invitee. Present whenever reachability is
+   * anything but `mesh`; surfaces must render it rather than imply the link
+   * works everywhere.
+   */
+  caveat?: string;
+}
+
+/** One concrete agent session that accepted one invitation. */
+export interface ChannelInviteRedemption {
+  id: ScoutId;
+  /** The channel participant this redemption created or confirmed. */
+  actorId: ScoutId;
+  agentId?: ScoutId;
+  /** The pre-existing harness session attached to the channel. */
+  sessionId?: string;
+  endpointId?: ScoutId;
+  nodeId?: ScoutId;
+  harness?: string;
+  projectRoot?: string;
+  displayName?: string;
+  redeemedAt: number;
+}
+
+export interface ChannelInviteInvitee {
+  displayName: string;
+  handle?: string;
+  /** Set when the invitation names a durable person actor up front. */
+  actorId?: ScoutId;
+}
+
+export interface ChannelInviteRecord {
+  id: ScoutId;
+  channelId: ScoutId;
+  scope: ChannelInviteScope;
+  /** Lowercase hex digest of the raw token. The raw token is never stored. */
+  tokenHash: string;
+  /** A short non-secret fragment so humans can tell two invitations apart. */
+  tokenHint: string;
+  createdAt: number;
+  createdByActorId: ScoutId;
+  expiresAt: number | null;
+  maxRedemptions: number | null;
+  revokedAt?: number;
+  revokedByActorId?: ScoutId;
+  invitee?: ChannelInviteInvitee;
+  route: ChannelInviteRoute;
+  redemptions: ChannelInviteRedemption[];
+  metadata?: MetadataMap;
+}
+
+export type ChannelInviteState = "active" | "expired" | "revoked" | "exhausted";
+
+export function channelInviteState(
+  invite: ChannelInviteRecord,
+  nowMs: number,
+): ChannelInviteState {
+  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";
+}
+
+export type ChannelInviteRejectionReason =
+  | "unknown_token"
+  | "expired"
+  | "revoked"
+  | "exhausted"
+  | "scope_mismatch"
+  | "channel_mismatch"
+  | "missing_identity";
+
+export interface ChannelInviteRejection {
+  reason: ChannelInviteRejectionReason;
+  message: string;
+}
+
+export interface ChannelInviteRedemptionRequest {
+  actorId: ScoutId;
+  agentId?: ScoutId;
+  sessionId?: string;
+  endpointId?: ScoutId;
+  nodeId?: ScoutId;
+  harness?: string;
+  projectRoot?: string;
+  displayName?: string;
+  channelId?: ScoutId;
+  scope?: string;
+}
+
+export type ChannelInviteRedemptionOutcome =
+  | {
+      ok: true;
+      /**
+       * The redemption already on file for this identity. Present on a retry;
+       * the caller must reuse it rather than appending a second row or
+       * consuming another slot.
+       */
+      existing: ChannelInviteRedemption | null;
+    }
+  | { ok: false; rejection: ChannelInviteRejection };
+
+/**
+ * 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: {
+  invite: ChannelInviteRecord;
+  request: ChannelInviteRedemptionRequest;
+  nowMs: number;
+}): ChannelInviteRedemptionOutcome {
+  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: ChannelInviteRecord,
+  request: Pick<ChannelInviteRedemptionRequest, "actorId" | "sessionId" | "agentId">,
+): ChannelInviteRedemption | null {
+  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: Exclude<ChannelInviteState, "active">,
+): ChannelInviteRejection {
+  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(): ChannelInviteRejection {
+  // 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: MetadataMap | undefined,
+): ChannelInviteRecord[] {
+  const raw = metadata?.[CHANNEL_INVITES_METADATA_KEY];
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((entry): entry is ChannelInviteRecord =>
+    Boolean(entry)
+    && typeof entry === "object"
+    && typeof (entry as ChannelInviteRecord).id === "string"
+    && typeof (entry as ChannelInviteRecord).tokenHash === "string"
+    && Array.isArray((entry as ChannelInviteRecord).redemptions));
+}
+
+/** Match a presented token against stored invitations by its digest. */
+export function findChannelInviteByTokenHash(
+  invites: ChannelInviteRecord[],
+  tokenHash: string,
+): ChannelInviteRecord | null {
+  const normalized = tokenHash.trim().toLowerCase();
+  if (!normalized) return null;
+  return invites.find((invite) => invite.tokenHash.toLowerCase() === normalized) ?? null;
+}
+
+/**
+ * The public view of an invitation: everything a human or agent needs to
+ * understand the offer, and nothing that could be replayed into membership.
+ */
+export interface ChannelInvitePublicView {
+  id: ScoutId;
+  channelId: ScoutId;
+  /** Public authorship, used to show who may revoke this invitation. */
+  createdByActorId: ScoutId;
+  scope: ChannelInviteScope;
+  state: ChannelInviteState;
+  tokenHint: string;
+  createdAt: number;
+  expiresAt: number | null;
+  maxRedemptions: number | null;
+  redemptionCount: number;
+  invitee?: ChannelInviteInvitee;
+  route: ChannelInviteRoute;
+  redemptions: ChannelInviteRedemption[];
+}
+
+export function channelInvitePublicView(
+  invite: ChannelInviteRecord,
+  nowMs: number,
+): ChannelInvitePublicView {
+  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/src/channel-reception.ts

@@ -0,0 +1,308 @@
+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";
+
+/**
+ * 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<DeliveryTransport>([
+  "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: DeliveryTransport | null | undefined,
+): ChannelReceptionRouteKind {
+  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;
+
+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 function deriveChannelReception(
+  evidence: ChannelReceptionEvidence,
+): ChannelReception {
+  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 } as const;
+
+  // 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: number): string {
+  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: ChannelReceptionState): string {
+  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/src/common.ts

@@ -82,6 +82,7 @@ export type DeliveryTransport =
   | "kimi_acp"
   | "cursor_acp"
   | "opencode_acp"
+  | "devin_acp"
   | "tmux"
   | "cursor_exec"
   | "cursor_cli_text"

package/src/conversation-projection.ts

@@ -1,7 +1,7 @@
 import type { ConversationKind } from "./conversations.js";
 import type { ObservedActivity } from "./observed-status.js";
 
-export const CONVERSATION_PROJECTION_VERSION = 1;
+export const CONVERSATION_PROJECTION_VERSION = 2;
 
 export type ConversationProjectionEntityKind =
   | "scout_conversation"