@openscout/protocol 0.2.16 → 0.2.17

package/src/collaboration.ts

@@ -0,0 +1,272 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+
+export type CollaborationKind = "question" | "work_item";
+
+export type CollaborationPriority = "low" | "normal" | "high" | "urgent";
+
+export type CollaborationAcceptanceState =
+  | "none"
+  | "pending"
+  | "accepted"
+  | "reopened";
+
+export type QuestionState =
+  | "open"
+  | "answered"
+  | "closed"
+  | "declined";
+
+export type WorkItemState =
+  | "open"
+  | "working"
+  | "waiting"
+  | "review"
+  | "done"
+  | "cancelled";
+
+export type CollaborationRelationKind =
+  | "blocks"
+  | "spawns"
+  | "relates_to"
+  | "references";
+
+export interface CollaborationRelation {
+  kind: CollaborationRelationKind;
+  targetId: ScoutId;
+  metadata?: MetadataMap;
+}
+
+export interface CollaborationWaitingOn {
+  kind: "actor" | "question" | "work_item" | "approval" | "artifact" | "condition";
+  label: string;
+  targetId?: ScoutId;
+  metadata?: MetadataMap;
+}
+
+export interface CollaborationProgress {
+  completedSteps?: number;
+  totalSteps?: number;
+  checkpoint?: string;
+  summary?: string;
+  percent?: number;
+}
+
+export interface CollaborationRecordBase {
+  id: ScoutId;
+  kind: CollaborationKind;
+  title: string;
+  summary?: string;
+  createdById: ScoutId;
+  ownerId?: ScoutId;
+  nextMoveOwnerId?: ScoutId;
+  conversationId?: ScoutId;
+  parentId?: ScoutId;
+  priority?: CollaborationPriority;
+  labels?: string[];
+  relations?: CollaborationRelation[];
+  createdAt: number;
+  updatedAt: number;
+  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;
+  acceptanceState: CollaborationAcceptanceState;
+  requestedById?: ScoutId;
+  waitingOn?: CollaborationWaitingOn;
+  progress?: CollaborationProgress;
+  startedAt?: number;
+  reviewRequestedAt?: number;
+  completedAt?: number;
+}
+
+export type CollaborationRecord = QuestionRecord | WorkItemRecord;
+
+export type CollaborationEventKind =
+  | "created"
+  | "claimed"
+  | "answered"
+  | "accepted"
+  | "reopened"
+  | "waiting"
+  | "progressed"
+  | "handoff"
+  | "review_requested"
+  | "done"
+  | "declined"
+  | "cancelled";
+
+export interface CollaborationEvent {
+  id: ScoutId;
+  recordId: ScoutId;
+  recordKind: CollaborationKind;
+  kind: CollaborationEventKind;
+  actorId: ScoutId;
+  at: number;
+  summary?: string;
+  metadata?: MetadataMap;
+}
+
+export function isQuestionTerminalState(state: QuestionState): boolean {
+  return state === "closed" || state === "declined";
+}
+
+export function isWorkItemTerminalState(state: WorkItemState): boolean {
+  return state === "done" || state === "cancelled";
+}
+
+export function collaborationRequiresNextMoveOwner(record: CollaborationRecord): boolean {
+  if (record.kind === "question") {
+    return !isQuestionTerminalState(record.state);
+  }
+
+  return !isWorkItemTerminalState(record.state);
+}
+
+export function collaborationRequiresOwner(record: CollaborationRecord): boolean {
+  return record.kind === "work_item" && !isWorkItemTerminalState(record.state);
+}
+
+export function collaborationRequiresWaitingOn(record: CollaborationRecord): boolean {
+  return record.kind === "work_item" && record.state === "waiting";
+}
+
+export function collaborationRequiresAcceptance(record: CollaborationRecord): boolean {
+  if (record.acceptanceState === "none") {
+    return false;
+  }
+
+  if (record.kind === "question") {
+    return Boolean(record.askedById && record.askedOfId);
+  }
+
+  return Boolean(record.requestedById);
+}
+
+export function validateCollaborationRecord(record: CollaborationRecord): string[] {
+  const errors: string[] = [];
+
+  if (!record.id.trim()) {
+    errors.push("collaboration record id is required");
+  }
+
+  if (!record.title.trim()) {
+    errors.push("collaboration title is required");
+  }
+
+  if (!record.createdById.trim()) {
+    errors.push("createdById is required");
+  }
+
+  if (record.parentId && record.parentId === record.id) {
+    errors.push("parentId cannot reference the record itself");
+  }
+
+  if (record.createdAt > record.updatedAt) {
+    errors.push("updatedAt must be greater than or equal to createdAt");
+  }
+
+  if (collaborationRequiresOwner(record) && !record.ownerId) {
+    errors.push("non-terminal work items require ownerId");
+  }
+
+  if (collaborationRequiresNextMoveOwner(record) && !record.nextMoveOwnerId) {
+    errors.push("non-terminal collaboration records require nextMoveOwnerId");
+  }
+
+  if (record.kind === "work_item" && collaborationRequiresWaitingOn(record) && !record.waitingOn) {
+    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) {
+    errors.push("waitingOn.targetId cannot reference the work item itself");
+  }
+
+  if (record.acceptanceState !== "none" && !collaborationRequiresAcceptance(record)) {
+    errors.push("acceptanceState requires the corresponding requester and reviewer identities");
+  }
+
+  return errors;
+}
+
+export function assertValidCollaborationRecord(record: CollaborationRecord): void {
+  const errors = validateCollaborationRecord(record);
+  if (errors.length > 0) {
+    throw new Error(errors.join("; "));
+  }
+}
+
+export function validateCollaborationEvent(
+  event: CollaborationEvent,
+  record?: CollaborationRecord,
+): string[] {
+  const errors: string[] = [];
+
+  if (!event.id.trim()) {
+    errors.push("collaboration event id is required");
+  }
+
+  if (!event.recordId.trim()) {
+    errors.push("collaboration event recordId is required");
+  }
+
+  if (!event.actorId.trim()) {
+    errors.push("collaboration event actorId is required");
+  }
+
+  if (record) {
+    if (record.id !== event.recordId) {
+      errors.push("collaboration event recordId does not match the target record");
+    }
+    if (record.kind !== event.recordKind) {
+      errors.push("collaboration event recordKind does not match the target record");
+    }
+  }
+
+  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.recordKind !== "work_item"
+  ) {
+    errors.push(`${event.kind} events only apply to work items`);
+  }
+
+  return errors;
+}
+
+export function assertValidCollaborationEvent(
+  event: CollaborationEvent,
+  record?: CollaborationRecord,
+): void {
+  const errors = validateCollaborationEvent(event, record);
+  if (errors.length > 0) {
+    throw new Error(errors.join("; "));
+  }
+}

