@lobu/runtime-device 20.2.0 → 21.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.
Files changed (107) hide show
  1. package/dist/component.json +1 -1
  2. package/dist/dependencies.bun.lock +42 -36
  3. package/npm-shrinkwrap.json +270 -224
  4. package/package.json +1 -1
  5. package/vendor/cli/dist/commands/_lib/apply/apply-cmd.d.ts +7 -2
  6. package/vendor/cli/dist/commands/_lib/apply/apply-cmd.js +77 -75
  7. package/vendor/cli/dist/commands/_lib/apply/client.d.ts +40 -25
  8. package/vendor/cli/dist/commands/_lib/apply/client.js +31 -39
  9. package/vendor/cli/dist/commands/_lib/apply/deployment.d.ts +1 -1
  10. package/vendor/cli/dist/commands/_lib/apply/deployment.js +2 -2
  11. package/vendor/cli/dist/commands/_lib/apply/desired-state.d.ts +47 -11
  12. package/vendor/cli/dist/commands/_lib/apply/desired-state.js +106 -7
  13. package/vendor/cli/dist/commands/_lib/apply/diff.d.ts +14 -6
  14. package/vendor/cli/dist/commands/_lib/apply/diff.js +42 -23
  15. package/vendor/cli/dist/commands/_lib/apply/map-config.js +2 -3
  16. package/vendor/cli/dist/commands/_lib/apply/render.js +2 -0
  17. package/vendor/cli/dist/commands/_lib/apply/rollback-cmd.js +3 -3
  18. package/vendor/cli/dist/commands/_lib/connector-loader.d.ts +5 -1
  19. package/vendor/cli/dist/commands/_lib/connector-loader.js +1 -1
  20. package/vendor/cli/dist/commands/_lib/ensure-deps-installed.d.ts +15 -26
  21. package/vendor/cli/dist/commands/_lib/ensure-deps-installed.js +227 -136
  22. package/vendor/cli/dist/commands/_lib/view-bundler.d.ts +33 -0
  23. package/vendor/cli/dist/commands/_lib/view-bundler.js +207 -0
  24. package/vendor/cli/dist/commands/_lib/view-reapply.d.ts +60 -0
  25. package/vendor/cli/dist/commands/_lib/view-reapply.js +182 -0
  26. package/vendor/cli/dist/commands/dev.d.ts +14 -5
  27. package/vendor/cli/dist/commands/dev.js +56 -8
  28. package/vendor/cli/dist/commands/init.d.ts +1 -1
  29. package/vendor/cli/dist/commands/init.js +4 -4
  30. package/vendor/cli/dist/config/define.d.ts +25 -8
  31. package/vendor/cli/dist/config/define.js +24 -0
  32. package/vendor/cli/dist/connectors/README.md +15 -16
  33. package/vendor/cli/dist/connectors/github.ts +15 -9
  34. package/vendor/cli/dist/connectors/google_calendar.ts +21 -31
  35. package/vendor/cli/dist/connectors/google_drive.ts +106 -131
  36. package/vendor/cli/dist/connectors/google_gmail.ts +53 -30
  37. package/vendor/cli/dist/connectors/hackernews.ts +2 -5
  38. package/vendor/cli/dist/connectors/jira.ts +62 -27
  39. package/vendor/cli/dist/connectors/linear.ts +55 -21
  40. package/vendor/cli/dist/connectors/microsoft_outlook.ts +151 -110
  41. package/vendor/cli/dist/connectors/postgres.ts +19 -11
  42. package/vendor/cli/dist/connectors/producthunt.ts +8 -6
  43. package/vendor/cli/dist/connectors/reddit.ts +2 -2
  44. package/vendor/cli/dist/connectors/rss.ts +2 -2
  45. package/vendor/cli/dist/connectors/whatsapp_web.ts +5 -4
  46. package/vendor/cli/dist/connectors/x.ts +32 -17
  47. package/vendor/cli/dist/connectors/youtube.ts +18 -5
  48. package/vendor/cli/dist/internal/connector-compiler.d.ts +1 -1
  49. package/vendor/cli/dist/internal/connector-compiler.js +216 -17
  50. package/vendor/cli/dist/runtime-components.json +4 -4
  51. package/vendor/cli/package.json +2 -1
  52. package/vendor/connector-sdk/dist/connector-runtime.d.ts +4 -6
  53. package/vendor/connector-sdk/dist/connector-runtime.js +3 -5
  54. package/vendor/connector-sdk/dist/connector-types.d.ts +28 -13
  55. package/vendor/connector-sdk/dist/define-connector.d.ts +4 -1
  56. package/vendor/connector-sdk/dist/define-connector.js +4 -1
  57. package/vendor/connector-sdk/dist/http-client.d.ts +18 -7
  58. package/vendor/connector-sdk/dist/http-client.js +15 -13
  59. package/vendor/connector-sdk/dist/index.d.ts +1 -1
  60. package/vendor/connector-sdk/dist/retry.d.ts +15 -3
  61. package/vendor/connector-sdk/dist/retry.js +40 -64
  62. package/vendor/connector-sdk/package.json +1 -1
  63. package/vendor/connector-worker/dist/agent-turn/guest-entry.js +122 -10
  64. package/vendor/connector-worker/dist/agent-turn/guest.bundle.js +78 -10
  65. package/vendor/connector-worker/dist/agent-turn/types.d.ts +34 -4
  66. package/vendor/connector-worker/dist/compile/index.d.ts +21 -2
  67. package/vendor/connector-worker/dist/compile/index.js +41 -8
  68. package/vendor/connector-worker/dist/compile/source-capture.d.ts +10 -0
  69. package/vendor/connector-worker/dist/compile/source-capture.js +108 -0
  70. package/vendor/connector-worker/dist/daemon/agent-turn.js +97 -10
  71. package/vendor/connector-worker/dist/daemon/automation.d.ts +1 -1
  72. package/vendor/connector-worker/dist/daemon/executor.d.ts +0 -1
  73. package/vendor/connector-worker/dist/daemon/executor.js +42 -51
  74. package/vendor/connector-worker/dist/daemon/start.js +5 -1
  75. package/vendor/connector-worker/dist/executor/interface.d.ts +12 -8
  76. package/vendor/connector-worker/dist/executor/isolate.js +45 -28
  77. package/vendor/connector-worker/dist/self-check/index.js +15 -13
  78. package/vendor/connector-worker/package.json +1 -1
  79. package/vendor/core/dist/agent-policy.js +3 -0
  80. package/vendor/core/dist/connector-query-errors.d.ts +3 -3
  81. package/vendor/core/dist/connector-query-errors.js +8 -3
  82. package/vendor/core/dist/contracts/tools/manage-connections.d.ts +24 -0
  83. package/vendor/core/dist/contracts/tools/manage-connections.js +13 -0
  84. package/vendor/core/dist/contracts/tools/manage-entity-schema.d.ts +15 -25
  85. package/vendor/core/dist/contracts/tools/manage-entity-schema.js +3 -5
  86. package/vendor/core/dist/contracts/tools/manage-feeds.d.ts +11 -0
  87. package/vendor/core/dist/contracts/tools/manage-feeds.js +12 -1
  88. package/vendor/core/dist/contracts/tools/manage-operations.d.ts +47 -6
  89. package/vendor/core/dist/contracts/tools/manage-operations.js +36 -1
  90. package/vendor/core/dist/contracts/tools/manage-views.d.ts +293 -0
  91. package/vendor/core/dist/contracts/tools/manage-views.js +203 -0
  92. package/vendor/core/dist/contracts/tools/source-files-schema.d.ts +7 -0
  93. package/vendor/core/dist/contracts/tools/source-files-schema.js +19 -0
  94. package/vendor/core/dist/contracts/tools/source-files.d.ts +14 -0
  95. package/vendor/core/dist/contracts/tools/source-files.js +55 -0
  96. package/vendor/core/dist/contracts/tools/view-content-hash.d.ts +37 -0
  97. package/vendor/core/dist/contracts/tools/view-content-hash.js +58 -0
  98. package/vendor/core/dist/contracts/tools/view-path.d.ts +18 -0
  99. package/vendor/core/dist/contracts/tools/view-path.js +24 -0
  100. package/vendor/core/dist/contracts/worker/protocol.d.ts +73 -8
  101. package/vendor/core/dist/contracts/worker/protocol.js +58 -9
  102. package/vendor/core/dist/reserved.d.ts +3 -3
  103. package/vendor/core/dist/reserved.js +9 -1
  104. package/vendor/core/dist/utils/secret-redaction.js +2 -0
  105. package/vendor/core/package.json +25 -5
  106. package/vendor/core/dist/contracts/tools/manage-view-templates.d.ts +0 -165
  107. package/vendor/core/dist/contracts/tools/manage-view-templates.js +0 -130
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lobu/cli",
3
- "version": "20.2.0",
3
+ "version": "21.0.0",
4
4
  "description": "CLI for deploying and managing AI agents on Lobu",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -45,6 +45,7 @@
