@band-ai/sdk 0.3.4 → 0.4.1

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.
Files changed (97) hide show
  1. package/README.md +54 -1
  2. package/dist/{ClaudeSDKAdapter-CXud2DBE.d.ts → CopilotACPAdapter-B_AVyAl6.d.ts} +249 -19
  3. package/dist/{ClaudeSDKAdapter-Cx6zhSaG.d.cts → CopilotACPAdapter-Clid9xGR.d.cts} +249 -19
  4. package/dist/{opencode-2YdscIc1.d.cts → acp-client-D-I_5lK-.d.cts} +23 -4
  5. package/dist/{opencode-Bld62x5t.d.ts → acp-client-DUXyczlF.d.ts} +23 -4
  6. package/dist/acp-server-BlcYMxKt.d.ts +17 -0
  7. package/dist/acp-server-CJhclo6P.d.cts +17 -0
  8. package/dist/adapters.cjs +2257 -969
  9. package/dist/adapters.d.cts +21 -132
  10. package/dist/adapters.d.ts +21 -132
  11. package/dist/adapters.js +26 -1922
  12. package/dist/{backends-D-dBdDm-.d.ts → backends-CgsPQa9B.d.ts} +2 -2
  13. package/dist/{backends-ZLxmQrTZ.d.cts → backends-Dh2WXcHQ.d.cts} +2 -2
  14. package/dist/{chunk-JY75VSQK.js → chunk-4OVNFDD7.js} +14 -1
  15. package/dist/chunk-6BE2EG5P.js +128 -0
  16. package/dist/{chunk-U6AFCLYZ.js → chunk-6TGXV5TE.js} +1824 -514
  17. package/dist/{chunk-OH6VVVKT.js → chunk-CBCHTTUY.js} +10 -0
  18. package/dist/{chunk-K5KAEYPF.js → chunk-HNWZZXAE.js} +288 -120
  19. package/dist/chunk-I34SXMTJ.js +6 -0
  20. package/dist/{chunk-XWHWJP4I.js → chunk-JDW5WSGF.js} +2 -2
  21. package/dist/{chunk-KXJ74J73.js → chunk-JIZE4EC6.js} +4 -10
  22. package/dist/chunk-OGOXY43L.js +119 -0
  23. package/dist/{chunk-W5IAI6Z4.js → chunk-OVXVZUPO.js} +5 -5
  24. package/dist/{chunk-YJ42AZO4.js → chunk-RJNJUISR.js} +5 -2
  25. package/dist/{chunk-MQY74R7D.js → chunk-SHZBLLDQ.js} +21 -9
  26. package/dist/{chunk-JADCAMZY.js → chunk-TGDDFBYS.js} +45 -0
  27. package/dist/{chunk-US226AS4.js → chunk-UENIC5FJ.js} +14 -11
  28. package/dist/{chunk-MQBBWYRP.js → chunk-UFO6XMCV.js} +3404 -572
  29. package/dist/{chunk-WA7CHXUS.js → chunk-UL3Y5C4J.js} +2 -2
  30. package/dist/{chunk-WL2HNJZ6.js → chunk-VOMJRQOM.js} +3 -3
  31. package/dist/{chunk-OD2G5LFQ.js → chunk-ZYOXI4JL.js} +41 -2
  32. package/dist/config.cjs +2 -12
  33. package/dist/config.js +2 -2
  34. package/dist/converters.cjs +36 -11
  35. package/dist/converters.d.cts +7 -5
  36. package/dist/converters.d.ts +7 -5
  37. package/dist/converters.js +11 -13
  38. package/dist/core.cjs +239 -5
  39. package/dist/core.d.cts +71 -6
  40. package/dist/core.d.ts +71 -6
  41. package/dist/core.js +31 -6
  42. package/dist/{customTools-BzF0IISO.d.cts → customTools-Bfecd0mJ.d.cts} +1 -1
  43. package/dist/{customTools-BzF0IISO.d.ts → customTools-Bfecd0mJ.d.ts} +1 -1
  44. package/dist/{disconnectReason-IuADl6TH.d.ts → disconnectReason-Cctmg1SN.d.cts} +1 -1
  45. package/dist/{disconnectReason-IuADl6TH.d.cts → disconnectReason-Cctmg1SN.d.ts} +1 -1
  46. package/dist/{dtos-B8KU_q4d.d.ts → dtos-CjQsN1_h.d.cts} +5 -12
  47. package/dist/{dtos-B8KU_q4d.d.cts → dtos-CjQsN1_h.d.ts} +5 -12
  48. package/dist/index.cjs +5289 -1474
  49. package/dist/index.d.cts +61 -22
  50. package/dist/index.d.ts +61 -22
  51. package/dist/index.js +151 -43
  52. package/dist/linear.cjs +45 -7
  53. package/dist/linear.d.cts +4 -3
  54. package/dist/linear.d.ts +4 -3
  55. package/dist/linear.js +10 -10
  56. package/dist/mcp-claude.cjs +11 -6
  57. package/dist/mcp-claude.d.cts +4 -3
  58. package/dist/mcp-claude.d.ts +4 -3
  59. package/dist/mcp-claude.js +4 -5
  60. package/dist/mcp.cjs +13 -7
  61. package/dist/mcp.d.cts +6 -5
  62. package/dist/mcp.d.ts +6 -5
  63. package/dist/mcp.js +5 -6
  64. package/dist/{pagination-DqdkQArT.d.cts → pagination-BZDhB_nO.d.cts} +2 -2
  65. package/dist/{pagination-BgEx-HeL.d.ts → pagination-CPz0J_vQ.d.ts} +2 -2
  66. package/dist/{protocols-Bz1rxcUg.d.cts → protocols-CabgO52c.d.cts} +38 -3
  67. package/dist/{protocols-Bwwcql0h.d.ts → protocols-Dpci6uae.d.ts} +38 -3
  68. package/dist/rest.cjs +43 -1
  69. package/dist/rest.d.cts +6 -5
  70. package/dist/rest.d.ts +6 -5
  71. package/dist/rest.js +6 -5
  72. package/dist/runtime.cjs +2113 -597
  73. package/dist/runtime.d.cts +44 -25
  74. package/dist/runtime.d.ts +44 -25
  75. package/dist/runtime.js +11 -11
  76. package/dist/{schemas-BgJhlqqO.d.cts → schemas-BKnh4fKR.d.cts} +209 -24
  77. package/dist/{schemas-C4mK1WSs.d.ts → schemas-CDa3V_I5.d.ts} +209 -24
  78. package/dist/{sdk-BTciSLRQ.d.cts → sdk-CXNqzoY1.d.cts} +1 -1
  79. package/dist/{sdk-qKJtMma_.d.ts → sdk-Cin80BTC.d.ts} +1 -1
  80. package/dist/{simpleAdapter-BpT4XbZC.d.cts → simpleAdapter-D75rcz9n.d.cts} +3 -1
  81. package/dist/{simpleAdapter--wznuoOw.d.ts → simpleAdapter-eLvsAQNo.d.ts} +3 -1
  82. package/dist/testing.cjs +25 -7
  83. package/dist/testing.d.cts +5 -3
  84. package/dist/testing.d.ts +5 -3
  85. package/dist/testing.js +9 -6
  86. package/dist/{types-BivGO7I9.d.ts → types-42-HWeX8.d.cts} +10 -4
  87. package/dist/types-CKU1N0SK.d.ts +137 -0
  88. package/dist/{types-BgYFd_Yw.d.cts → types-CjxZekMH.d.ts} +10 -4
  89. package/dist/types-DtcOLALn.d.cts +137 -0
  90. package/package.json +25 -26
  91. package/dist/acp-server-CiUqN3G3.d.ts +0 -24
  92. package/dist/acp-server-Dlj7D563.d.cts +0 -24
  93. package/dist/chunk-AVVDPXP4.js +0 -39
  94. package/dist/chunk-F63TPOI3.js +0 -29
  95. package/dist/chunk-V5TSWS7P.js +0 -62
  96. package/dist/types-BNNtOXu3.d.cts +0 -446
  97. package/dist/types-DFUtpxah.d.ts +0 -446
