@openscout/protocol 0.2.63 → 0.2.82

package/src/agent-broker-feed.ts

@@ -0,0 +1,102 @@
+import type { AgentState, DeliveryTransport, MetadataMap, ScoutId } from "./common.js";
+import type { DeliveryAttempt, DeliveryIntent } from "./deliveries.js";
+import type { FlightRecord, InvocationRequest } from "./invocations.js";
+import type { MessageRecord } from "./messages.js";
+import type { ScoutDispatchRecord } from "./scout-dispatch.js";
+
+export type AgentBrokerFeedItemKind =
+  | "message"
+  | "status"
+  | "invocation"
+  | "flight"
+  | "delivery"
+  | "delivery_attempt"
+  | "dispatch";
+
+export type AgentBrokerFeedSeverity = "info" | "status" | "warning" | "error";
+
+export type AgentBrokerFeedSource =
+  | "activity"
+  | "snapshot"
+  | "delivery"
+  | "dispatch";
+
+export interface AgentBrokerFeedEndpointStatus {
+  id: ScoutId;
+  nodeId: ScoutId;
+  harness: string;
+  transport: DeliveryTransport | string;
+  state: AgentState | string;
+  sessionId?: string;
+  projectRoot?: string;
+  cwd?: string;
+  lastError?: string;
+  lastFailureStage?: string;
+  updatedAt?: number;
+}
+
+export interface AgentBrokerFeedStatus {
+  agentId: ScoutId;
+  displayName?: string;
+  found: boolean;
+  agentState?: AgentState | string;
+  endpoints: AgentBrokerFeedEndpointStatus[];
+  activeFlightIds: ScoutId[];
+  pendingDeliveryIds: ScoutId[];
+  errorCount: number;
+  warningCount: number;
+  lastError?: string;
+  lastActivityAt?: number;
+}
+
+export interface AgentBrokerFeedItem {
+  id: string;
+  kind: AgentBrokerFeedItemKind;
+  severity: AgentBrokerFeedSeverity;
+  at: number;
+  title: string;
+  summary: string;
+  agentId?: ScoutId;
+  actorId?: ScoutId;
+  targetAgentId?: ScoutId;
+  conversationId?: ScoutId;
+  messageId?: ScoutId;
+  invocationId?: ScoutId;
+  flightId?: ScoutId;
+  deliveryId?: ScoutId;
+  dispatchId?: ScoutId;
+  status?: string;
+  reason?: string;
+  source: AgentBrokerFeedSource;
+  message?: MessageRecord;
+  invocation?: InvocationRequest;
+  flight?: FlightRecord;
+  delivery?: DeliveryIntent;
+  deliveryAttempt?: DeliveryAttempt;
+  dispatch?: ScoutDispatchRecord;
+  metadata?: MetadataMap;
+}
+
+export interface AgentBrokerFeedCounts {
+  items: number;
+  messages: number;
+  statuses: number;
+  invocations: number;
+  flights: number;
+  deliveries: number;
+  deliveryAttempts: number;
+  dispatches: number;
+  errors: number;
+  warnings: number;
+}
+
+export interface AgentBrokerFeed {
+  agentId: ScoutId;
+  generatedAt: number;
+  since: number | null;
+  limit: number;
+  cursor: number | null;
+  status: AgentBrokerFeedStatus;
+  counts: AgentBrokerFeedCounts;
+  items: AgentBrokerFeedItem[];
+}

package/src/agent-identity.ts

@@ -21,6 +21,7 @@ export interface AgentIdentityCandidate {
   profile?: string;
   harness?: string;
   model?: string;
+  referenceId?: string;
   aliases?: string[];
 }
 
@@ -366,16 +367,37 @@ function candidateAliases(candidate: AgentIdentityCandidate): string[] {
   return Array.from(new Set(aliases.map((alias) => trimIdentityPrefix(alias)).filter(Boolean)));
 }
 
