@axiom-lattice/protocols 7.9.0 → 7.10.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@axiom-lattice/protocols",
3
- "version": "7.9.0",
3
+ "version": "7.10.0",
4
4
  "description": "Unified protocol type definitions for Axiom Lattice framework",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -10,6 +10,8 @@ export interface AgentWebAppThreadMetadata {
10
10
  webAppId: string;
11
11
  userId: string;
12
12
  projectId: string;
13
+ /** External business key, present only for dynamic-project threads. */
14
+ webAppProjectKey?: string;
13
15
  label?: string;
14
16
  }
15
17
 
@@ -97,11 +99,15 @@ export type AgentWebAppErrorCode =
97
99
  | "WEB_APP_DISABLED"
98
100
  | "USER_ID_REQUIRED"
99
101
  | "INVALID_USER_ID"
102
+ | "INVALID_PROJECT_ID"
103
+ | "INVALID_THREAD_ID"
100
104
  | "PROJECT_NOT_ALLOWED"
101
105
  | "PROJECT_SELECTOR_DISABLED"
106
+ | "PROJECT_PROVISION_FAILED"
102
107
  | "MODEL_NOT_ALLOWED"
103
108
  | "FEATURE_DISABLED"
104
109
  | "THREAD_NOT_FOUND"
110
+ | "THREAD_OWNERSHIP_CONFLICT"
105
111
  | "STREAM_CONFLICT"
106
112
  | "STREAM_FAILED"
107
113
  | "RUN_CANCEL_UNAVAILABLE"
@@ -19,6 +19,8 @@ export interface AgentWebAppFeatures {
19
19
  genUI: boolean;
20
20
  /** File panel surface. Tolerated missing (treated as false) for records created before Phase 2. */
21
21
  files?: boolean;
22
+ /** Runtime accepts arbitrary external project keys. Omit when false. */
23
+ dynamicProjects?: boolean;
22
24
  }
23
25
 
24
26
  /** One quick-start suggestion offered in the Web App chat empty state. */
@@ -29,6 +31,9 @@ export interface AgentWebAppQuickPrompt {
29
31
  text: string;
30
32
  }
31
33
 
34
+ /** Default fallback when a web app has no explicit `appearance.locale`. */
35
+ export type AgentWebAppLocale = "en-US" | "zh-CN";
36
+
32
37
  /** Optional display customization for an Agent Web App. */
