@axiom-lattice/protocols 3.0.4 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
 
2
- > @axiom-lattice/protocols@3.0.4 build /home/runner/work/agentic/agentic/packages/protocols
2
+ > @axiom-lattice/protocols@4.0.0 build /home/runner/work/agentic/agentic/packages/protocols
3
3
  > tsup src/index.ts --format cjs,esm --dts --sourcemap
4
4
 
5
5
  CLI Building entry: src/index.ts
@@ -8,13 +8,13 @@
8
8
  CLI Target: es2020
9
9
  CJS Build start
10
10
  ESM Build start
11
- CJS dist/index.js 6.69 KB
12
- CJS dist/index.js.map 47.36 KB
13
- CJS ⚡️ Build success in 315ms
14
- ESM dist/index.mjs 4.78 KB
15
- ESM dist/index.mjs.map 44.88 KB
16
- ESM ⚡️ Build success in 316ms
11
+ ESM dist/index.mjs 12.80 KB
12
+ ESM dist/index.mjs.map 57.44 KB
13
+ ESM ⚡️ Build success in 182ms
14
+ CJS dist/index.js 14.69 KB
15
+ CJS dist/index.js.map 59.96 KB
16
+ CJS ⚡️ Build success in 186ms
17
17
  DTS Build start
18
- DTS ⚡️ Build success in 13450ms
19
- DTS dist/index.d.ts 142.64 KB
20
- DTS dist/index.d.mts 142.64 KB
18
+ DTS ⚡️ Build success in 11445ms
19
+ DTS dist/index.d.ts 148.90 KB
20
+ DTS dist/index.d.mts 148.90 KB
package/CHANGELOG.md CHANGED
@@ -1,5 +1,45 @@
1
1
  # @axiom-lattice/protocols
2
2
 
3
+ ## 4.0.0
4
+
5
+ ### Major Changes
6
+
7
+ - 1c783d0: Align A2A with the standard 0.3 protocol.
8
+
9
+ **Standard A2A 0.3 server (gateway):** per-assistant discovery and execution via
10
+ `GET /api/a2a/agents/:assistantId/.well-known/agent-card.json` and
11
+ `POST /api/a2a/agents/:assistantId/jsonrpc` (`message/send`, `message/stream`,
12
+ `tasks/get`, `tasks/cancel`), plus an internal `test-call` management route.
13
+ Every inbound task is persisted as a `TaskItem` (single-ID projection:
14
+ `TaskItem.id === A2A taskId`). File `bytes` parts are ingested into workspace
15
+ storage and referenced by URI.
16
+
17
+ **API key scope model:** keys are now `tenant + projectId (required) +
18
+ assistantIds[]` whitelist. Added `client.a2aKeys.*` (list/create/delete/disable/
19
+ enable/rotate) and UI (`A2AKeyList`, `A2AExposureSection` with agent-card preview
20
+ and dual-mode try-call).
21
+
22
+ **Breaking changes:**
23
+
24
+ - The legacy custom REST endpoints (`/api/a2a/tasks/send`,
25
+ `/api/a2a/tasks/:taskId`, `/api/a2a/tasks/:taskId/stream`,
26
+ `/api/a2a/tasks/:taskId/cancel`) are removed; use the JSON-RPC endpoint instead.
27
+ - The `A2A_API_KEYS` env format is simplified to `key:tenant:project,...`
28
+ (no workspace segment); `workspaceId` is removed from the key model and
29
+ creation flow.
30
+ - The `x-a2a-agent-id` request header is removed (the assistant is derived from
31
+ the URL path).
32
+ - `protocols` self-maintained A2A types are replaced by re-exports of
33
+ `@a2a-js/sdk` 0.3 types; `A2AApiKeyRecord`/`CreateA2AApiKeyInput` drop
34
+ `workspaceId` and gain `assistantIds`.
35
+
36
+ ### Patch Changes
37
+
38
+ - 4de3e59: Harden A2A task persistence with caller-provided local IDs, atomic canceled-state guards across task stores, and request leases that prevent active scoped runtimes from being evicted before or during stream consumption.
39
+ - 1ed2a67: up issues
40
+ - 83e1d5d: Add ProjectKind (business/training/personal) with a per-workspace shared training project. Gateway ensures a default training project exists idempotently on project list and protects the last training project from deletion; personal assistant spaces are marked `personal`; client-sdk `listProjects` accepts a `kind` filter; react-sdk splits business and training projects in WorkspaceContext and pins learning rounds to the read-only shared Training Context via TrainingContextCard. No TrainingWorkspace entity — training isolation reuses the existing projectId scope.
41
+ - e501a4b: Add optional Markdown belief traces and append-only task activities, return recent task work-item history, and align scoped task work-item ordering and filtering across stores.
42
+
3
43
  ## 3.0.4
4
44
 
5
45
  ### Patch Changes
package/dist/index.d.mts CHANGED
@@ -7,6 +7,7 @@ import { CompiledStateGraph } from '@langchain/langgraph';
7
7
  import { Embeddings } from '@langchain/core/embeddings';
8
8
  import { VectorStore } from '@langchain/core/vectorstores';
9
9
  import { DocumentInterface } from '@langchain/core/documents';
10
+ export { Message as A2AMessage, Part as A2APart, AgentSkill as A2ASkill, Task as A2ATask, TaskState as A2ATaskState, AgentCard } from '@a2a-js/sdk';
10
11
 
11
12
  /**
12
13
  * BaseLatticeProtocol
@@ -1637,6 +1638,24 @@ interface SkillStore {
1637
1638
  * @returns The resource content as string, or null if not found
1638
1639
  */
1639
1640
  loadSkillResource?(tenantId: string, id: string, resourcePath: string, context?: SkillStoreContext): Promise<string | null>;