+// Directory-wide operations (formatMinimalAgentIdentity, diagnoseAgentIdentity)
+// evaluate these per candidate pair, and broker snapshots can carry thousands
+// of candidates — recomputing parse/construct work per visit turns those
+// call sites quadratic in heavy string handling. Candidates are treated as
+// immutable once they enter these pipelines, so per-object memoization is safe.
+const explicitAliasesCache = new WeakMap<AgentIdentityCandidate, string[]>();
+const aliasKeysCache = new WeakMap<AgentIdentityCandidate, string[]>();
+const canonicalIdentityCache = new WeakMap<AgentIdentityCandidate, AgentIdentity | null>();
+
 function explicitCandidateAliases(candidate: AgentIdentityCandidate): string[] {
+  const cached = explicitAliasesCache.get(candidate);
+  if (cached) return cached;
   const canonical = candidateCanonicalIdentity(candidate);
   const implicitAliases = canonical?.definitionId === OPENSCOUT_COORDINATOR_AGENT_ID
     ? [SCOUT_DISPATCHER_AGENT_ID]
     : [];
-  return Array.from(new Set(
+  const aliases = Array.from(new Set(
     [...(candidate.aliases ?? []), ...implicitAliases]
       .map((alias) => normalizeAgentIdentitySegment(trimIdentityPrefix(alias)))
       .filter(Boolean),
   ));
+  explicitAliasesCache.set(candidate, aliases);
+  return aliases;
+}
+
+function candidateAliasKeys(candidate: AgentIdentityCandidate): string[] {
+  const cached = aliasKeysCache.get(candidate);
+  if (cached) return cached;
+  const keys = explicitCandidateAliases(candidate).map(canonicalizeAliasValue);
+  aliasKeysCache.set(candidate, keys);
+  return keys;
 }
 
 function canonicalizeAliasValue(value: string): string {
@@ -396,7 +418,10 @@ function identityAliasKeys(identity: AgentIdentity): string[] {
 }
 
 function candidateCanonicalIdentity(candidate: AgentIdentityCandidate): AgentIdentity | null {
-  return constructAgentIdentity({
+  if (canonicalIdentityCache.has(candidate)) {
+    return canonicalIdentityCache.get(candidate) ?? null;
+  }
+  const canonical = constructAgentIdentity({
     definitionId: candidate.definitionId || candidate.agentId,
     nodeQualifier: candidate.nodeQualifier,
     workspaceQualifier: candidate.workspaceQualifier,
@@ -404,6 +429,8 @@ function candidateCanonicalIdentity(candidate: AgentIdentityCandidate): AgentIde
     harness: candidate.harness,
     model: candidate.model,
   });
+  canonicalIdentityCache.set(candidate, canonical);
+  return canonical;
 }
 
 function candidateDimensionValue(
@@ -422,6 +449,82 @@ function candidateDimensionValue(
   return canonical.nodeQualifier;
 }
 
+function normalizeAgentReferenceValue(value: string | null | undefined): string {
+  return value?.trim().toLowerCase().replace(/[^a-z0-9]/g, "") ?? "";
+}
+
+function candidateReferenceValue(candidate: AgentIdentityCandidate): string {
+  return normalizeAgentReferenceValue(
+    candidate.referenceId
+      || candidate.workspaceQualifier
+      || candidate.agentId,
+  );
+}
+
+function candidateReferenceSuffix(candidate: AgentIdentityCandidate, length: number): string {
+  const value = candidateReferenceValue(candidate);
+  if (!value) {
+    return "";
+  }
+  return value.length <= length ? value : value.slice(-length);
+}
+
+export function formatAgentReferenceIdentity<T extends AgentIdentityCandidate>(
+  candidate: T,
+  candidates: T[],
+  options: { includeSigil?: boolean; minLength?: number; maxLength?: number } = {},
+): string {
+  const canonical = candidateCanonicalIdentity(candidate);
+  if (!canonical) {
+    return options.includeSigil === false ? "" : "@";
+  }
+
+  const minLength = Math.max(1, options.minLength ?? 5);
+  const maxLength = Math.max(minLength, options.maxLength ?? 8);
+  const peers = candidates.filter((peer) => {
+    if (peer === candidate) {
+      return false;
+    }
+    const peerCanonical = candidateCanonicalIdentity(peer);
+    return peerCanonical?.definitionId === canonical.definitionId;
+  });
+
+  let suffix = "";
+  for (let length = minLength; length <= maxLength; length += 1) {
+    const candidateSuffix = candidateReferenceSuffix(candidate, length);
+    if (!candidateSuffix) {
+      break;
+    }
+    suffix = candidateSuffix;
+    const collides = peers.some((peer) => candidateReferenceSuffix(peer, length) === candidateSuffix);
+    if (!collides) {
+      break;
+    }
+  }
+
+  if (!suffix) {
+    return formatAgentIdentity({ definitionId: canonical.definitionId }, options);
+  }
+
+  return formatAgentIdentity({
+    definitionId: canonical.definitionId,
+    workspaceQualifier: suffix,
+  }, options);
+}
+
+export function withAgentReferenceAliases<T extends AgentIdentityCandidate>(
+  candidates: T[],
+): T[] {
+  return candidates.map((candidate) => {
+    const alias = formatAgentReferenceIdentity(candidate, candidates);
+    const aliases = Array.from(new Set([...(candidate.aliases ?? []), alias].filter(Boolean)));
+    return {
+      ...candidate,
+      aliases,
+    };
+  });
+}
+
 function modelAliasKeys(value: string | undefined): string[] {
   const normalized = value ? normalizeAgentIdentitySegment(value) : "";
   if (!normalized) {
@@ -527,8 +630,8 @@ export function diagnoseAgentIdentity<T extends AgentIdentityCandidate>(
 ): AgentIdentityDiagnosis<T> {
   const aliasKeys = identityAliasKeys(identity);
   const exactAliasMatches = candidates.filter((candidate) => {
-    const candidateAliasKeys = explicitCandidateAliases(candidate).map(canonicalizeAliasValue);
-    return aliasKeys.some((key) => candidateAliasKeys.includes(key));
+    const keys = candidateAliasKeys(candidate);
+    return keys.length > 0 && aliasKeys.some((key) => keys.includes(key));
   });
   if (exactAliasMatches.length === 1) {
     return { kind: "resolved", match: exactAliasMatches[0] };
@@ -628,6 +731,26 @@ function buildIdentitySubset(
   });
 }
 
+const peersByDefinitionCache = new WeakMap<AgentIdentityCandidate[], Map<string, AgentIdentityCandidate[]>>();
+
+function peersByDefinitionId<T extends AgentIdentityCandidate>(candidates: T[]): Map<string, T[]> {
+  const cached = peersByDefinitionCache.get(candidates);
+  if (cached) return cached as Map<string, T[]>;
+  const groups = new Map<string, T[]>();
+  for (const candidate of candidates) {
+    const canonical = candidateCanonicalIdentity(candidate);
+    if (!canonical) continue;
+    const group = groups.get(canonical.definitionId);
+    if (group) {
+      group.push(candidate);
+    } else {
+      groups.set(canonical.definitionId, [candidate]);
+    }
+  }
+  peersByDefinitionCache.set(candidates, groups);
+  return groups;
+}
+
 export function formatMinimalAgentIdentity<T extends AgentIdentityCandidate>(
   candidate: T,
   candidates: T[],
@@ -638,10 +761,7 @@ export function formatMinimalAgentIdentity<T extends AgentIdentityCandidate>(
     return options.includeSigil === false ? "" : "@";
   }
 
-  const peers = candidates.filter((peer) => {
-    const peerCanonical = candidateCanonicalIdentity(peer);
-    return peerCanonical && peerCanonical.definitionId === canonical.definitionId;
-  });
+  const peers = peersByDefinitionId(candidates).get(canonical.definitionId) ?? [];
 
   const aliasMatches = explicitCandidateAliases(candidate)
     .map((alias) => ({ alias, identity: parseAgentIdentity(`@${alias}`) }))
@@ -683,20 +803,35 @@ export function formatMinimalAgentIdentity<T extends AgentIdentityCandidate>(
   return formatAgentIdentity(canonical, options);
 }
 
+/** @deprecated Use {@link AgentIdentity} instead. */
 export type AgentAddress = AgentIdentity;
+/** @deprecated Use {@link AgentIdentityCandidate} instead. */
 export type AgentAddressCandidate = AgentIdentityCandidate;
+/** @deprecated Use {@link AgentIdentity} instead. */
 export type AgentSelector = AgentIdentity;
+/** @deprecated Use {@link AgentIdentityCandidate} instead. */
 export type AgentSelectorCandidate = AgentIdentityCandidate;
 
+/** @deprecated Use {@link parseAgentIdentity} instead. */
 export const parseAgentAddress = parseAgentIdentity;
+/** @deprecated Use {@link formatAgentIdentity} instead. */
 export const formatAgentAddress = formatAgentIdentity;
+/** @deprecated Use {@link constructAgentIdentity} instead. */
 export const constructAgentAddress = constructAgentIdentity;
+/** @deprecated Use {@link extractAgentIdentities} instead. */
 export const extractAgentAddresses = extractAgentIdentities;
+/** @deprecated Use {@link agentIdentityMatches} instead. */
 export const agentAddressMatches = agentIdentityMatches;
+/** @deprecated Use {@link resolveAgentIdentity} instead. */
 export const resolveAgentAddress = resolveAgentIdentity;
 
+/** @deprecated Use {@link parseAgentIdentity} instead. */
 export const parseAgentSelector = parseAgentIdentity;
+/** @deprecated Use {@link formatAgentIdentity} instead. */
 export const formatAgentSelector = formatAgentIdentity;
+/** @deprecated Use {@link extractAgentIdentities} instead. */
 export const extractAgentSelectors = extractAgentIdentities;
+/** @deprecated Use {@link agentIdentityMatches} instead. */
 export const agentSelectorMatches = agentIdentityMatches;
+/** @deprecated Use {@link resolveAgentIdentity} instead. */
 export const resolveAgentSelector = resolveAgentIdentity;