package/dist/core.cjs CHANGED
@@ -20,15 +20,25 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
20
20
  // src/core/index.ts
21
21
  var core_exports = {};
22
22
  __export(core_exports, {
23
+ AgentFailure: () => import_band_sdk_core3.AgentFailure,
23
24
  BandSdkError: () => BandSdkError,
24
25
  ConsoleLogger: () => ConsoleLogger,
26
+ DeliveryFailedError: () => DeliveryFailedError,
27
+ FAILURE_EVENT_TYPE: () => FAILURE_EVENT_TYPE,
28
+ FAILURE_METADATA_KEY: () => FAILURE_METADATA_KEY,
25
29
  NoopLogger: () => NoopLogger,
30
+ ProviderTurnFailedError: () => ProviderTurnFailedError,
31
+ RecoverableTurnError: () => RecoverableTurnError,
26
32
  RuntimeStateError: () => RuntimeStateError,
27
33
  SimpleAdapter: () => SimpleAdapter,
28
34
  TransportError: () => TransportError,
29
35
  UnsupportedFeatureError: () => UnsupportedFeatureError,
30
36
  ValidationError: () => ValidationError,
31
- WebSocketDisconnectError: () => WebSocketDisconnectError
37
+ WebSocketDisconnectError: () => WebSocketDisconnectError,
38
+ agentFailure: () => agentFailure,
39
+ deliverReply: () => deliverReply,
40
+ reportTurnFailure: () => reportTurnFailure,
41
+ toFailureEvent: () => toFailureEvent
32
42
  });
33
43
  module.exports = __toCommonJS(core_exports);
34
44
 
@@ -68,6 +78,9 @@ var SimpleAdapter = class {
68
78
  }
69
79
  };
70
80
 
81
+ // src/core/index.ts
82
+ var import_band_sdk_core3 = require("@band-ai/band-sdk-core");
83
+
71
84
  // src/core/errors.ts
