@openscout/protocol 0.2.38 → 0.2.40

package/dist/agent-identity.d.ts

@@ -32,6 +32,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 const BUILT_IN_AGENT_DEFINITION_IDS: ReadonlySet<string>;
+export declare function isBuiltInAgentDefinitionId(value: string | null | undefined): boolean;
 export declare function isReservedAgentDefinitionId(value: string | null | undefined): boolean;
 export declare function parseAgentIdentity(value: string): AgentIdentity | null;
 export declare function formatAgentIdentity(input: AgentIdentityInput, options?: {

package/dist/agent-identity.js

@@ -25,6 +25,17 @@ export function normalizeAgentIdentitySegment(value) {
 }
 export const normalizeAgentSelectorSegment = normalizeAgentIdentitySegment;
 export const SCOUT_DISPATCHER_AGENT_ID = "scout";
+export const BUILT_IN_AGENT_DEFINITION_IDS = new Set([
+    SCOUT_DISPATCHER_AGENT_ID,
+    "builder",
+    "reviewer",
+    "research",
+]);
+export function isBuiltInAgentDefinitionId(value) {
+    if (!value)
+        return false;
+    return BUILT_IN_AGENT_DEFINITION_IDS.has(normalizeAgentIdentitySegment(value));
+}
 const RESERVED_AGENT_DEFINITION_IDS = new Set([
     SCOUT_DISPATCHER_AGENT_ID,
 ]);

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

@@ -48,6 +48,10 @@ 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;
 }>;
@@ -57,4 +61,4 @@ export type CollaborationEventAppendedEvent = ControlEventBase<"collaboration.ev
 export type ScoutDispatchedEvent = ControlEventBase<"scout.dispatched", {
     dispatch: ScoutDispatchRecord;
 }>;
-export type ControlEvent = NodeUpsertedEvent | ActorRegisteredEvent | AgentRegisteredEvent | AgentEndpointUpsertedEvent | ConversationUpsertedEvent | BindingUpsertedEvent | MessagePostedEvent | InvocationRequestedEvent | FlightUpdatedEvent | DeliveryPlannedEvent | DeliveryAttemptedEvent | CollaborationUpsertedEvent | CollaborationEventAppendedEvent | ScoutDispatchedEvent;
+export type ControlEvent = NodeUpsertedEvent | ActorRegisteredEvent | AgentRegisteredEvent | AgentEndpointUpsertedEvent | ConversationUpsertedEvent | BindingUpsertedEvent | MessagePostedEvent | InvocationRequestedEvent | FlightUpdatedEvent | DeliveryPlannedEvent | DeliveryAttemptedEvent | DeliveryStateChangedEvent | CollaborationUpsertedEvent | CollaborationEventAppendedEvent | ScoutDispatchedEvent;

package/package.json

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

package/src/agent-identity.ts

@@ -67,6 +67,18 @@ export const normalizeAgentSelectorSegment = normalizeAgentIdentitySegment;
 
 export const SCOUT_DISPATCHER_AGENT_ID = "scout";
 
+export const BUILT_IN_AGENT_DEFINITION_IDS: ReadonlySet<string> = new Set([
+  SCOUT_DISPATCHER_AGENT_ID,
+  "builder",
+  "reviewer",
+  "research",
+]);
+
+export function isBuiltInAgentDefinitionId(value: string | null | undefined): boolean {
+  if (!value) return false;
+  return BUILT_IN_AGENT_DEFINITION_IDS.has(normalizeAgentIdentitySegment(value));
+}
+
 const RESERVED_AGENT_DEFINITION_IDS: ReadonlySet<string> = new Set([
   SCOUT_DISPATCHER_AGENT_ID,
 ]);

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

@@ -61,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;
 }>;
@@ -85,6 +90,7 @@ export type ControlEvent =
   | FlightUpdatedEvent
   | DeliveryPlannedEvent
   | DeliveryAttemptedEvent
+  | DeliveryStateChangedEvent
   | CollaborationUpsertedEvent
   | CollaborationEventAppendedEvent
   | ScoutDispatchedEvent;