@maximem/synap-js-sdk 0.4.8 → 0.5.2

package/dist/{chunk-T5QQBJ6T.js → chunk-DJPYUPSV.js}

@@ -1,5 +1,11 @@
+import {
+  InsufficientCreditsError,
+  RateLimitError,
+  newCorrelationId
+} from "./chunk-BWMPKLFG.js";
+
 // src/grpc/descriptor.ts
-var PROTO_SHA = "a58c9b031b41530d";
+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",
@@ -216,6 +230,14 @@ var SYNAP_PROTO_DESCRIPTOR = {
                   "keyType": "string",
                   "type": "string",
                   "id": 14
+                },
+                "event_id": {
+                  "type": "string",
+                  "id": 17
+                },
+                "sent_at_ms": {
+                  "type": "int64",
+                  "id": 18
                 }
               }
             },
@@ -257,7 +279,8 @@ var SYNAP_PROTO_DESCRIPTOR = {
                   "oneof": [
                     "context_bundle",
                     "heartbeat_pong",
-                    "signal"
+                    "signal",
+                    "event_ack"
                   ]
                 }
               },
@@ -273,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
                 }
               }
             },
@@ -616,6 +656,192 @@ var SYNAP_PROTO_DESCRIPTOR = {
   }
 };
 
+// src/grpc/outbox-journal.ts
+var OP_QUEUED = "q";
+var OP_UNACKED = "u";
+var OP_ACKED = "a";
+var OP_DROPPED = "d";
+var COMPACT_AT_LINES = 500;
+var _fs = null;
+var _fsResolved = false;
+var _fsPending = null;
+async function resolveFs() {
+  if (_fsResolved) return;
+  if (_fsPending === null) {
+    _fsPending = (async () => {
+      try {
+        _fs = await import("fs");
+      } catch {
+        _fs = null;
+      }
+      _fsResolved = true;
+    })();
+  }
+  await _fsPending;
+}
+function defaultOutboxRoot() {
+  try {
+    const env = globalThis.process?.env;
+    const home = env?.["SYNAP_STORAGE_PATH"] ?? env?.["HOME"] ?? env?.["USERPROFILE"];
+    if (home !== void 0 && home !== "") {
+      return env?.["SYNAP_STORAGE_PATH"] !== void 0 && env["SYNAP_STORAGE_PATH"] !== "" ? env["SYNAP_STORAGE_PATH"] : `${home}/.synap`;
+    }
+  } catch {
+  }
+  return "";
+}
+var OutboxJournal = class {
+  path;
+  #fs;
+  #lines = 0;
+  #disabled = false;
+  /**
+   * @param root  Directory the journal lives under. One file per instance id,
+   *              because two clients on one instance share a stream in the
+   *              registry and so the events are the instance's, not the
+   *              object's.
+   */
+  /**
+   * Resolve `node:fs` once for the process. The stream client awaits this in
+   * `connect()` before any event can flow, so by the time anything is written
+   * the module is in hand and every append is a plain synchronous call. An
+   * async write still pending when the process dies is a write that did not
+   * happen, and this file exists for exactly that case.
+   */
+  static async init() {
+    await resolveFs();
+  }
+  constructor(root, instanceId, fsImpl) {
+    this.path = root === "" ? "" : `${root}/outbox/${instanceId}.jsonl`;
+    this.#fs = fsImpl !== void 0 ? fsImpl : _fs;
+    if (this.#fs === null || this.path === "") this.#disabled = true;
+  }
+  get enabled() {
+    return !this.#disabled;
+  }
+  // ------------------------------------------------------------------ writes
+  recordQueued(event) {
+    this.#append({ op: OP_QUEUED, e: event });
+  }
+  recordUnacked(event) {
+    this.#append({ op: OP_UNACKED, e: event });
+  }
+  recordAcked(id) {
+    this.#append({ op: OP_ACKED, id });
+  }
+  /** An event the buffers gave up on. It does not come back on restart either:
+   *  replaying what the depth or age bound deliberately evicted would quietly
+   *  undo the bound that evicted it. */
+  recordDropped(id) {
+    if (id === void 0 || id === "") return;
+    this.#append({ op: OP_DROPPED, id });
+  }
+  // ------------------------------------------------------------------- reads
+  /**
+   * Replay the file into `{queued, unacked}`, oldest first.
+   *
+   * A partial last line from a kill mid-append stops the read there. What came
+   * before it is the prefix that was durably written; a torn line is an event
+   * the caller was never told had been accepted.
+   */
+  load() {
+    const empty = { queued: [], unacked: [] };
+    if (this.#disabled || this.#fs === null) return empty;
+    let text;
+    try {
+      if (!this.#fs.existsSync(this.path)) return empty;
+      text = this.#fs.readFileSync(this.path, "utf8");
+    } catch {
+      return empty;
+    }
+    const queued = /* @__PURE__ */ new Map();
+    const unacked = /* @__PURE__ */ new Map();
+    let lines = 0;
+    for (const raw of text.split("\n")) {
+      const line = raw.trim();
+      if (line === "") continue;
+      let rec;
+      try {
+        rec = JSON.parse(line);
+      } catch {
+        break;
+      }
+      lines += 1;
+      const id = rec.op === OP_QUEUED || rec.op === OP_UNACKED ? rec.e?.event_id : rec.id;
+      if (id === void 0 || id === "") continue;
+      if (rec.op === OP_QUEUED) {
+        queued.set(id, rec.e);
+      } else if (rec.op === OP_UNACKED) {
+        queued.delete(id);
+        unacked.set(id, rec.e);
+      } else if (rec.op === OP_ACKED || rec.op === OP_DROPPED) {
+        queued.delete(id);
+        unacked.delete(id);
+      }
+    }
+    this.#lines = lines;
+    return { queued: [...queued.values()], unacked: [...unacked.values()] };
+  }
+  // ------------------------------------------------------------- maintenance
+  /**
+   * Rewrite the file to hold exactly what the buffers hold now.
+   *
+   * Written beside the target and renamed over it, because rename is atomic: a
+   * kill during a compaction leaves either the whole old file or the whole new
+   * one, never a half-written mix.
+   */
+  compact(queued, unacked) {
+    if (this.#disabled || this.#fs === null) return;
+    if (queued.length === 0 && unacked.length === 0) {
+      this.clear();
+      return;
+    }
+    try {
+      this.#mkdir();
+      const body = [
+        ...unacked.map((e) => JSON.stringify({ op: OP_UNACKED, e })),
+        ...queued.map((e) => JSON.stringify({ op: OP_QUEUED, e }))
+      ].join("\n") + "\n";
+      const tmp = `${this.path}.${Date.now()}.tmp`;
+      this.#fs.writeFileSync(tmp, body, "utf8");
+      this.#fs.renameSync(tmp, this.path);
+      this.#lines = queued.length + unacked.length;
+    } catch {
+    }
+  }
+  /** Nothing is outstanding, so there is nothing to replay. */
+  clear() {
+    if (this.#disabled || this.#fs === null) return;
+    try {
+      this.#fs.unlinkSync(this.path);
+    } catch {
+    }
+    this.#lines = 0;
+  }
+  get needsCompaction() {
+    return this.#lines >= COMPACT_AT_LINES;
+  }
+  // ---------------------------------------------------------------- internal
+  #mkdir() {
+    const dir = this.path.slice(0, this.path.lastIndexOf("/"));
+    this.#fs?.mkdirSync(dir, { recursive: true });
+  }
+  #append(record) {
+    if (this.#disabled || this.#fs === null) return;
+    try {
+      this.#mkdir();
+      this.#fs.appendFileSync(this.path, `${JSON.stringify(record)}
+`, "utf8");
+      this.#lines += 1;
+    } catch (err) {
+      console.warn(
+        `[synap] outbox journal write failed (${String(err)}); buffered events will not survive a restart from here on`
+      );
+      this.#disabled = true;
+    }
+  }
+};
+
 // src/grpc/stream-client.ts
 var UNCACHEABLE_BUNDLE_TYPE = "reactive";
 var MAX_RECONNECT_ATTEMPTS = 10;
@@ -624,7 +850,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 = metadataValue(metadata, "request-id") ?? correlationId;
+  const manageUrl = metadataValue(metadata, "credit-manage-url");
+  if (reason === "overages_disabled") {
+    return new 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 RateLimitError(details, {
+    correlationId: requestId,
+    reason,
+    upgradeUrl: metadataValue(metadata, "credit-upgrade-url"),
+    manageUrl
+  });
+}
+function isCreditStop(error) {
+  if (!(error instanceof InsufficientCreditsError) && !(error instanceof RateLimitError)) {
+    return false;
+  }
+  const reason = error.reason;
+  return typeof reason === "string" && CREDIT_STOP_REASONS.has(reason);
+}
 var GrpcStreamClient = class {
   host;
   port;
@@ -636,6 +921,19 @@ 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;
+  // Disk backing for the two buffers above. They survive a dropped
+  // connection and not the process; this is what the next start reads.
+  #journal;
   #grpc = null;
   #ServiceStub = null;
   #credentials;
@@ -652,6 +950,10 @@ var GrpcStreamClient = class {
     this.useTls = options.useTls ?? true;
     this.#sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     this.#connectTimeoutMs = options.connectTimeoutMs ?? 1e4;
+    this.#journal = new OutboxJournal(
+      options.outboxPath ?? defaultOutboxRoot(),
+      credentials.instanceId
+    );
   }
   get currentState() {
     return this.#state;
@@ -659,21 +961,190 @@ 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();
+    await OutboxJournal.init();
     this.#shutdownRequested = false;
+    this.#lastError = null;
+    this.#restoreFromJournal();
     await this.#establish();
     this.#startHeartbeat();
   }
+  /**
+   * Pull a previous process's unsent events back into the send queue.
+   *
+   * Everything lands in the send queue, including what was unacknowledged last
+   * time. The stream those events were written to is gone, so "the server may
+   * already have it" is not a state we can resume; it has to be written again.
+   * That is safe because each event carries the id it was first sent with and
+   * the server drops a second sighting of it before dispatch, so an event it
+   * DID process is deduplicated there rather than doubling the turn.
+   */
+  #restoreFromJournal() {
+    const { queued, unacked } = this.#journal.load();
+    if (queued.length === 0 && unacked.length === 0) return;
+    const now = Date.now();
+    for (const event of [...unacked, ...queued]) {
+      this.#sendQueue.push({
+        queuedAt: now,
+        event
+      });
+    }
+    console.warn(
+      `[synap] restored ${unacked.length + queued.length} event(s) from the previous process (${unacked.length} unacknowledged, ${queued.length} queued); they go out on this stream`
+    );
+    this.#compactJournal();
+  }
+  #compactJournal() {
+    this.#journal.compact(
+      this.#sendQueue.map((h) => h.event),
+      [...this.#unacked.values()].map(
+        (h) => h.event
+      )
+    );
+  }
   async disconnect() {
     this.#shutdownRequested = true;
     this.#stopHeartbeat();
-    this.#closeCall();
+    this.#flushBeforeClose();
+    const call = this.#call;
+    if (call !== null) {
+      try {
+        call.end();
+      } catch {
+      }
+      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.#compactJournal();
     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 : newCorrelationId(),
+      sent_at_ms: 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();
+      this.#journal.recordDropped(evicted?.event.event_id);
+      console.warn(
+        `[synap] send queue full (max=${SEND_QUEUE_MAX_DEPTH}); dropping oldest event (event_type=${evicted?.event.event_type})`
+      );
+    }
+    this.#sendQueue.push({ queuedAt: Date.now(), event });
+    this.#journal.recordQueued(event);
+  }
+  #pruneQueue() {
+    const cutoff = Date.now() - SEND_QUEUE_MAX_AGE_MS;
+    while (this.#sendQueue.length > 0 && (this.#sendQueue[0]?.queuedAt ?? 0) < cutoff) {
+      const expired = this.#sendQueue.shift();
+      this.#journal.recordDropped(expired?.event.event_id);
+      console.warn(
+        `[synap] queued event expired (age>${SEND_QUEUE_MAX_AGE_MS}ms); dropping (event_type=${expired?.event.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);
+      this.#journal.recordDropped(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 });
+    this.#journal.recordUnacked(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 } });
@@ -684,6 +1155,21 @@ 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 {
@@ -741,6 +1227,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", () => {
@@ -750,8 +1241,18 @@ 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 ack.event_ids ?? []) {
+        this.#unacked.delete(id);
+        this.#journal.recordAcked(id);
+      }
+      if (this.#journal.needsCompaction) this.#compactJournal();
+      return;
+    }
     if (msg["context_bundle"]) {
       this.#handleBundle(msg["context_bundle"]);
       return;
@@ -803,6 +1304,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();
@@ -820,7 +1335,11 @@ var GrpcStreamClient = class {
     if (this.#shutdownRequested) return;
     try {
       await this.#establish();
-    } catch {
+    } catch (error) {
+      if (isCreditStop(error)) {
+        this.#handleCreditStop(error);
+        return;
+      }
       void this.#handleDisconnect("reconnect_failed");
     }
   }
@@ -864,6 +1383,10 @@ var GrpcStreamClient = class {
 
 export {
   PROTO_SHA,
+  CREDIT_ABORT_DETAILS,
+  CREDIT_STOP_REASONS,
+  creditErrorFromRpc,
+  isCreditStop,
   GrpcStreamClient
 };
-//# sourceMappingURL=chunk-T5QQBJ6T.js.map
+//# sourceMappingURL=chunk-DJPYUPSV.js.map