@openscout/protocol 0.1.0

package/README.md

@@ -0,0 +1,245 @@
+# OpenScout Control Protocol
+
+`@openscout/protocol` defines the durable local communication and execution contract for OpenScout.
+
+This package is intentionally not named `relay`. Relay is now a surface and compatibility layer. The control protocol is the canonical model underneath it.
+
+## What Makes This A Good Local Communication Protocol
+
+The target is a protocol that is:
+
+- explicit: conversation, work, delivery, and external bindings are separate records
+- durable: the broker is the only writer and local state is stored canonically
+- addressable: actors, conversations, messages, invocations, flights, and deliveries all have stable IDs
+- replayable: read models can be rebuilt from durable records and events
+- observable: status, ownership, outputs, and failures are inspectable
+- recoverable: broker restarts do not have to erase the story of what happened
+- harness-agnostic: harness details live at endpoints and adapters, not in the protocol itself
+
+If someone asks why this is better than terminal scrollback or ad hoc file sharing, that is the answer.
+
+## Core Model
+
+The protocol keeps a small set of nouns and gives each one a single job:
+
+- `actor`: an identity in the system such as a person, helper, agent, system process, bridge, or device
+- `agent`: a durable autonomous target with capabilities and one or more endpoints
+- `conversation`: an addressable context boundary such as a channel, direct message, thread, or system conversation
+- `message`: a human-readable conversation record
+- `invocation`: an explicit request for work
+- `flight`: the tracked lifecycle of one invocation
+- `delivery`: a transport-specific fan-out intent for a message or invocation
+- `binding`: a mapping from an OpenScout conversation to an external thread or channel
+- `event`: an append-only fact emitted whenever one of the durable records changes
+
+## Emerging Collaboration Model
+
+The protocol package now also exports a collaboration vocabulary for the next layer above
+messages and invocations. This is the first thin slice toward explicit human-agent and
+agent-agent workflow tracking. It is intentionally small.
+
+The current canonical collaboration kinds are:
+
+- `question`: a lightweight information-seeking interaction with states such as `open`,
+  `answered`, `closed`, and `declined`
+- `work_item`: a durable execution object with states such as `open`, `working`,
+  `waiting`, `review`, `done`, and `cancelled`
+
+These are peers, not points on one severity ladder:
+
+- a question can resolve directly
+- a question can attach to a work item
+- a question can spawn a work item
+- a work item can accumulate progress, waiting conditions, and review state without
+  pretending it started as a question
+
+Acceptance is modeled separately from workflow state so that a reply and satisfaction do
+not collapse into one transition. A work item can be done without peer acceptance, and a
+question can be answered without being closed yet.
+
+The exported collaboration shapes are a protocol vocabulary for upcoming runtime and UI
+work. They do not yet imply that the broker persists the full collaboration layer today.
+See [docs/collaboration-workflows-v1.md](../../docs/collaboration-workflows-v1.md) for the
+v1 model.
+
+## Identity Model
+
+The important distinction is between a helper and an agent:
+
+- `person`: the actual human identity
+- `helper`: a session-bound assistant working on behalf of a person
+- `agent`: a durable autonomous player with its own identity and capabilities
+- `system`: runtime-owned internal identity
+- `bridge`: external platform adapter identity
+- `device`: a concrete endpoint such as a native app client or speaker session
+
+This lets a person work with a helper in Codex or Claude while still invoking real agents as first-class targets.
+
+## Core Design Rules
+
+1. A message is conversation.
+2. An invocation is work.
+3. A flight is the tracked lifecycle of that work.
+4. Delivery is planned explicitly per target and transport.
+5. Bindings map external channels into the same internal model.
+6. Voice is metadata and transport, not the canonical message body.
+7. The broker is the only canonical writer.
+
+## Bootstrap And Startup
+
+The intended machine lifecycle is:
+
+1. `scout init` creates machine-local settings, a relay agent registry, and repo-local `.openscout/project.json` when needed.
+2. The runtime installs a launch agent under `~/Library/LaunchAgents/` for the broker.
+3. `launchd` keeps the broker process alive and restarts it if it exits.
+4. Workspace discovery scans configured roots and repo-local manifests to map projects to agent identities.
+5. Agents register endpoints that describe their harness, transport, session, cwd, and project root.
+6. Surfaces such as the desktop shell, CLI, and relay compatibility layer talk to the broker instead of writing shared files directly.
+
+## Conversation, Work, And Delivery
+
+### Conversation
+
+Conversation is human-readable history:
+
+- channels
+- direct messages
+- group direct messages
+- threads
+- system conversations
+
+Conversation state is designed for:
+
+- visibility
+- unread tracking
+- mentions
+- search
+- auditability
+
+### Invocation
+
+Invocation is a request for action:
+
+- consult an agent
+- execute a task
+- summarize state
+- report status
+- wake an agent
+
+Invocations create flights. Flights stream lifecycle state separately from the chat surface they came from.
+
+### Delivery
+
+Each authored message exists once. Delivery fans out into typed intents.
+
+The runtime plans deliveries separately for:
+
+- conversation visibility
+- notifications
+- explicit invocations
+- bridge outbound traffic
+- speech playback
+
+That means a single message can be visible to a channel, notify a mention, invoke an agent, and bridge outbound without duplicating the body.
+
+## Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant S as "Surface (CLI/Desktop/Bridge)"
+    participant B as "Broker"
+    participant DB as "Local Store"
+    participant H as "Agent Harness"
+
+    S->>B: Post message or invocation
+    B->>DB: Persist durable record
+    B->>DB: Append control event
+    B->>H: Plan delivery or wake target endpoint
+    H->>B: Flight update (queued/running/waiting/completed/failed)
+    B->>DB: Persist flight and delivery state
+    H->>B: Result message, artifact, or status
+    B->>DB: Persist output and append event
+    B-->>S: Stream updated conversation and work state
+```
+
+The important part is the separation:
+
+- messages make the conversation legible
+- invocations make work explicit
+- flights track execution without overloading chat
+- deliveries make routing visible instead of implicit
+
+## Storage Model
+
+The runtime package owns the SQLite schema. The durable model is:
+
+- `nodes`
+- `actors`
+- `agents`
+- `agent_endpoints`
+- `conversations`
+- `conversation_members`
+- `messages`
+- `message_mentions`
+- `message_attachments`
+- `invocations`
+- `flights`
+- `bindings`
+- `deliveries`
+- `delivery_attempts`
+- `events`
+
+SQLite is the canonical store because it stays local and inspectable while handling append races, indexing, leases, retries, and subscriptions better than raw JSONL.
+
+## Why Work Does Not Get Lost
+
+The protocol is designed so that the system does not depend on terminal scrollback to remember what happened.
+
+- messages are durable conversation records
+- invocations are durable work requests
+- flights are durable execution state
+- deliveries and delivery attempts make routing and failures inspectable
+- bindings make external channel mappings durable
+- append-only events let read models be rebuilt
+
+That does not require every surface to be smart. The broker owns the hard part, and the surfaces can recover by reading the canonical store.
+
+## Harness-Agnostic By Design
+
+OpenScout should not fork its protocol per harness.
+
+- endpoint records describe `harness`, `transport`, `session_id`, `cwd`, and `project_root`
+- the same invocation and flight model applies whether the endpoint is Claude, Codex, tmux, or a future harness
+- harness-specific launch and wake behavior belongs in runtime adapters
+- bridge integrations stay at the edge and map into the same durable model
+
+This keeps the protocol stable even when the execution layer changes.
+
+## Modalities
+
+The protocol supports multiple modalities, but text remains canonical.
+
+- HTTP: commands, admin, webhook intake
+- WebSocket: subscriptions, streaming flight updates, typing/presence
+- local socket: trusted local clients such as the native app and CLI
+- bridges: Telegram, Discord, telecom adapters
+- voice: transcripts, playback directives, media references
+
+Raw media does not belong in the primary message log. The protocol stores transcript, speech, and attachment metadata while media transport stays on a dedicated transport.
+
+## What The Protocol Is Not
+
+OpenScout is intentionally not trying to be:
+
+- a hosted chat service
+- a workflow engine with mandatory plan bureaucracy
+- a harness-specific control plane
+- a replacement for Telegram, Discord, or tmux
+
+It is the durable local substrate that makes agent communication legible, inspectable, and recoverable.
+
+## Migration Direction
+
+The control protocol replaces Relay as the core architecture.
+
+Any remaining Relay-specific tools should be treated as surfaces or compatibility utilities, not as canonical storage or runtime paths.

package/dist/actors.d.ts

@@ -0,0 +1,49 @@
+import type { ActorKind, AdvertiseScope, AgentState, MetadataMap, ScoutId } from "./common.js";
+export type AgentClass = "general" | "builder" | "reviewer" | "researcher" | "operator" | "bridge" | "system";
+export type AgentCapability = "chat" | "invoke" | "deliver" | "speak" | "listen" | "bridge" | "summarize" | "review" | "execute";
+export type AgentHarness = "codex" | "claude" | "native" | "worker" | "bridge" | "http";
+export type WakePolicy = "manual" | "on_demand" | "keep_warm";
+export interface ActorIdentity {
+    id: ScoutId;
+    kind: ActorKind;
+    displayName: string;
+    handle?: string;
+    labels?: string[];
+    metadata?: MetadataMap;
+}
+export interface AgentDefinition extends ActorIdentity {
+    kind: "agent";
+    definitionId: ScoutId;
+    nodeQualifier?: string;
+    workspaceQualifier?: string;
+    selector?: string;
+    defaultSelector?: string;
+    agentClass: AgentClass;
+    capabilities: AgentCapability[];
+    wakePolicy: WakePolicy;
+    homeNodeId: ScoutId;
+    authorityNodeId: ScoutId;
+    advertiseScope: AdvertiseScope;
+    ownerId?: ScoutId;
+}
+export interface HelperDefinition extends ActorIdentity {
+    kind: "helper";
+    ownerId: ScoutId;
+    nodeId: ScoutId;
+    engine: AgentHarness;
+    capabilities: AgentCapability[];
+}
+export interface AgentEndpoint {
+    id: ScoutId;
+    agentId: ScoutId;
+    nodeId: ScoutId;
+    harness: AgentHarness;
+    transport: "local_socket" | "http" | "websocket" | "claude_stream_json" | "codex_app_server" | "codex_exec" | "claude_resume" | "tmux";
+    state: AgentState;
+    address?: string;
+    sessionId?: string;
+    pane?: string;
+    cwd?: string;
+    projectRoot?: string;
+    metadata?: MetadataMap;
+}

package/dist/actors.js

@@ -0,0 +1 @@
+export {};

package/dist/agent-selectors.d.ts

@@ -0,0 +1,27 @@
+import type { ScoutId } from "./common.js";
+export interface AgentSelector {
+    raw: string;
+    label: string;
+    definitionId: ScoutId;
+    nodeQualifier?: string;
+    workspaceQualifier?: string;
+}
+export interface AgentSelectorCandidate {
+    agentId: ScoutId;
+    definitionId?: ScoutId;
+    nodeQualifier?: string;
+    workspaceQualifier?: string;
+    aliases?: string[];
+}
+export declare function normalizeAgentSelectorSegment(value: string): string;
+export declare function parseAgentSelector(value: string): AgentSelector | null;
+export declare function formatAgentSelector(input: {
+    definitionId: ScoutId;
+    nodeQualifier?: string;
+    workspaceQualifier?: string;
+}, options?: {
+    includeSigil?: boolean;
+}): string;
+export declare function extractAgentSelectors(text: string): AgentSelector[];
+export declare function agentSelectorMatches(selector: AgentSelector, candidate: AgentSelectorCandidate): boolean;
+export declare function resolveAgentSelector<T extends AgentSelectorCandidate>(selector: AgentSelector, candidates: T[]): T | null;

package/dist/agent-selectors.js

@@ -0,0 +1,103 @@
+function trimSelectorPrefix(value) {
+    return value
+        .trim()
+        .replace(/^@+/, "")
+        .replace(/[.,!?;:)\]]+$/, "");
+}
+export function normalizeAgentSelectorSegment(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._/-]+/g, "-")
+        .replace(/[\\/]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+export function parseAgentSelector(value) {
+    const raw = trimSelectorPrefix(value);
+    if (!raw) {
+        return null;
+    }
+    const [definitionAndNode, workspacePart] = raw.split("#", 2);
+    const [definitionPart, nodePart] = definitionAndNode.split("@", 2);
+    const definitionId = normalizeAgentSelectorSegment(definitionPart);
+    const nodeQualifier = nodePart ? normalizeAgentSelectorSegment(nodePart) : undefined;
+    const workspaceQualifier = workspacePart ? normalizeAgentSelectorSegment(workspacePart) : undefined;
+    if (!definitionId) {
+        return null;
+    }
+    return {
+        raw,
+        label: formatAgentSelector({
+            definitionId,
+            nodeQualifier,
+            workspaceQualifier,
+        }),
+        definitionId,
+        ...(nodeQualifier ? { nodeQualifier } : {}),
+        ...(workspaceQualifier ? { workspaceQualifier } : {}),
+    };
+}
+export function formatAgentSelector(input, options = {}) {
+    const definitionId = normalizeAgentSelectorSegment(input.definitionId);
+    if (!definitionId) {
+        return options.includeSigil === false ? "" : "@";
+    }
+    const nodeQualifier = input.nodeQualifier ? normalizeAgentSelectorSegment(input.nodeQualifier) : "";
+    const workspaceQualifier = input.workspaceQualifier ? normalizeAgentSelectorSegment(input.workspaceQualifier) : "";
+    const prefix = options.includeSigil === false ? "" : "@";
+    return [
+        `${prefix}${definitionId}`,
+        nodeQualifier ? `@${nodeQualifier}` : "",
+        workspaceQualifier ? `#${workspaceQualifier}` : "",
+    ].join("");
+}
+export function extractAgentSelectors(text) {
+    const matches = Array.from(text.matchAll(/(^|\s)@([a-z0-9._/-]+(?:@[a-z0-9._/-]+)?(?:#[a-z0-9._/-]+)?)/gi));
+    const selectors = new Map();
+    for (const match of matches) {
+        const candidate = parseAgentSelector(match[2] ?? "");
+        if (!candidate) {
+            continue;
+        }
+        selectors.set(candidate.label, candidate);
+    }
+    return Array.from(selectors.values());
+}
+function candidateAliases(candidate) {
+    const definitionId = normalizeAgentSelectorSegment(candidate.definitionId || candidate.agentId);
+    const nodeQualifier = candidate.nodeQualifier ? normalizeAgentSelectorSegment(candidate.nodeQualifier) : undefined;
+    const workspaceQualifier = candidate.workspaceQualifier ? normalizeAgentSelectorSegment(candidate.workspaceQualifier) : undefined;
+    const aliases = [
+        definitionId,
+        formatAgentSelector({ definitionId, nodeQualifier }),
+        formatAgentSelector({ definitionId, workspaceQualifier }),
+        formatAgentSelector({ definitionId, nodeQualifier, workspaceQualifier }),
+        ...((candidate.aliases ?? []).map((alias) => alias.trim()).filter(Boolean)),
+    ];
+    return Array.from(new Set(aliases.map((alias) => trimSelectorPrefix(alias)).filter(Boolean)));
+}
+export function agentSelectorMatches(selector, candidate) {
+    const definitionId = normalizeAgentSelectorSegment(candidate.definitionId || candidate.agentId);
+    if (selector.definitionId !== definitionId) {
+        return false;
+    }
+    const nodeQualifier = candidate.nodeQualifier ? normalizeAgentSelectorSegment(candidate.nodeQualifier) : undefined;
+    if (selector.nodeQualifier && selector.nodeQualifier !== nodeQualifier) {
+        return candidateAliases(candidate).includes(trimSelectorPrefix(selector.label));
+    }
+    const workspaceQualifier = candidate.workspaceQualifier ? normalizeAgentSelectorSegment(candidate.workspaceQualifier) : undefined;
+    if (selector.workspaceQualifier && selector.workspaceQualifier !== workspaceQualifier) {
+        return candidateAliases(candidate).includes(trimSelectorPrefix(selector.label));
+    }
+    return true;
+}
+export function resolveAgentSelector(selector, candidates) {
+    const matches = candidates.filter((candidate) => agentSelectorMatches(selector, candidate));
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    if (!selector.nodeQualifier && !selector.workspaceQualifier) {
+        return matches.find((candidate) => normalizeAgentSelectorSegment(candidate.agentId) === selector.definitionId) ?? matches[0] ?? null;
+    }
+    return null;
+}

package/dist/collaboration.d.ts

@@ -0,0 +1,85 @@
+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 declare function isQuestionTerminalState(state: QuestionState): boolean;
+export declare function isWorkItemTerminalState(state: WorkItemState): boolean;
+export declare function collaborationRequiresNextMoveOwner(record: CollaborationRecord): boolean;
+export declare function collaborationRequiresOwner(record: CollaborationRecord): boolean;
+export declare function collaborationRequiresWaitingOn(record: CollaborationRecord): boolean;
+export declare function collaborationRequiresAcceptance(record: CollaborationRecord): boolean;
+export declare function validateCollaborationRecord(record: CollaborationRecord): string[];
+export declare function assertValidCollaborationRecord(record: CollaborationRecord): void;
+export declare function validateCollaborationEvent(event: CollaborationEvent, record?: CollaborationRecord): string[];
+export declare function assertValidCollaborationEvent(event: CollaborationEvent, record?: CollaborationRecord): void;

package/dist/collaboration.js

@@ -0,0 +1,113 @@
+export function isQuestionTerminalState(state) {
+    return state === "closed" || state === "declined";
+}
+export function isWorkItemTerminalState(state) {
+    return state === "done" || state === "cancelled";
+}
+export function collaborationRequiresNextMoveOwner(record) {
+    if (record.kind === "question") {
+        return !isQuestionTerminalState(record.state);
+    }
+    return !isWorkItemTerminalState(record.state);
+}
+export function collaborationRequiresOwner(record) {
+    return record.kind === "work_item" && !isWorkItemTerminalState(record.state);
+}
+export function collaborationRequiresWaitingOn(record) {
+    return record.kind === "work_item" && record.state === "waiting";
+}
+export function collaborationRequiresAcceptance(record) {
+    if (record.acceptanceState === "none") {
+        return false;
+    }
+    if (record.kind === "question") {
+        return Boolean(record.askedById && record.askedOfId);
+    }
+    return Boolean(record.requestedById);
+}
+export function validateCollaborationRecord(record) {
+    const errors = [];
+    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) {
+    const errors = validateCollaborationRecord(record);
+    if (errors.length > 0) {
+        throw new Error(errors.join("; "));
+    }
+}
+export function validateCollaborationEvent(event, record) {
+    const errors = [];
+    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, record) {
+    const errors = validateCollaborationEvent(event, record);
+    if (errors.length > 0) {
+        throw new Error(errors.join("; "));
+    }
+}

package/dist/common.d.ts

@@ -0,0 +1,14 @@
+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/dist/common.js

@@ -0,0 +1 @@
+export {};

package/dist/conversations.d.ts

@@ -0,0 +1,24 @@
+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/dist/conversations.js

@@ -0,0 +1 @@
+export {};

package/dist/deliveries.d.ts

@@ -0,0 +1,35 @@
+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/dist/deliveries.js

@@ -0,0 +1 @@
+export {};

package/dist/events.d.ts

@@ -0,0 +1,56 @@
+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/dist/events.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./common.js";
+export * from "./actors.js";
+export * from "./agent-selectors.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/dist/index.js

@@ -0,0 +1,11 @@
+export * from "./common.js";
+export * from "./actors.js";
+export * from "./agent-selectors.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/dist/invocations.d.ts

@@ -0,0 +1,38 @@
+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/dist/invocations.js

@@ -0,0 +1 @@
+export {};

package/dist/mesh.d.ts

@@ -0,0 +1,15 @@
+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/dist/mesh.js

@@ -0,0 +1 @@
+export {};

package/dist/messages.d.ts

@@ -0,0 +1,43 @@
+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/dist/messages.js

@@ -0,0 +1 @@
+export {};

package/dist/transports.d.ts

@@ -0,0 +1,66 @@
+import type { DeliveryTransport, MetadataMap, ScoutId } from "./common.js";
+import type { AgentDefinition, AgentEndpoint, ActorIdentity } from "./actors.js";
+import type { ConversationBinding, ConversationDefinition } from "./conversations.js";
+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";
+export interface SubscriptionRequest {
+    actorId: ScoutId;
+    conversationIds?: ScoutId[];
+    flightIds?: ScoutId[];
+    eventKinds?: string[];
+}
+export interface PostMessageCommand {
+    kind: "conversation.post";
+    message: MessageRecord;
+}
+export interface InvokeAgentCommand {
+    kind: "agent.invoke";
+    invocation: InvocationRequest;
+}
+export interface EnsureAwakeCommand {
+    kind: "agent.ensure_awake";
+    agentId: ScoutId;
+    requesterId: ScoutId;
+    reason: string;
+    metadata?: MetadataMap;
+}
+export interface SubscribeCommand {
+    kind: "stream.subscribe";
+    subscription: SubscriptionRequest;
+    transport: Extract<DeliveryTransport, "local_socket" | "websocket">;
+}
+export interface NodeUpsertCommand {
+    kind: "node.upsert";
+    node: NodeDefinition;
+}
+export interface ActorUpsertCommand {
+    kind: "actor.upsert";
+    actor: ActorIdentity;
+}
+export interface AgentUpsertCommand {
+    kind: "agent.upsert";
+    agent: AgentDefinition;
+}
+export interface AgentEndpointUpsertCommand {
+    kind: "agent.endpoint.upsert";
+    endpoint: AgentEndpoint;
+}
+export interface ConversationUpsertCommand {
+    kind: "conversation.upsert";
+    conversation: ConversationDefinition;
+}
+export interface BindingUpsertCommand {
+    kind: "binding.upsert";
+    binding: ConversationBinding;
+}
+export interface CollaborationUpsertCommand {
+    kind: "collaboration.upsert";
+    record: CollaborationRecord;
+}
+export interface CollaborationEventAppendCommand {
+    kind: "collaboration.event.append";
+    event: CollaborationEvent;
+}
+export type ControlCommand = NodeUpsertCommand | ActorUpsertCommand | AgentUpsertCommand | AgentEndpointUpsertCommand | ConversationUpsertCommand | BindingUpsertCommand | CollaborationUpsertCommand | CollaborationEventAppendCommand | PostMessageCommand | InvokeAgentCommand | EnsureAwakeCommand | SubscribeCommand;

package/dist/transports.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@openscout/protocol",
+  "version": "0.1.0",
+  "description": "Typed protocol for the OpenScout local control plane",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./src/index.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  }
+}