1641
+ /**
1642
+ * Load a resource without text decoding.
1643
+ * @returns The resource bytes, or null if the resource does not exist
1644
+ */
1645
+ loadSkillResourceRaw?(tenantId: string, id: string, resourcePath: string, context?: SkillStoreContext): Promise<Buffer | null>;
1646
+ /**
1647
+ * Write a resource file into a skill's resources directory
1648
+ * @param tenantId Tenant identifier
1649
+ * @param id Skill identifier
1650
+ * @param resourcePath Path to the resource relative to resources/ directory
1651
+ * @param content Resource content
1652
+ * @param context Optional runtime context for sandbox resolution
1653
+ */
1654
+ writeSkillResource?(tenantId: string, id: string, resourcePath: string, content: string, context?: SkillStoreContext): Promise<void>;
1655
+ /**
1656
+ * Write a resource without text encoding.
1657
+ */
1658
+ writeSkillResourceRaw?(tenantId: string, id: string, resourcePath: string, data: Buffer, context?: SkillStoreContext): Promise<void>;
1640
1659
  }
1641
1660
 
1642
1661
  /**
@@ -1961,6 +1980,12 @@ interface WorkspaceStore {
1961
1980
  updateWorkspace(tenantId: string, id: string, updates: UpdateWorkspaceRequest): Promise<Workspace | null>;
1962
1981
  deleteWorkspace(tenantId: string, id: string): Promise<boolean>;
1963
1982
  }
1983
+ /**
1984
+ * Project kind classification
1985
+ *
1986
+ * Defaults to "business" for legacy rows and omitted input.
1987
+ */
1988
+ type ProjectKind = "business" | "training" | "personal";
1964
1989
  /**
1965
1990
  * Project type definition
1966
1991
  */
@@ -1972,6 +1997,8 @@ interface Project {
1972
1997
  description?: string;
1973
1998
  /** Application-specific configuration stored as JSON */
1974
1999
  config?: Record<string, unknown>;
2000
+ /** Project classification; defaults to "business" when omitted */
2001
+ kind?: ProjectKind;
1975
2002
  createdAt: Date;
1976
2003
  updatedAt: Date;
1977
2004
  }
@@ -1983,6 +2010,8 @@ interface CreateProjectRequest {
1983
2010
  description?: string;
1984
2011
  /** Application-specific configuration stored as JSON (optional) */
1985
2012
  config?: Record<string, unknown>;
2013
+ /** Project classification; defaults to "business" when omitted */
2014
+ kind?: ProjectKind;
1986
2015
  }
1987
2016
  /**
1988
2017
  * Update project request type
@@ -1996,13 +2025,21 @@ interface UpdateProjectRequest {
1996
2025
  description?: string;
1997
2026
  /** Application-specific configuration stored as JSON (replaces existing if provided) */
1998
2027
  config?: Record<string, unknown>;
2028
+ /** Project classification */
2029
+ kind?: ProjectKind;
2030
+ }
2031
+ /**
2032
+ * Filter options for listing projects within a workspace
2033
+ */
2034
+ interface ProjectFilter {
2035
+ kind?: ProjectKind;
1999
2036
  }
2000
2037
  /**
2001
2038
  * ProjectStore interface
2002
2039
  * Provides CRUD operations for project data
2003
2040
  */