45
45
  "ora": "^8.0.1",
46
46
  "postgres": "file:../postgres",
47
47
  "tar": "^7.4.3",
48
+ "tinyglobby": "0.2.16",
48
49
  "yaml": "^2.7.1",
49
50
  "proper-lockfile": "4.1.2",
50
51
  "ajv": "^8.17.1",
@@ -38,15 +38,13 @@ export declare abstract class ConnectorRuntime<C = Record<string, unknown>, F =
38
38
  /**
39
39
  * Sync data from the connected service.
40
40
  *
41
- * Called by the worker when a sync run is executed.
42
- * Should return events to ingest and an updated checkpoint.
43
- * Long-running connectors may optionally use `ctx.emitEvents()` and
44
- * `ctx.updateCheckpoint()` to stream progress before returning.
41
+ * Called by the worker when a sync run is executed. Commit each page of
42
+ * events with its checkpoint through `ctx.commit` as it is fetched, then
43
+ * return how the pass ended.
45
44
  *
46
45
  * @param ctx - Sync context with feed config, checkpoint, and credentials
47
- * @returns Events and updated checkpoint
48
46
  */
49
- sync(ctx: SyncContext<C, F>): Promise<SyncResult<C>>;
47
+ sync(ctx: SyncContext<C, F>): Promise<SyncResult>;
50
48
  /**
51
49
  * Read one configured feed directly from its source. Feed handlers own native
52
50
  * filtering and pagination; the platform never infers semantics from a feed
@@ -36,13 +36,11 @@ export class ConnectorRuntime {
36
36
  /**
37
37
  * Sync data from the connected service.
38
38
  *
39
- * Called by the worker when a sync run is executed.
40
- * Should return events to ingest and an updated checkpoint.
41
- * Long-running connectors may optionally use `ctx.emitEvents()` and
42
- * `ctx.updateCheckpoint()` to stream progress before returning.
39
+ * Called by the worker when a sync run is executed. Commit each page of
40
+ * events with its checkpoint through `ctx.commit` as it is fetched, then
41
+ * return how the pass ended.
43
42
  *
44
43
  * @param ctx - Sync context with feed config, checkpoint, and credentials
45
- * @returns Events and updated checkpoint
46
44
  */
