@granular-software/sdk 0.4.37 → 0.4.39

package/dist/cli/index.js

@@ -18991,7 +18991,10 @@ var WSClient = class {
     if (!expiresAt) {
       return;
     }
-    const refreshInMs = Math.max(1e3, expiresAt - Date.now() - TOKEN_REFRESH_LEEWAY_MS);
+    const refreshInMs = Math.max(
+      1e3,
+      expiresAt - Date.now() - TOKEN_REFRESH_LEEWAY_MS
+    );
     const delay = Math.min(refreshInMs, MAX_TIMER_DELAY_MS);
     this.tokenRefreshTimer = setTimeout(() => {
       void this.refreshTokenInBackground();
@@ -19037,7 +19040,10 @@ var WSClient = class {
       return refreshedToken;
     } catch (error2) {
       if (expiresAt > Date.now()) {
-        console.warn("[Granular] Token refresh failed, using current token:", error2);
+        console.warn(
+          "[Granular] Token refresh failed, using current token:",
+          error2
+        );
         return this.token;
       }
       throw error2;
@@ -19064,7 +19070,9 @@ var WSClient = class {
       }
     }
     if (!WebSocketClass) {
-      throw new Error('No WebSocket implementation found. If using Node.js, please install "ws" and pass the constructor to the SDK options: { WebSocketCtor: WebSocket }.');
+      throw new Error(
+        'No WebSocket implementation found. If using Node.js, please install "ws" and pass the constructor to the SDK options: { WebSocketCtor: WebSocket }.'
+      );
     }
     return new Promise((resolve2, reject) => {
       try {
@@ -19196,7 +19204,10 @@ var WSClient = class {
         try {
           this.options.onUnexpectedClose(info2);
         } catch (callbackError) {
-          console.error("[Granular] onUnexpectedClose callback failed:", callbackError);
+          console.error(
+            "[Granular] onUnexpectedClose callback failed:",
+            callbackError
+          );
         }
       }
       this.reconnectTimer = setTimeout(() => {
@@ -19213,7 +19224,10 @@ var WSClient = class {
             try {
               this.options.onReconnectError(reconnectInfo);
             } catch (callbackError) {
-              console.error("[Granular] onReconnectError callback failed:", callbackError);
+              console.error(
+                "[Granular] onReconnectError callback failed:",
+                callbackError
+              );
             }
           }
         });
@@ -19222,7 +19236,10 @@ var WSClient = class {
   }
   handleMessage(message) {
     if (typeof message !== "object" || message === null) return;
-    debugWs("[Granular DEBUG] Received message:", JSON.stringify(message).slice(0, 500));
+    debugWs(
+      "[Granular DEBUG] Received message:",
+      JSON.stringify(message).slice(0, 500)
+    );
     if ("type" in message && message.type === "sync") {
       const syncMessage = message;
       let bytes;
@@ -19252,21 +19269,39 @@ var WSClient = class {
         this.syncState = newSyncState;
         const docAny = this.doc;
         if (docAny.catalog) {
-          debugWs("[Granular DEBUG] Doc catalog sync applied. Keys in catalog:", Object.keys(docAny.catalog || {}));
-          debugWs("[Granular DEBUG] RawToolCatalogs:", Object.keys(docAny.catalog.rawToolCatalogs || {}));
+          debugWs(
+            "[Granular DEBUG] Doc catalog sync applied. Keys in catalog:",
+            Object.keys(docAny.catalog || {})
+          );
+          debugWs(
+            "[Granular DEBUG] RawToolCatalogs:",
+            Object.keys(docAny.catalog.rawToolCatalogs || {})
+          );
         } else {
-          debugWs("[Granular DEBUG] Doc synced but no catalog yet. Keys in doc:", Object.keys(docAny));
+          debugWs(
+            "[Granular DEBUG] Doc synced but no catalog yet. Keys in doc:",
+            Object.keys(docAny)
+          );
         }
         this.emit("sync", this.doc);
       } catch (e) {
         try {
-          debugWs("[Granular DEBUG] receiveSyncMessage failed, trying applyChanges...");
+          debugWs(
+            "[Granular DEBUG] receiveSyncMessage failed, trying applyChanges..."
+          );
           const [newDoc] = Automerge__namespace.applyChanges(this.doc, [bytes]);
           this.doc = newDoc;
           this.emit("sync", this.doc);
-          debugWs("[Granular DEBUG] applyChanges succeeded. Doc:", JSON.stringify(Automerge__namespace.toJS(this.doc)));
+          debugWs(
+            "[Granular DEBUG] applyChanges succeeded. Doc:",
+            JSON.stringify(Automerge__namespace.toJS(this.doc))
+          );
         } catch (applyError) {
-          console.warn("[Granular] Failed to apply sync message (both sync & applyChanges)", e, applyError);
+          console.warn(
+            "[Granular] Failed to apply sync message (both sync & applyChanges)",
+            e,
+            applyError
+          );
         }
       }
       return;
@@ -19275,10 +19310,16 @@ var WSClient = class {
       const snapshotMessage = message;
       try {
         const bytes = new Uint8Array(snapshotMessage.data);
-        debugWs("[Granular DEBUG] Loading Automerge session snapshot bytes:", bytes.length);
+        debugWs(
+          "[Granular DEBUG] Loading Automerge session snapshot bytes:",
+          bytes.length
+        );
         this.doc = Automerge__namespace.load(bytes);
         this.emit("sync", this.doc);
-        debugWs("[Granular DEBUG] Automerge session snapshot loaded. Doc:", JSON.stringify(Automerge__namespace.toJS(this.doc)));
+        debugWs(
+          "[Granular DEBUG] Automerge session snapshot loaded. Doc:",
+          JSON.stringify(Automerge__namespace.toJS(this.doc))
+        );
       } catch (e) {
         console.warn("[Granular] Failed to load snapshot message", e);
       }
@@ -19290,6 +19331,7 @@ var WSClient = class {
         const bytes = new Uint8Array(changeMessage.data);
         const [newDoc] = Automerge__namespace.applyChanges(this.doc, [bytes]);
         this.doc = newDoc;
+        this.emit("change", changeMessage);
         this.emit("sync", this.doc);
       } catch (e) {
         console.warn("[Granular] Failed to apply change message", e);
@@ -19302,12 +19344,16 @@ var WSClient = class {
       if (pending) {
         if (response.type === "rpc_error") {
           pending.reject(
-            new Error(`RPC error: ${response.error?.message || "Unknown error"}`)
+            new Error(
+              `RPC error: ${response.error?.message || "Unknown error"}`
+            )
           );
         } else {
           pending.resolve(response.result);
         }
-        this.messageQueue = this.messageQueue.filter((q) => q.id !== response.id);
+        this.messageQueue = this.messageQueue.filter(
+          (q) => q.id !== response.id
+        );
       }
       return;
     }
@@ -19590,6 +19636,7 @@ function withPromptTranscriptTimeout(promise) {
 var Session = class {
   client;
   clientId;
+  initialQuota;
   jobsMap = /* @__PURE__ */ new Map();
   pendingAgentMessagesByJobId = /* @__PURE__ */ new Map();
   eventListeners = /* @__PURE__ */ new Map();
@@ -19605,9 +19652,10 @@ var Session = class {
   promptCache = /* @__PURE__ */ new Map();
   /** Prompt ids locally answered before the document sync catches up. */
   hiddenPromptIds = /* @__PURE__ */ new Set();
-  constructor(client, clientId) {
+  constructor(client, clientId, options = {}) {
     this.client = client;
     this.clientId = clientId || `client_${Date.now()}`;
+    this.initialQuota = options.initialQuota || null;
     this.setupEventHandlers();
     this.setupToolInvokeHandler();
   }
@@ -19656,6 +19704,16 @@ var Session = class {
   get document() {
     return this.client.doc;
   }
+  get quota() {
+    return this.getQuota();
+  }
+  getQuota() {
+    const quota = this.client.doc.billing?.quota;
+    if (quota && typeof quota === "object") {
+      return quota;
+    }
+    return this.initialQuota;
+  }
   get sessionId() {
     return this.client.currentSessionId;
   }
@@ -21084,9 +21142,10 @@ function normalizeShowRefs(value) {
   const show = {
     entryPaths: normalizeRefs(record.entryPaths),
     listNames: normalizeRefs(record.listNames),
-    variableNames: normalizeRefs(record.variableNames)
+    variableNames: normalizeRefs(record.variableNames),
+    fileIds: normalizeRefs(record.fileIds)
   };
-  return show.entryPaths || show.listNames || show.variableNames ? show : void 0;
+  return show.entryPaths || show.listNames || show.variableNames || show.fileIds ? show : void 0;
 }
 function stringifyTranscriptValue(value, fallback2 = "") {
   if (typeof value === "string") {
@@ -21294,7 +21353,10 @@ function buildJobCodeEntry(jobId, job2) {
     jobId,
     code,
     jobStatus,
-    jobResultPreview: stringifyTranscriptValue(job2.result, "No job result recorded."),
+    jobResultPreview: stringifyTranscriptValue(
+      job2.result,
+      "No job result recorded."
+    ),
     error: error2,
     source: "job_code"
   };
@@ -21303,12 +21365,16 @@ function buildSessionTranscript(input) {
   const liveDoc = input.liveDoc || null;
   const sessionHeap = input.sessionHeap || EMPTY_HEAP;
   const transcript = [];
-  const conversationMessages = asArray(asRecord3(liveDoc?.conversation)?.messages).map((message) => normalizeConversationMessage(message)).filter((message) => Boolean(message));
+  const conversationMessages = asArray(
+    asRecord3(liveDoc?.conversation)?.messages
+  ).map((message) => normalizeConversationMessage(message)).filter((message) => Boolean(message));
   const conversationPromptIds = new Set(
     conversationMessages.map((message) => message.promptId).filter((promptId) => Boolean(promptId))
   );
   const assistantConversationJobIds = new Set(
-    conversationMessages.filter((message) => message.role === "assistant" && Boolean(message.jobId)).map((message) => message.jobId)
+    conversationMessages.filter(
+      (message) => message.role === "assistant" && Boolean(message.jobId)
+    ).map((message) => message.jobId)
   );
   transcript.push(...conversationMessages);
   const jobsById = asRecord3(asRecord3(liveDoc?.jobs)?.byId) || {};
@@ -21326,7 +21392,10 @@ function buildSessionTranscript(input) {
       ...normalizePromptEntries(jobId, job2.prompts, conversationPromptIds)
     );
     if (!assistantConversationJobIds.has(jobId)) {
-      const agentEntries = normalizeAgentMessageEntries(jobId, job2.agentMessages);
+      const agentEntries = normalizeAgentMessageEntries(
+        jobId,
+        job2.agentMessages
+      );
       if (agentEntries.length > 0) {
         transcript.push(...agentEntries);
       } else {
@@ -21511,6 +21580,110 @@ async function invokeRegisteredEffect(effectMap, request) {
   return resolved.handler(request.input, context);
 }
 
+// src/spend.ts
+function toGranularHttpBase(apiUrl) {
+  const url = new URL(apiUrl);
+  if (url.protocol === "ws:") {
+    url.protocol = "http:";
+  } else if (url.protocol === "wss:") {
+    url.protocol = "https:";
+  }
+  url.pathname = url.pathname.replace(/\/ws\/connect$/, "").replace(/\/ws$/, "");
+  if (!url.pathname || url.pathname === "/") {
+    url.pathname = "/granular";
+  }
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+function cleanIdPart(value) {
+  return value.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function buildOpenAISpendEventId(usage, context = {}) {
+  const requestId = usage.requestId?.trim();
+  if (!requestId) return void 0;
+  const scope = context.sessionId || context.environmentId || context.subjectId || context.sandboxId || "global";
+  return ["spend", "openai", scope, requestId].map(cleanIdPart).join("_");
+}
+function pricingEffectiveAtSeconds(value) {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? Math.floor(parsed / 1e3) : null;
+}
+function compactContext(context) {
+  return Object.fromEntries(
+    Object.entries(context).filter(
+      ([, value]) => value != null && value !== ""
+    )
+  );
+}
+function omitTenantId(context) {
+  const scopedContext = { ...context };
+  delete scopedContext.tenantId;
+  return scopedContext;
+}
+async function recordOpenAIUsageSpend(options) {
+  const usageContext = compactContext({
+    ...options.usage.usageContext || {},
+    ...options.context || {}
+  });
+  const context = omitTenantId(usageContext);
+  const spendEventId = options.usage.spendEventId || buildOpenAISpendEventId(options.usage, context);
+  const metadata = {
+    ...options.metadata || {},
+    ...options.usage.rawUsage !== void 0 ? { openaiUsage: options.usage.rawUsage } : {},
+    usageContext: context
+  };
+  const response = await fetch(
+    `${toGranularHttpBase(options.apiUrl)}/control/spend/events`,
+    {
+      method: "POST",
+      cache: "no-store",
+      headers: {
+        Authorization: `Bearer ${options.token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        ...spendEventId ? { spendEventId } : {},
+        sandboxId: context.sandboxId || null,
+        environmentId: context.environmentId || null,
+        sessionId: context.sessionId || null,
+        subjectId: context.subjectId || null,
+        permissionProfileId: context.permissionProfileId || null,
+        source: "openai",
+        lineItemType: "llm_tokens",
+        provider: options.usage.provider,
+        model: options.usage.model,
+        operation: options.usage.operation || "chat.completions",
+        requestId: options.usage.requestId || null,
+        inputTokens: options.usage.inputTokens,
+        outputTokens: options.usage.outputTokens,
+        cachedInputTokens: options.usage.cachedInputTokens,
+        reasoningTokens: options.usage.reasoningTokens,
+        quantity: options.usage.totalTokens,
+        quantityUnit: "tokens",
+        inputPricePerMillionMicros: options.usage.inputPricePerMillionMicros,
+        cachedInputPricePerMillionMicros: options.usage.cachedInputPricePerMillionMicros,
+        outputPricePerMillionMicros: options.usage.outputPricePerMillionMicros,
+        amountMicros: options.usage.amountMicros,
+        currency: options.usage.currency,
+        pricingSource: options.usage.pricingSource,
+        pricingEffectiveAt: pricingEffectiveAtSeconds(
+          options.usage.pricingEffectiveAt
+        ),
+        estimated: false,
+        metadata
+      })
+    }
+  );
+  if (!response.ok) {
+    throw new Error(
+      `Granular spend event failed (${response.status}): ${await response.text()}`
+    );
+  }
+  return response.json();
+}
+
 // src/manifest-metamodels.ts
 function buildFieldMetamodelMutations(fieldPath, spec) {
   return DEFAULT_METAMODEL_PACKAGES.flatMap(
@@ -21575,6 +21748,25 @@ var LOCAL_CONTROL_REQUEST_RETRY_DELAY_MS = 500;
 var SESSION_DATA_REQUEST_RETRY_COUNT = 4;
 var SESSION_DATA_REQUEST_RETRY_DELAY_MS = 500;
 var EFFECT_HOST_CONNECT_TIMEOUT_MS = 15e3;
+function filenameFromUploadBody(body) {
+  const maybe = body;
+  return typeof maybe.name === "string" && maybe.name.trim() ? maybe.name.trim() : null;
+}
+function contentTypeFromUploadBody(body) {
+  const maybe = body;
+  return typeof maybe.type === "string" && maybe.type.trim() ? maybe.type.trim() : null;
+}
+function bodyInitFromSessionFileUpload(body) {
+  if (typeof body === "string") return body;
+  if (body instanceof ArrayBuffer) return body;
+  if (ArrayBuffer.isView(body)) {
+    return body.buffer.slice(
+      body.byteOffset,
+      body.byteOffset + body.byteLength
+    );
+  }
+  return body;
+}
 var EFFECT_CATALOG_SYNC_TIMEOUT_MS = 3e4;
 var EFFECT_CATALOG_SYNC_RETRY_COUNT = 3;
 var EFFECT_CATALOG_SYNC_RETRY_DELAY_MS = 1e3;
@@ -23012,7 +23204,7 @@ var EnvironmentSession = class extends Session {
   /** The last known graph container status, updated by checkReadiness() or on heartbeat */
   graphContainerStatus = null;
   constructor(client, environment, clientId, options = {}) {
-    super(client, clientId);
+    super(client, clientId, { initialQuota: options.initialQuota });
     this.environment = environment;
     this.sessionDataRoutePrefix = options.sessionDataRoutePrefix || "/orchestrator/ws/sessions";
   }
@@ -23059,7 +23251,7 @@ var EnvironmentSession = class extends Session {
     const doc = this.document;
     return normalizeHeapSnapshot(doc?.heap);
   }
-  async sessionDataRequest(path7, query, init2 = {}) {
+  buildSessionDataUrl(path7, query) {
     const searchParams = new URLSearchParams();
     for (const [key, value] of Object.entries(query || {})) {
       if (value !== null && typeof value !== "undefined" && value !== "") {
@@ -23067,20 +23259,21 @@ var EnvironmentSession = class extends Session {
       }
     }
     const queryString = searchParams.toString();
-    const url = `${this.environment.runtimeBaseUrl}${this.sessionDataRoutePrefix}/${encodeURIComponent(this.sessionId)}${path7}${queryString ? `?${queryString}` : ""}`;
-    const body = typeof init2.body === "undefined" ? void 0 : JSON.stringify(init2.body);
+    return `${this.environment.runtimeBaseUrl}${this.sessionDataRoutePrefix}/${encodeURIComponent(this.sessionId)}${path7}${queryString ? `?${queryString}` : ""}`;
+  }
+  async sessionDataFetch(path7, query, init2 = {}) {
+    const url = this.buildSessionDataUrl(path7, query);
     for (let attempt = 1; attempt <= SESSION_DATA_REQUEST_RETRY_COUNT; attempt += 1) {
       try {
+        const headers = new Headers(init2.headers);
+        headers.set("Authorization", `Bearer ${this.environment.authToken}`);
         const response = await fetch(url, {
           method: init2.method || "GET",
-          headers: {
-            Authorization: `Bearer ${this.environment.authToken}`,
-            "Content-Type": "application/json"
-          },
-          ...typeof body === "undefined" ? {} : { body }
+          headers,
+          ...typeof init2.body === "undefined" ? {} : { body: init2.body }
         });
         if (response.ok) {
-          return response.json();
+          return response;
         }
         const errorText = await response.text();
         const error2 = new Error(
@@ -23101,6 +23294,15 @@ var EnvironmentSession = class extends Session {
     }
     throw new Error(`Session data API Error: exhausted retries for ${url}`);
   }
+  async sessionDataRequest(path7, query, init2 = {}) {
+    const body = typeof init2.body === "undefined" ? void 0 : JSON.stringify(init2.body);
+    const response = await this.sessionDataFetch(path7, query, {
+      method: init2.method || "GET",
+      headers: { "Content-Type": "application/json" },
+      ...typeof body === "undefined" ? {} : { body }
+    });
+    return response.json();
+  }
   async collectAllSessionItems(listPage) {
     const items = [];
     let cursor = null;
@@ -23141,6 +23343,53 @@ var EnvironmentSession = class extends Session {
       )
     };
   }
+  get files() {
+    return {
+      list: (options = {}) => this.sessionDataRequest(
+        "/files",
+        options
+      ),
+      get: (fileId) => this.sessionDataRequest(
+        `/files/${encodeURIComponent(fileId)}`
+      ),
+      upload: async (body, options = {}) => {
+        const headers = new Headers({
+          "Content-Type": options.contentType || contentTypeFromUploadBody(body) || "application/octet-stream",
+          "x-granular-filename": options.filename || filenameFromUploadBody(body) || "upload",
+          "x-granular-file-source": options.source || "sdk"
+        });
+        if (options.parentFileIds?.length) {
+          headers.set(
+            "x-granular-parent-file-ids",
+            JSON.stringify(options.parentFileIds)
+          );
+        }
+        if (options.metadata) {
+          headers.set(
+            "x-granular-file-metadata",
+            JSON.stringify(options.metadata)
+          );
+        }
+        const response = await this.sessionDataFetch("/files", void 0, {
+          method: "POST",
+          headers,
+          body: bodyInitFromSessionFileUpload(body)
+        });
+        return response.json();
+      },
+      download: async (fileId) => {
+        const response = await this.sessionDataFetch(
+          `/files/${encodeURIComponent(fileId)}/content`
+        );
+        return response.arrayBuffer();
+      },
+      delete: (fileId) => this.sessionDataRequest(
+        `/files/${encodeURIComponent(fileId)}`,
+        void 0,
+        { method: "DELETE" }
+      )
+    };
+  }
   get heap() {
     return {
       entries: {
@@ -23811,6 +24060,15 @@ var Granular = class _Granular {
     const environment = this.bindEnvironmentHandle(envData);
     return this.bindWebSocketEnvironmentSession(environment, clientId, minted);
   }
+  async recordOpenAIUsageSpend(usage, context, options) {
+    return recordOpenAIUsageSpend({
+      apiUrl: this.apiUrl,
+      token: this.apiKey,
+      usage,
+      context,
+      metadata: options?.metadata
+    });
+  }
   /**
    * Mark a session closed in the control plane. If `environment` is the connected handle for that
    * `sessionId`, disconnects the WebSocket so the runtime tears down cleanly.
@@ -23965,7 +24223,8 @@ var Granular = class _Granular {
     const environmentSession = new EnvironmentSession(
       client,
       environment,
-      clientId
+      clientId,
+      { initialQuota: session2.quota || null }
     );
     await environmentSession.hello();
     return environmentSession;