@openscout/protocol 0.2.37 → 0.2.39

package/dist/agent-identity.d.ts

@@ -31,6 +31,8 @@ export interface AgentIdentityAlias {
 }
 export declare function normalizeAgentIdentitySegment(value: string): string;
 export declare const normalizeAgentSelectorSegment: typeof normalizeAgentIdentitySegment;
+export declare const SCOUT_DISPATCHER_AGENT_ID = "scout";
+export declare function isReservedAgentDefinitionId(value: string | null | undefined): boolean;
 export declare function parseAgentIdentity(value: string): AgentIdentity | null;
 export declare function formatAgentIdentity(input: AgentIdentityInput, options?: {
     includeSigil?: boolean;
@@ -45,6 +47,16 @@ export declare function extractAgentMentions(text: string): {
 };
 export declare function agentIdentityMatches(identity: AgentIdentity, candidate: AgentIdentityCandidate): boolean;
 export declare function resolveAgentIdentity<T extends AgentIdentityCandidate>(identity: AgentIdentity, candidates: T[]): T | null;
+export type AgentIdentityDiagnosis<T extends AgentIdentityCandidate> = {
+    kind: "resolved";
+    match: T;
+} | {
+    kind: "ambiguous";
+    candidates: T[];
+} | {
+    kind: "unknown";
+};
+export declare function diagnoseAgentIdentity<T extends AgentIdentityCandidate>(identity: AgentIdentity, candidates: T[]): AgentIdentityDiagnosis<T>;
 export declare function constructAgentAlias(input: {
     alias: string;
     target: AgentIdentityInput;

package/dist/agent-identity.js

@@ -24,6 +24,15 @@ export function normalizeAgentIdentitySegment(value) {
         .replace(/^-+|-+$/g, "");
 }
 export const normalizeAgentSelectorSegment = normalizeAgentIdentitySegment;
+export const SCOUT_DISPATCHER_AGENT_ID = "scout";
+const RESERVED_AGENT_DEFINITION_IDS = new Set([
+    SCOUT_DISPATCHER_AGENT_ID,
+]);
+export function isReservedAgentDefinitionId(value) {
+    if (!value)
+        return false;
+    return RESERVED_AGENT_DEFINITION_IDS.has(normalizeAgentIdentitySegment(value));
+}
 function normalizeDimensionKey(value) {
     return DIMENSION_ALIASES[normalizeAgentIdentitySegment(value)] ?? null;
 }
@@ -277,27 +286,36 @@ export function agentIdentityMatches(identity, candidate) {
     return true;
 }
 export function resolveAgentIdentity(identity, candidates) {
+    const diagnosis = diagnoseAgentIdentity(identity, candidates);
+    return diagnosis.kind === "resolved" ? diagnosis.match : null;
+}
+export function diagnoseAgentIdentity(identity, candidates) {
     const aliasKeys = identityAliasKeys(identity);
     const exactAliasMatches = candidates.filter((candidate) => {
         const candidateAliasKeys = explicitCandidateAliases(candidate).map(canonicalizeAliasValue);
         return aliasKeys.some((key) => candidateAliasKeys.includes(key));
     });
     if (exactAliasMatches.length === 1) {
-        return exactAliasMatches[0];
+        return { kind: "resolved", match: exactAliasMatches[0] };
     }
     if (exactAliasMatches.length > 1) {
-        return null;
+        return { kind: "ambiguous", candidates: exactAliasMatches };
     }
     const matches = candidates.filter((candidate) => agentIdentityMatches(identity, candidate));
     if (matches.length === 1) {
-        return matches[0];
+        return { kind: "resolved", match: matches[0] };
+    }
+    if (matches.length === 0) {
+        return { kind: "unknown" };
     }
     if (!identity.nodeQualifier && !identity.workspaceQualifier && !identity.profile && !identity.harness) {
-        return matches.find((candidate) => normalizeAgentIdentitySegment(candidate.agentId) === identity.definitionId)
-            ?? matches[0]
-            ?? null;
+        const exactIdMatch = matches.find((candidate) => normalizeAgentIdentitySegment(candidate.agentId) === identity.definitionId);
+        if (exactIdMatch) {
+            return { kind: "resolved", match: exactIdMatch };
+        }
+        return { kind: "ambiguous", candidates: matches };
     }
-    return null;
+    return { kind: "ambiguous", candidates: matches };
 }
 export function constructAgentAlias(input) {
     const alias = normalizeAgentIdentitySegment(trimIdentityPrefix(input.alias));

package/dist/common.d.ts

@@ -2,7 +2,8 @@ export type ScoutId = string;
 export type ActorKind = "person" | "helper" | "agent" | "system" | "bridge" | "device";
 export type AgentState = "offline" | "idle" | "active" | "waiting";
 export type VisibilityScope = "private" | "workspace" | "public" | "system";
-export type DeliveryStatus = "pending" | "leased" | "sent" | "acknowledged" | "failed" | "cancelled";
+export type DeliveryStatus = "accepted" | "peer_acked" | "running" | "completed" | "deferred" | "failed" | "cancelled" | "pending" | "leased" | "sent" | "acknowledged";
+export type DeliveryFailureReason = "peer_unreachable" | "peer_rejected" | "agent_offline" | "timeout" | "harness_error" | "dispatch" | "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";

package/dist/events.d.ts

@@ -6,6 +6,7 @@ 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";
+import type { ScoutDispatchRecord } from "./scout-dispatch.js";
 export interface ControlEventBase<K extends string, P> {
     id: ScoutId;
     kind: K;
@@ -47,10 +48,17 @@ export type DeliveryPlannedEvent = ControlEventBase<"delivery.planned", {
 export type DeliveryAttemptedEvent = ControlEventBase<"delivery.attempted", {
     attempt: DeliveryAttempt;
 }>;
+export type DeliveryStateChangedEvent = ControlEventBase<"delivery.state.changed", {
+    delivery: DeliveryIntent;
+    previousStatus?: DeliveryIntent["status"];
+}>;
 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;
+export type ScoutDispatchedEvent = ControlEventBase<"scout.dispatched", {
+    dispatch: ScoutDispatchRecord;
+}>;
+export type ControlEvent = NodeUpsertedEvent | ActorRegisteredEvent | AgentRegisteredEvent | AgentEndpointUpsertedEvent | ConversationUpsertedEvent | BindingUpsertedEvent | MessagePostedEvent | InvocationRequestedEvent | FlightUpdatedEvent | DeliveryPlannedEvent | DeliveryAttemptedEvent | DeliveryStateChangedEvent | CollaborationUpsertedEvent | CollaborationEventAppendedEvent | ScoutDispatchedEvent;

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from "./conversations.js";
 export * from "./collaboration.js";
 export * from "./messages.js";
 export * from "./invocations.js";
+export * from "./scout-dispatch.js";
 export * from "./deliveries.js";
 export * from "./transports.js";
 export * from "./events.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./conversations.js";
 export * from "./collaboration.js";
 export * from "./messages.js";
 export * from "./invocations.js";
+export * from "./scout-dispatch.js";
 export * from "./deliveries.js";
 export * from "./transports.js";
 export * from "./events.js";

package/dist/scout-dispatch.d.ts

@@ -0,0 +1,31 @@
+import type { AdvertiseScope, DeliveryTransport, ScoutId } from "./common.js";
+export type ScoutDispatchKind = "ambiguous" | "unknown" | "unparseable";
+export type ScoutCandidateEndpointState = "online" | "offline" | "unknown";
+export interface ScoutDispatchCandidate {
+    agentId: ScoutId;
+    displayName: string;
+    authorityNodeId?: ScoutId;
+    homeNodeId?: ScoutId;
+    advertiseScope?: AdvertiseScope;
+    selector?: string | null;
+    defaultSelector?: string | null;
+    workspace?: string | null;
+    node?: string | null;
+    projectRoot?: string | null;
+    endpointState: ScoutCandidateEndpointState;
+    transport?: DeliveryTransport | null;
+}
+export interface ScoutDispatchEnvelope {
+    kind: ScoutDispatchKind;
+    askedLabel: string;
+    detail: string;
+    candidates: ScoutDispatchCandidate[];
+    dispatchedAt: number;
+    dispatcherNodeId: ScoutId;
+}
+export interface ScoutDispatchRecord extends ScoutDispatchEnvelope {
+    id: ScoutId;
+    invocationId?: ScoutId;
+    conversationId?: ScoutId;
+    requesterId?: ScoutId;
+}

package/dist/scout-dispatch.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openscout/protocol",
-  "version": "0.2.37",
+  "version": "0.2.39",
   "description": "Typed protocol for the OpenScout local control plane",
   "type": "module",
   "exports": {

package/src/agent-identity.test.ts

@@ -3,15 +3,18 @@ import { describe, expect, test } from "bun:test";
 import {
   constructAgentAlias,
   constructAgentIdentity,
+  diagnoseAgentIdentity,
   extractAgentIdentities,
   formatAgentAlias,
   formatAgentIdentity,
   formatMinimalAgentIdentity,
+  isReservedAgentDefinitionId,
   parseAgentIdentity,
   parseAgentSelector,
   resolveAgentAlias,
   resolveAgentIdentity,
   resolveAgentSelector,
+  SCOUT_DISPATCHER_AGENT_ID,
 } from "./agent-identity.js";
 
 describe("agent identity grammar", () => {
@@ -271,3 +274,75 @@ describe("agent identity resolution", () => {
     expect(formatMinimalAgentIdentity(candidates[5], candidates)).toBe("@hudson.node:backup-mac-mini");
   });
 });
+
+describe("scout dispatcher reservation", () => {
+  test("reserves the scout definition id", () => {
+    expect(SCOUT_DISPATCHER_AGENT_ID).toBe("scout");
+    expect(isReservedAgentDefinitionId("scout")).toBe(true);
+    expect(isReservedAgentDefinitionId("Scout")).toBe(true);
+    expect(isReservedAgentDefinitionId("SCOUT ")).toBe(true);
+    expect(isReservedAgentDefinitionId("scoutie")).toBe(false);
+    expect(isReservedAgentDefinitionId("scout-ie")).toBe(false);
+    expect(isReservedAgentDefinitionId("")).toBe(false);
+    expect(isReservedAgentDefinitionId(null)).toBe(false);
+    expect(isReservedAgentDefinitionId(undefined)).toBe(false);
+  });
+});
+
+describe("agent identity diagnosis", () => {
+  const scoutieMiniMain = {
+    agentId: "scoutie.mini.main",
+    definitionId: "scoutie",
+    nodeQualifier: "mini",
+    workspaceQualifier: "main",
+    aliases: ["@scoutie.main.node:mini", "@scoutie"],
+  };
+  const scoutieMainMini = {
+    agentId: "scoutie.main.mini",
+    definitionId: "scoutie",
+    nodeQualifier: "mini",
+    workspaceQualifier: "main",
+    aliases: ["@scoutie.main.node:mini", "@scoutie"],
+  };
+  const arachMini = {
+    agentId: "arach.mini",
+    definitionId: "arach",
+    nodeQualifier: "mini",
+    aliases: ["@arach.node:mini", "@arach"],
+  };
+
+  test("returns resolved when exactly one candidate matches", () => {
+    const identity = parseAgentIdentity("@arach");
+    expect(identity).not.toBeNull();
+    const result = diagnoseAgentIdentity(identity!, [scoutieMiniMain, arachMini]);
+    expect(result.kind).toBe("resolved");
+    if (result.kind === "resolved") {
+      expect(result.match.agentId).toBe("arach.mini");
+    }
+  });
+
+  test("returns ambiguous when multiple exact alias matches exist", () => {
+    const identity = parseAgentIdentity("@scoutie");
+    expect(identity).not.toBeNull();
+    const result = diagnoseAgentIdentity(identity!, [scoutieMiniMain, scoutieMainMini, arachMini]);
+    expect(result.kind).toBe("ambiguous");
+    if (result.kind === "ambiguous") {
+      expect(result.candidates.map((c) => c.agentId).sort()).toEqual([
+        "scoutie.main.mini",
+        "scoutie.mini.main",
+      ]);
+    }
+  });
+
+  test("returns unknown when no candidate matches", () => {
+    const identity = parseAgentIdentity("@nonexistent");
+    expect(identity).not.toBeNull();
+    const result = diagnoseAgentIdentity(identity!, [scoutieMiniMain, arachMini]);
+    expect(result.kind).toBe("unknown");
+  });
+
+  test("resolveAgentIdentity returns null on ambiguity (back-compat)", () => {
+    const identity = parseAgentIdentity("@scoutie");
+    expect(resolveAgentIdentity(identity!, [scoutieMiniMain, scoutieMainMini])).toBeNull();
+  });
+});

package/src/agent-identity.ts

@@ -65,6 +65,17 @@ export function normalizeAgentIdentitySegment(value: string): string {
 
 export const normalizeAgentSelectorSegment = normalizeAgentIdentitySegment;
 
+export const SCOUT_DISPATCHER_AGENT_ID = "scout";
+
+const RESERVED_AGENT_DEFINITION_IDS: ReadonlySet<string> = new Set([
+  SCOUT_DISPATCHER_AGENT_ID,
+]);
+
+export function isReservedAgentDefinitionId(value: string | null | undefined): boolean {
+  if (!value) return false;
+  return RESERVED_AGENT_DEFINITION_IDS.has(normalizeAgentIdentitySegment(value));
+}
+
 function normalizeDimensionKey(value: string): AgentIdentityDimension | null {
   return DIMENSION_ALIASES[normalizeAgentIdentitySegment(value)] ?? null;
 }
@@ -363,30 +374,50 @@ export function resolveAgentIdentity<T extends AgentIdentityCandidate>(
   identity: AgentIdentity,
   candidates: T[],
 ): T | null {
+  const diagnosis = diagnoseAgentIdentity(identity, candidates);
+  return diagnosis.kind === "resolved" ? diagnosis.match : null;
+}
+
+export type AgentIdentityDiagnosis<T extends AgentIdentityCandidate> =
+  | { kind: "resolved"; match: T }
+  | { kind: "ambiguous"; candidates: T[] }
+  | { kind: "unknown" };
+
+export function diagnoseAgentIdentity<T extends AgentIdentityCandidate>(
+  identity: AgentIdentity,
+  candidates: T[],
+): AgentIdentityDiagnosis<T> {
   const aliasKeys = identityAliasKeys(identity);
   const exactAliasMatches = candidates.filter((candidate) => {
     const candidateAliasKeys = explicitCandidateAliases(candidate).map(canonicalizeAliasValue);
     return aliasKeys.some((key) => candidateAliasKeys.includes(key));
   });
   if (exactAliasMatches.length === 1) {
-    return exactAliasMatches[0];
+    return { kind: "resolved", match: exactAliasMatches[0] };
   }
   if (exactAliasMatches.length > 1) {
-    return null;
+    return { kind: "ambiguous", candidates: exactAliasMatches };
   }
 
   const matches = candidates.filter((candidate) => agentIdentityMatches(identity, candidate));
   if (matches.length === 1) {
-    return matches[0];
+    return { kind: "resolved", match: matches[0] };
+  }
+  if (matches.length === 0) {
+    return { kind: "unknown" };
   }
 
   if (!identity.nodeQualifier && !identity.workspaceQualifier && !identity.profile && !identity.harness) {
-    return matches.find((candidate) => normalizeAgentIdentitySegment(candidate.agentId) === identity.definitionId)
-      ?? matches[0]
-      ?? null;
+    const exactIdMatch = matches.find(
+      (candidate) => normalizeAgentIdentitySegment(candidate.agentId) === identity.definitionId,
+    );
+    if (exactIdMatch) {
+      return { kind: "resolved", match: exactIdMatch };
+    }
+    return { kind: "ambiguous", candidates: matches };
   }
 
-  return null;
+  return { kind: "ambiguous", candidates: matches };
 }
 
 export function constructAgentAlias(input: {

package/src/common.ts

@@ -17,11 +17,27 @@ export type AgentState =
 export type VisibilityScope = "private" | "workspace" | "public" | "system";
 
 export type DeliveryStatus =
+  // Outbox lifecycle (Issue 3 of broker-three-contracts)
+  | "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
+  | "cancelled"
+  // Legacy values kept for backwards-compatible journal replay
   | "pending"
   | "leased"
   | "sent"
-  | "acknowledged"
-  | "failed"
+  | "acknowledged";
+
+export type DeliveryFailureReason =
+  | "peer_unreachable"   // TCP/network failure — retry-able
+  | "peer_rejected"      // peer broker explicitly refused — not retried
+  | "agent_offline"      // peer ACK'd but target agent never claimed
+  | "timeout"
+  | "harness_error"
+  | "dispatch"           // ambiguous label — see metadata.scoutDispatch
   | "cancelled";
 
 export type DeliveryPolicy = "best_effort" | "must_ack" | "durable" | "ephemeral";

package/src/events.ts

@@ -6,6 +6,7 @@ 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";
+import type { ScoutDispatchRecord } from "./scout-dispatch.js";
 
 export interface ControlEventBase<K extends string, P> {
   id: ScoutId;
@@ -60,6 +61,11 @@ export type DeliveryAttemptedEvent = ControlEventBase<"delivery.attempted", {
   attempt: DeliveryAttempt;
 }>;
 
+export type DeliveryStateChangedEvent = ControlEventBase<"delivery.state.changed", {
+  delivery: DeliveryIntent;
+  previousStatus?: DeliveryIntent["status"];
+}>;
+
 export type CollaborationUpsertedEvent = ControlEventBase<"collaboration.upserted", {
   record: CollaborationRecord;
 }>;
@@ -68,6 +74,10 @@ export type CollaborationEventAppendedEvent = ControlEventBase<"collaboration.ev
   event: CollaborationEvent;
 }>;
 
+export type ScoutDispatchedEvent = ControlEventBase<"scout.dispatched", {
+  dispatch: ScoutDispatchRecord;
+}>;
+
 export type ControlEvent =
   | NodeUpsertedEvent
   | ActorRegisteredEvent
@@ -80,5 +90,7 @@ export type ControlEvent =
   | FlightUpdatedEvent
   | DeliveryPlannedEvent
   | DeliveryAttemptedEvent
+  | DeliveryStateChangedEvent
   | CollaborationUpsertedEvent
-  | CollaborationEventAppendedEvent;
+  | CollaborationEventAppendedEvent
+  | ScoutDispatchedEvent;

package/src/index.ts

@@ -9,6 +9,7 @@ export * from "./conversations.js";
 export * from "./collaboration.js";
 export * from "./messages.js";
 export * from "./invocations.js";
+export * from "./scout-dispatch.js";
 export * from "./deliveries.js";
 export * from "./transports.js";
 export * from "./events.js";

package/src/scout-dispatch.ts

@@ -0,0 +1,36 @@
+import type { AdvertiseScope, DeliveryTransport, ScoutId } from "./common.js";
+
+export type ScoutDispatchKind = "ambiguous" | "unknown" | "unparseable";
+
+export type ScoutCandidateEndpointState = "online" | "offline" | "unknown";
+
+export interface ScoutDispatchCandidate {
+  agentId: ScoutId;
+  displayName: string;
+  authorityNodeId?: ScoutId;
+  homeNodeId?: ScoutId;
+  advertiseScope?: AdvertiseScope;
+  selector?: string | null;
+  defaultSelector?: string | null;
+  workspace?: string | null;
+  node?: string | null;
+  projectRoot?: string | null;
+  endpointState: ScoutCandidateEndpointState;
+  transport?: DeliveryTransport | null;
+}
+
+export interface ScoutDispatchEnvelope {
+  kind: ScoutDispatchKind;
+  askedLabel: string;
+  detail: string;
+  candidates: ScoutDispatchCandidate[];
+  dispatchedAt: number;
+  dispatcherNodeId: ScoutId;
+}
+
+export interface ScoutDispatchRecord extends ScoutDispatchEnvelope {
+  id: ScoutId;
+  invocationId?: ScoutId;
+  conversationId?: ScoutId;
+  requesterId?: ScoutId;
+}