package/src/common.ts

@@ -0,0 +1,71 @@
+export type ScoutId = string;
+
+export type ActorKind =
+  | "person"
+  | "helper"
+  | "agent"
+  | "system"
+  | "bridge"
+  | "device";
+
+export type AgentState =
+  | "offline"
+  | "idle"
+  | "active"
+  | "waiting"
+  | "degraded";
+
+export type VisibilityScope = "private" | "workspace" | "public" | "system";
+
+export type DeliveryStatus =
+  | "pending"
+  | "leased"
+  | "sent"
+  | "acknowledged"
+  | "failed"
+  | "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"
+  | "peer_broker"
+  | "http"
+  | "webhook"
+  | "telegram"
+  | "discord"
+  | "sms"
+  | "email"
+  | "tts"
+  | "native_voice"
+  | "claude_stream_json"
+  | "codex_app_server"
+  | "codex_exec"
+  | "claude_resume"
+  | "tmux";
+
+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";
+
+export interface MetadataMap {
+  [key: string]: unknown;
+}

package/src/conversations.ts

@@ -0,0 +1,37 @@
+import type {
+  MetadataMap,
+  ScoutId,
+  ShareMode,
+  VisibilityScope,
+} from "./common.js";
+
+export type ConversationKind =
+  | "channel"
+  | "direct"
+  | "group_direct"
+  | "thread"
+  | "system";
+
+export interface ConversationDefinition {
+  id: ScoutId;
+  kind: ConversationKind;
+  title: string;
+  visibility: VisibilityScope;
+  shareMode: ShareMode;
+  authorityNodeId: ScoutId;
+  participantIds: ScoutId[];
+  topic?: string;
+  parentConversationId?: ScoutId;
+  messageId?: ScoutId;
+  metadata?: MetadataMap;
+}
+
+export interface ConversationBinding {
+  id: ScoutId;
+  conversationId: ScoutId;
+  platform: string;
+  mode: "inbound" | "outbound" | "bidirectional";
+  externalChannelId: string;
+  externalThreadId?: string;
+  metadata?: MetadataMap;
+}

package/src/deliveries.ts