2004
2041
  interface ProjectStore {
2005
- getProjectsByWorkspace(tenantId: string, workspaceId: string): Promise<Project[]>;
2042
+ getProjectsByWorkspace(tenantId: string, workspaceId: string, filter?: ProjectFilter): Promise<Project[]>;
2006
2043
  getProjectById(tenantId: string, id: string): Promise<Project | null>;
2007
2044
  createProject(tenantId: string, workspaceId: string, id: string, data: CreateProjectRequest): Promise<Project>;
2008
2045
  updateProject(tenantId: string, id: string, updates: UpdateProjectRequest): Promise<Project | null>;
@@ -3741,6 +3778,11 @@ interface TaskItem {
3741
3778
  * Create task request type
3742
3779
  */
3743
3780
  interface CreateTaskRequest {
3781
+ /**
3782
+ * Caller-provided task identifier. When set, the store uses this id instead of
3783
+ * generating one — used for single-ID mapping with external systems (e.g. A2A).
3784
+ */
3785
+ id?: string;
3744
3786
  /**
3745
3787
  * Task title
3746
3788
  */
@@ -3827,6 +3869,8 @@ interface TaskFileRef {
3827
3869
  uri: string;
3828
3870
  /** Display name (useful when uri is a uuid or bare path) */
3829
3871
  name?: string;
3872
+ /** MIME type of the referenced file (e.g. "application/pdf"), when known */
3873
+ mimeType?: string;
3830
3874
  /** Who attached the file: the user (reference material) or an agent (artifact) */
3831
3875
  addedBy?: "user" | "agent";
3832
3876
  }
@@ -3877,7 +3921,7 @@ interface UpdateTaskRequest {
3877
3921
  /**
3878
3922
  * Additional contextual data
3879
3923
  */
3880
- context?: Record<string, unknown>;
3924
+ context?: Record<string, unknown> | null;
3881
3925
  /**
3882
3926
  * Owner type
3883
3927
  */
@@ -3897,11 +3941,11 @@ interface UpdateTaskRequest {
3897
3941
  /**
3898
3942
  * Task result output
3899
3943
  */
3900
- result?: string;
3944
+ result?: string | null;
3901
3945
  /**
3902
3946
  * Reason for task failure (when status is 'failed')
3903
3947
  */
3904
- failureReason?: string;
3948
+ failureReason?: string | null;
3905
3949
  /** File references attached to this task */
3906
3950
  files?: TaskFileRef[];
3907
3951
  }
@@ -3994,6 +4038,61 @@ interface TaskStore {
3994
4038
  * @returns Updated task if found, null otherwise
3995
4039
  */
3996
4040
  update(tenantId: string, id: string, updates: UpdateTaskRequest): Promise<TaskItem | null>;
4041
+ /**
4042
+ * Atomically update a task only when its current status is expected.
4043
+ *
4044
+ * Storage implementations must evaluate the status predicate in the same
4045
+ * atomic mutation that applies `updates`; callers must not emulate this with
4046
+ * a separate read followed by {@link update}.
4047
+ *
4048
+ * @param tenantId Tenant identifier.
4049
+ * @param id Task identifier.
4050
+ * @param updates Partial task data to update.
4051
+ * @param expectedStatuses Current statuses that permit the update.
4052
+ * @returns The updated task, or `null` when the task is missing or its status is not expected.
4053
+ */
4054
+ updateIfStatusIn(tenantId: string, id: string, updates: UpdateTaskRequest, expectedStatuses: TaskItem["status"][]): Promise<TaskItem | null>;
4055
+ /**
4056
+ * Atomically updates a task only when its status and update timestamp match a read snapshot.
4057
+ *
4058
+ * Implementations must normalize `Date` and string timestamps to the same stable ISO
4059
+ * representation and evaluate both predicates in the mutation itself.
4060
+ *
4061
+ * @param tenantId Tenant identifier.
4062
+ * @param id Task identifier.
4063
+ * @param updates Partial task data to update.
4064
+ * @param expectedStatuses Current statuses that permit the update.
4065
+ * @param expectedUpdatedAt Update timestamp captured from the validated task snapshot.
4066
+ * @returns The updated task, or `null` when the task is missing or either snapshot predicate differs.
4067
+ */
4068
+ updateIfStatusAndUpdatedAt(tenantId: string, id: string, updates: UpdateTaskRequest, expectedStatuses: TaskItem["status"][], expectedUpdatedAt: Date | string): Promise<TaskItem | null>;
4069
+ /**
4070
+ * Atomically updates a child only when both child and parent snapshots match.
4071
+ *
4072
+ * @param tenantId Tenant identifier shared by the child and parent.
4073
+ * @param id Child task identifier.
4074
+ * @param updates Partial child task data to update.
4075
+ * @param expectedStatuses Child statuses that permit the update.
4076
+ * @param expectedUpdatedAt Child update timestamp captured during validation.
4077
+ * @param parentId Parent task identifier captured during validation.
4078
+ * @param expectedParentUpdatedAt Parent update timestamp captured during validation.
4079
+ * @returns The updated child, or `null` when either task is missing or either snapshot differs.
4080
+ */
4081
+ updateIfStatusUpdatedAtAndParentUpdatedAt(tenantId: string, id: string, updates: UpdateTaskRequest, expectedStatuses: TaskItem["status"][], expectedUpdatedAt: Date | string, parentId: string, expectedParentUpdatedAt: Date | string): Promise<TaskItem | null>;
4082
+ /**
4083
+ * Atomically update a task unless its current status is blocked.
4084
+ *
4085
+ * Storage implementations must evaluate the status predicate in the same
4086
+ * atomic mutation that applies `updates`; callers must not emulate this with
4087
+ * a separate read followed by {@link update}.
4088
+ *
4089
+ * @param tenantId Tenant identifier.
4090
+ * @param id Task identifier.
4091
+ * @param updates Partial task data to update.
4092
+ * @param blockedStatuses Current statuses that prevent the update.
4093
+ * @returns The updated task, or `null` when the task is missing or blocked.
4094
+ */
4095
+ updateIfStatusNotIn(tenantId: string, id: string, updates: UpdateTaskRequest, blockedStatuses: TaskItem["status"][]): Promise<TaskItem | null>;
3997
4096
  /**
3998
4097
  * Delete a task by ID
3999
4098
  * @param tenantId Tenant identifier
@@ -4021,6 +4120,8 @@ interface TaskWorkItem {
4021
4120
  summary?: string;
4022
4121
  detail?: Record<string, unknown>;
4023
4122
  attempt?: number;
4123
+ /** Deterministic task-scoped identity used for idempotent event replay. */
4124
+ eventKey?: string;
4024
4125
  createdAt: Date;
4025
4126
  }
4026
4127
  interface CreateWorkItemRequest {
@@ -4035,20 +4136,87 @@ interface CreateWorkItemRequest {
4035
4136
  detail?: Record<string, unknown>;
4036
4137
  attempt?: number;
4037
4138
  }
4139
+ /**
4140
+ * Work-item creation request requiring a deterministic event identity.
4141
+ *
4142
+ * Event keys are unique within a tenant and task, not globally.
4143
+ */
4144
+ interface CreateWorkItemIfAbsentRequest extends CreateWorkItemRequest {
4145
+ /** Deterministic task-scoped identity used for idempotent event replay. */
4146
+ eventKey: string;
4147
+ }
4038
4148
  interface TaskWorkItemListFilter {
4039
4149
  tenantId: string;
4040
4150
  taskId: string;
4041
4151
  workspaceId?: string;
4042
4152
  projectId?: string;
4043
4153
  action?: string;
4154
+ order?: 'asc' | 'desc';
4044
4155
  limit?: number;
4045
4156
  offset?: number;
4046
4157
  }
4047
4158
  interface TaskWorkItemStore {
4048
4159
  create(params: CreateWorkItemRequest): Promise<TaskWorkItem>;
4049
4160
  list(filter: TaskWorkItemListFilter): Promise<TaskWorkItem[]>;
4161
+ /**
4162
+ * Find an event by deterministic identity without list pagination.
4163
+ *
4164
+ * @param tenantId Tenant identifier.
4165
+ * @param taskId Task identifier that scopes the event key.
4166
+ * @param eventKey Deterministic event identity.
4167
+ * @returns The matching item, or `null` when absent.
4168
+ */
4169
+ findByEventKey(tenantId: string, taskId: string, eventKey: string): Promise<TaskWorkItem | null>;
4170
+ /**
4171
+ * Atomically create an event unless its task-scoped key already exists.
4172
+ * Existing events are returned unchanged, preserving immutable replay.
4173
+ *
4174
+ * @param params Work-item fields including the required event key.
4175
+ * @returns The existing or newly created work item.
4176
+ */
4177
+ createIfAbsentByEventKey(params: CreateWorkItemIfAbsentRequest): Promise<TaskWorkItem>;
4050
4178
  }
4051
4179
 
4180
+ /** A single canonical belief recorded in a task description. */
4181
+ interface TaskBeliefEntry {
4182
+ key: string;
4183
+ probability: number;
4184
+ target: number;
4185
+ basis: string;
4186
+ }
4187
+ /** The canonical belief snapshot embedded in task Markdown. */
4188
+ interface TaskBeliefState {
4189
+ entries: TaskBeliefEntry[];
4190
+ }
4191
+ /** Stable diagnostic identifiers returned by the Belief State parser. */
4192
+ type TaskBeliefDiagnosticCode = "MISSING_BELIEF_STATE" | "DUPLICATE_BELIEF_STATE" | "INVALID_BELIEF_HEADERS" | "MALFORMED_BELIEF_ROW" | "INVALID_BELIEF_KEY" | "INVALID_BELIEF_PERCENT" | "DUPLICATE_BELIEF_KEY";
4193
+ /** A structured failure produced while parsing a task Belief State. */
4194
+ interface TaskBeliefParseFailure {
4195
+ success: false;
4196
+ code: TaskBeliefDiagnosticCode;
4197
+ message: string;
4198
+ line?: number;
4199
+ key?: string;
4200
+ column?: "probability" | "target";
4201
+ }
4202
+ /** A successfully parsed task Belief State. */
4203
+ interface TaskBeliefParseSuccess {
4204
+ success: true;
4205
+ state: TaskBeliefState;
4206
+ }
4207
+ /** The discriminated result of parsing a task Belief State. */
4208
+ type TaskBeliefParseResult = TaskBeliefParseSuccess | TaskBeliefParseFailure;
4209
+ /** Parses the unique non-code-fenced canonical Belief State section in Markdown. */
4210
+ declare function parseTaskBeliefState(markdown: string): TaskBeliefParseResult;
4211
+ /** Compares two Belief States while ignoring entry order and insignificant whitespace. */
4212
+ declare function taskBeliefStatesEqual(left: TaskBeliefState, right: TaskBeliefState): boolean;
4213
+ /**
4214
+ * Replaces a unique Belief State section, or inserts one after Acceptance Criteria content.
4215
+ *
4216
+ * @throws {Error} If the state is noncanonical or the Markdown contains duplicate sections.
4217
+ */
4218
+ declare function replaceTaskBeliefState(markdown: string, state: TaskBeliefState): string;
4219
+
4052
4220
  /**
4053
4221
  * LocalA2ATemplateConfig
4054
4222
  *
@@ -4148,172 +4316,67 @@ interface ChannelAdapter<TConfig = unknown> {
4148
4316
  }
4149
4317
 
4150
4318
  /**
4151
- * A2AProtocol - Google Agent-to-Agent Protocol type definitions
4152
- *
4153
- * Based on the A2A open protocol spec for AI agent interoperability.
4154
- * @see https://github.com/google/A2A
4319
+ * A2AProtocol - re-exports standard A2A 0.3 types from @a2a-js/sdk
4320
+ * plus Axiom-specific auth/exposure types.
4155
4321
  */
4156
- interface A2ASkill {
4157
- id: string;
4158
- name: string;
4159
- description: string;
4160
- tags: string[];
4161
- examples: string[];
4162
- }
4163
- interface A2ACapabilities {
4164
- streaming: boolean;
4165
- pushNotifications: boolean;
4166
- stateTransitionHistory: boolean;
4167
- }
4168
- interface A2AProvider {
4169
- organization: string;
4170
- url?: string;
4171
- }
4172
- interface AgentCard {
4173
- name: string;
4174
- description: string;
4175
- url: string;
4176
- provider: A2AProvider;
4177
- version: string;
4178
- documentationUrl?: string;
4179
- capabilities: A2ACapabilities;
4180
- defaultInputModes: string[];
4181
- defaultOutputModes: string[];
4182
- skills: A2ASkill[];
4183
- }
4184
- interface A2ATextPart {
4185
- type: "text";
4186
- text: string;
4187
- }
4188
- interface A2AFilePart {
4189
- type: "file";
4190
- file: {
4322
+
4323
+ /**
4324
+ * Per-agent A2A exposure configuration — controls whether an agent is
4325
+ * reachable over A2A and which skills are advertised on its AgentCard.
4326
+ */
4327
+ interface A2AExposure {
4328
+ /** Whether this agent is exposed over the A2A protocol */
4329
+ enabled: boolean;
4330
+ /** Skills advertised on the AgentCard; defaults to a single generic skill when omitted */
4331
+ skills?: Array<{
4332
+ id: string;
4191
4333
  name: string;
4192
- mimeType: string;
4193
- bytes?: string;
4194
- uri?: string;
4195
- };
4196
- }
4197
- interface A2ADataPart {
4198
- type: "data";
4199
- data: Record<string, unknown>;
4200
- }
4201
- type A2APart = A2ATextPart | A2AFilePart | A2ADataPart;
4202
- interface A2AMessage {
4203
- role: "user" | "agent";
4204
- parts: A2APart[];
4205
- messageId?: string;
4206
- contextId?: string;
4207
- referenceTaskIds?: string[];
4208
- metadata?: Record<string, unknown>;
4209
- }
4210
- type A2ATaskState = "working" | "input-required" | "completed" | "failed" | "canceled" | "rejected";
4211
- interface A2ATaskStatus {
4212
- state: A2ATaskState;
4213
- message?: A2AMessage;
4214
- timestamp: string;
4215
- }
4216
- interface A2AArtifact {
4217
- name?: string;
4218
- description?: string;
4219
- parts: A2APart[];
4220
- metadata?: Record<string, unknown>;
4221
- }
4222
- interface A2ATask {
4223
- id: string;
4224
- sessionId?: string;
4225
- contextId?: string;
4226
- status: A2ATaskStatus;
4227
- artifacts: A2AArtifact[];
4228
- history?: A2AMessage[];
4229
- metadata?: Record<string, unknown>;
4230
- }
4231
- interface A2ATaskSendRequest {
4232
- id?: string;
4233
- sessionId?: string;
4234
- message: A2AMessage;
4235
- pushNotification?: A2APushNotification;
4236
- historyLength?: number;
4237
- metadata?: Record<string, unknown>;
4238
- }
4239
- interface A2APushNotification {
4240
- url: string;
4241
- token?: string;
4242
- }
4243
- interface A2ATaskUpdatePayload {
4244
- id: string;
4245
- sessionId?: string;
4246
- contextId?: string;
4247
- status: A2ATaskStatus;
4248
- final?: boolean;
4249
- metadata?: Record<string, unknown>;
4250
- }
4251
- interface A2ATaskArtifactUpdatePayload {
4252
- id: string;
4253
- sessionId?: string;
4254
- contextId?: string;
4255
- artifact: A2AArtifact;
4256
- final?: boolean;
4257
- metadata?: Record<string, unknown>;
4258
- }
4259
- type A2ASSEEvent = {
4260
- event: "task";
4261
- data: A2ATaskUpdatePayload;
4262
- } | {
4263
- event: "status-update";
4264
- data: A2ATaskUpdatePayload;
4265
- } | {
4266
- event: "artifact-update";
4267
- data: A2ATaskArtifactUpdatePayload;
4268
- } | {
4269
- event: "error";
4270
- data: {
4271
- code: string;
4272
- message: string;
4273
- };
4274
- };
4275
- interface A2AConfig {
4276
- agentName: string;
4277
- agentDescription: string;
4278
- agentUrl: string;
4279
- organization: string;
4280
- version?: string;
4281
- capabilities?: Partial<A2ACapabilities>;
4282
- defaultInputModes?: string[];
4283
- defaultOutputModes?: string[];
4284
- skills?: A2ASkill[];
4285
- apiKeyMap: Map<string, A2AApiKeyEntry>;
4334
+ description: string;
4335
+ tags?: string[];
4336
+ examples?: string[];
4337
+ }>;
4338
+ /** Supported input modes (MIME types); defaults to text modes when omitted */
4339
+ inputModes?: string[];
4340
+ /** Supported output modes (MIME types); defaults to text modes when omitted */
4341
+ outputModes?: string[];
4286
4342
  }
4343
+ /**
4344
+ * In-memory API key entry used for request authentication.
4345
+ * Empty/undefined assistantIds means all exposed agents in the tenant.
4346
+ */
4287
4347
  interface A2AApiKeyEntry {
4288
4348
  key: string;
4289
- tenantId?: string;
4290
- projectId?: string;
4291
- workspaceId?: string;
4349
+ tenantId: string;
4350
+ projectId: string;
4351
+ assistantIds?: string[];
4292
4352
  }
4293
- declare const A2A_DEFAULT_CAPABILITIES: A2ACapabilities;
4294
- declare const A2A_DEFAULT_INPUT_MODES: string[];
4295
- declare const A2A_DEFAULT_OUTPUT_MODES: string[];
4353
+ /**
4354
+ * Authentication context attached to an incoming A2A request after key validation.
4355
+ */
4296
4356
  interface A2AAuthContext {
4297
4357
  authenticated: boolean;
4298
4358
  apiKey?: string;
4299
4359
  tenantId?: string;
4300
4360
  projectId?: string;
4301
- workspaceId?: string;
4361
+ assistantIds?: string[];
4302
4362
  source?: "bearer" | "x-api-key";
4303
4363
  }
4304
4364
 
4305
4365
  /**
4306
4366
  * A2AApiKeyStoreProtocol
4307
4367
  *
4308
- * Persistence interface for A2A API keys with tenant/project/workspace scoping.
4368
+ * Persistence interface for A2A API keys scoped by tenant + required project,
4369
+ * with an optional assistantIds whitelist.
4309
4370
  */
4310
4371
 
4311
4372
  interface A2AApiKeyRecord {
4312
4373
  id: string;
4313
4374
  key: string;
4314
4375
  tenantId: string;
4315
- projectId?: string;
4316
- workspaceId?: string;
4376
+ /** Required project scope — must exist in the tenant */
4377
+ projectId: string;
4378
+ /** Assistant whitelist; empty/undefined = all exposed agents in the tenant */
4379
+ assistantIds?: string[];
4317
4380
  label?: string;
4318
4381
  enabled: boolean;
4319
4382
  createdAt: Date;
@@ -4321,13 +4384,17 @@ interface A2AApiKeyRecord {
4321
4384
  }
4322
4385
  interface CreateA2AApiKeyInput {
4323
4386
  tenantId: string;
4324
- projectId?: string;
4325
- workspaceId?: string;
4387
+ /** Required project scope — must exist in the tenant */
4388
+ projectId: string;
4389
+ /** Assistant whitelist; empty/undefined = all exposed agents in the tenant */
4390
+ assistantIds?: string[];
4326
4391
  label?: string;
4327
4392
  }
4328
4393
  interface A2AApiKeyStore {
4329
4394
  /** Look up a key record by its bearer token value (for auth). */
4330
4395
  findByKey(key: string): Promise<A2AApiKeyRecord | null>;
4396
+ /** Look up a key record by its management identifier. */
4397
+ findById(id: string): Promise<A2AApiKeyRecord | null>;
4331
4398
  /** List all keys, optionally filtered by tenant. */
4332
4399
  list(params: {
4333
4400
  tenantId?: string;
@@ -4855,4 +4922,4 @@ type Timestamp = number;
4855
4922
  */
4856
4923
  type Callback<T = any, R = void> = (data: T) => R | Promise<R>;
4857
4924
 
4858
- export { type A2AApiKeyEntry, type A2AApiKeyRecord, type A2AApiKeyStore, type A2AArtifact, type A2AAuthContext, type A2ACapabilities, type A2AConfig, type A2ADataPart, type A2AFilePart, type A2AMessage, type A2APart, type A2AProvider, type A2APushNotification, type A2ARemoteAgentConfig, type A2ASSEEvent, type A2ASkill, type A2ATask, type A2ATaskArtifactUpdatePayload, type A2ATaskSendRequest, type A2ATaskState, type A2ATaskStatus, type A2ATaskUpdatePayload, type A2ATextPart, A2A_DEFAULT_CAPABILITIES, A2A_DEFAULT_INPUT_MODES, A2A_DEFAULT_OUTPUT_MODES, type AgentCard, type AgentClient, type AgentConfig, type AgentConfigWithTools, type AgentLatticeProtocol, type AgentMenuConfig, type AgentMiddlewareConfig, type AgentRunConfig, AgentType, type Assistant, type AssistantMessage, type AssistantStore, type Attachment, type AvailableModule, type BaseLatticeProtocol, type BaseMessage, type Binding, type BindingRegistry, type BootstrapFilesConfig, type BrowserMiddlewareConfig, type Callback, type ChannelAdapter, type ChannelInstallation, type ChannelInstallationStore, type ChannelInstallationType, type ClawMiddlewareConfig, type CodeEvalMiddlewareConfig, type Collection, type CollectionField, type CollectionFieldType, type CollectionMiddlewareConfig, type CollectionSchema, type CollectionStore, type ConnectionEntry, type ConnectionStore, type ConversationRecord, type CreateA2AApiKeyInput, type CreateAssistantRequest, type CreateBindingInput, type CreateChannelInstallationRequest, type CreateCollectionRequest, type CreateConversationInput, type CreateDatabaseConfigRequest, type CreateEvalCaseRequest, type CreateEvalProjectRequest, type CreateEvalRunRequest, type CreateEvalSuiteRequest, type CreateMcpServerConfigRequest, type CreateMenuItemInput, type CreateMetricsServerConfigRequest, type CreateProjectRequest, type CreateRunStepRequest, type CreateShareRequest, type CreateSkillRequest, type CreateTaskRequest, type CreateTenantRequest, type CreateThreadRequest, type CreateUserRequest, type CreateUserTenantLinkRequest, type CreateWorkItemRequest, type CreateWorkflowRunRequest, type CreateWorkspaceRequest, type CustomMenuConfig, type DataSource, type DatabaseConfig, type DatabaseConfigEntry, type DatabaseConfigStore, type DatabaseType, type DeepAgentConfig, type DeveloperMessage, type DispatchResult, type EmbeddingsConfig, type EmbeddingsLatticeProtocol, type EvalCase, type EvalProject, type EvalProjectReport, type EvalRun, type EvalRunResult, type EvalStore, type EvalSuite, type ExecuteSqlQueryRequest, type ExecuteSqlQueryResponse, type FilterCondition, type GraphBuildOptions, type HtmlMenuConfig, type IConversationStore, type ID, type InboundMessage, type InternalAgentNode, type InternalBaseNode, type InternalDSL, type InternalEdge, type InternalInput, type InternalInputNode, type InternalMapNode, type InternalNode, type InternalNodeConfig, type InternalOutput, type InternalState, type InternalStateField, type InternalTerminalNode, type InterruptMessage, type InterruptPolicy, type LLMConfig, type LarkChannelInstallationConfig, type LatticeError, type LatticeEventBus, type LatticeMessage, type LocalA2AProviderId, type LocalA2AProviderState, type LocalA2AProviderStatus, type LocalA2ATemplateDefinition, type LocalRuntimeConfig, type LoggerClient, type LoggerConfig, type LoggerContext, type LoggerLatticeProtocol, LoggerType, type McpClient, type McpClientOptions, type McpConnectionStatus, type McpLatticeMessage, type McpLatticeProtocol, McpMessageType, type McpServerConfig, type McpServerConfigEntry, type McpServerConfigStore, type McpStats, type McpTool, type McpToolResult, type McpTransportType, type MemoryClient, type MemoryConfig, type MemoryLatticeProtocol, MemoryType, type MenuContentConfig, type MenuContentType, type MenuItem, type MenuRegistry, type MenuTarget, type Message, type MessageChunk, type MessageChunkType, MessageChunkTypes, type MessageContext, type MessageMiddleware, type MetricColumn, type MetricDataPoint, type MetricMeta, type MetricQueryResult, type MetricsMiddlewareConfig, type MetricsServerConfig, type MetricsServerConfigEntry, type MetricsServerConfigStore, type MetricsServerType, type MiddlewareType, type ModelLatticeProtocol, type OutboundMessage, type PaginatedResult, type PaginationParams, type PinoFileOptions, type Plugin, type PluginConnection, type PluginConnectionFieldSchema, type PluginConnectionTestResult, type PluginContext, type PluginDiscoveredResource, type PluginMeta, type PluginMetaOutput, type PluginMiddlewareFactory, type PluginToolMeta, type ProcessingAgentConfig, type Project, type ProjectStore, type QueryParams, type QueryResultFormat, type QueryWorkflowRunsOptions, type QueryWorkflowRunsResult, type QueueClient, type QueueConfig, type QueueLatticeProtocol, type QueueResult, QueueType, type ReactAgentConfig, type ReplyTarget, type ResourceAddress, type ResourceResolver, type Result, type RunStep, type STTClient, type STTConfig, type STTModelLatticeProtocol, type SandboxMiddlewareConfig, type ScheduleClient, type ScheduleConfig, type ScheduleCronOptions, ScheduleExecutionType, type ScheduleLatticeProtocol, type ScheduleOnceOptions, type ScheduleStorage, ScheduleType, type ScheduledTaskDefinition, ScheduledTaskStatus, type SchedulerMiddlewareConfig, type SemanticMetricsFilter, type SemanticMetricsQueryRequest, type SemanticMetricsQueryResponse, type SemanticMetricsServerConfig, type ShareRecord, type ShareResult, type ShareVisibility, type SharedResourceStore, type Skill, type SkillClient, type SkillClientType, type SkillConfig, type SkillLatticeProtocol, type SkillStore, type SkillStoreContext, type SqlMiddlewareConfig, type StepStatus, type StepType, type StorageType, type SystemMessage, type TableQueryRequest, type TableQueryResponse, type TaskFileRef, type TaskHandler, type TaskItem, type TaskListFilter, type TaskStore, type TaskWorkItem, type TaskWorkItemListFilter, type TaskWorkItemStore, type TeamAgentConfig, type TeamTeammateConfig, type Tenant, type TenantStatus, type TenantStore, type TestMcpServerToolsResponse, type Thread, type ThreadStore, type Timestamp, type ToolCall, type ToolConfig, type ToolExecutor, type ToolLatticeProtocol, type ToolMessage, type TopologyEdge, type TranscriptionResult, type UIComponent, UIComponentType, type UIConfig, type UILatticeProtocol, type UpdateChannelInstallationRequest, type UpdateCollectionRequest, type UpdateDatabaseConfigRequest, type UpdateMcpServerConfigRequest, type UpdateMenuItemInput, type UpdateMetricsServerConfigRequest, type UpdateProjectRequest, type UpdateRunStepRequest, type UpdateTaskRequest, type UpdateTenantRequest, type UpdateUserRequest, type UpdateUserTenantLinkRequest, type UpdateWorkflowRunRequest, type UpdateWorkspaceRequest, type User, type UserMessage, type UserStatus, type UserStore, type UserTenantLink, type UserTenantLinkStore, type UserTenantRole, type VectorStoreConfig, type VectorStoreCreateParams, type VectorStoreLatticeProtocol, type VectorStoreProvider, type WechatChannelInstallationConfig, type WorkflowAgentConfig, type WorkflowRun, type WorkflowRunStatus, type WorkflowTrackingStore, type Workspace, type WorkspaceStore, type YamlAgentStep, type YamlMapStep, type YamlParallelBlock, type YamlTopLevelStep, type YamlWorkflow, getSubAgentsFromConfig, getToolsFromConfig, hasTools, isA2ARemoteAgentConfig, isDeepAgentConfig, isProcessingAgentConfig, isTeamAgentConfig, isWorkflowAgentConfig };
4925
+ export { type A2AApiKeyEntry, type A2AApiKeyRecord, type A2AApiKeyStore, type A2AAuthContext, type A2AExposure, type A2ARemoteAgentConfig, type AgentClient, type AgentConfig, type AgentConfigWithTools, type AgentLatticeProtocol, type AgentMenuConfig, type AgentMiddlewareConfig, type AgentRunConfig, AgentType, type Assistant, type AssistantMessage, type AssistantStore, type Attachment, type AvailableModule, type BaseLatticeProtocol, type BaseMessage, type Binding, type BindingRegistry, type BootstrapFilesConfig, type BrowserMiddlewareConfig, type Callback, type ChannelAdapter, type ChannelInstallation, type ChannelInstallationStore, type ChannelInstallationType, type ClawMiddlewareConfig, type CodeEvalMiddlewareConfig, type Collection, type CollectionField, type CollectionFieldType, type CollectionMiddlewareConfig, type CollectionSchema, type CollectionStore, type ConnectionEntry, type ConnectionStore, type ConversationRecord, type CreateA2AApiKeyInput, type CreateAssistantRequest, type CreateBindingInput, type CreateChannelInstallationRequest, type CreateCollectionRequest, type CreateConversationInput, type CreateDatabaseConfigRequest, type CreateEvalCaseRequest, type CreateEvalProjectRequest, type CreateEvalRunRequest, type CreateEvalSuiteRequest, type CreateMcpServerConfigRequest, type CreateMenuItemInput, type CreateMetricsServerConfigRequest, type CreateProjectRequest, type CreateRunStepRequest, type CreateShareRequest, type CreateSkillRequest, type CreateTaskRequest, type CreateTenantRequest, type CreateThreadRequest, type CreateUserRequest, type CreateUserTenantLinkRequest, type CreateWorkItemIfAbsentRequest, type CreateWorkItemRequest, type CreateWorkflowRunRequest, type CreateWorkspaceRequest, type CustomMenuConfig, type DataSource, type DatabaseConfig, type DatabaseConfigEntry, type DatabaseConfigStore, type DatabaseType, type DeepAgentConfig, type DeveloperMessage, type DispatchResult, type EmbeddingsConfig, type EmbeddingsLatticeProtocol, type EvalCase, type EvalProject, type EvalProjectReport, type EvalRun, type EvalRunResult, type EvalStore, type EvalSuite, type ExecuteSqlQueryRequest, type ExecuteSqlQueryResponse, type FilterCondition, type GraphBuildOptions, type HtmlMenuConfig, type IConversationStore, type ID, type InboundMessage, type InternalAgentNode, type InternalBaseNode, type InternalDSL, type InternalEdge, type InternalInput, type InternalInputNode, type InternalMapNode, type InternalNode, type InternalNodeConfig, type InternalOutput, type InternalState, type InternalStateField, type InternalTerminalNode, type InterruptMessage, type InterruptPolicy, type LLMConfig, type LarkChannelInstallationConfig, type LatticeError, type LatticeEventBus, type LatticeMessage, type LocalA2AProviderId, type LocalA2AProviderState, type LocalA2AProviderStatus, type LocalA2ATemplateDefinition, type LocalRuntimeConfig, type LoggerClient, type LoggerConfig, type LoggerContext, type LoggerLatticeProtocol, LoggerType, type McpClient, type McpClientOptions, type McpConnectionStatus, type McpLatticeMessage, type McpLatticeProtocol, McpMessageType, type McpServerConfig, type McpServerConfigEntry, type McpServerConfigStore, type McpStats, type McpTool, type McpToolResult, type McpTransportType, type MemoryClient, type MemoryConfig, type MemoryLatticeProtocol, MemoryType, type MenuContentConfig, type MenuContentType, type MenuItem, type MenuRegistry, type MenuTarget, type Message, type MessageChunk, type MessageChunkType, MessageChunkTypes, type MessageContext, type MessageMiddleware, type MetricColumn, type MetricDataPoint, type MetricMeta, type MetricQueryResult, type MetricsMiddlewareConfig, type MetricsServerConfig, type MetricsServerConfigEntry, type MetricsServerConfigStore, type MetricsServerType, type MiddlewareType, type ModelLatticeProtocol, type OutboundMessage, type PaginatedResult, type PaginationParams, type PinoFileOptions, type Plugin, type PluginConnection, type PluginConnectionFieldSchema, type PluginConnectionTestResult, type PluginContext, type PluginDiscoveredResource, type PluginMeta, type PluginMetaOutput, type PluginMiddlewareFactory, type PluginToolMeta, type ProcessingAgentConfig, type Project, type ProjectFilter, type ProjectKind, type ProjectStore, type QueryParams, type QueryResultFormat, type QueryWorkflowRunsOptions, type QueryWorkflowRunsResult, type QueueClient, type QueueConfig, type QueueLatticeProtocol, type QueueResult, QueueType, type ReactAgentConfig, type ReplyTarget, type ResourceAddress, type ResourceResolver, type Result, type RunStep, type STTClient, type STTConfig, type STTModelLatticeProtocol, type SandboxMiddlewareConfig, type ScheduleClient, type ScheduleConfig, type ScheduleCronOptions, ScheduleExecutionType, type ScheduleLatticeProtocol, type ScheduleOnceOptions, type ScheduleStorage, ScheduleType, type ScheduledTaskDefinition, ScheduledTaskStatus, type SchedulerMiddlewareConfig, type SemanticMetricsFilter, type SemanticMetricsQueryRequest, type SemanticMetricsQueryResponse, type SemanticMetricsServerConfig, type ShareRecord, type ShareResult, type ShareVisibility, type SharedResourceStore, type Skill, type SkillClient, type SkillClientType, type SkillConfig, type SkillLatticeProtocol, type SkillStore, type SkillStoreContext, type SqlMiddlewareConfig, type StepStatus, type StepType, type StorageType, type SystemMessage, type TableQueryRequest, type TableQueryResponse, type TaskBeliefDiagnosticCode, type TaskBeliefEntry, type TaskBeliefParseFailure, type TaskBeliefParseResult, type TaskBeliefParseSuccess, type TaskBeliefState, type TaskFileRef, type TaskHandler, type TaskItem, type TaskListFilter, type TaskStore, type TaskWorkItem, type TaskWorkItemListFilter, type TaskWorkItemStore, type TeamAgentConfig, type TeamTeammateConfig, type Tenant, type TenantStatus, type TenantStore, type TestMcpServerToolsResponse, type Thread, type ThreadStore, type Timestamp, type ToolCall, type ToolConfig, type ToolExecutor, type ToolLatticeProtocol, type ToolMessage, type TopologyEdge, type TranscriptionResult, type UIComponent, UIComponentType, type UIConfig, type UILatticeProtocol, type UpdateChannelInstallationRequest, type UpdateCollectionRequest, type UpdateDatabaseConfigRequest, type UpdateMcpServerConfigRequest, type UpdateMenuItemInput, type UpdateMetricsServerConfigRequest, type UpdateProjectRequest, type UpdateRunStepRequest, type UpdateTaskRequest, type UpdateTenantRequest, type UpdateUserRequest, type UpdateUserTenantLinkRequest, type UpdateWorkflowRunRequest, type UpdateWorkspaceRequest, type User, type UserMessage, type UserStatus, type UserStore, type UserTenantLink, type UserTenantLinkStore, type UserTenantRole, type VectorStoreConfig, type VectorStoreCreateParams, type VectorStoreLatticeProtocol, type VectorStoreProvider, type WechatChannelInstallationConfig, type WorkflowAgentConfig, type WorkflowRun, type WorkflowRunStatus, type WorkflowTrackingStore, type Workspace, type WorkspaceStore, type YamlAgentStep, type YamlMapStep, type YamlParallelBlock, type YamlTopLevelStep, type YamlWorkflow, getSubAgentsFromConfig, getToolsFromConfig, hasTools, isA2ARemoteAgentConfig, isDeepAgentConfig, isProcessingAgentConfig, isTeamAgentConfig, isWorkflowAgentConfig, parseTaskBeliefState, replaceTaskBeliefState, taskBeliefStatesEqual };