@openscout/protocol 0.2.102 → 0.2.105

package/dist/transports.d.ts

@@ -5,6 +5,7 @@ import type { InvocationRequest } from "./invocations.js";
 import type { NodeDefinition } from "./mesh.js";
 import type { MessageRecord } from "./messages.js";
 import type { CollaborationEvent, CollaborationRecord } from "./collaboration.js";
+import type { ChannelInviteRedemptionRequest, ChannelInviteRoute, ChannelInviteInvitee } from "./channel-invites.js";
 export interface SubscriptionRequest {
     actorId: ScoutId;
     conversationIds?: ScoutId[];
@@ -63,5 +64,42 @@ export interface CollaborationEventAppendCommand {
     kind: "collaboration.event.append";
     event: CollaborationEvent;
 }
-export type ControlCommand = NodeUpsertCommand | ActorUpsertCommand | AgentUpsertCommand | AgentEndpointUpsertCommand | ConversationUpsertCommand | BindingUpsertCommand | CollaborationUpsertCommand | CollaborationEventAppendCommand | PostMessageCommand | InvokeAgentCommand | EnsureAwakeCommand | SubscribeCommand;
+/**
+ * Invitation writes are broker commands rather than conversation upserts so
+ * the read-modify-write of a channel's invitation set happens inside the
+ * broker's serialized command queue. Two operators minting an invitation at
+ * the same instant must not clobber each other's record.
+ */
+export interface ChannelInviteCreateCommand {
+    kind: "channel.invite.create";
+    channelId: ScoutId;
+    inviteId: ScoutId;
+    /** Digest only. The raw token never crosses this boundary. */
+    tokenHash: string;
+    tokenHint: string;
+    createdByActorId: ScoutId;
+    createdAt: number;
+    expiresAt: number | null;
+    maxRedemptions: number | null;
+    route: ChannelInviteRoute;
+    invitee?: ChannelInviteInvitee;
+    metadata?: MetadataMap;
+}
+export interface ChannelInviteRevokeCommand {
+    kind: "channel.invite.revoke";
+    channelId: ScoutId;
+    inviteId: ScoutId;
+    revokedByActorId: ScoutId;
+    revokedAt: number;
+}
+export interface ChannelInviteRedeemCommand {
+    kind: "channel.invite.redeem";
+    channelId: ScoutId;
+    /** Digest of the presented token; the broker matches, never the caller. */
+    tokenHash: string;
+    redemptionId: ScoutId;
+    redeemedAt: number;
+    request: ChannelInviteRedemptionRequest;
+}
+export type ControlCommand = NodeUpsertCommand | ActorUpsertCommand | AgentUpsertCommand | AgentEndpointUpsertCommand | ConversationUpsertCommand | BindingUpsertCommand | CollaborationUpsertCommand | CollaborationEventAppendCommand | ChannelInviteCreateCommand | ChannelInviteRevokeCommand | ChannelInviteRedeemCommand | PostMessageCommand | InvokeAgentCommand | EnsureAwakeCommand | SubscribeCommand;
 //# sourceMappingURL=transports.d.ts.map

package/dist/transports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports.d.ts","sourceRoot":"","sources":["../src/transports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAElF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,UAAU,EAAE,iBAAiB,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,kBAAkB,CAAC;IACzB,YAAY,EAAE,mBAAmB,CAAC;IAClC,SAAS,EAAE,OAAO,CAAC,iBAAiB,EAAE,cAAc,GAAG,WAAW,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,eAAe,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,YAAY,EAAE,sBAAsB,CAAC;CACtC;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,4BAA4B,CAAC;IACnC,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED,MAAM,MAAM,cAAc,GACtB,iBAAiB,GACjB,kBAAkB,GAClB,kBAAkB,GAClB,0BAA0B,GAC1B,yBAAyB,GACzB,oBAAoB,GACpB,0BAA0B,GAC1B,+BAA+B,GAC/B,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,CAAC"}
+{"version":3,"file":"transports.d.ts","sourceRoot":"","sources":["../src/transports.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openscout/protocol",
-  "version": "0.2.102",
+  "version": "0.2.105",
   "description": "Typed protocol for the OpenScout local control plane",
   "license": "Apache-2.0",
   "type": "module",
@@ -57,5 +57,5 @@
   "devDependencies": {
     "typescript": "^5"
   },
-  "gitHead": "c50900700bff66c1b1947d3413e54a7b1279d581"
+  "gitHead": "4f6679bb04ff580a99a4124d1875ce30cb3b68bd"
 }

package/src/actors.ts

@@ -43,6 +43,7 @@ export type AgentEndpointTransport = Extract<
   | "kimi_acp"
   | "cursor_acp"
   | "opencode_acp"
+  | "devin_acp"
   | "tmux"
   | "cursor_exec"
   | "cursor_cli_text"
@@ -59,6 +60,7 @@ export const AGENT_HARNESSES = [
   "flue",
   "cursor",
   "opencode",
+  "devin",
   "native",
   "worker",
   "bridge",

package/src/broker-routes.ts

@@ -25,6 +25,7 @@ export const scoutBrokerPaths = {
     messages: "/v1/messages",
     brokerMessages: "/v1/broker/messages",
     eventsStream: "/v1/events/stream",
+    commands: "/v1/commands",
     actors: "/v1/actors",
     agents: "/v1/agents",
     endpoints: "/v1/endpoints",

package/src/channel-identity.ts

@@ -59,6 +59,157 @@ export function systemChannelNaturalKey(name: string): string {
   return `system:${encodeIdentityPart(name.trim().toLowerCase() || "system")}`;
 }
 
+/* -- spaces ---------------------------------------------------------------- */
+
+/**
+ * The space every channel that predates spaces belongs to.
+ *
+ * It is not a migration target; it is the name of what already exists. A
+ * channel with no space marker *is* a default-space channel, decided at read
+ * time by {@link channelSpaceSlug}, so no record is ever rewritten to acquire
+ * one.
+ */
+export const DEFAULT_CHAT_SPACE_SLUG = "home";
+
+/** Metadata key carrying a channel's (or a space record's) space slug. */
+export const CHANNEL_SPACE_SLUG_METADATA = "spaceSlug";
+
+/** Natural-key prefix for the conversation record that *is* a space. */
+export const SPACE_NATURAL_KEY_PREFIX = "space:";
+
+/**
+ * Slugs are the durable half of a space's identity, so they are deliberately
+ * boring: lowercase, digits and single-width hyphens, never leading or
+ * trailing punctuation. The human-readable half is the conversation `title`,
+ * which is free-form and renameable; the slug never changes once minted
+ * because it is mixed into every channel id in the space.
+ */
+const CHAT_SPACE_SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
+
+export function isChatSpaceSlug(value: string | null | undefined): value is string {
+  return typeof value === "string" && CHAT_SPACE_SLUG_PATTERN.test(value);
+}
+
+/**
+ * Read a slug from untrusted input, or return `null`.
+ *
+ * Lowercasing and trimming are accepted because they cannot change which space
+ * is meant. Anything else -- a space character, a slash, a percent escape --
+ * is refused rather than repaired: silently rewriting `work/secret` into
+ * `worksecret` would resolve a request to a space the caller did not name.
+ */
+export function normalizeChatSpaceSlug(value: string | null | undefined): string | null {
+  const candidate = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return isChatSpaceSlug(candidate) ? candidate : null;
+}
+
+/**
+ * Derive a slug from a human title, for creation only.
+ *
+ * This one *does* rewrite, because the title is prose the operator typed and
+ * the slug is an identifier we are minting from it. It is never used to
+ * interpret a slug that arrived on a request.
+ */
+export function chatSpaceSlugFromTitle(title: string): string | null {
+  const slug = title
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32)
+    .replace(/-+$/g, "");
+  return isChatSpaceSlug(slug) ? slug : null;
+}
+
+/** The natural key of the conversation record that carries a space. */
+export function spaceNaturalKey(spaceSlug: string): string {
+  return `${SPACE_NATURAL_KEY_PREFIX}${encodeIdentityPart(
+    spaceSlug.trim().toLowerCase() || DEFAULT_CHAT_SPACE_SLUG,
+  )}`;
+}
+
+/**
+ * The natural key of a named channel *inside a space*.
+ *
+ * The default space returns the byte-identical legacy string, which is what
+ * keeps every channel that exists today on the exact id it already has:
+ * `stableChannelId` is a pure function of this key, so an unchanged key is an
+ * unchanged id, an unchanged feed, and unchanged invitations. Nothing is
+ * migrated because nothing moves.
+ *
+ * `/` is the separator because {@link encodeIdentityPart} percent-encodes it,
+ * so a channel whose *name* contains a slash encodes to `%2F` and can never be
+ * mistaken for the space boundary. A legacy key and a spaced key are therefore
+ * distinguishable by inspection, in both directions.
+ */
+export function spacedChannelNaturalKey(spaceSlug: string, channel: string): string {
+  const slug = normalizeChatSpaceSlug(spaceSlug) ?? DEFAULT_CHAT_SPACE_SLUG;
+  const name = encodeIdentityPart(channel.trim().toLowerCase() || "shared");
+  return slug === DEFAULT_CHAT_SPACE_SLUG
+    ? namedChannelNaturalKey(channel)
+    : `channel:${slug}/${name}`;
+}
+
+/**
+ * Which space a conversation belongs to.
+ *
+ * Read in priority order: the explicit marker, then the natural key, then the
+ * default. The fallback is not a guess -- a record with no marker was written
+ * before spaces existed, and the default space is precisely the set of things
+ * that existed before spaces. That is why this can be derived at read time
+ * instead of backfilled.
+ */
+export function channelSpaceSlug(conversation: ConversationIdentityRecord): string {
+  const declared = normalizeChatSpaceSlug(
+    conversation.metadata?.[CHANNEL_SPACE_SLUG_METADATA] as string | undefined,
+  );
+  if (declared) return declared;
+
+  const naturalKey = conversationNaturalKey(conversation);
+  return chatSpaceSlugFromNaturalKey(naturalKey) ?? DEFAULT_CHAT_SPACE_SLUG;
+}
+
+/**
+ * The space named inside a natural key, or `null` when the key names none.
+ *
+ * `null` is distinct from `"home"`: it means this key carries no space at all
+ * (a direct message, a system record, a legacy channel), and the caller
+ * decides what that means. Only {@link channelSpaceSlug} turns it into the
+ * default.
+ */
+export function chatSpaceSlugFromNaturalKey(
+  naturalKey: string | null | undefined,
+): string | null {
+  const key = naturalKey?.trim();
+  if (!key) return null;
+  if (key.startsWith(SPACE_NATURAL_KEY_PREFIX)) {
+    return normalizeChatSpaceSlug(
+      decodeURIComponent(key.slice(SPACE_NATURAL_KEY_PREFIX.length)),
+    );
+  }
+  if (!key.startsWith("channel:")) return null;
+  const rest = key.slice("channel:".length);
+  const boundary = rest.indexOf("/");
+  // No separator is a legacy key, and a legacy key is a default-space key.
+  if (boundary < 0) return DEFAULT_CHAT_SPACE_SLUG;
+  return normalizeChatSpaceSlug(rest.slice(0, boundary));
+}
+
+/**
+ * Whether a conversation record is a space rather than a room.
+ *
+ * Two independent markers have to agree. `kind: "system"` is what keeps the
+ * record out of every conversation list; the natural-key prefix is what says
+ * it is a *space* and not some other system record. Requiring both means a
+ * future system conversation cannot be mistaken for a space, and a channel
+ * cannot be mistaken for one either.
+ */
+export function isChatSpaceRecord(conversation: ConversationIdentityRecord): boolean {
+  if (conversation.kind !== "system") return false;
+  const naturalKey = channelNaturalKeyFromMetadata(conversation.metadata);
+  return Boolean(naturalKey?.startsWith(SPACE_NATURAL_KEY_PREFIX));
+}
+
 export function channelNaturalKeyFromMetadata(
   metadata: MetadataMap | undefined,
 ): string | null {

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,
+  };
+}