@@ -0,0 +1,46 @@
+import type {
+  DeliveryPolicy,
+  DeliveryReason,
+  DeliveryStatus,
+  DeliveryTargetKind,
+  DeliveryTransport,
+  MetadataMap,
+  ScoutId,
+} from "./common.js";
+
+export interface DeliveryTarget {
+  id: ScoutId;
+  kind: DeliveryTargetKind;
+  transport: DeliveryTransport;
+  address?: string;
+  bindingId?: ScoutId;
+  metadata?: MetadataMap;
+}
+
+export interface DeliveryIntent {
+  id: ScoutId;
+  messageId?: ScoutId;
+  invocationId?: ScoutId;
+  targetId: ScoutId;
+  targetNodeId?: ScoutId;
+  targetKind: DeliveryTargetKind;
+  transport: DeliveryTransport;
+  reason: DeliveryReason;
+  policy: DeliveryPolicy;
+  status: DeliveryStatus;
+  bindingId?: ScoutId;
+  leaseOwner?: string;
+  leaseExpiresAt?: number;
+  metadata?: MetadataMap;
+}
+
+export interface DeliveryAttempt {
+  id: ScoutId;
+  deliveryId: ScoutId;
+  attempt: number;
+  status: "sent" | "acknowledged" | "failed";
+  error?: string;
+  externalRef?: string;
+  createdAt: number;
+  metadata?: MetadataMap;
+}

package/src/events.ts

@@ -0,0 +1,84 @@
+import type { ScoutId } from "./common.js";
+import type { NodeDefinition } from "./mesh.js";
+import type { ConversationBinding, ConversationDefinition } from "./conversations.js";
+import type { DeliveryAttempt, DeliveryIntent } from "./deliveries.js";
+import type { FlightRecord, InvocationRequest } from "./invocations.js";
+import type { MessageRecord } from "./messages.js";
+import type { AgentDefinition, AgentEndpoint, ActorIdentity } from "./actors.js";
+import type { CollaborationEvent, CollaborationRecord } from "./collaboration.js";
+
+export interface ControlEventBase<K extends string, P> {
+  id: ScoutId;
+  kind: K;
+  ts: number;
+  actorId: ScoutId;
+  nodeId?: ScoutId;
+  payload: P;
+}
+
+export type NodeUpsertedEvent = ControlEventBase<"node.upserted", {
+  node: NodeDefinition;
+}>;
+
+export type ActorRegisteredEvent = ControlEventBase<"actor.registered", {
+  actor: ActorIdentity;
+}>;
+
+export type AgentRegisteredEvent = ControlEventBase<"agent.registered", {
+  agent: AgentDefinition;
+}>;
+
+export type AgentEndpointUpsertedEvent = ControlEventBase<"agent.endpoint.upserted", {
+  endpoint: AgentEndpoint;
+}>;
+
+export type ConversationUpsertedEvent = ControlEventBase<"conversation.upserted", {
+  conversation: ConversationDefinition;
+}>;
+
+export type BindingUpsertedEvent = ControlEventBase<"binding.upserted", {
+  binding: ConversationBinding;
+}>;
+
+export type MessagePostedEvent = ControlEventBase<"message.posted", {
+  message: MessageRecord;
+}>;
+
+export type InvocationRequestedEvent = ControlEventBase<"invocation.requested", {
+  invocation: InvocationRequest;
+}>;
+
+export type FlightUpdatedEvent = ControlEventBase<"flight.updated", {
+  flight: FlightRecord;
+}>;
+
+export type DeliveryPlannedEvent = ControlEventBase<"delivery.planned", {
+  delivery: DeliveryIntent;
+}>;
+
+export type DeliveryAttemptedEvent = ControlEventBase<"delivery.attempted", {
+  attempt: DeliveryAttempt;
+}>;
+
+export type CollaborationUpsertedEvent = ControlEventBase<"collaboration.upserted", {
+  record: CollaborationRecord;
+}>;
+
+export type CollaborationEventAppendedEvent = ControlEventBase<"collaboration.event.appended", {
+  event: CollaborationEvent;
+}>;
+
+export type ControlEvent =
+  | NodeUpsertedEvent
+  | ActorRegisteredEvent
+  | AgentRegisteredEvent
+  | AgentEndpointUpsertedEvent
+  | ConversationUpsertedEvent
+  | BindingUpsertedEvent
+  | MessagePostedEvent
+  | InvocationRequestedEvent
+  | FlightUpdatedEvent
+  | DeliveryPlannedEvent
+  | DeliveryAttemptedEvent
+  | CollaborationUpsertedEvent
+  | CollaborationEventAppendedEvent;

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from "./common.js";
+export * from "./actors.js";
+export * from "./agent-identity.js";
+export * from "./agent-address.js";
+export * from "./agent-selectors.js";
+export * from "./relay-agent-card.js";
+export * from "./mesh.js";
+export * from "./conversations.js";
+export * from "./collaboration.js";
+export * from "./messages.js";
+export * from "./invocations.js";
+export * from "./deliveries.js";
+export * from "./transports.js";
+export * from "./events.js";

package/src/invocations.ts