72
85
  var BandSdkError = class extends Error {
73
86
  constructor(message, cause) {
@@ -99,9 +112,36 @@ var RuntimeStateError = class extends BandSdkError {
99
112
  this.name = "RuntimeStateError";
100
113
  }
101
114
  };
115
+ var RecoverableTurnError = class extends BandSdkError {
116
+ constructor(message, cause) {
117
+ super(message, cause);
118
+ this.name = "RecoverableTurnError";
119
+ }
120
+ };
121
+
122
+ // src/contracts/chatEvents.ts
123
+ var CHAT_EVENT_TYPES = ["tool_call", "tool_result", "thought", "error", "task"];
124
+ var CHAT_MESSAGE_TYPES = ["text", ...CHAT_EVENT_TYPES];
125
+ var VISIBLE_CONTENT_PATTERN = /[\p{L}\p{N}\p{P}\p{S}]/u;
126
+ function isBlankEventContent(content) {
127
+ return !VISIBLE_CONTENT_PATTERN.test(content);
128
+ }
129
+
130
+ // src/contracts/protocols.ts
131
+ var FAILURE_EVENT_TYPE = "error";
132
+ var FAILURE_METADATA_KEY = "failure";
133
+ function toFailureEvent(failure) {
134
+ const content = isBlankEventContent(failure.message) ? `${failure.provider} failed without an error message.` : failure.message;
135
+ return {
136
+ content,
137
+ messageType: FAILURE_EVENT_TYPE,
138
+ metadata: { [FAILURE_METADATA_KEY]: failure.toObject() }
139
+ };
140
+ }
102
141
 
103
142
  // src/platform/streaming/disconnectReason.ts
104
143
  var import_zod = require("zod");
144
+ var import_band_sdk_core = require("@band-ai/band-sdk-core");
105
145
  var UPGRADE_CODES = [
106
146
  "invalid_on_conflict",
107
147
  "connection_conflict",
@@ -130,7 +170,7 @@ var upgradeErrorSchema = import_zod.z.object({
130
170
  })
131
171
  })
132
172
  ),
133
- headers: import_zod.z.record(import_zod.z.unknown()).optional()
173
+ headers: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
134
174
  });
135
175
  var WebSocketDisconnectError = class extends Error {
136
176
  reason;
@@ -141,11 +181,15 @@ var WebSocketDisconnectError = class extends Error {
141
181
  }
142
182
  };
143
183
 
184
+ // src/core/sensitiveTerms.ts
185
+ var SENSITIVE_KEY_TERMS = "authorization|api[-_ ]?key|token|secret|password|cookie";
186
+ var GATEWAY_FREE_TEXT_SENSITIVE_KEY_TERMS = `${SENSITIVE_KEY_TERMS}|session`;
187
+
144
188
  // src/core/logger.ts
145
189
  var noop = () => void 0;
146
190
  var REDACTED_VALUE = "[REDACTED]";
147
191
  var CIRCULAR_VALUE = "[Circular]";