47
45
  async sync(ctx) {
48
46
  const handler = this.definition.feeds?.[ctx.feedKey]?.sync;
@@ -803,10 +803,22 @@ export interface SyncContext<C = Record<string, unknown>, F = Record<string, unk
803
803
  sessionState?: Record<string, unknown> | null;
804
804
  /** App-installation context when this connection is backed by an App install. */
805
805
  installation?: ConnectorInstallationContext;
806
- /** Optional hook for streaming event chunks while sync is in progress */
807
- emitEvents?: (events: EventEnvelope[]) => Promise<void>;
808
- /** Optional hook for persisting progress checkpoints during long syncs */
809
- updateCheckpoint?: (checkpoint: C | null) => Promise<void>;
806
+ /**
807
+ * Durably store `events`, then move the feed's checkpoint to `checkpoint`.
808
+ * The returned promise resolves only after both have committed and rejects
809
+ * (failing the run) on either failure. A large page may be stored in chunks,
810
+ * but its checkpoint moves only with the final chunk, so a failed commit may
811
+ * leave deduplicable events behind but never skips an unstored event. Commit
812
+ * as you go, once per source page, awaiting each call before the next: a run
813
+ * that stops resumes from the last checkpoint that resolved.
814
+ *
815
+ * Pass `null` to store events without moving the checkpoint, and an empty
816
+ * `events` array to record progress over a page that yielded nothing (a
817
+ * continuation token past filtered-out items). The checkpoint is opaque to
818
+ * the platform; the next run receives the last committed one as
819
+ * `ctx.checkpoint`.
820
+ */
821
+ commit: (events: EventEnvelope[], checkpoint: C | null) => Promise<void>;
810
822
  }