@@ -0,0 +1,55 @@
+import type { AgentHarness } from "./actors.js";
+import type { MetadataMap, ScoutId } from "./common.js";
+
+export type InvocationAction =
+  | "consult"
+  | "execute"
+  | "summarize"
+  | "status"
+  | "wake";
+
+export type FlightState =
+  | "queued"
+  | "waking"
+  | "running"
+  | "waiting"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+export interface InvocationExecutionPreference {
+  harness?: AgentHarness;
+}
+
+export interface InvocationRequest {
+  id: ScoutId;
+  requesterId: ScoutId;
+  requesterNodeId: ScoutId;
+  targetAgentId: ScoutId;
+  targetNodeId?: ScoutId;
+  action: InvocationAction;
+  task: string;
+  conversationId?: ScoutId;
+  messageId?: ScoutId;
+  context?: MetadataMap;
+  execution?: InvocationExecutionPreference;
+  ensureAwake: boolean;
+  stream: boolean;
+  timeoutMs?: number;
+  createdAt: number;
+  metadata?: MetadataMap;
+}
+
+export interface FlightRecord {
+  id: ScoutId;
+  invocationId: ScoutId;
+  requesterId: ScoutId;
+  targetAgentId: ScoutId;
+  state: FlightState;
+  summary?: string;
+  output?: string;
+  error?: string;
+  startedAt?: number;
+  completedAt?: number;
+  metadata?: MetadataMap;
+}

package/src/mesh.ts

@@ -0,0 +1,16 @@
+import type { AdvertiseScope, MetadataMap, ScoutId } from "./common.js";
+
+export interface NodeDefinition {
+  id: ScoutId;
+  meshId: ScoutId;
+  name: string;
+  hostName?: string;
+  advertiseScope: AdvertiseScope;
+  brokerUrl?: string;
+  tailnetName?: string;
+  capabilities?: string[];
+  labels?: string[];
+  metadata?: MetadataMap;
+  lastSeenAt?: number;
+  registeredAt: number;
+}

package/src/messages.ts

@@ -0,0 +1,55 @@
+import type {
+  DeliveryPolicy,
+  DeliveryReason,
+  MetadataMap,
+  ScoutId,
+  VisibilityScope,
+} from "./common.js";
+
+export type MessageClass = "agent" | "log" | "system" | "status" | "artifact";
+
+export interface MessageSpeechDirective {
+  text: string;
+  voice?: string;
+  interruptible?: boolean;
+}
+
+export interface MessageAttachment {
+  id: ScoutId;
+  mediaType: string;
+  fileName?: string;
+  blobKey?: string;
+  url?: string;
+  metadata?: MetadataMap;
+}
+
+export interface MessageMention {
+  actorId: ScoutId;
+  label?: string;
+}
+
+export interface MessageAudience {
+  visibleTo?: ScoutId[];
+  notify?: ScoutId[];
+  invoke?: ScoutId[];
+  reason?: DeliveryReason;
+}
+
+export interface MessageRecord {
+  id: ScoutId;
+  conversationId: ScoutId;
+  actorId: ScoutId;
+  originNodeId: ScoutId;
+  class: MessageClass;
+  body: string;
+  replyToMessageId?: ScoutId;
+  threadConversationId?: ScoutId;
+  mentions?: MessageMention[];
+  attachments?: MessageAttachment[];
+  speech?: MessageSpeechDirective;
+  audience?: MessageAudience;
+  visibility: VisibilityScope;
+  policy: DeliveryPolicy;
+  createdAt: number;
+  metadata?: MetadataMap;
+}

package/src/relay-agent-card.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+
+import { buildRelayReturnAddress } from "./relay-agent-card";
+
+describe("buildRelayReturnAddress", () => {
+  test("keeps only meaningful optional fields", () => {
+    const address = buildRelayReturnAddress({
+      actorId: "dewey.node.workspace",
+      handle: "dewey",
+      displayName: "Dewey",
+      selector: "@dewey.node.workspace",
+      defaultSelector: "@dewey",
+      conversationId: "dm.dewey.arc",
+      replyToMessageId: "msg-1",
+      nodeId: "node-1",
+      projectRoot: "/Users/arach/dev/dewey",
+      sessionId: "relay-dewey-claude",
+      metadata: {
+        surface: "scout-card",
+      },
+    });
+
+    expect(address).toEqual({
+      actorId: "dewey.node.workspace",
+      handle: "dewey",
+      displayName: "Dewey",
+      selector: "@dewey.node.workspace",
+      defaultSelector: "@dewey",
+      conversationId: "dm.dewey.arc",
+      replyToMessageId: "msg-1",
+      nodeId: "node-1",
+      projectRoot: "/Users/arach/dev/dewey",
+      sessionId: "relay-dewey-claude",
+      metadata: {
+        surface: "scout-card",
+      },
+    });
+  });
+
+  test("drops empty optional fields", () => {
+    const address = buildRelayReturnAddress({
+      actorId: "arc",
+      handle: "arc",
+      displayName: "  ",
+      selector: " ",
+      metadata: {},
+    });
+
+    expect(address).toEqual({
+      actorId: "arc",
+      handle: "arc",
+    });
+  });
+});