@openscout/protocol 0.2.64 → 0.2.83

package/src/channel-identity.ts

@@ -0,0 +1,147 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+
+export type ConversationIdentityRecord = {
+  id: ScoutId;
+  kind: string;
+  metadata?: MetadataMap;
+};
+
+export const CHANNEL_ID_PREFIX = "chn-";
+export const CHAT_ID_PREFIX = CHANNEL_ID_PREFIX;
+export const LEGACY_CHAT_ID_PREFIX = "chat_";
+export const LEGACY_CHANNEL_ID_PREFIX = "c.";
+export const CHANNEL_NATURAL_KEY_METADATA = "naturalKey";
+
+export function mintChannelId(randomUuid: () => string): ScoutId {
+  return `${CHAT_ID_PREFIX}${randomUuid().toLowerCase().replace(/-/g, "")}`;
+}
+
+/**
+ * Mint the opaque id for a named/system channel from its canonical identity.
+ * Every concurrent creator therefore arrives at the same broker record even
+ * when each caller began from a stale snapshot.
+ */
+export function stableChannelId(naturalKey: string): ScoutId {
+  const normalized = naturalKey.trim().toLowerCase();
+  const hash = (seed: bigint): string => {
+    let value = seed;
+    for (let index = 0; index < normalized.length; index += 1) {
+      value ^= BigInt(normalized.charCodeAt(index));
+      value = BigInt.asUintN(64, value * 0x100000001b3n);
+    }
+    return value.toString(16).padStart(16, "0");
+  };
+  return `${CHAT_ID_PREFIX}${hash(0xcbf29ce484222325n)}${hash(0x84222325cbf29ce4n)}`;
+}
+
+export function isOpaqueChannelId(value: string | null | undefined): value is ScoutId {
+  if (typeof value !== "string") return false;
+  return (
+    value.startsWith(CHAT_ID_PREFIX) && value.length > CHAT_ID_PREFIX.length
+  ) || (
+    value.startsWith(LEGACY_CHAT_ID_PREFIX)
+    && value.length > LEGACY_CHAT_ID_PREFIX.length
+  ) || (
+    value.startsWith(LEGACY_CHANNEL_ID_PREFIX)
+    && value.length > LEGACY_CHANNEL_ID_PREFIX.length
+  );
+}
+
+export function directChannelNaturalKey(participantIds: ScoutId[]): string {
+  return `direct:${stableIdentityParts(participantIds).join(",")}`;
+}
+
+export function namedChannelNaturalKey(channel: string): string {
+  return `channel:${encodeIdentityPart(channel.trim().toLowerCase() || "shared")}`;
+}
+
+export function systemChannelNaturalKey(name: string): string {
+  return `system:${encodeIdentityPart(name.trim().toLowerCase() || "system")}`;
+}
+
+export function channelNaturalKeyFromMetadata(
+  metadata: MetadataMap | undefined,
+): string | null {
+  const value = metadata?.[CHANNEL_NATURAL_KEY_METADATA];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+/**
+ * Read the semantic identity of a conversation, including the structural ids
+ * written by Scout versions that predate `metadata.naturalKey`.
+ *
+ * Structural ids remain read-only compatibility aliases. New writes must use
+ * an opaque id and persist the natural key in metadata.
+ */
+export function conversationNaturalKey(
+  conversation: ConversationIdentityRecord,
+): string | null {
+  const explicit = channelNaturalKeyFromMetadata(conversation.metadata);
+  if (explicit) {
+    return explicit;
+  }
+
+  if (conversation.kind !== "channel" && conversation.kind !== "system") {
+    return null;
+  }
+
+  const metadataChannel = conversation.metadata?.channel;
+  const legacyChannel = conversation.id.startsWith("channel.")
+    ? conversation.id.slice("channel.".length)
+    : null;
+  const channel = typeof metadataChannel === "string" && metadataChannel.trim()
+    ? metadataChannel.trim()
+    : legacyChannel?.trim() || null;
+  if (!channel) {
+    return null;
+  }
+
+  return conversation.kind === "system"
+    ? systemChannelNaturalKey(channel)
+    : namedChannelNaturalKey(channel);
+}
+
+/**
+ * Return every record for one semantic conversation in deterministic priority
+ * order: the stable named-channel id, another opaque id, then structural
+ * compatibility aliases. This prevents snapshot insertion order from choosing
+ * which chat receives a write.
+ */
+export function conversationsWithNaturalKey<T extends ConversationIdentityRecord>(
+  conversations: Iterable<T>,
+  naturalKey: string,
+): T[] {
+  const normalizedNaturalKey = naturalKey.trim();
+  const stableId = normalizedNaturalKey.startsWith("channel:")
+    || normalizedNaturalKey.startsWith("system:")
+    ? stableChannelId(normalizedNaturalKey)
+    : null;
+  const priority = (conversation: T): number => {
+    if (stableId && conversation.id === stableId) return 0;
+    if (isOpaqueChannelId(conversation.id)) return 1;
+    return 2;
+  };
+
+  return [...conversations]
+    .filter((conversation) => conversationNaturalKey(conversation) === normalizedNaturalKey)
+    .sort((left, right) => priority(left) - priority(right) || left.id.localeCompare(right.id));
+}
+
+export function preferredConversationWithNaturalKey<T extends ConversationIdentityRecord>(
+  conversations: Iterable<T>,
+  naturalKey: string,
+): T | undefined {
+  return conversationsWithNaturalKey(conversations, naturalKey)[0];
+}
+
+function stableIdentityParts(values: ScoutId[]): string[] {
+  return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)))
+    .sort()
+    .map(encodeIdentityPart);
+}
+
+function encodeIdentityPart(value: string): string {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (char) =>
+    `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}

package/src/collaboration.ts

@@ -1,6 +1,6 @@
 import type { MetadataMap, ScoutId } from "./common.js";
 
-export type CollaborationKind = "question" | "work_item";
+export type CollaborationKind = "work_item" | "question";
 
 export type CollaborationPriority = "low" | "normal" | "high" | "urgent";
 
@@ -10,12 +10,6 @@ export type CollaborationAcceptanceState =
   | "accepted"
   | "reopened";
 
-export type QuestionState =
-  | "open"
-  | "answered"
-  | "closed"
-  | "declined";
-
 export type WorkItemState =
   | "open"
   | "working"
@@ -24,6 +18,12 @@ export type WorkItemState =
   | "done"
   | "cancelled";
 
+export type QuestionState =
+  | "open"
+  | "answered"
+  | "closed"
+  | "declined";
+
 export type CollaborationRelationKind =
   | "blocks"
   | "spawns"
@@ -37,7 +37,7 @@ export interface CollaborationRelation {
 }
 
 export interface CollaborationWaitingOn {
-  kind: "actor" | "question" | "work_item" | "approval" | "artifact" | "condition";
+  kind: "actor" | "work_item" | "approval" | "artifact" | "condition";
   label: string;
   targetId?: ScoutId;
   metadata?: MetadataMap;
@@ -69,17 +69,6 @@ export interface CollaborationRecordBase {
   metadata?: MetadataMap;
 }
 
-export interface QuestionRecord extends CollaborationRecordBase {
-  kind: "question";
-  state: QuestionState;
-  acceptanceState: CollaborationAcceptanceState;
-  askedById?: ScoutId;
-  askedOfId?: ScoutId;
-  answerMessageId?: ScoutId;
-  spawnedWorkItemId?: ScoutId;
-  closedAt?: number;
-}
-
 export interface WorkItemRecord extends CollaborationRecordBase {
   kind: "work_item";
   state: WorkItemState;
@@ -92,12 +81,33 @@ export interface WorkItemRecord extends CollaborationRecordBase {
   completedAt?: number;
 }
 
-export type CollaborationRecord = QuestionRecord | WorkItemRecord;
+/**
+ * A lightweight information-seeking interaction. A peer of {@link WorkItemRecord},
+ * not a point on the same severity ladder: a question can resolve directly, attach
+ * to a work item, or spawn one.
+ *
+ * Acceptance is modeled separately from workflow state (via `acceptanceState`) so a
+ * reply and satisfaction do not collapse into one transition — a question can be
+ * `answered` without yet being `closed`.
+ */
+export interface QuestionRecord extends CollaborationRecordBase {
+  kind: "question";
+  state: QuestionState;
+  acceptanceState: CollaborationAcceptanceState;
+  /** The actor being asked to answer. */
+  askedById?: ScoutId;
+  answeredById?: ScoutId;
+  /** The delivered answer text, present once `state` is `answered`. */
+  answer?: string;
+  answeredAt?: number;
+  closedAt?: number;
+}
+
+export type CollaborationRecord = WorkItemRecord | QuestionRecord;
 
 export type CollaborationEventKind =
   | "created"
   | "claimed"
-  | "answered"
   | "accepted"
   | "reopened"
   | "waiting"
@@ -105,7 +115,7 @@ export type CollaborationEventKind =
   | "handoff"
   | "review_requested"
   | "done"
-  | "declined"
+  | "dismissed"
   | "cancelled";
 
 export interface CollaborationEvent {
@@ -119,20 +129,47 @@ export interface CollaborationEvent {
   metadata?: MetadataMap;
 }
 
+export function isWorkItemTerminalState(state: WorkItemState): boolean {
+  return state === "done" || state === "cancelled";
+}
+
+/**
+ * A question is terminal once it is `closed` or `declined`. `answered` is NOT terminal
+ * — acceptance is tracked separately, so an answered question may still await closure.
+ */
 export function isQuestionTerminalState(state: QuestionState): boolean {
   return state === "closed" || state === "declined";
 }
 
-export function isWorkItemTerminalState(state: WorkItemState): boolean {
-  return state === "done" || state === "cancelled";
+/** Terminal-state check across both collaboration kinds. */
+export function isCollaborationTerminalState(record: CollaborationRecord): boolean {
+  return record.kind === "work_item"
+    ? isWorkItemTerminalState(record.state)
+    : isQuestionTerminalState(record.state);
 }
 
-export function collaborationRequiresNextMoveOwner(record: CollaborationRecord): boolean {
-  if (record.kind === "question") {
-    return !isQuestionTerminalState(record.state);
-  }
+/** Narrow a {@link CollaborationRecord} to a {@link WorkItemRecord}. */
+export function isWorkItem(record: CollaborationRecord): record is WorkItemRecord {
+  return record.kind === "work_item";
+}
 
-  return !isWorkItemTerminalState(record.state);
+/** Narrow a {@link CollaborationRecord} to a {@link QuestionRecord}. */
+export function isQuestion(record: CollaborationRecord): record is QuestionRecord {
+  return record.kind === "question";
+}
+
+/**
+ * The actor a collaboration record is directed at / awaiting acceptance from: the
+ * `requestedById` for a work item, the `askedById` for a question. Consumers that
+ * route or attribute a record by its requester should use this rather than reaching
+ * for a kind-specific field, so questions are handled instead of silently dropped.
+ */
+export function collaborationRequesterId(record: CollaborationRecord): ScoutId | undefined {
+  return isWorkItem(record) ? record.requestedById : record.askedById;
+}
+
+export function collaborationRequiresNextMoveOwner(record: CollaborationRecord): boolean {
+  return !isCollaborationTerminalState(record);
 }
 
 export function collaborationRequiresOwner(record: CollaborationRecord): boolean {
@@ -148,11 +185,7 @@ export function collaborationRequiresAcceptance(record: CollaborationRecord): bo
     return false;
   }
 
-  if (record.kind === "question") {
-    return Boolean(record.askedById && record.askedOfId);
-  }
-
-  return Boolean(record.requestedById);
+  return Boolean(collaborationRequesterId(record));
 }
 
 export function validateCollaborationRecord(record: CollaborationRecord): string[] {
@@ -190,14 +223,18 @@ export function validateCollaborationRecord(record: CollaborationRecord): string
     errors.push("waiting work items require waitingOn");
   }
 
-  if (record.kind === "question") {
-    if (record.spawnedWorkItemId && record.spawnedWorkItemId === record.id) {
-      errors.push("question spawnedWorkItemId cannot reference the question itself");
-    }
-  } else if (record.waitingOn?.targetId && record.waitingOn.targetId === record.id) {
+  if (
+    record.kind === "work_item"
+    && record.waitingOn?.targetId
+    && record.waitingOn.targetId === record.id
+  ) {
     errors.push("waitingOn.targetId cannot reference the work item itself");
   }
 
+  if (record.kind === "question" && record.state === "answered" && !record.answer?.trim()) {
+    errors.push("answered questions require an answer");
+  }
+
   if (record.acceptanceState !== "none" && !collaborationRequiresAcceptance(record)) {
     errors.push("acceptanceState requires the corresponding requester and reviewer identities");
   }
@@ -239,20 +276,13 @@ export function validateCollaborationEvent(
     }
   }
 
-  if (event.kind === "answered" && event.recordKind !== "question") {
-    errors.push("answered events only apply to questions");
-  }
-
-  if (event.kind === "declined" && event.recordKind !== "question") {
-    errors.push("declined events only apply to questions");
-  }
-
   if (
     (event.kind === "waiting"
       || event.kind === "progressed"
       || event.kind === "review_requested"
       || event.kind === "done"
-      || event.kind === "cancelled")
+      || event.kind === "cancelled"
+      || event.kind === "claimed")
     && event.recordKind !== "work_item"
   ) {
     errors.push(`${event.kind} events only apply to work items`);

package/src/common.ts

@@ -4,26 +4,35 @@ export type ActorKind =
   | "person"
   | "helper"
   | "agent"
+  | "session"
   | "system"
   | "bridge"
   | "device";
 
 export type AgentState =
+  | "registered"
+  | "attaching"
+  | "waking"
   | "offline"
   | "idle"
   | "active"
-  | "waiting";
+  | "waiting"
+  | "working"
+  | "unreachable"
+  | "failed"
+  | "superseded"
+  | "stopped";
 
 export type VisibilityScope = "private" | "workspace" | "public" | "system";
 
 export type DeliveryStatus =
-  // Outbox lifecycle (Issue 3 of broker-three-contracts)
+  // Outbox lifecycle
   | "accepted"        // local journal write done, awaiting forward
   | "peer_acked"      // peer broker journaled the envelope
   | "running"         // target agent claimed the flight
   | "completed"       // terminal success
-  | "deferred"        // within retry window — see metadata.nextAttemptAt
-  | "failed"          // terminal failure — see metadata.failureReason
+  | "deferred"        // within retry window — see DeliveryMetadata.nextAttemptAt
+  | "failed"          // terminal failure — see DeliveryMetadata.failureReason
   | "cancelled"
   // Legacy values kept for backwards-compatible journal replay
   | "pending"
@@ -63,11 +72,21 @@ export type DeliveryTransport =
   | "email"
   | "tts"
   | "native_voice"
+  | "claude_channel"
   | "claude_stream_json"
   | "codex_app_server"
   | "codex_exec"
   | "claude_resume"
-  | "tmux";
+  | "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 DeliveryReason =
   | "conversation_visibility"

package/src/cursor-transport.ts

@@ -0,0 +1,34 @@
+/**
+ * Local Cursor harness transport modes under evaluation.
+ * See docs/eng/sco-047-cursor-transport-spike.md.
+ */
+export const CURSOR_LOCAL_TRANSPORT_MODES = [
+  "cursor_cli_text",
+  "cursor_cli_stream_json",
+  "cursor_sdk_local",
+  "cursor_sdk_local_no_key",
+] as const;
+
+export type CursorLocalTransportMode = typeof CURSOR_LOCAL_TRANSPORT_MODES[number];
+
+export type CursorTransportAuthSource =
+  | "none"
+  | "env"
+  | "cursor_api_key_file"
+  | "cli_flag"
+  | "sdk_option";
+
+export type CursorTransportSpikeResult = {
+  mode: CursorLocalTransportMode;
+  ok: boolean;
+  durationMs: number;
+  authSource: CursorTransportAuthSource;
+  sessionId?: string;
+  agentId?: string;
+  runId?: string;
+  outputText?: string;
+  eventCount?: number;
+  errorCode?: string;
+  errorMessage?: string;
+  notes?: string[];
+};

package/src/debug-attach.ts

@@ -0,0 +1,38 @@
+import type { ScoutId } from "./common.js";
+
+export interface AgentEndpointDebugTransport {
+  kind: "tmux";
+  state: "ready" | "starting" | "missing" | "stale" | "error";
+  sessionName: string;
+  paneTarget?: string;
+  cwd?: string;
+  attachable: boolean;
+  multiAttach: boolean;
+  lastProbeAt: number;
+  lastAttachAt?: number;
+  lastDetachAt?: number;
+  activeClients?: number;
+  detail?: string;
+}
+
+export interface DebugTmuxAttachPlan {
+  endpointId: ScoutId;
+  transport: "tmux";
+  sessionName: string;
+  paneTarget?: string;
+  command?: ["tmux", "attach-session", "-t", string];
+  terminalRelay?: {
+    backend: "tmux";
+    tmuxSession: string;
+  };
+}
+
+export function isDebugTransportAttachable(
+  transport: Pick<AgentEndpointDebugTransport, "state" | "attachable"> | null | undefined,
+): boolean {
+  return Boolean(transport?.attachable && transport.state === "ready");
+}
+
+export function buildTmuxAttachCommand(sessionName: string): ["tmux", "attach-session", "-t", string] {
+  return ["tmux", "attach-session", "-t", sessionName];
+}

package/src/deliveries.ts

@@ -1,4 +1,5 @@
 import type {
+  DeliveryFailureReason,
   DeliveryPolicy,
   DeliveryReason,
   DeliveryStatus,
@@ -8,6 +9,20 @@ import type {
   ScoutId,
 } from "./common.js";
 
+/**
+ * Delivery metadata carries a small set of well-known keys alongside arbitrary
+ * extension data. The typed fields document the keys the runtime reads on the
+ * retry path; the {@link MetadataMap} index signature keeps the bag open for
+ * transport-specific extras. The wire/persistence shape is unchanged — these
+ * were always plain metadata keys, now they are typed.
+ */
+export interface DeliveryMetadata extends MetadataMap {
+  /** Epoch ms of the next retry attempt. Set while `status` is `"deferred"`. */
+  nextAttemptAt?: number;
+  /** Classified failure reason. Set when `status` is `"failed"`. */
+  failureReason?: DeliveryFailureReason;
+}
+
 export interface DeliveryTarget {
   id: ScoutId;
   kind: DeliveryTargetKind;
@@ -31,7 +46,7 @@ export interface DeliveryIntent {
   bindingId?: ScoutId;
   leaseOwner?: string;
   leaseExpiresAt?: number;
-  metadata?: MetadataMap;
+  metadata?: DeliveryMetadata;
 }
 
 export interface DeliveryAttempt {

package/src/durable-actions.ts

@@ -0,0 +1,125 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+
+// First implementation slice. Add work_item/question/approval only after ask,
+// message_delivery, and checkback semantics prove out against real paths.
+export type DurableActionKind = "ask" | "message_delivery" | "checkback";
+
+export type DurableCheckbackMode =
+  | "notify"
+  | "scoutbot"
+  | "agent"
+  | "routine";
+
+export interface DurableCheckbackMetadata extends MetadataMap {
+  dueAt: number;
+  mode?: DurableCheckbackMode;
+  title?: string;
+  body?: string;
+  prompt?: string;
+  ownerId?: ScoutId;
+  conversationId?: ScoutId;
+  recordId?: ScoutId;
+  route?: unknown;
+  recurrence?: unknown;
+}
+
+export type DurableActionState =
+  | "pending"
+  | "leased"
+  | "running"
+  | "waiting"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+export type DurableAttemptState =
+  | "pending"
+  | "running"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+export interface DurableAction {
+  id: ScoutId;
+  kind: DurableActionKind;
+  subjectId: ScoutId;
+  authorityCellId: ScoutId;
+  state: DurableActionState;
+  idempotencyKey?: string;
+  leaseOwner?: string;
+  leaseGeneration: number;
+  leaseExpiresAt?: number;
+  createdAt: number;
+  updatedAt: number;
+  metadata?: MetadataMap;
+}
+
+export interface DurableAttempt {
+  id: ScoutId;
+  actionId: ScoutId;
+  attempt: number;
+  state: DurableAttemptState;
+  leaseGeneration: number;
+  error?: string;
+  startedAt?: number;
+  completedAt?: number;
+  metadata?: MetadataMap;
+}
+
+export interface DurableCheckpoint {
+  actionId: ScoutId;
+  name: string;
+  payload?: unknown;
+  ownerAttemptId?: ScoutId;
+  leaseOwner?: string;
+  leaseGeneration?: number;
+  createdAt: number;
+}
+
+export interface DurableSignal {
+  actionId: ScoutId;
+  name: string;
+  payload?: unknown;
+  leaseOwner?: string;
+  leaseGeneration?: number;
+  emittedAt: number;
+}
+
+export interface DurableActionCreateInput {
+  id: ScoutId;
+  kind: DurableActionKind;
+  subjectId: ScoutId;
+  authorityCellId: ScoutId;
+  idempotencyKey?: string;
+  createdAt: number;
+  metadata?: MetadataMap;
+}
+
+export interface DurableActionClaimInput {
+  actionId: ScoutId;
+  owner: string;
+  leaseMs: number;
+  claimedAt: number;
+}
+
+export interface DurableActionHeartbeatInput {
+  actionId: ScoutId;
+  owner: string;
+  generation: number;
+  leaseMs: number;
+  heartbeatAt: number;
+}
+
+export interface DurableActionLease {
+  owner: string;
+  generation: number;
+  expiresAt: number;
+}
+
+export interface DurableActionCommandReceipt {
+  accepted: boolean;
+  duplicate?: boolean;
+  action: DurableAction;
+  lease?: DurableActionLease;
+  events: string[];
+}