33
38
  export interface AgentWebAppAppearance {
34
39
  title?: string;
@@ -36,6 +41,13 @@ export interface AgentWebAppAppearance {
36
41
  primaryColor?: string;
37
42
  /** Up to 6 quick-start suggestions for the chat empty state. */
38
43
  quickPrompts?: AgentWebAppQuickPrompt[];
44
+ /**
45
+ * UI locale for the embedded chat. `AgentChatApp` renders the Console chat
46
+ * stack, whose copy is owned by the SDK's i18n layer; this field lets a
47
+ * publication pin that language independently of any host page. Absent = the
48
+ * host's own locale or `en-US` (same as today).
49
+ */
50
+ locale?: AgentWebAppLocale;
39
51
  }
40
52
 
41
53
  /** Identity assurance levels reported by the runtime. */
@@ -106,6 +106,22 @@ export interface ChannelAdapter<TConfig = unknown> {
106
106
  message: OutboundMessage,
107
107
  installation: ChannelInstallation,
108
108
  ): Promise<void>;
109
+ /**
110
+ * 可选:把 Agent 产出的文件作为附件发送到会话。
111
+ *
112
+ * 调用方会先交付文本回复,再调用本方法;实现应以**独立的平台消息**发送
113
+ * `attachments`(渠道支持时),而不是把它附加到同一条文本回复里。
114
+ *
115
+ * @remarks
116
+ * 渠道通常需要**独立的平台消息**来承载文件(例如先发文本气泡,再发文件
117
+ * 消息),因此本方法与 `sendReply` 分开。`OutboundMessage.attachments`
118
+ * 不参与出站交付:入站附件用它承载,出站附件一律经本方法发送。
119
+ */
120
+ sendAttachments?(
121
+ replyTarget: ReplyTarget,
122
+ attachments: readonly Attachment[],
123
+ installation: ChannelInstallation,
124
+ ): Promise<void>;
109
125
  /**
110
126
  * 可选:流式回复。
111
127
  *
@@ -54,6 +54,7 @@ export interface LarkChannelInstallationConfig {
54
54
  export interface WechatChannelInstallationConfig {
55
55
  botToken: string;
56
56
  uin?: string;
57
+ cdnBaseUrl?: string;
57
58
  }
58
59
 
59
60
  /**
@@ -34,6 +34,11 @@ export interface ObservabilityDashboardResult {
34
34
  export interface ObservabilityDashboardEnvelope {
35
35
  /** Provider type, also used as the UI element key suffix. */
36
36
  provider: string;
37
+ /**
38
+ * Tenant the dashboard was scoped to, resolved from the authenticated
39
+ * session. Display-only; absent on envelopes from older gateways.
40
+ */
41
+ tenantId?: string;
37
42
  /** Requested time window. */
38
43
  range: ObservabilityDashboardRange;
39
44
  /** Server generation timestamp. */
@@ -154,11 +154,17 @@ export interface ScheduleStorage {
154
154
  /**
155
155
  * Atomically claims one due fire by transitioning the task `pending -> running`.
156
156
  *
157
+ * The claim is scoped to the expected occurrence timestamp so a stale timer
158
+ * from another replica cannot re-claim the next occurrence after the winner
159
+ * has already written the task back to `pending`.
160
+ *
157
161
  * @param taskId Task to claim.
158
- * @returns True when this caller won the claim (task was `pending`); false if
159
- * another replica already claimed it or it is not pending.
162
+ * @param expectedFireAt The occurrence this caller armed: `executeAt` for a
163
+ * one-time task, `nextRunAt` for a cron task.
164
+ * @returns True only when the stored task is `pending`, its current occurrence
165
+ * still equals `expectedFireAt`, and that occurrence is due; false otherwise.
160
166
  */
161
- claimScheduledRun(taskId: string): Promise<boolean>;
167
+ claimScheduledRun(taskId: string, expectedFireAt: number): Promise<boolean>;
162
168
 
163
169
  /**
164
170
  * Requeues `running` tasks whose `updatedAt` is older than `olderThanMs` back
@@ -0,0 +1,16 @@
1
+ import type { AgentInterrupt } from "./AgentInterruptProtocol";
2
+
3
+ /** Coarse run state of a conversation thread. */
4
+ export type ThreadRunState = "idle" | "busy" | "interrupted" | "error";
5
+
6
+ /**
7
+ * Provider-agnostic thread status snapshot.
8
+ *
9
+ * `TInterrupt` lets each surface use its own reviewed interrupt projection:
10
+ * Console uses `AgentInterrupt`, Agent Web App uses its redacted widget shape.
11
+ */
12
+ export interface ThreadStatus<TInterrupt = AgentInterrupt> {
13
+ status: ThreadRunState;
14
+ pendingMessages: number;
15
+ interrupts: TInterrupt[];
16
+ }
@@ -87,12 +87,14 @@ type AgentWebAppBootstrapFeatureKeys =
87
87
  | "attachments"
88
88
  | "hitl"
89
89
  | "genUI"
90
- | "files";
90
+ | "files"
91
+ | "dynamicProjects";
91
92
  type AgentWebAppBootstrapAppearanceKeys =
92
93
  | "title"
93
94
  | "welcomeMessage"
94
95
  | "primaryColor"
95
- | "quickPrompts";
96
+ | "quickPrompts"
97
+ | "locale";
96
98
 
97
99
  type _BootstrapHasExactTopLevelKeys = Expect<
98
100
  Equal<keyof AgentWebAppBootstrap, AgentWebAppBootstrapKeys>
@@ -133,15 +135,19 @@ const errorCodes = [
133
135
  "WEB_APP_DISABLED",
134
136
  "USER_ID_REQUIRED",
135
137
  "INVALID_USER_ID",
138
+ "INVALID_PROJECT_ID",
139
+ "INVALID_THREAD_ID",
136
140
  "PROJECT_NOT_ALLOWED",
137
141
  "PROJECT_SELECTOR_DISABLED",
138
142
  "MODEL_NOT_ALLOWED",
139
143
  "FEATURE_DISABLED",
140
144
  "THREAD_NOT_FOUND",
145
+ "THREAD_OWNERSHIP_CONFLICT",
141
146
  "STREAM_CONFLICT",
142
147
  "STREAM_FAILED",
143
148
  "RUN_CANCEL_UNAVAILABLE",
144
149
  "RUN_CANCEL_STORE_UNAVAILABLE",
150
+ "PROJECT_PROVISION_FAILED",
145
151
  "INVALID_REQUEST",
146
152
  "INTERNAL_ERROR",
147
153
  ] as const satisfies readonly AgentWebAppErrorCode[];
@@ -172,6 +178,7 @@ const features = {
172
178
  attachments: true,
173
179
  hitl: true,
174
180
  genUI: true,
181
+ dynamicProjects: true,
175
182
  } satisfies CreateAgentWebAppInput["features"];
176
183
 
177
184
  const quickPrompt: AgentWebAppQuickPrompt = {
@@ -304,15 +311,19 @@ describe("Agent Web App protocol types", () => {
304
311
  "WEB_APP_DISABLED",
305
312
  "USER_ID_REQUIRED",
306
313
  "INVALID_USER_ID",
314
+ "INVALID_PROJECT_ID",
315
+ "INVALID_THREAD_ID",
307
316
  "PROJECT_NOT_ALLOWED",
308
317
  "PROJECT_SELECTOR_DISABLED",
309
318
  "MODEL_NOT_ALLOWED",
310
319
  "FEATURE_DISABLED",
311
320
  "THREAD_NOT_FOUND",
321
+ "THREAD_OWNERSHIP_CONFLICT",
312
322
  "STREAM_CONFLICT",
313
323
  "STREAM_FAILED",
314
324
  "RUN_CANCEL_UNAVAILABLE",
315
325
  "RUN_CANCEL_STORE_UNAVAILABLE",
326
+ "PROJECT_PROVISION_FAILED",
316
327
  "INVALID_REQUEST",
317
328
  "INTERNAL_ERROR",
318
329
  ]);
package/src/index.ts CHANGED
@@ -18,6 +18,7 @@ export * from "./VectorStoreLatticeProtocol";
18
18
  export * from "./LoggerLatticeProtocol";
19
19
  export * from "./MessageProtocol";
20
20
  export * from "./AgentInterruptProtocol";
21
+ export * from "./ThreadStatusProtocol";
21
22
  export * from "./ThreadStoreProtocol";
22
23
  export * from "./AssistantStoreProtocol";
23
24
  export * from "./SkillLatticeProtocol";