@openscout/protocol 0.2.50 → 0.2.52

package/README.md

@@ -4,6 +4,10 @@
 
 This package is intentionally not named `relay`. Relay is now a surface and compatibility layer. The control protocol is the canonical model underneath it.
 
+For the definitive Scout glossary, see [docs/glossary.md](../../docs/glossary.md). For Scout's current A2A posture and vocabulary mapping, see [docs/a2a-alignment.md](../../docs/a2a-alignment.md).
+
+Scout is aware of adjacent standards such as A2A, but this package is not trying to become an A2A clone. The goal is clean correspondence without giving up Scout-specific mechanics such as broker-owned routing, `invocation` plus `flight`, or the `question` / `work_item` collaboration model.
+
 ## What Makes This A Good Local Communication Protocol
 
 The target is a protocol that is:
@@ -32,6 +36,8 @@ The protocol keeps a small set of nouns and gives each one a single job:
 - `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
 
+For discovery, Scout also uses a `ScoutAgentCard`: a local discovery and routing card that overlaps intentionally with A2A-style discovery fields such as provider, skills, supported interfaces, and security hints without claiming to be the A2A wire-level `AgentCard`.
+
 ## Emerging Collaboration Model
 
 The protocol package now also exports a collaboration vocabulary for the next layer above

package/dist/index.d.ts

@@ -3,7 +3,7 @@ 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 "./scout-agent-card.js";
 export * from "./mesh.js";
 export * from "./conversations.js";
 export * from "./collaboration.js";

package/dist/index.js

@@ -3,7 +3,7 @@ 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 "./scout-agent-card.js";
 export * from "./mesh.js";
 export * from "./conversations.js";
 export * from "./collaboration.js";

package/dist/relay-agent-card.d.ts

@@ -1,38 +1 @@
-import type { AgentEndpoint, AgentHarness } from "./actors.js";
-import type { MetadataMap, ScoutId } from "./common.js";
-export interface RelayReturnAddress {
-    actorId: ScoutId;
-    handle: string;
-    displayName?: string;
-    selector?: string;
-    defaultSelector?: string;
-    conversationId?: ScoutId;
-    replyToMessageId?: ScoutId;
-    nodeId?: ScoutId;
-    projectRoot?: string;
-    sessionId?: string;
-    metadata?: MetadataMap;
-}
-export interface RelayAgentCard {
-    id: ScoutId;
-    agentId: ScoutId;
-    definitionId: ScoutId;
-    displayName: string;
-    handle: string;
-    selector?: string;
-    defaultSelector?: string;
-    projectName?: string;
-    projectRoot: string;
-    currentDirectory: string;
-    harness: AgentHarness;
-    transport: AgentEndpoint["transport"];
-    sessionId?: string;
-    branch?: string;
-    createdAt: number;
-    createdById?: ScoutId;
-    brokerRegistered: boolean;
-    inboxConversationId?: ScoutId;
-    returnAddress: RelayReturnAddress;
-    metadata?: MetadataMap;
-}
-export declare function buildRelayReturnAddress(input: RelayReturnAddress): RelayReturnAddress;
+export * from "./scout-agent-card.js";

package/dist/relay-agent-card.js

@@ -1,34 +1 @@
-export function buildRelayReturnAddress(input) {
-    const next = {
-        actorId: input.actorId,
-        handle: input.handle.trim(),
-    };
-    if (input.displayName?.trim()) {
-        next.displayName = input.displayName.trim();
-    }
-    if (input.selector?.trim()) {
-        next.selector = input.selector.trim();
-    }
-    if (input.defaultSelector?.trim()) {
-        next.defaultSelector = input.defaultSelector.trim();
-    }
-    if (input.conversationId?.trim()) {
-        next.conversationId = input.conversationId.trim();
-    }
-    if (input.replyToMessageId?.trim()) {
-        next.replyToMessageId = input.replyToMessageId.trim();
-    }
-    if (input.nodeId?.trim()) {
-        next.nodeId = input.nodeId.trim();
-    }
-    if (input.projectRoot?.trim()) {
-        next.projectRoot = input.projectRoot.trim();
-    }
-    if (input.sessionId?.trim()) {
-        next.sessionId = input.sessionId.trim();
-    }
-    if (input.metadata && Object.keys(input.metadata).length > 0) {
-        next.metadata = input.metadata;
-    }
-    return next;
-}
+export * from "./scout-agent-card.js";

package/dist/scout-agent-card.d.ts

@@ -0,0 +1,81 @@
+import type { AgentEndpoint, AgentHarness } from "./actors.js";
+import type { MetadataMap, ScoutId } from "./common.js";
+export interface ScoutAgentProvider {
+    organization?: string;
+    url?: string;
+}
+export interface ScoutAgentSkill {
+    id?: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+    examples?: string[];
+}
+export interface ScoutSupportedInterface {
+    protocol: string;
+    transport?: string;
+    url?: string;
+    description?: string;
+}
+export interface ScoutSecurityScheme {
+    type: string;
+    description?: string;
+    name?: string;
+    in?: string;
+    scheme?: string;
+    bearerFormat?: string;
+    openIdConnectUrl?: string;
+}
+export interface ScoutReturnAddress {
+    actorId: ScoutId;
+    handle: string;
+    displayName?: string;
+    selector?: string;
+    defaultSelector?: string;
+    conversationId?: ScoutId;
+    replyToMessageId?: ScoutId;
+    nodeId?: ScoutId;
+    projectRoot?: string;
+    sessionId?: string;
+    metadata?: MetadataMap;
+}
+/**
+ * Scout's local discovery and routing card for one addressable agent target.
+ *
+ * This is intentionally not the A2A wire-level `AgentCard`, but it overlaps
+ * with A2A on discovery-oriented fields such as provider, skills, interfaces,
+ * and security hints so Scout can project cleanly to adjacent protocols later.
+ */
+export interface ScoutAgentCard {
+    id: ScoutId;
+    agentId: ScoutId;
+    definitionId: ScoutId;
+    displayName: string;
+    description?: string;
+    provider?: ScoutAgentProvider;
+    version?: string;
+    documentationUrl?: string;
+    skills?: ScoutAgentSkill[];
+    defaultInputModes?: string[];
+    defaultOutputModes?: string[];
+    supportedInterfaces?: ScoutSupportedInterface[];
+    securitySchemes?: Record<string, ScoutSecurityScheme>;
+    securityRequirements?: string[][];
+    handle: string;
+    selector?: string;
+    defaultSelector?: string;
+    projectName?: string;
+    projectRoot: string;
+    currentDirectory: string;
+    harness: AgentHarness;
+    transport: AgentEndpoint["transport"];
+    sessionId?: string;
+    branch?: string;
+    createdAt: number;
+    createdById?: ScoutId;
+    brokerRegistered: boolean;
+    inboxConversationId?: ScoutId;
+    returnAddress: ScoutReturnAddress;
+    metadata?: MetadataMap;
+}
+export declare function buildScoutReturnAddress(input: ScoutReturnAddress): ScoutReturnAddress;

package/dist/scout-agent-card.js

@@ -0,0 +1,34 @@
+export function buildScoutReturnAddress(input) {
+    const next = {
+        actorId: input.actorId,
+        handle: input.handle.trim(),
+    };
+    if (input.displayName?.trim()) {
+        next.displayName = input.displayName.trim();
+    }
+    if (input.selector?.trim()) {
+        next.selector = input.selector.trim();
+    }
+    if (input.defaultSelector?.trim()) {
+        next.defaultSelector = input.defaultSelector.trim();
+    }
+    if (input.conversationId?.trim()) {
+        next.conversationId = input.conversationId.trim();
+    }
+    if (input.replyToMessageId?.trim()) {
+        next.replyToMessageId = input.replyToMessageId.trim();
+    }
+    if (input.nodeId?.trim()) {
+        next.nodeId = input.nodeId.trim();
+    }
+    if (input.projectRoot?.trim()) {
+        next.projectRoot = input.projectRoot.trim();
+    }
+    if (input.sessionId?.trim()) {
+        next.sessionId = input.sessionId.trim();
+    }
+    if (input.metadata && Object.keys(input.metadata).length > 0) {
+        next.metadata = input.metadata;
+    }
+    return next;
+}

package/package.json

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

package/src/index.ts

@@ -3,7 +3,7 @@ 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 "./scout-agent-card.js";
 export * from "./mesh.js";
 export * from "./conversations.js";
 export * from "./collaboration.js";

package/src/relay-agent-card.ts

@@ -1,76 +1 @@
-import type { AgentEndpoint, AgentHarness } from "./actors.js";
-import type { MetadataMap, ScoutId } from "./common.js";
-
-export interface RelayReturnAddress {
-  actorId: ScoutId;
-  handle: string;
-  displayName?: string;
-  selector?: string;
-  defaultSelector?: string;
-  conversationId?: ScoutId;
-  replyToMessageId?: ScoutId;
-  nodeId?: ScoutId;
-  projectRoot?: string;
-  sessionId?: string;
-  metadata?: MetadataMap;
-}
-
-export interface RelayAgentCard {
-  id: ScoutId;
-  agentId: ScoutId;
-  definitionId: ScoutId;
-  displayName: string;
-  handle: string;
-  selector?: string;
-  defaultSelector?: string;
-  projectName?: string;
-  projectRoot: string;
-  currentDirectory: string;
-  harness: AgentHarness;
-  transport: AgentEndpoint["transport"];
-  sessionId?: string;
-  branch?: string;
-  createdAt: number;
-  createdById?: ScoutId;
-  brokerRegistered: boolean;
-  inboxConversationId?: ScoutId;
-  returnAddress: RelayReturnAddress;
-  metadata?: MetadataMap;
-}
-
-export function buildRelayReturnAddress(input: RelayReturnAddress): RelayReturnAddress {
-  const next: RelayReturnAddress = {
-    actorId: input.actorId,
-    handle: input.handle.trim(),
-  };
-
-  if (input.displayName?.trim()) {
-    next.displayName = input.displayName.trim();
-  }
-  if (input.selector?.trim()) {
-    next.selector = input.selector.trim();
-  }
-  if (input.defaultSelector?.trim()) {
-    next.defaultSelector = input.defaultSelector.trim();
-  }
-  if (input.conversationId?.trim()) {
-    next.conversationId = input.conversationId.trim();
-  }
-  if (input.replyToMessageId?.trim()) {
-    next.replyToMessageId = input.replyToMessageId.trim();
-  }
-  if (input.nodeId?.trim()) {
-    next.nodeId = input.nodeId.trim();
-  }
-  if (input.projectRoot?.trim()) {
-    next.projectRoot = input.projectRoot.trim();
-  }
-  if (input.sessionId?.trim()) {
-    next.sessionId = input.sessionId.trim();
-  }
-  if (input.metadata && Object.keys(input.metadata).length > 0) {
-    next.metadata = input.metadata;
-  }
-
-  return next;
-}
+export * from "./scout-agent-card.js";

package/src/{relay-agent-card.test.ts → scout-agent-card.test.ts}

@@ -1,10 +1,10 @@
 import { describe, expect, test } from "bun:test";
 
-import { buildRelayReturnAddress } from "./relay-agent-card";
+import { buildScoutReturnAddress } from "./scout-agent-card";
 
-describe("buildRelayReturnAddress", () => {
+describe("buildScoutReturnAddress", () => {
   test("keeps only meaningful optional fields", () => {
-    const address = buildRelayReturnAddress({
+    const address = buildScoutReturnAddress({
       actorId: "dewey.node.workspace",
       handle: "dewey",
       displayName: "Dewey",
@@ -38,7 +38,7 @@ describe("buildRelayReturnAddress", () => {
   });
 
   test("drops empty optional fields", () => {
-    const address = buildRelayReturnAddress({
+    const address = buildScoutReturnAddress({
       actorId: "arc",
       handle: "arc",
       displayName: "  ",

package/src/scout-agent-card.ts

@@ -0,0 +1,123 @@
+import type { AgentEndpoint, AgentHarness } from "./actors.js";
+import type { MetadataMap, ScoutId } from "./common.js";
+
+export interface ScoutAgentProvider {
+  organization?: string;
+  url?: string;
+}
+
+export interface ScoutAgentSkill {
+  id?: string;
+  name: string;
+  description?: string;
+  tags?: string[];
+  examples?: string[];
+}
+
+export interface ScoutSupportedInterface {
+  protocol: string;
+  transport?: string;
+  url?: string;
+  description?: string;
+}
+
+export interface ScoutSecurityScheme {
+  type: string;
+  description?: string;
+  name?: string;
+  in?: string;
+  scheme?: string;
+  bearerFormat?: string;
+  openIdConnectUrl?: string;
+}
+
+export interface ScoutReturnAddress {
+  actorId: ScoutId;
+  handle: string;
+  displayName?: string;
+  selector?: string;
+  defaultSelector?: string;
+  conversationId?: ScoutId;
+  replyToMessageId?: ScoutId;
+  nodeId?: ScoutId;
+  projectRoot?: string;
+  sessionId?: string;
+  metadata?: MetadataMap;
+}
+
+/**
+ * Scout's local discovery and routing card for one addressable agent target.
+ *
+ * This is intentionally not the A2A wire-level `AgentCard`, but it overlaps
+ * with A2A on discovery-oriented fields such as provider, skills, interfaces,
+ * and security hints so Scout can project cleanly to adjacent protocols later.
+ */
+export interface ScoutAgentCard {
+  id: ScoutId;
+  agentId: ScoutId;
+  definitionId: ScoutId;
+  displayName: string;
+  description?: string;
+  provider?: ScoutAgentProvider;
+  version?: string;
+  documentationUrl?: string;
+  skills?: ScoutAgentSkill[];
+  defaultInputModes?: string[];
+  defaultOutputModes?: string[];
+  supportedInterfaces?: ScoutSupportedInterface[];
+  securitySchemes?: Record<string, ScoutSecurityScheme>;
+  securityRequirements?: string[][];
+  handle: string;
+  selector?: string;
+  defaultSelector?: string;
+  projectName?: string;
+  projectRoot: string;
+  currentDirectory: string;
+  harness: AgentHarness;
+  transport: AgentEndpoint["transport"];
+  sessionId?: string;
+  branch?: string;
+  createdAt: number;
+  createdById?: ScoutId;
+  brokerRegistered: boolean;
+  inboxConversationId?: ScoutId;
+  returnAddress: ScoutReturnAddress;
+  metadata?: MetadataMap;
+}
+
+export function buildScoutReturnAddress(input: ScoutReturnAddress): ScoutReturnAddress {
+  const next: ScoutReturnAddress = {
+    actorId: input.actorId,
+    handle: input.handle.trim(),
+  };
+
+  if (input.displayName?.trim()) {
+    next.displayName = input.displayName.trim();
+  }
+  if (input.selector?.trim()) {
+    next.selector = input.selector.trim();
+  }
+  if (input.defaultSelector?.trim()) {
+    next.defaultSelector = input.defaultSelector.trim();
+  }
+  if (input.conversationId?.trim()) {
+    next.conversationId = input.conversationId.trim();
+  }
+  if (input.replyToMessageId?.trim()) {
+    next.replyToMessageId = input.replyToMessageId.trim();
+  }
+  if (input.nodeId?.trim()) {
+    next.nodeId = input.nodeId.trim();
+  }
+  if (input.projectRoot?.trim()) {
+    next.projectRoot = input.projectRoot.trim();
+  }
+  if (input.sessionId?.trim()) {
+    next.sessionId = input.sessionId.trim();
+  }
+  if (input.metadata && Object.keys(input.metadata).length > 0) {
+    next.metadata = input.metadata;
+  }
+
+  return next;
+}