@maximem/synap-js-sdk 0.4.7 → 0.5.1

package/dist/{chunk-OCMM2Z5P.js → chunk-BWMPKLFG.js}

@@ -56,9 +56,18 @@ var NetworkTimeoutError = class extends SynapTransientError {
 var RateLimitError = class extends SynapTransientError {
   static errorCode = "rate_limit";
   retryAfterSeconds;
+  /** Machine-readable cause, when the stop was a credit stop. */
+  reason;
+  /** Where a Trial customer upgrades. Python calls this `upgrade_url`. */
+  upgradeUrl;
+  /** Where billing is managed. Python calls this `manage_url`. */
+  manageUrl;
   constructor(message, options = {}) {
     super(message, options);
     this.retryAfterSeconds = options.retryAfterSeconds ?? null;
+    this.reason = options.reason ?? null;
+    this.upgradeUrl = options.upgradeUrl ?? null;
+    this.manageUrl = options.manageUrl ?? null;
   }
 };
 var ServiceUnavailableError = class extends SynapTransientError {
@@ -78,12 +87,23 @@ var InsufficientCreditsError = class extends SynapPermanentError {
   recoveryUrl;
   /** Where a redeem code can be entered. Python calls this `redeem_url`. */
   redeemUrl;
+  /**
+   * Machine-readable cause. `'overages_disabled'` means the plan is paid and
+   * the balance is spent, but the account has not allowed usage past zero, so
+   * the work stops until someone allows overages or adds credits. Null when an
+   * older server did not send one.
+   */
+  reason;
+  /** Where that setting and billing are managed. Python calls this `manage_url`. */
+  manageUrl;
   constructor(message, options = {}) {
     super(message, options);
     this.balanceCredits = options.balanceCredits ?? null;
     this.requiredCredits = options.requiredCredits ?? null;
     this.recoveryUrl = options.recoveryUrl ?? null;
     this.redeemUrl = options.redeemUrl ?? null;
+    this.reason = options.reason ?? null;
+    this.manageUrl = options.manageUrl ?? null;
   }
 };
 var InvalidInputError = class extends SynapPermanentError {
@@ -150,6 +170,23 @@ var TransientError = SynapTransientError;
 var PermanentError = SynapPermanentError;
 var ConnectionError = NetworkTimeoutError;
 
+// src/util/correlation.ts
+function newCorrelationId() {
+  const c = globalThis.crypto;
+  if (typeof c?.randomUUID === "function") return c.randomUUID();
+  if (typeof c?.getRandomValues === "function") {
+    const b = c.getRandomValues(new Uint8Array(16));
+    b[6] = (b[6] ?? 0) & 15 | 64;
+    b[8] = (b[8] ?? 0) & 63 | 128;
+    const h = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
+    const r = Math.random() * 16 | 0;
+    return (ch === "x" ? r : r & 3 | 8).toString(16);
+  });
+}
+
 export {
   SynapError,
   isSynapError,
@@ -173,6 +210,7 @@ export {
   SDKError,
   TransientError,
   PermanentError,
-  ConnectionError
+  ConnectionError,
+  newCorrelationId
 };
-//# sourceMappingURL=chunk-OCMM2Z5P.js.map
+//# sourceMappingURL=chunk-BWMPKLFG.js.map

package/dist/chunk-BWMPKLFG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/util/correlation.ts"],"sourcesContent":["/**\n * Synap SDK error taxonomy.\n *\n * Mirrors `maximem_synap/models/errors.py` 1:1, including the four\n * backward-compatibility aliases at the bottom. If you add an error to one\n * SDK, add it to the other in the same change.\n *\n * ## Why every error carries a `.code`\n *\n * This package ships dual ESM + CJS. A consumer whose dependency graph pulls\n * in both formats gets *two* copies of every class in this file, and then:\n *\n *     try { ... } catch (e) { if (e instanceof SynapError) { ... } }\n *\n * silently evaluates to `false` against the copy from the other format. Error\n * handling stops working and nothing throws to tell you. `.code` is a plain\n * string, so it is immune. Prefer it at package boundaries:\n *\n *     if (isSynapError(e) && e.code === 'rate_limit') { ... }\n *\n * `Symbol.hasInstance` is also wired up on the base class, so `instanceof`\n * works across realms too -- but `.code` is the documented contract.\n */\n\n/** Stable, format-independent discriminators. Never renumber or reuse. */\nexport type SynapErrorCode =\n  | 'synap_error'\n  | 'transient'\n  | 'permanent'\n  | 'network_timeout'\n  | 'rate_limit'\n  | 'insufficient_credits'\n  | 'service_unavailable'\n  | 'invalid_input'\n  | 'invalid_instance_id'\n  | 'invalid_conversation_id'\n  | 'authentication'\n  | 'context_not_found'\n  | 'conflict'\n  | 'transcript_conflict'\n  | 'session_expired'\n  | 'listening_already_active'\n  | 'listening_not_active'\n  | 'agent_unavailable';\n\nconst BRAND = Symbol.for('@maximem/synap-js-sdk.SynapError');\n\nexport interface SynapErrorOptions {\n  correlationId?: string | null;\n  cause?: unknown;\n}\n\nexport class SynapError extends Error {\n  /**\n   * The single declaration site for each subclass's code.\n   *\n   * It is `static` rather than a class field on purpose. Under\n   * `useDefineForClassFields` (the default at our ES2022 target) a class field\n   * is an *instance* property, so it is invisible from the constructor object.\n   * `Symbol.hasInstance` below only has the constructor to work with, so a\n   * field would leave it unable to tell `AuthenticationError` from\n   * `RateLimitError` -- it would report every Synap error as an instance of\n   * every other one.\n   */\n  static readonly errorCode: SynapErrorCode = 'synap_error';\n  /** True for errors where a retry may succeed. Static for the same reason. */\n  static readonly isTransient: boolean = false;\n\n  /** Own, enumerable, so logs and JSON.stringify include it. */\n  readonly code: SynapErrorCode;\n  readonly correlationId: string | null;\n  readonly transient: boolean;\n\n  constructor(message: string, options: SynapErrorOptions = {}) {\n    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);\n    const ctor = new.target as typeof SynapError;\n    this.name = new.target.name;\n    this.code = ctor.errorCode;\n    this.transient = ctor.isTransient;\n    this.correlationId = options.correlationId ?? null;\n    Object.defineProperty(this, BRAND, { value: true, enumerable: false });\n    // Without this, subclassing a built-in under a downlevel target breaks the\n    // prototype chain and `instanceof` fails even within a single copy.\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  static override [Symbol.hasInstance](instance: unknown): boolean {\n    if (instance === null || typeof instance !== 'object') return false;\n    // Cross-realm / dual-format tolerant: identify by brand, then narrow by the\n    // subclass's own code so `e instanceof RateLimitError` stays meaningful.\n    if (!(BRAND in instance)) return false;\n    const expected = (this as unknown as { errorCode?: SynapErrorCode }).errorCode;\n    // Called on something that is not one of our classes: fall back to the brand.\n    if (expected === undefined) return true;\n    // Everything branded descends from the root.\n    if (expected === 'synap_error') return true;\n    const actual = (instance as { code?: string }).code;\n    return actual === expected || descendsFrom(actual, expected);\n  }\n}\n\n/** Type guard that works across ESM/CJS copies and realms. */\nexport function isSynapError(e: unknown): e is SynapError {\n  return typeof e === 'object' && e !== null && BRAND in e;\n}\n\nexport class SynapTransientError extends SynapError {\n  static override readonly errorCode: SynapErrorCode = 'transient';\n  static override readonly isTransient: boolean = true;\n}\n\nexport class SynapPermanentError extends SynapError {\n  static override readonly errorCode: SynapErrorCode = 'permanent';\n  static override readonly isTransient: boolean = false;\n}\n\n// ─── Transient ────────────────────────────────────────────────────────────────\n\nexport class NetworkTimeoutError extends SynapTransientError {\n  static override readonly errorCode: SynapErrorCode = 'network_timeout';\n}\n\n/**\n * Rate limit exceeded (HTTP 429, gRPC RESOURCE_EXHAUSTED).\n *\n * Also carries the two credit stops the server reports as 429, because both\n * recover with time or a plan change rather than with a retry of this request:\n * `reason: 'trial_limit_reached'` (the Trial cap is spent, see `upgradeUrl`)\n * and `reason: 'subscription_inactive'` (a paid plan whose subscription is past\n * due, unpaid or cancelled, see `manageUrl`). `reason` is null for an ordinary\n * rate limit and against a server too old to send one.\n */\nexport class RateLimitError extends SynapTransientError {\n  static override readonly errorCode: SynapErrorCode = 'rate_limit';\n  readonly retryAfterSeconds: number | null;\n  /** Machine-readable cause, when the stop was a credit stop. */\n  readonly reason: string | null;\n  /** Where a Trial customer upgrades. Python calls this `upgrade_url`. */\n  readonly upgradeUrl: string | null;\n  /** Where billing is managed. Python calls this `manage_url`. */\n  readonly manageUrl: string | null;\n\n  constructor(\n    message: string,\n    options: SynapErrorOptions & {\n      retryAfterSeconds?: number | null;\n      reason?: string | null;\n      upgradeUrl?: string | null;\n      manageUrl?: string | null;\n    } = {},\n  ) {\n    super(message, options);\n    this.retryAfterSeconds = options.retryAfterSeconds ?? null;\n    this.reason = options.reason ?? null;\n    this.upgradeUrl = options.upgradeUrl ?? null;\n    this.manageUrl = options.manageUrl ?? null;\n  }\n}\n\nexport class ServiceUnavailableError extends SynapTransientError {\n  static override readonly errorCode: SynapErrorCode = 'service_unavailable';\n}\n\nexport class AgentUnavailableError extends SynapTransientError {\n  static override readonly errorCode: SynapErrorCode = 'agent_unavailable';\n  constructor(message = 'Agent unavailable', options: SynapErrorOptions = {}) {\n    super(message, options);\n  }\n}\n\n// ─── Permanent ────────────────────────────────────────────────────────────────\n\n/**\n * The caller's credit wallet cannot cover this request.\n *\n * HTTP 402, and gRPC RESOURCE_EXHAUSTED with credit-related trailing metadata.\n * Permanent by design: retrying without topping up burns quota and never\n * succeeds. This is the error behind \"the agent forgot\" reports where retrieval\n * silently returns nothing.\n */\nexport class InsufficientCreditsError extends SynapPermanentError {\n  static override readonly errorCode: SynapErrorCode = 'insufficient_credits';\n  readonly balanceCredits: number | null;\n  readonly requiredCredits: number | null;\n  /** Where the balance can be viewed. Python calls this `recovery_url`. */\n  readonly recoveryUrl: string | null;\n  /** Where a redeem code can be entered. Python calls this `redeem_url`. */\n  readonly redeemUrl: string | null;\n  /**\n   * Machine-readable cause. `'overages_disabled'` means the plan is paid and\n   * the balance is spent, but the account has not allowed usage past zero, so\n   * the work stops until someone allows overages or adds credits. Null when an\n   * older server did not send one.\n   */\n  readonly reason: string | null;\n  /** Where that setting and billing are managed. Python calls this `manage_url`. */\n  readonly manageUrl: string | null;\n\n  constructor(\n    message: string,\n    options: SynapErrorOptions & {\n      balanceCredits?: number | null;\n      requiredCredits?: number | null;\n      recoveryUrl?: string | null;\n      redeemUrl?: string | null;\n      reason?: string | null;\n      manageUrl?: string | null;\n    } = {},\n  ) {\n    super(message, options);\n    this.balanceCredits = options.balanceCredits ?? null;\n    this.requiredCredits = options.requiredCredits ?? null;\n    this.recoveryUrl = options.recoveryUrl ?? null;\n    this.redeemUrl = options.redeemUrl ?? null;\n    this.reason = options.reason ?? null;\n    this.manageUrl = options.manageUrl ?? null;\n  }\n}\n\nexport class InvalidInputError extends SynapPermanentError {\n  static override readonly errorCode: SynapErrorCode = 'invalid_input';\n}\n\n/**\n * Raised by `validateInstanceId` before any network call, matching Python's\n * `utils/validators.py`. The message text is identical in both SDKs.\n */\nexport class InvalidInstanceIdError extends InvalidInputError {\n  static override readonly errorCode: SynapErrorCode = 'invalid_instance_id';\n}\n\n/** See the note on InvalidInstanceIdError. Raised by `validateConversationId`. */\nexport class InvalidConversationIdError extends InvalidInputError {\n  static override readonly errorCode: SynapErrorCode = 'invalid_conversation_id';\n}\n\nexport class AuthenticationError extends SynapPermanentError {\n  static override readonly errorCode: SynapErrorCode = 'authentication';\n}\n\nexport class ContextNotFoundError extends SynapPermanentError {\n  static override readonly errorCode: SynapErrorCode = 'context_not_found';\n}\n\nexport class ConflictError extends SynapPermanentError {\n  static override readonly errorCode: SynapErrorCode = 'conflict';\n}\n\nexport class TranscriptConflictError extends ConflictError {\n  static override readonly errorCode: SynapErrorCode = 'transcript_conflict';\n}\n\nexport class SessionExpiredError extends SynapPermanentError {\n  static override readonly errorCode: SynapErrorCode = 'session_expired';\n}\n\nexport class ListeningAlreadyActiveError extends SynapPermanentError {\n  static override readonly errorCode: SynapErrorCode = 'listening_already_active';\n}\n\nexport class ListeningNotActiveError extends SynapPermanentError {\n  static override readonly errorCode: SynapErrorCode = 'listening_not_active';\n}\n\n// ─── Hierarchy metadata (drives the cross-copy instanceof above) ──────────────\n\nconst PARENT: Partial<Record<SynapErrorCode, SynapErrorCode>> = {\n  transient: 'synap_error',\n  permanent: 'synap_error',\n  network_timeout: 'transient',\n  rate_limit: 'transient',\n  service_unavailable: 'transient',\n  agent_unavailable: 'transient',\n  insufficient_credits: 'permanent',\n  invalid_input: 'permanent',\n  invalid_instance_id: 'invalid_input',\n  invalid_conversation_id: 'invalid_input',\n  authentication: 'permanent',\n  context_not_found: 'permanent',\n  conflict: 'permanent',\n  transcript_conflict: 'conflict',\n  session_expired: 'permanent',\n  listening_already_active: 'permanent',\n  listening_not_active: 'permanent',\n};\n\nfunction descendsFrom(actual: string | undefined, expected: string): boolean {\n  let cur = actual as SynapErrorCode | undefined;\n  const seen = new Set<string>();\n  while (cur && !seen.has(cur)) {\n    seen.add(cur);\n    if (cur === expected) return true;\n    cur = PARENT[cur];\n  }\n  return false;\n}\n\n// ─── Backward-compatibility aliases (mirrors the tail of errors.py) ──────────\n// `ConnectionError` deliberately shadows the global in a module scope. Python\n// does the same thing; keeping the name means ported code reads identically.\n\nexport const SDKError = SynapError;\nexport const TransientError = SynapTransientError;\nexport const PermanentError = SynapPermanentError;\nexport const ConnectionError = NetworkTimeoutError;\n","/**\n * Correlation ID generation.\n *\n * `globalThis.crypto` is unflagged from Node 19 onward and this package\n * declares `engines.node >= 20`, so `randomUUID` is normally present. It is\n * still feature-detected rather than assumed, because `engines` is advisory:\n * npm warns and installs anyway, and the SDK also runs on Workers, Edge and\n * Bun, where the available crypto surface varies.\n *\n * Deliberately does NOT import `node:crypto`. That import is what breaks Edge\n * and Workers builds at bundle time, and a correlation ID is not a security\n * value, so there is nothing to gain from it.\n */\nexport function newCorrelationId(): string {\n  const c = globalThis.crypto;\n  if (typeof c?.randomUUID === 'function') return c.randomUUID();\n\n  if (typeof c?.getRandomValues === 'function') {\n    const b = c.getRandomValues(new Uint8Array(16));\n    // RFC 4122 version (4) and variant bits. The `?? 0` guards satisfy\n    // `noUncheckedIndexedAccess`; a 16-byte array always has these slots.\n    b[6] = ((b[6] ?? 0) & 0x0f) | 0x40;\n    b[8] = ((b[8] ?? 0) & 0x3f) | 0x80;\n    const h = Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');\n    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;\n  }\n\n  // Last resort. Correlation IDs are for tracing only, never for security, so\n  // Math.random is acceptable here and only here.\n  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (ch) => {\n    const r = (Math.random() * 16) | 0;\n    return (ch === 'x' ? r : (r & 0x3) | 0x8).toString(16);\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-3JSE64GW.cjs → chunk-IA2N5NUY.cjs}

@@ -1,5 +1,11 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/grpc/descriptor.ts
-var PROTO_SHA = "1a9a098645d1b3cf";
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+
+
+var _chunkT372OL3Qcjs = require('./chunk-T372OL3Q.cjs');
+
+// src/grpc/descriptor.ts
+var PROTO_SHA = "c1d834043608ad4f";
 var SYNAP_PROTO_DESCRIPTOR = {
   "nested": {
     "synap": {
@@ -202,6 +208,14 @@ var SYNAP_PROTO_DESCRIPTOR = {
                   "type": "string",
                   "id": 11
                 },
+                "tool_result_json": {
+                  "type": "string",
+                  "id": 15
+                },
+                "tool_call_id": {
+                  "type": "string",
+                  "id": 16
+                },
                 "search_queries": {
                   "rule": "repeated",
                   "type": "string",
@@ -211,6 +225,19 @@ var SYNAP_PROTO_DESCRIPTOR = {
                   "rule": "repeated",
                   "type": "string",
                   "id": 13
+                },
+                "scope": {
+                  "keyType": "string",
+                  "type": "string",
+                  "id": 14
+                },
+                "event_id": {
+                  "type": "string",
+                  "id": 17
+                },
+                "sent_at_ms": {
+                  "type": "int64",
+                  "id": 18
                 }
               }
             },
@@ -252,7 +279,8 @@ var SYNAP_PROTO_DESCRIPTOR = {
                   "oneof": [
                     "context_bundle",
                     "heartbeat_pong",
-                    "signal"
+                    "signal",
+                    "event_ack"
                   ]
                 }
               },
@@ -268,6 +296,23 @@ var SYNAP_PROTO_DESCRIPTOR = {
                 "signal": {
                   "type": "StreamSignal",
                   "id": 3
+                },
+                "event_ack": {
+                  "type": "EventAck",
+                  "id": 4
+                }
+              }
+            },
+            "EventAck": {
+              "fields": {
+                "event_ids": {
+                  "rule": "repeated",
+                  "type": "string",
+                  "id": 1
+                },
+                "timestamp_ms": {
+                  "type": "int64",
+                  "id": 2
                 }
               }
             },
@@ -394,6 +439,10 @@ var SYNAP_PROTO_DESCRIPTOR = {
                 "ttl_hint_seconds": {
                   "type": "int32",
                   "id": 23
+                },
+                "anticipation_scope_rung": {
+                  "type": "string",
+                  "id": 24
                 }
               }
             },
@@ -615,7 +664,66 @@ var BACKOFF_MAX_MS = 3e4;
 var HEARTBEAT_INTERVAL_MS = 3e4;
 var HEARTBEAT_TIMEOUT_MS = 1e4;
 var MAX_MISSED_HEARTBEATS = 3;
+var SEND_QUEUE_MAX_DEPTH = 100;
+var CLOSE_GRACE_MS = 2e3;
+var SEND_QUEUE_MAX_AGE_MS = 5 * 60 * 1e3;
 var MIN_TTL_SECONDS = 60;
+var GRPC_RESOURCE_EXHAUSTED = 8;
+var CREDIT_ABORT_DETAILS = "insufficient_credits";
+var CREDIT_STOP_REASONS = /* @__PURE__ */ new Set([
+  "overages_disabled",
+  "trial_limit_reached",
+  "subscription_inactive"
+]);
+function metadataValue(metadata, key) {
+  if (metadata === null || typeof metadata !== "object") return null;
+  const getter = metadata.get;
+  const raw = typeof getter === "function" ? getter.call(metadata, key) : metadata[key];
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  if (value === void 0 || value === null) return null;
+  const text = typeof value === "string" ? value : String(value);
+  return text === "" ? null : text;
+}
+function numberOrNull(value) {
+  if (value === null) return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function creditErrorFromRpc(error, correlationId = null) {
+  if (error === null || typeof error !== "object") return null;
+  if (error.code !== GRPC_RESOURCE_EXHAUSTED) return null;
+  const metadata = error.metadata;
+  const reason = metadataValue(metadata, "credit-reason");
+  if (reason === null || !CREDIT_STOP_REASONS.has(reason)) return null;
+  const rawDetails = error.details;
+  const details = typeof rawDetails === "string" && rawDetails !== "" ? rawDetails : CREDIT_ABORT_DETAILS;
+  const requestId = _nullishCoalesce(metadataValue(metadata, "request-id"), () => ( correlationId));
+  const manageUrl = metadataValue(metadata, "credit-manage-url");
+  if (reason === "overages_disabled") {
+    return new (0, _chunkT372OL3Qcjs.InsufficientCreditsError)(details, {
+      correlationId: requestId,
+      balanceCredits: numberOrNull(metadataValue(metadata, "credit-balance")),
+      requiredCredits: numberOrNull(metadataValue(metadata, "credit-minimum-required")),
+      recoveryUrl: metadataValue(metadata, "credit-recovery-url"),
+      redeemUrl: metadataValue(metadata, "credit-redeem-url"),
+      reason,
+      manageUrl
+    });
+  }
+  return new (0, _chunkT372OL3Qcjs.RateLimitError)(details, {
+    correlationId: requestId,
+    reason,
+    upgradeUrl: metadataValue(metadata, "credit-upgrade-url"),
+    manageUrl
+  });
+}
+function isCreditStop(error) {
+  if (!(error instanceof _chunkT372OL3Qcjs.InsufficientCreditsError) && !(error instanceof _chunkT372OL3Qcjs.RateLimitError)) {
+    return false;
+  }
+  const reason = error.reason;
+  return typeof reason === "string" && CREDIT_STOP_REASONS.has(reason);
+}
 var GrpcStreamClient = class {
   
   
@@ -627,6 +735,16 @@ var GrpcStreamClient = class {
   #missedHeartbeats = 0;
   #heartbeatTimer = null;
   #shutdownRequested = false;
+  // Events that could not be written because there was no stream.
+  #sendQueue = [];
+  // Events written to a live stream that the server has not acknowledged. The
+  // queue above covers "the stream was down"; this covers the half that
+  // actually loses sessions — the write succeeded, the stream broke before the
+  // server processed it, and nobody knows.
+  #unacked = /* @__PURE__ */ new Map();
+  // Why the stream stopped, when it stopped for a reason the caller can act on
+  // (today: a credit refusal). Mirrors Python's `last_error`.
+  #lastError = null;
   #grpc = null;
   #ServiceStub = null;
   #credentials;
@@ -650,21 +768,149 @@ var GrpcStreamClient = class {
   get isConnected() {
     return this.#state === "connected";
   }
+  /**
+   * The error that ended the stream, if one did.
+   *
+   * Set when the server refused the stream for credits, so an `onDisconnect`
+   * handler can read the balance, the reason and the URL to fix it. Null for an
+   * ordinary disconnect.
+   */
+  get lastError() {
+    return this.#lastError;
+  }
   async connect() {
     await this.#loadGrpc();
     this.#shutdownRequested = false;
+    this.#lastError = null;
     await this.#establish();
     this.#startHeartbeat();
   }
   async disconnect() {
     this.#shutdownRequested = true;
     this.#stopHeartbeat();
-    this.#closeCall();
+    this.#flushBeforeClose();
+    const call = this.#call;
+    if (call !== null) {
+      try {
+        call.end();
+      } catch (e) {
+      }
+      await new Promise((resolve) => {
+        let settled = false;
+        const done = () => {
+          if (!settled) {
+            settled = true;
+            resolve();
+          }
+        };
+        const timer = setTimeout(() => {
+          const left = this.undelivered();
+          if (left.unacknowledged > 0 || left.queued > 0) {
+            console.warn(
+              `[synap] closing with ${left.queued} queued and ${left.unacknowledged} unacknowledged event(s) the server did not confirm within ${CLOSE_GRACE_MS}ms`
+            );
+          }
+          done();
+        }, CLOSE_GRACE_MS);
+        if (typeof timer.unref === "function") timer.unref();
+        call.on("end", () => {
+          clearTimeout(timer);
+          done();
+        });
+        call.on("status", () => {
+          clearTimeout(timer);
+          done();
+        });
+        call.on("error", () => {
+          clearTimeout(timer);
+          done();
+        });
+      });
+    }
+    this.#call = null;
     this.#setState("closed");
   }
-  /** Fire-and-forget: a dropped event must never fail the caller's turn. */
+  /**
+   * What this client could not get to the server.
+   *
+   * Every send path returns void, so a caller had no way to tell a delivered
+   * turn from a lost one. Mirrors Python's `undelivered()`.
+   */
+  undelivered() {
+    return { queued: this.#sendQueue.length, unacknowledged: this.#unacked.size };
+  }
+  /**
+   * Never fails the caller's turn, and no longer loses it either.
+   *
+   * A write that cannot go out is buffered and replayed on reconnect, and a
+   * write that does go out is held until the server acknowledges it. Before
+   * this, both cases ended at a silent `return`.
+   */
   sendConversationEvent(event) {
-    this.#write({ conversation_event: { ...event } });
+    const stamped = {
+      ...event,
+      event_id: event.event_id && event.event_id !== "" ? event.event_id : _chunkT372OL3Qcjs.newCorrelationId.call(void 0, ),
+      sent_at_ms: _nullishCoalesce(event.sent_at_ms, () => ( Date.now()))
+    };
+    if (!this.isConnected || this.#call === null) {
+      this.#enqueue(stamped);
+      return;
+    }
+    this.#write({ conversation_event: { ...stamped } });
+    this.#trackUnacked(stamped);
+  }
+  #enqueue(event) {
+    this.#pruneQueue();
+    if (this.#sendQueue.length >= SEND_QUEUE_MAX_DEPTH) {
+      const evicted = this.#sendQueue.shift();
+      console.warn(
+        `[synap] send queue full (max=${SEND_QUEUE_MAX_DEPTH}); dropping oldest event (event_type=${_optionalChain([evicted, 'optionalAccess', _ => _.event, 'access', _2 => _2.event_type])})`
+      );
+    }
+    this.#sendQueue.push({ queuedAt: Date.now(), event });
+  }
+  #pruneQueue() {
+    const cutoff = Date.now() - SEND_QUEUE_MAX_AGE_MS;
+    while (this.#sendQueue.length > 0 && (_nullishCoalesce(_optionalChain([this, 'access', _3 => _3.#sendQueue, 'access', _4 => _4[0], 'optionalAccess', _5 => _5.queuedAt]), () => ( 0))) < cutoff) {
+      const expired = this.#sendQueue.shift();
+      console.warn(
+        `[synap] queued event expired (age>${SEND_QUEUE_MAX_AGE_MS}ms); dropping (event_type=${_optionalChain([expired, 'optionalAccess', _6 => _6.event, 'access', _7 => _7.event_type])})`
+      );
+    }
+  }
+  #trackUnacked(event) {
+    const id = event.event_id;
+    if (id === void 0 || id === "") return;
+    const cutoff = Date.now() - SEND_QUEUE_MAX_AGE_MS;
+    for (const [oldestId, held] of this.#unacked) {
+      if (held.queuedAt >= cutoff && this.#unacked.size < SEND_QUEUE_MAX_DEPTH) break;
+      this.#unacked.delete(oldestId);
+      console.warn(
+        `[synap] unacknowledged event dropped: the server never confirmed it (event_type=${held.event.event_type})`
+      );
+    }
+    this.#unacked.set(id, { queuedAt: Date.now(), event });
+  }
+  /**
+   * Replay what the server never confirmed, then what never went out.
+   *
+   * That order is the order things happened in: an unacked event was written
+   * to the previous stream, so it is older than anything that piled up while
+   * there was no stream at all. Safe to repeat — every event carries the id it
+   * was first sent with and the server drops a second sighting of it.
+   */
+  #replayBuffered() {
+    const unacked = [...this.#unacked.values()];
+    const queued = this.#sendQueue;
+    this.#sendQueue = [];
+    for (const held of [...unacked, ...queued]) {
+      this.#write({ conversation_event: { ...held.event } });
+    }
+    if (unacked.length > 0 || queued.length > 0) {
+      console.warn(
+        `[synap] replayed ${unacked.length} unacknowledged and ${queued.length} queued event(s) after reconnect`
+      );
+    }
   }
   sendSessionControl(input) {
     this.#write({ session_control: { ...input } });
@@ -675,11 +921,26 @@ var GrpcStreamClient = class {
   sendContextAssembled(event) {
     this.#write({ context_assembled: { ...event } });
   }
+  #flushBeforeClose() {
+    if (!this.isConnected || this.#call === null) {
+      if (this.#sendQueue.length > 0 || this.#unacked.size > 0) {
+        console.warn(
+          `[synap] closing with ${this.#sendQueue.length} queued and ${this.#unacked.size} unacknowledged event(s) and no stream to send them on; they are lost`
+        );
+      }
+      return;
+    }
+    const queued = this.#sendQueue;
+    this.#sendQueue = [];
+    for (const held of queued) {
+      this.#write({ conversation_event: { ...held.event } });
+    }
+  }
   #write(msg) {
     if (!this.isConnected || this.#call === null) return;
     try {
       this.#call.write(msg);
-    } catch (e) {
+    } catch (e2) {
     }
   }
   async #loadGrpc() {
@@ -732,6 +993,11 @@ var GrpcStreamClient = class {
     const call = stub["Listen"](metadata);
     call.on("data", (msg) => this.#handleMessage(msg));
     call.on("error", (err) => {
+      const creditError = creditErrorFromRpc(err);
+      if (creditError !== null) {
+        this.#handleCreditStop(creditError);
+        return;
+      }
       void this.#handleDisconnect(`error: ${String(err)}`);
     });
     call.on("end", () => {
@@ -741,8 +1007,14 @@ var GrpcStreamClient = class {
     this.#setState("connected");
     this.#reconnectAttempts = 0;
     this.#lastPongAt = Date.now();
+    this.#replayBuffered();
   }
   #handleMessage(msg) {
+    const ack = msg["event_ack"];
+    if (ack) {
+      for (const id of _nullishCoalesce(ack.event_ids, () => ( []))) this.#unacked.delete(id);
+      return;
+    }
     if (msg["context_bundle"]) {
       this.#handleBundle(msg["context_bundle"]);
       return;
@@ -753,7 +1025,7 @@ var GrpcStreamClient = class {
       return;
     }
     const signal = msg["signal"];
-    if (_optionalChain([signal, 'optionalAccess', _ => _.signal_type]) === "closing") {
+    if (_optionalChain([signal, 'optionalAccess', _8 => _8.signal_type]) === "closing") {
       void this.#handleDisconnect("server_signal_closing");
     }
   }
@@ -762,14 +1034,14 @@ var GrpcStreamClient = class {
     const conversationId = String(_nullishCoalesce(bundle["anticipation_conversation_id"], () => ( "")));
     if (bundleType !== UNCACHEABLE_BUNDLE_TYPE) this.#store(bundle, bundleType, conversationId);
     if (bundleType === "compaction_update" && conversationId !== "") {
-      _optionalChain([this, 'access', _2 => _2.#options, 'access', _3 => _3.onCompactionUpdate, 'optionalCall', _4 => _4(conversationId, bundle)]);
+      _optionalChain([this, 'access', _9 => _9.#options, 'access', _10 => _10.onCompactionUpdate, 'optionalCall', _11 => _11(conversationId, bundle)]);
     }
-    _optionalChain([this, 'access', _5 => _5.#options, 'access', _6 => _6.onContext, 'optionalCall', _7 => _7(bundle)]);
+    _optionalChain([this, 'access', _12 => _12.#options, 'access', _13 => _13.onContext, 'optionalCall', _14 => _14(bundle)]);
   }
   #store(bundle, bundleType, conversationId) {
     const itemsByType = {};
     for (const [type, list] of Object.entries(_nullishCoalesce(bundle["items_by_type"], () => ( {})))) {
-      const items = _optionalChain([list, 'optionalAccess', _8 => _8.items]);
+      const items = _optionalChain([list, 'optionalAccess', _15 => _15.items]);
       itemsByType[type] = _nullishCoalesce(items, () => ( []));
     }
     const ttlHint = Number(_nullishCoalesce(bundle["ttl_hint_seconds"], () => ( 0)));
@@ -780,6 +1052,10 @@ var GrpcStreamClient = class {
       // customer; falling back to customer id keeps org-scope bundles usable.
       entityId: String(_nullishCoalesce(bundle["anticipation_user_id"], () => ( ""))) || String(_nullishCoalesce(bundle["anticipation_customer_id"], () => ( ""))) || null,
       conversationId: conversationId || null,
+      // The rung the server retrieved this bundle at. Absent from anything an
+      // older server sent, and absent reads as "named no rung" rather than as
+      // "matches anything".
+      scopeRung: String(_nullishCoalesce(bundle["anticipation_scope_rung"], () => ( ""))) || null,
       itemsByType,
       // 0 means "use the SDK default"; anything else is floored at 60s.
       ttlHintSeconds: ttlHint > 0 ? Math.max(ttlHint, MIN_TTL_SECONDS) : null,
@@ -790,6 +1066,20 @@ var GrpcStreamClient = class {
       ]
     });
   }
+  /**
+   * End the stream because the server refused it for credits.
+   *
+   * Reconnecting cannot clear a credit refusal, so the stream closes and the
+   * typed error is kept on `lastError` for the application to read. Mirrors
+   * Python's `_handle_credit_stop`.
+   */
+  #handleCreditStop(error) {
+    this.#lastError = error;
+    this.#shutdownRequested = true;
+    this.#stopHeartbeat();
+    this.#closeCall();
+    this.#setState("disconnected");
+  }
   async #handleDisconnect(_reason) {
     if (this.#shutdownRequested) return;
     this.#closeCall();
@@ -807,7 +1097,11 @@ var GrpcStreamClient = class {
     if (this.#shutdownRequested) return;
     try {
       await this.#establish();
-    } catch (e2) {
+    } catch (error) {
+      if (isCreditStop(error)) {
+        this.#handleCreditStop(error);
+        return;
+      }
       void this.#handleDisconnect("reconnect_failed");
     }
   }
@@ -828,7 +1122,7 @@ var GrpcStreamClient = class {
         void this.#handleDisconnect("heartbeat_write_error");
       }
     }, HEARTBEAT_INTERVAL_MS);
-    _optionalChain([this, 'access', _9 => _9.#heartbeatTimer, 'access', _10 => _10.unref, 'optionalCall', _11 => _11()]);
+    _optionalChain([this, 'access', _16 => _16.#heartbeatTimer, 'access', _17 => _17.unref, 'optionalCall', _18 => _18()]);
   }
   #stopHeartbeat() {
     if (this.#heartbeatTimer !== null) {
@@ -838,19 +1132,23 @@ var GrpcStreamClient = class {
   }
   #closeCall() {
     try {
-      _optionalChain([this, 'access', _12 => _12.#call, 'optionalAccess', _13 => _13.end, 'call', _14 => _14()]);
+      _optionalChain([this, 'access', _19 => _19.#call, 'optionalAccess', _20 => _20.end, 'call', _21 => _21()]);
     } catch (e4) {
     }
     this.#call = null;
   }
   #setState(state) {
     this.#state = state;
-    _optionalChain([this, 'access', _15 => _15.#options, 'access', _16 => _16.onStateChange, 'optionalCall', _17 => _17(state)]);
+    _optionalChain([this, 'access', _22 => _22.#options, 'access', _23 => _23.onStateChange, 'optionalCall', _24 => _24(state)]);
   }
 };
 
 
 
 
-exports.PROTO_SHA = PROTO_SHA; exports.GrpcStreamClient = GrpcStreamClient;
-//# sourceMappingURL=chunk-3JSE64GW.cjs.map
+
+
+
+
+exports.PROTO_SHA = PROTO_SHA; exports.CREDIT_ABORT_DETAILS = CREDIT_ABORT_DETAILS; exports.CREDIT_STOP_REASONS = CREDIT_STOP_REASONS; exports.creditErrorFromRpc = creditErrorFromRpc; exports.isCreditStop = isCreditStop; exports.GrpcStreamClient = GrpcStreamClient;
+//# sourceMappingURL=chunk-IA2N5NUY.cjs.map