148
- var SENSITIVE_KEY_PATTERN = /(authorization|api[-_]?key|token|secret|password|cookie)/i;
192
+ var SENSITIVE_KEY_PATTERN = new RegExp(`(${SENSITIVE_KEY_TERMS})`, "i");
149
193
  var NoopLogger = class {
150
194
  debug = noop;
151
195
  info = noop;
@@ -168,7 +212,7 @@ var ConsoleLogger = class {
168
212
  `);
169
213
  }
170
214
  emit(level, message, context) {
171
- const fn = console[level];
215
+ const fn = console[level].bind(console);
172
216
  if (context === void 0) {
173
217
  fn(message);
174
218
  return;
@@ -214,15 +258,205 @@ function sanitizeValue(value, seen = /* @__PURE__ */ new WeakSet()) {
214
258
  }
215
259
  return sanitized;
216
260
  }
261
+
262
+ // src/core/coercion.ts
263
+ var MAX_ERROR_CAUSE_DEPTH = 5;
264
+ var MAX_ERROR_DETAIL_LENGTH = 500;
265
+ var LENGTH_TRUNCATED_MARKER = "... (truncated)";
266
+ var DEPTH_TRUNCATED_MARKER = "... (cause chain truncated)";
267
+ function asOptionalRecord(value) {
268
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
269
+ return void 0;
270
+ }
271
+ return value;
272
+ }
273
+ function asNonEmptyString(value) {
274
+ if (typeof value !== "string") {
275
+ return null;
276
+ }
277
+ const trimmed = value.trim();
278
+ return trimmed.length > 0 ? trimmed : null;
279
+ }
280
+ function toDisplayText(value) {
281
+ if (typeof value === "string") {
282
+ return value;
283
+ }
284
+ if (value == null) {
285
+ return "";
286
+ }
287
+ try {
288
+ const json = JSON.stringify(value);
289
+ return typeof json === "string" ? json : String(value);
290
+ } catch {
291
+ return String(value);
292
+ }
293
+ }
294
+ function asErrorMessage(error) {
295
+ return formatCaughtError(error, 0);
296
+ }
297
+ function formatCaughtError(error, depth) {
298
+ if (typeof error !== "object" || error === null) {
299
+ return truncate(String(error));
300
+ }
301
+ const message = truncate(asNestedMessage(error) ?? String(error));
302
+ const detail = selectDetail(asOptionalRecord(error));
303
+ if (detail === void 0) {
304
+ return message;
305
+ }
306
+ if (depth >= MAX_ERROR_CAUSE_DEPTH) {
307
+ return `${message} (${DEPTH_TRUNCATED_MARKER})`;
308
+ }
309
+ return `${message} (${formatErrorDetail(detail, depth + 1)})`;
310
+ }
311
+ function selectDetail(record) {
312
+ if (isPresentDetail(record?.data)) {
313
+ return record?.data;
314
+ }
315
+ if (isPresentDetail(record?.cause)) {
316
+ return record?.cause;
317
+ }
318
+ return void 0;
319
+ }
320
+ function isPresentDetail(value) {
321
+ if (value === void 0 || value === null) {
322
+ return false;
323
+ }
324
+ if (typeof value === "string") {
325
+ return asNonEmptyString(value) !== null;
326
+ }
327
+ if (value instanceof Error) {
328
+ return true;
329
+ }
330
+ if (Array.isArray(value)) {
331
+ return value.length > 0;
332
+ }
333
+ if (typeof value === "object") {
334
+ return isPlainObject(value) ? Object.keys(value).length > 0 : true;
335
+ }
336
+ return true;
337
+ }
338
+ function isPlainObject(value) {
339
+ const proto = Object.getPrototypeOf(value);
340
+ return proto === Object.prototype || proto === null;
341
+ }
342
+ function formatErrorDetail(detail, depth) {
343
+ if (detail instanceof Error || selectDetail(asOptionalRecord(detail)) !== void 0) {
344
+ return formatCaughtError(detail, depth);
345
+ }
346
+ return truncate(formatLeafDetail(detail));
347
+ }
348
+ function formatLeafDetail(detail) {
349
+ if (typeof detail === "string") {
350
+ return detail;
351
+ }
352
+ if (typeof detail === "number" && !Number.isFinite(detail)) {
353
+ return String(detail);
354
+ }
355
+ const builtin = formatNonEnumerableDetail(detail);
356
+ if (builtin !== null) {
357
+ return builtin;
358
+ }
359
+ const nested = asNestedMessage(detail);
360
+ if (nested !== null) {
361
+ return nested;
362
+ }
363
+ return toDisplayText(detail);
364
+ }
365
+ function formatNonEnumerableDetail(detail) {
366
+ if (detail instanceof RegExp) {
367
+ return detail.toString();
368
+ }
369
+ if (detail instanceof Map) {
370
+ return `Map ${toDisplayText([...detail])}`;
371
+ }
372
+ if (detail instanceof Set) {
373
+ return `Set ${toDisplayText([...detail])}`;
374
+ }
375
+ return null;
376
+ }
377
+ function truncate(text) {
378
+ return text.length > MAX_ERROR_DETAIL_LENGTH ? `${text.slice(0, MAX_ERROR_DETAIL_LENGTH)}${LENGTH_TRUNCATED_MARKER}` : text;
379
+ }
380
+ function asNestedMessage(value) {
381
+ const record = asOptionalRecord(value);
382
+ return asNonEmptyString(record?.message);
383
+ }
384
+
385
+ // src/core/deliveryFailedError.ts
386
+ var DeliveryFailedError = class extends RecoverableTurnError {
387
+ constructor(cause) {
388
+ super(asErrorMessage(cause), cause);
389
+ this.cause = cause;
390
+ this.name = "DeliveryFailedError";
391
+ }
392
+ };
393
+ async function deliverReply(tools, content, mentions = []) {
394
+ try {
395
+ return await tools.sendMessage(content, mentions);
396
+ } catch (error) {
397
+ throw new DeliveryFailedError(error);
398
+ }
399
+ }
400
+
401
+ // src/core/providerFailure.ts
402
+ var import_band_sdk_core2 = require("@band-ai/band-sdk-core");
403
+ var ProviderTurnFailedError = class extends RecoverableTurnError {
404
+ constructor(failure) {
405
+ super(failure.message);
406
+ this.failure = failure;
407
+ this.name = "ProviderTurnFailedError";
408
+ }
409
+ };
410
+ async function trySendFailure(tools, failure, logger, logContext) {
411
+ logger?.warn("provider_failure.reported", {
412
+ provider: failure.provider,
413
+ code: failure.code,
414
+ ...logContext
415
+ });
416
+ try {
417
+ await tools.sendFailure(failure);
418
+ } catch (error) {
419
+ logger?.warn("provider_failure.report_failed", {
420
+ provider: failure.provider,
421
+ code: failure.code,
422
+ ...logContext,
423
+ error
424
+ });
425
+ }
426
+ }
427
+ async function reportTurnFailure(tools, failure, logger, logContext) {
428
+ await trySendFailure(tools, failure, logger, logContext);
429
+ throw new ProviderTurnFailedError(failure);
430
+ }
431
+ function agentFailure(provider, message, code, detail) {
432
+ if (detail === void 0) {
433
+ return new import_band_sdk_core2.AgentFailure(provider, message, code);
434
+ }
435
+ try {
436
+ return new import_band_sdk_core2.AgentFailure(provider, message, code, detail);
437
+ } catch {
438
+ return new import_band_sdk_core2.AgentFailure(provider, message, code);
439
+ }
440
+ }
217
441
  // Annotate the CommonJS export names for ESM import in node:
218
442
  0 && (module.exports = {
443
+ AgentFailure,
219
444
  BandSdkError,
220
445
  ConsoleLogger,
446
+ DeliveryFailedError,
447
+ FAILURE_EVENT_TYPE,
448
+ FAILURE_METADATA_KEY,
221
449
  NoopLogger,
450
+ ProviderTurnFailedError,
451
+ RecoverableTurnError,
222
452
  RuntimeStateError,
223
453
  SimpleAdapter,
224
454
  TransportError,
225
455
  UnsupportedFeatureError,
226
456
  ValidationError,
227
- WebSocketDisconnectError
457
+ WebSocketDisconnectError,
458
+ agentFailure,
459
+ deliverReply,
460
+ reportTurnFailure,
461
+ toFailureEvent
228
462
  });
package/dist/core.d.cts CHANGED
@@ -1,8 +1,12 @@
1
- export { S as SimpleAdapter } from './simpleAdapter-BpT4XbZC.cjs';
2
- export { A as AdapterToolsProtocol, a as AgentToolsProtocol, C as ContactTools, F as FrameworkAdapter, b as FrameworkAdapterInput, H as HistoryConverter, M as MemoryTools, c as MessagingTools, P as ParticipantTools, d as PeerLookupTools, e as Preprocessor, R as RoomParticipantTools, T as ToolExecutor, f as ToolSchemaProvider } from './protocols-Bz1rxcUg.cjs';
3
- export { W as WebSocketConflictPolicy, a as WebSocketDisconnectError, b as WebSocketDisconnectReason } from './disconnectReason-IuADl6TH.cjs';
4
- export { C as ConsoleLogger, L as Logger, N as NoopLogger } from './logger-CABQOnlR.cjs';
5
- import './dtos-B8KU_q4d.cjs';
1
+ export { S as SimpleAdapter } from './simpleAdapter-D75rcz9n.cjs';
2
+ import { AgentFailure } from '@band-ai/band-sdk-core';
3
+ export { AgentFailure } from '@band-ai/band-sdk-core';
4
+ import { e as MessagingTools } from './protocols-CabgO52c.cjs';
5
+ export { A as AdapterToolsProtocol, b as AgentToolsProtocol, C as ContactTools, c as FAILURE_EVENT_TYPE, d as FAILURE_METADATA_KEY, F as FrameworkAdapter, a as FrameworkAdapterInput, H as HistoryConverter, M as MemoryTools, f as ParticipantTools, g as PeerLookupTools, h as Preprocessor, R as RoomParticipantTools, T as ToolExecutor, i as ToolSchemaProvider, t as toFailureEvent } from './protocols-CabgO52c.cjs';
6
+ export { W as WebSocketConflictPolicy, a as WebSocketDisconnectError, b as WebSocketDisconnectReason } from './disconnectReason-Cctmg1SN.cjs';
7
+ import { L as Logger } from './logger-CABQOnlR.cjs';
8
+ export { C as ConsoleLogger, N as NoopLogger } from './logger-CABQOnlR.cjs';
9
+ import { h as MentionInput, T as ToolOperationResult } from './dtos-CjQsN1_h.cjs';
6
10
 
7
11
  declare class BandSdkError extends Error {
8
12
  constructor(message: string, cause?: unknown);
@@ -19,5 +23,66 @@ declare class TransportError extends BandSdkError {
19
23
  declare class RuntimeStateError extends BandSdkError {
20
24
  constructor(message: string);
21
25
  }
26
+ /**
27
+ * A failure confined to the turn that raised it. `Execution` keeps the room's
28
+ * loop — and every other room — running for these, where any other error
29
+ * stops the whole runtime.
30
+ *
31
+ * The turn still fails: `PlatformRuntime` has already marked the message
32
+ * failed by the time one of these reaches the queue. What it must not do is
33
+ * take the agent down with it, which is the right response to a broken
34
+ * adapter and the wrong one to a single reply that could not be posted.
35
+ */
36
+ declare class RecoverableTurnError extends BandSdkError {
37
+ constructor(message: string, cause?: unknown);
38
+ }
39
+
40
+ /**
41
+ * Marks a rejection as coming from delivering an already-decided reply, not
42
+ * from the provider itself.
43
+ *
44
+ * `RecoverableTurnError`, because failing to post one reply is a failure of
45
+ * that turn and nothing more: the runtime marks the message failed and keeps
46
+ * every room serving. Reporting it as an `AgentFailure` would blame the
47
+ * provider for a Band-side fault; taking the runtime down would answer a
48
+ * transient post failure with an outage.
49
+ */
50
+ declare class DeliveryFailedError extends RecoverableTurnError {
51
+ readonly cause: unknown;
52
+ constructor(cause: unknown);
53
+ }
54
+ declare function deliverReply(tools: MessagingTools, content: string, mentions?: MentionInput): Promise<ToolOperationResult>;
55
+
56
+ /**
57
+ * A provider failure that has already been reported to the room.
58
+ *
59
+ * Thrown, not returned, so the turn still *fails*: `PlatformRuntime` marks a
60
+ * message failed only when `onEvent` throws, and the platform re-syncs failed
61
+ * messages rather than processed ones. Returning here would flip a failed turn
62
+ * to `processed` and drop its retry along with it.
63
+ *
64
+ * `RecoverableTurnError` is what changes: the turn fails, the room and every
65
+ * other room keep running. Reporting a provider error must not take the agent
66
+ * down, which is what an ordinary throw from here used to do.
67
+ */
68
+ declare class ProviderTurnFailedError extends RecoverableTurnError {
69
+ readonly failure: AgentFailure;
70
+ constructor(failure: AgentFailure);
71
+ }
72
+ /**
73
+ * Reports a terminal provider failure, then fails the turn that hit it.
74
+ */
75
+ declare function reportTurnFailure(tools: MessagingTools, failure: AgentFailure, logger?: Logger, logContext?: Record<string, unknown>): Promise<never>;
76
+ /**
77
+ * Builds an `AgentFailure` whose `detail` cannot make the constructor throw.
78
+ *
79
+ * `detail` carries raw provider payloads — an HTTP body, an RPC error object —
80
+ * and the constructor rejects anything it cannot serialize: a `Buffer`, a
81
+ * function-valued property, a cycle. It is built on failure paths, often as an
82
+ * argument outside the enclosing guard, where a throw would replace the very
83
+ * failure being reported. An unusable detail is dropped instead; the provider,
84
+ * message and code are typed as strings, so only `detail` can be exotic.
85
+ */
86
+ declare function agentFailure(provider: string, message: string, code?: string, detail?: unknown): AgentFailure;
22
87
 
23
- export { BandSdkError, RuntimeStateError, TransportError, UnsupportedFeatureError, ValidationError };
88
+ export { BandSdkError, DeliveryFailedError, Logger, MessagingTools, ProviderTurnFailedError, RecoverableTurnError, RuntimeStateError, TransportError, UnsupportedFeatureError, ValidationError, agentFailure, deliverReply, reportTurnFailure };
package/dist/core.d.ts CHANGED
@@ -1,8 +1,12 @@
1
- export { S as SimpleAdapter } from './simpleAdapter--wznuoOw.js';
2
- export { A as AdapterToolsProtocol, a as AgentToolsProtocol, C as ContactTools, F as FrameworkAdapter, b as FrameworkAdapterInput, H as HistoryConverter, M as MemoryTools, c as MessagingTools, P as ParticipantTools, d as PeerLookupTools, e as Preprocessor, R as RoomParticipantTools, T as ToolExecutor, f as ToolSchemaProvider } from './protocols-Bwwcql0h.js';
3
- export { W as WebSocketConflictPolicy, a as WebSocketDisconnectError, b as WebSocketDisconnectReason } from './disconnectReason-IuADl6TH.js';
4
- export { C as ConsoleLogger, L as Logger, N as NoopLogger } from './logger-CABQOnlR.js';
5
- import './dtos-B8KU_q4d.js';
1
+ export { S as SimpleAdapter } from './simpleAdapter-eLvsAQNo.js';
2
+ import { AgentFailure } from '@band-ai/band-sdk-core';
3
+ export { AgentFailure } from '@band-ai/band-sdk-core';
4
+ import { e as MessagingTools } from './protocols-Dpci6uae.js';
5
+ export { A as AdapterToolsProtocol, b as AgentToolsProtocol, C as ContactTools, c as FAILURE_EVENT_TYPE, d as FAILURE_METADATA_KEY, F as FrameworkAdapter, a as FrameworkAdapterInput, H as HistoryConverter, M as MemoryTools, f as ParticipantTools, g as PeerLookupTools, h as Preprocessor, R as RoomParticipantTools, T as ToolExecutor, i as ToolSchemaProvider, t as toFailureEvent } from './protocols-Dpci6uae.js';
6
+ export { W as WebSocketConflictPolicy, a as WebSocketDisconnectError, b as WebSocketDisconnectReason } from './disconnectReason-Cctmg1SN.js';
7
+ import { L as Logger } from './logger-CABQOnlR.js';
8
+ export { C as ConsoleLogger, N as NoopLogger } from './logger-CABQOnlR.js';
9
+ import { h as MentionInput, T as ToolOperationResult } from './dtos-CjQsN1_h.js';
6
10
 
7
11
  declare class BandSdkError extends Error {
8
12
  constructor(message: string, cause?: unknown);
@@ -19,5 +23,66 @@ declare class TransportError extends BandSdkError {
19
23
  declare class RuntimeStateError extends BandSdkError {
20
24
  constructor(message: string);
21
25
  }
26
+ /**
27
+ * A failure confined to the turn that raised it. `Execution` keeps the room's
28
+ * loop — and every other room — running for these, where any other error
29
+ * stops the whole runtime.
30
+ *
31
+ * The turn still fails: `PlatformRuntime` has already marked the message
32
+ * failed by the time one of these reaches the queue. What it must not do is
33
+ * take the agent down with it, which is the right response to a broken
34
+ * adapter and the wrong one to a single reply that could not be posted.
35
+ */
36
+ declare class RecoverableTurnError extends BandSdkError {
37
+ constructor(message: string, cause?: unknown);
38
+ }
39
+
40
+ /**
41
+ * Marks a rejection as coming from delivering an already-decided reply, not
42
+ * from the provider itself.
43
+ *
44
+ * `RecoverableTurnError`, because failing to post one reply is a failure of
45
+ * that turn and nothing more: the runtime marks the message failed and keeps
46
+ * every room serving. Reporting it as an `AgentFailure` would blame the
47
+ * provider for a Band-side fault; taking the runtime down would answer a
48
+ * transient post failure with an outage.
49
+ */
50
+ declare class DeliveryFailedError extends RecoverableTurnError {
51
+ readonly cause: unknown;
52
+ constructor(cause: unknown);
53
+ }
54
+ declare function deliverReply(tools: MessagingTools, content: string, mentions?: MentionInput): Promise<ToolOperationResult>;
55
+
56
+ /**
57
+ * A provider failure that has already been reported to the room.
58
+ *
59
+ * Thrown, not returned, so the turn still *fails*: `PlatformRuntime` marks a
60
+ * message failed only when `onEvent` throws, and the platform re-syncs failed
61
+ * messages rather than processed ones. Returning here would flip a failed turn
62
+ * to `processed` and drop its retry along with it.
63
+ *
64
+ * `RecoverableTurnError` is what changes: the turn fails, the room and every
65
+ * other room keep running. Reporting a provider error must not take the agent
66
+ * down, which is what an ordinary throw from here used to do.
67
+ */
68
+ declare class ProviderTurnFailedError extends RecoverableTurnError {
69
+ readonly failure: AgentFailure;
70
+ constructor(failure: AgentFailure);
71
+ }
72
+ /**
73
+ * Reports a terminal provider failure, then fails the turn that hit it.
74
+ */
75
+ declare function reportTurnFailure(tools: MessagingTools, failure: AgentFailure, logger?: Logger, logContext?: Record<string, unknown>): Promise<never>;
76
+ /**
77
+ * Builds an `AgentFailure` whose `detail` cannot make the constructor throw.
78
+ *
79
+ * `detail` carries raw provider payloads — an HTTP body, an RPC error object —
80
+ * and the constructor rejects anything it cannot serialize: a `Buffer`, a
81
+ * function-valued property, a cycle. It is built on failure paths, often as an
82
+ * argument outside the enclosing guard, where a throw would replace the very
83
+ * failure being reported. An unusable detail is dropped instead; the provider,
84
+ * message and code are typed as strings, so only `detail` can be exotic.
85
+ */
86
+ declare function agentFailure(provider: string, message: string, code?: string, detail?: unknown): AgentFailure;
22
87
 
23
- export { BandSdkError, RuntimeStateError, TransportError, UnsupportedFeatureError, ValidationError };
88
+ export { BandSdkError, DeliveryFailedError, Logger, MessagingTools, ProviderTurnFailedError, RecoverableTurnError, RuntimeStateError, TransportError, UnsupportedFeatureError, ValidationError, agentFailure, deliverReply, reportTurnFailure };
package/dist/core.js CHANGED
@@ -1,28 +1,53 @@
1
1
  import {
2
- SimpleAdapter
3
- } from "./chunk-AVVDPXP4.js";
2
+ AgentFailure
3
+ } from "./chunk-I34SXMTJ.js";
4
+ import {
5
+ DeliveryFailedError,
6
+ ProviderTurnFailedError,
7
+ SimpleAdapter,
8
+ agentFailure,
9
+ deliverReply,
10
+ reportTurnFailure
11
+ } from "./chunk-OGOXY43L.js";
4
12
  import {
5
13
  WebSocketDisconnectError
6
- } from "./chunk-US226AS4.js";
14
+ } from "./chunk-UENIC5FJ.js";
15
+ import "./chunk-6BE2EG5P.js";
16
+ import {
17
+ FAILURE_EVENT_TYPE,
18
+ FAILURE_METADATA_KEY,
19
+ toFailureEvent
20
+ } from "./chunk-TGDDFBYS.js";
7
21
  import {
8
22
  ConsoleLogger,
9
23
  NoopLogger
10
- } from "./chunk-OD2G5LFQ.js";
24
+ } from "./chunk-ZYOXI4JL.js";
11
25
  import {
12
26
  BandSdkError,
27
+ RecoverableTurnError,
13
28
  RuntimeStateError,
14
29
  TransportError,
15
30
  UnsupportedFeatureError,
16
31
  ValidationError
17
- } from "./chunk-JY75VSQK.js";
32
+ } from "./chunk-4OVNFDD7.js";
18
33
  export {
34
+ AgentFailure,
19
35
  BandSdkError,
20
36
  ConsoleLogger,
37
+ DeliveryFailedError,
38
+ FAILURE_EVENT_TYPE,
39
+ FAILURE_METADATA_KEY,
21
40
  NoopLogger,
41
+ ProviderTurnFailedError,
42
+ RecoverableTurnError,
22
43
  RuntimeStateError,
23
44
  SimpleAdapter,
24
45
  TransportError,
25
46
  UnsupportedFeatureError,
26
47
  ValidationError,
27
- WebSocketDisconnectError
48
+ WebSocketDisconnectError,
49
+ agentFailure,
50
+ deliverReply,
51
+ reportTurnFailure,
52
+ toFailureEvent
28
53
  };
@@ -1,7 +1,7 @@
1
1
  import { z } from 'zod';
2
2
 
3
3
  interface CustomToolDef {
4
- schema: z.AnyZodObject;
4
+ schema: z.ZodObject;
5
5
  handler: (args: Record<string, unknown>) => unknown;
6
6
  name: string;
7
7
  description?: string;
@@ -1,7 +1,7 @@
1
1
  import { z } from 'zod';
2
2
 
3
3
  interface CustomToolDef {
4
- schema: z.AnyZodObject;
4
+ schema: z.ZodObject;
5
5
  handler: (args: Record<string, unknown>) => unknown;
6
6
  name: string;
7
7
  description?: string;
@@ -3,7 +3,7 @@ interface AgentControlSupersedeDisconnectReason {
3
3
  source: "agent_control";
4
4
  code: string;
5
5
  message: string;
6
- retryable: false;
6
+ retryable: boolean;
7
7
  retryAfter: number | null;
8
8
  targetSocketId: string | null;
9
9
  correlationId: string | null;
@@ -3,7 +3,7 @@ interface AgentControlSupersedeDisconnectReason {
3
3
  source: "agent_control";
4
4
  code: string;
5
5
  message: string;
6
- retryable: false;
6
+ retryable: boolean;
7
7
  retryAfter: number | null;
8
8
  targetSocketId: string | null;
9
9
  correlationId: string | null;
@@ -1,18 +1,11 @@
1
- /** Canonical memory enums; DTOs, tool schemas, and validation derive from these constants. */
2
- /** Which memory types are valid for each memory tier. */
3
- declare const MEMORY_SYSTEM_TYPES: {
4
- readonly sensory: readonly ["iconic", "echoic", "haptic"];
5
- readonly working: readonly ["episodic", "semantic", "procedural"];
6
- readonly long_term: readonly ["episodic", "semantic", "procedural"];
7
- };
8
- type MemorySystem = keyof typeof MEMORY_SYSTEM_TYPES;
9
- type MemoryType = (typeof MEMORY_SYSTEM_TYPES)[MemorySystem][number];
1
+ import { MemorySystem, MemoryType } from '@band-ai/band-sdk-core';
2
+
10
3
  /** Logical subject category (user/agent/tool/guideline); not scope `subject` or `subject_id`. */
11
4
  declare const MEMORY_SEGMENTS: readonly ["user", "agent", "tool", "guideline"];
12
5
  /** Visibility scope for `band_store_memory`. */
13
- declare const MEMORY_STORE_SCOPES: readonly ["subject", "organization"];
6
+ declare const MEMORY_STORE_SCOPES: readonly ["agent", "subject", "organization"];
14
7
  /** Scope filter for `band_list_memories`. */
15
- declare const MEMORY_LIST_SCOPES: readonly ["subject", "organization", "all"];
8
+ declare const MEMORY_LIST_SCOPES: readonly ["agent", "subject", "organization", "all"];
16
9
  /** Lifecycle state; list filter and set by supersede/archive tools. */
17
10
  declare const MEMORY_STATUSES: readonly ["active", "superseded", "archived", "all"];
18
11
  /** Logical subject category (user/agent/tool/guideline); not scope `subject` or `subject_id`. */
@@ -180,4 +173,4 @@ interface ToolModelSchema {
180
173
  [key: string]: unknown;
181
174
  }
182
175
 
183
- export type { AddContactArgs as A, ContactRecord as C, ListContactsArgs as L, MetadataMap as M, ParticipantRecord as P, RemoveContactArgs as R, StoreMemoryArgs as S, ToolOperationResult as T, MentionInput as a, ToolSchemaRecord as b, PaginatedList as c, PeerRecord as d, ListContactRequestsArgs as e, ContactRequestsResult as f, RespondContactRequestArgs as g, ListMemoriesArgs as h, MemoryRecord as i, MentionReference as j, ContactRequestAction as k, PaginationMetadataLike as l, ToolModelMessage as m, ToolModelSchema as n };
176
+ export type { AddContactArgs as A, ContactRecord as C, ListContactsArgs as L, MetadataMap as M, PeerRecord as P, RemoveContactArgs as R, StoreMemoryArgs as S, ToolOperationResult as T, MentionReference as a, ListContactRequestsArgs as b, ContactRequestsResult as c, RespondContactRequestArgs as d, ListMemoriesArgs as e, MemoryRecord as f, ParticipantRecord as g, MentionInput as h, PaginatedList as i, ToolSchemaRecord as j, ContactRequestAction as k, PaginationMetadataLike as l, ToolModelMessage as m, ToolModelSchema as n };
@@ -1,18 +1,11 @@
1
- /** Canonical memory enums; DTOs, tool schemas, and validation derive from these constants. */
2
- /** Which memory types are valid for each memory tier. */
3
- declare const MEMORY_SYSTEM_TYPES: {
4
- readonly sensory: readonly ["iconic", "echoic", "haptic"];
5
- readonly working: readonly ["episodic", "semantic", "procedural"];
6
- readonly long_term: readonly ["episodic", "semantic", "procedural"];
7
- };
8
- type MemorySystem = keyof typeof MEMORY_SYSTEM_TYPES;
9
- type MemoryType = (typeof MEMORY_SYSTEM_TYPES)[MemorySystem][number];
1
+ import { MemorySystem, MemoryType } from '@band-ai/band-sdk-core';
2
+
10
3
  /** Logical subject category (user/agent/tool/guideline); not scope `subject` or `subject_id`. */
11
4
  declare const MEMORY_SEGMENTS: readonly ["user", "agent", "tool", "guideline"];
12
5
  /** Visibility scope for `band_store_memory`. */
13
- declare const MEMORY_STORE_SCOPES: readonly ["subject", "organization"];
6
+ declare const MEMORY_STORE_SCOPES: readonly ["agent", "subject", "organization"];
14
7
  /** Scope filter for `band_list_memories`. */
15
- declare const MEMORY_LIST_SCOPES: readonly ["subject", "organization", "all"];
8
+ declare const MEMORY_LIST_SCOPES: readonly ["agent", "subject", "organization", "all"];
16
9
  /** Lifecycle state; list filter and set by supersede/archive tools. */
17
10
  declare const MEMORY_STATUSES: readonly ["active", "superseded", "archived", "all"];
18
11
  /** Logical subject category (user/agent/tool/guideline); not scope `subject` or `subject_id`. */
@@ -180,4 +173,4 @@ interface ToolModelSchema {
180
173
  [key: string]: unknown;
181
174
  }
182
175
 
183
- export type { AddContactArgs as A, ContactRecord as C, ListContactsArgs as L, MetadataMap as M, ParticipantRecord as P, RemoveContactArgs as R, StoreMemoryArgs as S, ToolOperationResult as T, MentionInput as a, ToolSchemaRecord as b, PaginatedList as c, PeerRecord as d, ListContactRequestsArgs as e, ContactRequestsResult as f, RespondContactRequestArgs as g, ListMemoriesArgs as h, MemoryRecord as i, MentionReference as j, ContactRequestAction as k, PaginationMetadataLike as l, ToolModelMessage as m, ToolModelSchema as n };
176
+ export type { AddContactArgs as A, ContactRecord as C, ListContactsArgs as L, MetadataMap as M, PeerRecord as P, RemoveContactArgs as R, StoreMemoryArgs as S, ToolOperationResult as T, MentionReference as a, ListContactRequestsArgs as b, ContactRequestsResult as c, RespondContactRequestArgs as d, ListMemoriesArgs as e, MemoryRecord as f, ParticipantRecord as g, MentionInput as h, PaginatedList as i, ToolSchemaRecord as j, ContactRequestAction as k, PaginationMetadataLike as l, ToolModelMessage as m, ToolModelSchema as n };