811
823
  /**
812
824
  * The credential a run is handed. On the isolate lane `accessToken` is a
@@ -824,15 +836,18 @@ export interface SyncCredentials {
824
836
  scope?: string | null;
825
837
  }
826
838
  /**
827
- * Result from ConnectorRuntime.sync().
828
- *
829
- * Generic parameter `C` matches the connector's checkpoint shape.
839
+ * How a sync pass ended. Its events and checkpoints were already committed
840
+ * through `ctx.commit`; the result only says what should happen next.
830
841
  */
831
- export interface SyncResult<C = Record<string, unknown>> {
832
- /** Events to write to the events table */
833
- events: EventEnvelope[];
834
- /** Updated checkpoint to persist */
835
- checkpoint: C | null;
842
+ export interface SyncResult {
843
+ /**
844
+ * `complete` — the source is caught up; the next run follows the feed's
845
+ * schedule. `more` — the pass stopped early at a committed boundary (a time
846
+ * or size budget) with work remaining, so the platform starts the next run
847
+ * right away instead of waiting for the schedule. `more` is honored only
848
+ * when the run committed a checkpoint.
849
+ */
850
+ status: 'complete' | 'more';
836
851
  /** Updated auth state to persist on the linked auth profile (browser cookies, etc.) */
837
852
  auth_update?: Record<string, unknown> | null;
838
853
  /** Optional metadata about the sync */
@@ -925,7 +940,7 @@ export interface FeedReadResult {
925
940
  /** Required for a windowed read; absence means the reader cannot honor it. */
926
941
  window?: FeedReadWindowCoverage;
927
942
  }
928
- export type FeedSyncHandler<C = Record<string, unknown>, F = Record<string, unknown>> = (ctx: SyncContext<C, F>) => Promise<SyncResult<C>>;
943
+ export type FeedSyncHandler<C = Record<string, unknown>, F = Record<string, unknown>> = (ctx: SyncContext<C, F>) => Promise<SyncResult>;
929
944
  export type FeedReadHandler<F = Record<string, unknown>> = (ctx: FeedReadContext<F>) => Promise<FeedReadResult>;
930
945
  /** Executable feed definition held only inside a connector runtime. */
931
946
  export interface RuntimeFeedDefinition<C = Record<string, unknown>, F = Record<string, unknown>> extends Omit<FeedDefinition, 'operations'> {
@@ -21,7 +21,10 @@
21
21
  * ```ts
22
22
  * export default defineConnector({
23
23
  * key: 'github', name: 'GitHub', version: '1.0.0',
24
- * feeds: { stars: { name: 'Stars', sync: async (ctx) => ({ events, checkpoint }) } },
24
+ * feeds: { stars: { name: 'Stars', sync: async (ctx) => {
25
+ * await ctx.commit(events, checkpoint);
26
+ * return { status: 'complete' };
27
+ * } } },
25
28
  * actions: { star_repo: { name: 'Star', execute: async (ctx) => ({ success: true }) } },
26
29
  * });
27
30
  * ```
@@ -21,7 +21,10 @@
21
21
  * ```ts
22
22
  * export default defineConnector({
23
23
  * key: 'github', name: 'GitHub', version: '1.0.0',
24
- * feeds: { stars: { name: 'Stars', sync: async (ctx) => ({ events, checkpoint }) } },
24
+ * feeds: { stars: { name: 'Stars', sync: async (ctx) => {
25
+ * await ctx.commit(events, checkpoint);
26
+ * return { status: 'complete' };
27
+ * } } },
25
28
  * actions: { star_repo: { name: 'Star', execute: async (ctx) => ({ success: true }) } },
26
29
  * });
27
30
  * ```
@@ -30,6 +30,16 @@ interface HttpClientRetryOptions {
30
30
  context?: Record<string, any>;
31
31
  onRetry?: (error: Error, attempt: number) => void;
32
32
  }
33
+ /** `RequestInit` plus the one hint retrying needs from the caller. */
34
+ export interface HttpRequestInit extends RequestInit {
35
+ /**
36
+ * The request is safe to repeat although its method is not idempotent — a
37
+ * GraphQL query or a search sent as POST. Without it a POST/PATCH is retried
38
+ * only on a 429, never on a 5xx or a dropped connection, because those do not
39
+ * say whether the server already acted on it (a sent email, a created issue).
40
+ */
41
+ idempotent?: boolean;
42
+ }
33
43
  export interface CreateHttpClientOptions {
34
44
  /**
35
45
  * Static bearer token shorthand: sent as `Authorization: Bearer <token>`
@@ -56,18 +66,19 @@ export interface HttpClient {
56
66
  /**
57
67
  * Fetch with auth + retry, resolving with the raw `Response` for non-2xx
58
68
  * statuses so callers can keep their own `response.ok` handling. Transient
59
- * statuses (429/5xx) still throw to drive the retry loop, so they surface
60
- * as a thrown `HttpStatusError` once retries are exhausted.
69
+ * statuses (408, 429, 5xx — see `classifyToolError`) still throw to drive the
70
+ * retry loop, so they surface as a thrown `HttpStatusError` once retries are
71
+ * exhausted.
61
72
  */
62
- raw(url: string, init?: RequestInit): Promise<Response>;
73
+ raw(url: string, init?: HttpRequestInit): Promise<Response>;
63
74
  /** Fetch with auth + retry; throws `HttpStatusError` on any non-2xx status. */
64
- request(url: string, init?: RequestInit): Promise<Response>;
75
+ request(url: string, init?: HttpRequestInit): Promise<Response>;
65
76
  /** `request()` + parse the response body as JSON (any method via `init`). */
66
- json<T>(url: string, init?: RequestInit): Promise<T>;
77
+ json<T>(url: string, init?: HttpRequestInit): Promise<T>;
67
78
  /** GET returning parsed JSON. */
68
- get<T>(url: string, init?: RequestInit): Promise<T>;
79
+ get<T>(url: string, init?: HttpRequestInit): Promise<T>;
69
80
  /** POST `body` as JSON (unless a Content-Type is supplied) returning parsed JSON. */
70
- post<T>(url: string, body?: unknown, init?: RequestInit): Promise<T>;
81
+ post<T>(url: string, body?: unknown, init?: HttpRequestInit): Promise<T>;
71
82
  }
72
83
  export declare function createHttpClient(options?: CreateHttpClientOptions): HttpClient;
73
84
  export interface RequireBearerClientOptions {
@@ -7,14 +7,10 @@
7
7
  * `Retry-After`, and descriptive errors that include the status code and a
8
8
  * truncated response body.
9
9
  */
10
- import { withHttpRetry } from './retry.js';
10
+ import { isTransientStatus, withHttpRetry } from './retry.js';
11
11
  import { sleep } from './sleep.js';
12
- /**
13
- * Statuses treated as transient: the client throws an `HttpStatusError` for
14
- * these so `withHttpRetry` can retry them (its keyword classifier recognizes
15
- * the status code embedded in the message).
16
- */
17
- const TRANSIENT_STATUSES = new Set([429, 500, 502, 503, 504]);
12
+ /** Methods RFC 9110 §9.2.2 defines as idempotent: repeating one has the effect of sending it once. */
13
+ const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE', 'PUT', 'DELETE']);
18
14
  const BODY_PREVIEW_CHARS = 500;
19
15
  const DEFAULT_MAX_RETRY_AFTER_MS = 30_000;
20
16
  /** Error thrown for non-2xx responses. Message: `<prefix> <METHOD> <url> failed (<status>): <truncated body>`. */
@@ -85,10 +81,11 @@ export function createHttpClient(options = {}) {
85
81
  async function attempt(url, init, throwOnAnyError) {
86
82
  const method = (init?.method ?? 'GET').toUpperCase();
87
83
  const headers = await buildHeaders(init);
88
- const response = await fetch(url, { ...init, headers });
84
+ const { idempotent: _idempotent, ...fetchInit } = init ?? {};
85
+ const response = await fetch(url, { ...fetchInit, headers });
89
86
  if (response.ok)
90
87
  return response;
91
- if (TRANSIENT_STATUSES.has(response.status)) {
88
+ if (isTransientStatus(response.status)) {
92
89
  const error = await statusError(response, method, url);
93
90
  if (response.status === 429 && retryEnabled) {
94
91
  const retryAfterMs = parseRetryAfterMs(response.headers.get('Retry-After'));
@@ -101,13 +98,18 @@ export function createHttpClient(options = {}) {
101
98
  throw await statusError(response, method, url);
102
99
  return response;
103
100
  }
104
- function withRetry(fn) {
101
+ function withRetry(init, fn) {
105
102
  if (!retryEnabled)
106
103
  return fn();
107
- return withHttpRetry(fn, { operation: `${errorPrefix} request`, ...retryOptions });
104
+ const method = (init?.method ?? 'GET').toUpperCase();
105
+ return withHttpRetry(fn, {
106
+ operation: `${errorPrefix} request`,
107
+ ...retryOptions,
108
+ repeatable: IDEMPOTENT_METHODS.has(method) || init?.idempotent === true,
109
+ });
108
110
  }
109
- const raw = (url, init) => withRetry(() => attempt(url, init, false));
110
- const request = (url, init) => withRetry(() => attempt(url, init, true));
111
+ const raw = (url, init) => withRetry(init, () => attempt(url, init, false));
112
+ const request = (url, init) => withRetry(init, () => attempt(url, init, true));
111
113
  const json = async (url, init) => {
112
114
  const response = await request(url, init);
113
115
  return (await response.json());
@@ -23,7 +23,7 @@ export type { AccessIdentitySpec, AccessMember, AccessResource, AclSourceDef, Ch
23
23
  export { ACL_RESOURCE_TYPE, ACL_RESOURCE_TYPE_SLUG, } from './acl-source.js';
24
24
  import { EVENT_RECALL_IDENTITY_NAMESPACES, getIdentityNamespaceDefinition, IDENTITY, IDENTITY_NAMESPACE_REGISTRY, isEventRecallIdentityNamespace } from './identity-namespaces.js';
25
25
  export { EVENT_RECALL_IDENTITY_NAMESPACES, getIdentityNamespaceDefinition, IDENTITY, IDENTITY_NAMESPACE_REGISTRY, isEventRecallIdentityNamespace, };
26
- export type { CreateHttpClientOptions, HttpClient, RequireBearerClientOptions, } from './http-client.js';
26
+ export type { CreateHttpClientOptions, HttpClient, HttpRequestInit, RequireBearerClientOptions, } from './http-client.js';
27
27
  export { createHttpClient, HttpStatusError, requireBearerClient } from './http-client.js';
28
28
  export { sdkLogger, sdkLogger as logger } from './logger.js';
29
29
  export type { CursorPage, OffsetPage, PaginateByCursorOptions, PaginateByOffsetOptions, } from './pagination.js';
@@ -1,9 +1,12 @@
1
1
  /**
2
2
  * HTTP retry helper for connector SDK.
3
3
  *
4
- * Exponential backoff with full jitter (5 retries, 1s → 16s), retry on
5
- * transient network/rate-limit/server errors, abort on permanent client errors
6
- * (401/403/404/etc.).
4
+ * Exponential backoff with full jitter (5 retries, 1s → 16s). Whether an error
5
+ * is worth retrying is decided by `classifyToolError`, the one catalog shared
6
+ * with the server: an HTTP status or SQLSTATE the error carries always wins,
7
+ * and message text is consulted only when it carries neither. A response
8
+ * body or URL is never evidence — a 503 whose body says "invalid" is still a
9
+ * 503.
7
10
  *
8
11
  * The backoff loop lives here rather than being imported from `@lobu/core`:
9
12
  * core's root entry drags winston, Sentry and OpenTelemetry into every
@@ -11,10 +14,19 @@
11
14
  * isolate. It keeps the semantics of core's `retryWithBackoff` for the one
12
15
  * configuration `withHttpRetry` uses: exponential, capped, full jitter.
13
16
  */
17
+ /** Whether a response with this HTTP status may succeed if the request is repeated. */
18
+ export declare function isTransientStatus(status: number): boolean;
14
19
  interface RetryOptions {
15
20
  operation?: string;
16
21
  context?: Record<string, any>;
17
22
  onRetry?: (error: Error, attempt: number) => void;
23
+ /**
24
+ * Whether repeating the call is safe when an earlier attempt may already have
25
+ * taken effect. Default `true`. Pass `false` for a write (a send, a create): it
26
+ * is then retried only on a 429, which proves the server did not act on it —
27
+ * never on a 5xx or a dropped connection (RFC 9110 §9.2.2).
28
+ */
29
+ repeatable?: boolean;
18
30
  }
19
31
  /**
20
32
  * HTTP retry strategy
@@ -1,9 +1,12 @@
1
1
  /**
2
2
  * HTTP retry helper for connector SDK.
3
3
  *
4
- * Exponential backoff with full jitter (5 retries, 1s → 16s), retry on
5
- * transient network/rate-limit/server errors, abort on permanent client errors
6
- * (401/403/404/etc.).
4
+ * Exponential backoff with full jitter (5 retries, 1s → 16s). Whether an error
5
+ * is worth retrying is decided by `classifyToolError`, the one catalog shared
6
+ * with the server: an HTTP status or SQLSTATE the error carries always wins,
7
+ * and message text is consulted only when it carries neither. A response
8
+ * body or URL is never evidence — a 503 whose body says "invalid" is still a
9
+ * 503.
7
10
  *
8
11
  * The backoff loop lives here rather than being imported from `@lobu/core`:
9
12
  * core's root entry drags winston, Sentry and OpenTelemetry into every
@@ -11,6 +14,7 @@
11
14
  * isolate. It keeps the semantics of core's `retryWithBackoff` for the one
12
15
  * configuration `withHttpRetry` uses: exponential, capped, full jitter.
13
16
  */
17
+ import { classifyToolError, isRetryable, } from '@lobu/core/connector-query-errors';
14
18
  import { sdkLogger } from './logger.js';
15
19
  async function retryWithBackoff(fn, options) {
16
20
  const { maxRetries, baseDelay, maxDelay, shouldRetry, onRetry } = options;
@@ -41,61 +45,38 @@ async function retryWithBackoff(fn, options) {
41
45
  }
42
46
  throw lastError;
43
47
  }
44
- const TRANSIENT_KEYWORDS = [
45
- // network
46
- 'network',
47
- 'econnrefused',
48
- 'etimedout',
49
- 'enotfound',
50
- 'econnreset',
51
- 'fetch failed',
52
- 'socket',
53
- 'dns',
54
- // database
55
- 'connection pool',
56
- 'too many connections',
57
- 'connection limit',
58
- 'connection reset',
59
- 'connection refused',
60
- 'server closed',
61
- 'connection terminated',
62
- 'connection timeout',
63
- 'deadlock',
64
- 'lock timeout',
65
- 'query timeout',
66
- 'statement timeout',
67
- 'transaction',
68
- 'postgres',
69
- 'postgresql',
70
- 'pg_',
71
- 'relation does not exist',
72
- 'syntax error',
73
- // rate limit
74
- 'rate limit',
75
- '429',
76
- 'too many requests',
77
- // server
78
- '500',
79
- '502',
80
- '503',
81
- '504',
82
- 'server error',
83
- 'service unavailable',
84
- 'gateway timeout',
85
- ];
86
- const PERMANENT_KEYWORDS = [
87
- 'not found',
88
- '404',
89
- 'unauthorized',
90
- '401',
91
- 'forbidden',
92
- '403',
93
- 'invalid',
94
- 'bad request',
95
- '400',
96
- ];
97
- function errorMessage(error) {
98
- return (error instanceof Error ? error.message : String(error)).toLowerCase();
48
+ /**
49
+ * The structured signal an error carries, read off the error itself. An
50
+ * `HttpStatusError` carries `status`; a postgres.js error carries a SQLSTATE
51
+ * `code`. The message rides along only as the catalog's last resort, for
52
+ * errors that arrive as text alone (a failed fetch inside the isolate is a
53
+ * bare `TypeError('fetch failed: …')`).
54
+ */
55
+ function errorSignal(error) {
56
+ if (!(error instanceof Error))
57
+ return { message: String(error) };
58
+ const fields = error;
59
+ return {
60
+ httpStatus: typeof fields.status === 'number' ? fields.status : undefined,
61
+ pgCode: typeof fields.code === 'string' ? fields.code : undefined,
62
+ message: error.message,
63
+ };
64
+ }
65
+ /** Whether a response with this HTTP status may succeed if the request is repeated. */
66
+ export function isTransientStatus(status) {
67
+ return isRetryable(classifyToolError({ httpStatus: status }));
68
+ }
69
+ /** Whether `error` may succeed if the identical call is repeated. */
70
+ function isTransientError(error) {
71
+ return isRetryable(classifyToolError(errorSignal(error)));
72
+ }
73
+ /**
74
+ * Whether `error` proves the server refused the request without acting on it.
75
+ * Only a 429 says so; a 5xx or a dropped connection says nothing about whether
76
+ * a write landed.
77
+ */
78
+ function isUnprocessed(error) {
79
+ return classifyToolError(errorSignal(error)) === 'RATE_LIMITED';
99
80
  }
100
81
  /**
101
82
  * HTTP retry strategy
@@ -110,12 +91,7 @@ export async function withHttpRetry(fn, options) {
110
91
  maxRetries: totalRetries,
111
92
  baseDelay: 1000,
112
93
  maxDelay: 16000,
113
- shouldRetry: (error) => {
114
- const msg = errorMessage(error);
115
- if (PERMANENT_KEYWORDS.some((k) => msg.includes(k)))
116
- return false;
117
- return TRANSIENT_KEYWORDS.some((k) => msg.includes(k));
118
- },
94
+ shouldRetry: options?.repeatable === false ? isUnprocessed : isTransientError,
119
95
  onRetry: (attempt, error) => {
120
96
  options?.onRetry?.(error, attempt);
121
97
  sdkLogger.debug({
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lobu/connector-sdk",
3
- "version": "20.2.0",
3
+ "version": "21.0.0",
4
4
  "description": "Lobu memory SDK — build pluggable connectors for Lobu memory",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",