@axiom-lattice/protocols 2.1.39 → 2.1.40

package/src/A2AProtocol.ts

@@ -0,0 +1,184 @@
+/**
+ * A2AProtocol - Google Agent-to-Agent Protocol type definitions
+ *
+ * Based on the A2A open protocol spec for AI agent interoperability.
+ * @see https://github.com/google/A2A
+ */
+
+// ─── Agent Card ───────────────────────────────────────────────────────────
+
+export interface A2ASkill {
+  id: string;
+  name: string;
+  description: string;
+  tags: string[];
+  examples: string[];
+}
+
+export interface A2ACapabilities {
+  streaming: boolean;
+  pushNotifications: boolean;
+  stateTransitionHistory: boolean;
+}
+
+export interface A2AProvider {
+  organization: string;
+  url?: string;
+}
+
+export interface AgentCard {
+  name: string;
+  description: string;
+  url: string;
+  provider: A2AProvider;
+  version: string;
+  documentationUrl?: string;
+  capabilities: A2ACapabilities;
+  defaultInputModes: string[];
+  defaultOutputModes: string[];
+  skills: A2ASkill[];
+}
+
+// ─── Artifact / Part ──────────────────────────────────────────────────────
+
+export interface A2ATextPart {
+  type: "text";
+  text: string;
+}
+
+export interface A2AFilePart {
+  type: "file";
+  file: {
+    name: string;
+    mimeType: string;
+    bytes?: string;
+    uri?: string;
+  };
+}
+
+export interface A2ADataPart {
+  type: "data";
+  data: Record<string, unknown>;
+}
+
+export type A2APart = A2ATextPart | A2AFilePart | A2ADataPart;
+
+// ─── Message ──────────────────────────────────────────────────────────────
+
+export interface A2AMessage {
+  role: "user" | "agent";
+  parts: A2APart[];
+  metadata?: Record<string, unknown>;
+}
+
+// ─── Task ─────────────────────────────────────────────────────────────────
+
+export type A2ATaskState =
+  | "working"
+  | "input-required"
+  | "completed"
+  | "failed"
+  | "canceled"
+  | "rejected";
+
+export interface A2ATaskStatus {
+  state: A2ATaskState;
+  message?: A2AMessage;
+  timestamp: string;
+}
+
+export interface A2AArtifact {
+  name?: string;
+  description?: string;
+  parts: A2APart[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface A2ATask {
+  id: string;
+  sessionId?: string;
+  status: A2ATaskStatus;
+  artifacts: A2AArtifact[];
+  history?: A2AMessage[];
+  metadata?: Record<string, unknown>;
+}
+
+// ─── Request / Response ───────────────────────────────────────────────────
+
+export interface A2ATaskSendRequest {
+  id?: string;
+  sessionId?: string;
+  message: A2AMessage;
+  pushNotification?: A2APushNotification;
+  historyLength?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface A2APushNotification {
+  url: string;
+  token?: string;
+}
+
+export interface A2ATaskUpdatePayload {
+  id: string;
+  sessionId?: string;
+  status: A2ATaskStatus;
+  final?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface A2ATaskArtifactUpdatePayload {
+  id: string;
+  sessionId?: string;
+  artifact: A2AArtifact;
+  final?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+// ─── SSE Events ───────────────────────────────────────────────────────────
+
+export type A2ASSEEvent =
+  | { event: "task"; data: A2ATaskUpdatePayload }
+  | { event: "status-update"; data: A2ATaskUpdatePayload }
+  | { event: "artifact-update"; data: A2ATaskArtifactUpdatePayload }
+  | { event: "error"; data: { code: string; message: string } };
+
+// ─── Config ───────────────────────────────────────────────────────────────
+
+export interface A2AConfig {
+  agentName: string;
+  agentDescription: string;
+  agentUrl: string;
+  organization: string;
+  version?: string;
+  capabilities?: Partial<A2ACapabilities>;
+  defaultInputModes?: string[];
+  defaultOutputModes?: string[];
+  skills?: A2ASkill[];
+  apiKeyMap: Map<string, A2AApiKeyEntry>;
+}
+
+export interface A2AApiKeyEntry {
+  key: string;
+  tenantId?: string;
+  projectId?: string;
+  workspaceId?: string;
+}
+
+export const A2A_DEFAULT_CAPABILITIES: A2ACapabilities = {
+  streaming: true,
+  pushNotifications: false,
+  stateTransitionHistory: false,
+};
+
+export const A2A_DEFAULT_INPUT_MODES = ["text", "text/plain"];
+export const A2A_DEFAULT_OUTPUT_MODES = ["text", "text/plain", "text/markdown"];
+
+export interface A2AAuthContext {
+  authenticated: boolean;
+  apiKey?: string;
+  tenantId?: string;
+  projectId?: string;
+  workspaceId?: string;
+  source?: "bearer" | "x-api-key";
+}

package/src/AgentLatticeProtocol.ts

@@ -16,6 +16,8 @@ export enum AgentType {
   DEEP_AGENT = "deep_agent",
   TEAM = "team",
   PROCESSING = "processing",
+  /** Remote A2A agent — delegates to an external A2A-compatible server */
+  A2A_REMOTE = "a2a_remote",
 }
 
 /**
@@ -204,6 +206,44 @@ export function isTeamAgentConfig(
   return config.type === AgentType.TEAM;
 }
 
+// ─── A2A_REMOTE Agent ──────────────────────────────────────────────────────
+
+/**
+ * A2A_REMOTE agent configuration — delegates to an external A2A server.
+ *
+ * This agent type wraps a remote A2A endpoint so orchestrators can treat
+ * external agents the same as local LangGraph agents.
+ */
+export interface A2ARemoteAgentConfig extends BaseAgentConfig {
+  type: AgentType.A2A_REMOTE;
+  /**
+   * URL of the remote agent's agent card (e.g. http://host:3000/.well-known/agent-card.json).
+   * The builder fetches this card to discover the JSON-RPC endpoint.
+   */
+  agentCardUrl: string;
+  /**
+   * Optional API key sent as Bearer token or X-API-Key header.
+   */
+  apiKey?: string;
+  /**
+   * HTTP timeout in milliseconds (default: 300_000 = 5 min).
+   */
+  timeout?: number;
+  /**
+   * Optional tool keys (not used by the builder, but included for type compatibility).
+   */
+  tools?: string[];
+}
+
+/**
+ * Type guard to check if config is A2ARemoteAgentConfig
+ */
+export function isA2ARemoteAgentConfig(
+  config: AgentConfig
+): config is A2ARemoteAgentConfig {
+  return config.type === AgentType.A2A_REMOTE;
+}
+
 /**
  * Agent configuration union type
  * Different agent types have different configuration options
@@ -213,6 +253,7 @@ export type AgentConfig =
   | DeepAgentConfig
   | TeamAgentConfig
   | ProcessingAgentConfig
+  | A2ARemoteAgentConfig
 
 /**
  * Agent configuration with tools property
@@ -222,6 +263,7 @@ export type AgentConfigWithTools =
   | DeepAgentConfig
   | TeamAgentConfig
   | ProcessingAgentConfig
+  | A2ARemoteAgentConfig
 
 /**
  * Type guard to check if config has tools property

package/src/WorkspaceStoreProtocol.ts

@@ -59,6 +59,8 @@ export interface Project {
   workspaceId: string;
   name: string;
   description?: string;
+  /** Application-specific configuration stored as JSON */
+  config?: Record<string, unknown>;
   createdAt: Date;
   updatedAt: Date;
 }
@@ -69,14 +71,22 @@ export interface Project {
 export interface CreateProjectRequest {
   name: string;
   description?: string;
+  /** Application-specific configuration stored as JSON (optional) */
+  config?: Record<string, unknown>;
 }
 
 /**
  * Update project request type
+ *
+ * @remarks
+ * - The `config` field uses **replace** semantics: if provided, it completely
+ *   overwrites the existing config. To preserve the current config, omit this field.
  */
 export interface UpdateProjectRequest {
   name?: string;
   description?: string;
+  /** Application-specific configuration stored as JSON (replaces existing if provided) */
+  config?: Record<string, unknown>;
 }
 
 /**

package/src/index.ts

@@ -34,6 +34,8 @@ export * from "./BindingProtocol";
 export * from "./EvalStoreProtocol";
 
 export * from "./ChannelAdapterProtocol";
+export * from "./A2AProtocol";
+export * from "./A2AApiKeyStoreProtocol";
 
 // 导出通用类型
 export * from "./types";