@coldiq/mcp 0.3.18 → 0.3.19

package/dist/tools/get-session-usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-session-usage.d.ts","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB,sBAAsB,CAAA;AAEtD,eAAO,MAAM,0BAA0B,QAMuB,CAAA;AAE9D,eAAO,MAAM,qBAAqB,IAAK,CAAA;AAEvC,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GAG3E"}
+{"version":3,"file":"get-session-usage.d.ts","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,mBAAmB,sBAAsB,CAAA;AAEtD,eAAO,MAAM,0BAA0B,QAOY,CAAA;AAEnD,eAAO,MAAM,qBAAqB,IAAK,CAAA;AAMvC,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GA8B3E"}

package/dist/tools/get-session-usage.js

@@ -1,14 +1,45 @@
 import { getSessionUsage } from '../session-usage.js';
+import { callApi } from '../client.js';
 export const getSessionUsageName = 'get_session_usage';
-export const getSessionUsageDescription = 'Report the ColdIQ credits spent so far in THIS conversation (the current MCP session). ' +
-    'Returns the total credits charged, the number of billed calls, a per-endpoint breakdown of where ' +
-    'credits went (highest spend first), and the account balance reported after the most recent billed call. ' +
-    'Use this to answer "how many credits has this chat used" or "what did I spend credits on here". ' +
-    'Note: it counts only calls made during the current session and resets if the conversation restarts; ' +
-    'for the authoritative live balance use get_credit_balance.';
+export const getSessionUsageDescription = 'Report the ColdIQ credits spent so far in this MCP process: total credits charged, billed-call count, ' +
+    'and a per-endpoint breakdown (highest spend first), plus the live authoritative balance for reconciliation. ' +
+    'The session tally is BEST-EFFORT — it sums what each call reported at request time and therefore: (a) cannot ' +
+    'see out-of-band async settlement (webhook refunds/charges that land after the call returns), (b) excludes ' +
+    'transport failures that never reached the server, and (c) persists for the life of the MCP process, so a ' +
+    'reused process can include earlier conversations. Treat session_spend as indicative; use authoritative_balance ' +
+    '(or get_credit_balance) as the source of truth.';
 export const getSessionUsageSchema = {};
+const SESSION_USAGE_NOTE = 'session_spend is a best-effort, header-derived tally for this MCP process; it excludes out-of-band async ' +
+    'settlement and resets only when the process restarts. Reconcile against authoritative_balance (live).';
 export async function getSessionUsageHandler(_input) {
     const usage = getSessionUsage();
-    return { content: [{ type: 'text', text: JSON.stringify({ data: usage }) }] };
+    // Reconcile against the authoritative balance. /me/credits is not billed, so this
+    // call never pollutes the tally. Best-effort: a failure just omits the field.
+    let authoritativeBalance;
+    try {
+        const res = await callApi('GET', '/me/credits');
+        if (res.ok && res.data && typeof res.data === 'object') {
+            const bal = res.data.data?.balance;
+            if (typeof bal === 'number')
+                authoritativeBalance = bal;
+        }
+    }
+    catch {
+        // ignore — reconciliation is best-effort
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    data: {
+                        ...usage,
+                        ...(authoritativeBalance !== undefined ? { authoritative_balance: authoritativeBalance } : {}),
+                        note: SESSION_USAGE_NOTE,
+                    },
+                }),
+            },
+        ],
+    };
 }
 //# sourceMappingURL=get-session-usage.js.map

package/dist/tools/get-session-usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-session-usage.js","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAErD,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAA;AAEtD,MAAM,CAAC,MAAM,0BAA0B,GACrC,yFAAyF;IACzF,mGAAmG;IACnG,0GAA0G;IAC1G,kGAAkG;IAClG,sGAAsG;IACtG,4DAA4D,CAAA;AAE9D,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAA;AAEvC,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAA+B;IAC1E,MAAM,KAAK,GAAG,eAAe,EAAE,CAAA;IAC/B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAA;AACxF,CAAC"}
+{"version":3,"file":"get-session-usage.js","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAA;AAEtD,MAAM,CAAC,MAAM,0BAA0B,GACrC,wGAAwG;IACxG,8GAA8G;IAC9G,+GAA+G;IAC/G,4GAA4G;IAC5G,2GAA2G;IAC3G,iHAAiH;IACjH,iDAAiD,CAAA;AAEnD,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAA;AAEvC,MAAM,kBAAkB,GACtB,2GAA2G;IAC3G,uGAAuG,CAAA;AAEzG,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAA+B;IAC1E,MAAM,KAAK,GAAG,eAAe,EAAE,CAAA;IAE/B,kFAAkF;IAClF,8EAA8E;IAC9E,IAAI,oBAAwC,CAAA;IAC5C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,aAAa,CAAC,CAAA;QAC/C,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,IAAI,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,MAAM,GAAG,GAAI,GAAG,CAAC,IAAyC,CAAC,IAAI,EAAE,OAAO,CAAA;YACxE,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,oBAAoB,GAAG,GAAG,CAAA;QACzD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,yCAAyC;IAC3C,CAAC;IAED,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,IAAI,EAAE;wBACJ,GAAG,KAAK;wBACR,GAAG,CAAC,oBAAoB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC9F,IAAI,EAAE,kBAAkB;qBACzB;iBACF,CAAC;aACH;SACF;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldiq/mcp",
-  "version": "0.3.18",
+  "version": "0.3.19",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

package/src/tools/get-session-usage.ts

@@ -1,18 +1,51 @@
 import { getSessionUsage } from '../session-usage.js'
+import { callApi } from '../client.js'
 
 export const getSessionUsageName = 'get_session_usage'
 
 export const getSessionUsageDescription =
-  'Report the ColdIQ credits spent so far in THIS conversation (the current MCP session). ' +
-  'Returns the total credits charged, the number of billed calls, a per-endpoint breakdown of where ' +
-  'credits went (highest spend first), and the account balance reported after the most recent billed call. ' +
-  'Use this to answer "how many credits has this chat used" or "what did I spend credits on here". ' +
-  'Note: it counts only calls made during the current session and resets if the conversation restarts; ' +
-  'for the authoritative live balance use get_credit_balance.'
+  'Report the ColdIQ credits spent so far in this MCP process: total credits charged, billed-call count, ' +
+  'and a per-endpoint breakdown (highest spend first), plus the live authoritative balance for reconciliation. ' +
+  'The session tally is BEST-EFFORT — it sums what each call reported at request time and therefore: (a) cannot ' +
+  'see out-of-band async settlement (webhook refunds/charges that land after the call returns), (b) excludes ' +
+  'transport failures that never reached the server, and (c) persists for the life of the MCP process, so a ' +
+  'reused process can include earlier conversations. Treat session_spend as indicative; use authoritative_balance ' +
+  '(or get_credit_balance) as the source of truth.'
 
 export const getSessionUsageSchema = {}
 
+const SESSION_USAGE_NOTE =
+  'session_spend is a best-effort, header-derived tally for this MCP process; it excludes out-of-band async ' +
+  'settlement and resets only when the process restarts. Reconcile against authoritative_balance (live).'
+
 export async function getSessionUsageHandler(_input: Record<string, unknown>) {
   const usage = getSessionUsage()
-  return { content: [{ type: 'text' as const, text: JSON.stringify({ data: usage }) }] }
+
+  // Reconcile against the authoritative balance. /me/credits is not billed, so this
+  // call never pollutes the tally. Best-effort: a failure just omits the field.
+  let authoritativeBalance: number | undefined
+  try {
+    const res = await callApi('GET', '/me/credits')
+    if (res.ok && res.data && typeof res.data === 'object') {
+      const bal = (res.data as { data?: { balance?: unknown } }).data?.balance
+      if (typeof bal === 'number') authoritativeBalance = bal
+    }
+  } catch {
+    // ignore — reconciliation is best-effort
+  }
+
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({
+          data: {
+            ...usage,
+            ...(authoritativeBalance !== undefined ? { authoritative_balance: authoritativeBalance } : {}),
+            note: SESSION_USAGE_NOTE,
+          },
+        }),
+      },
+    ],
+  }
 }

package/tests/session-usage.test.ts

@@ -6,6 +6,7 @@ import {
   resetSessionUsage,
 } from '../src/session-usage.js'
 import { initClient, callApi } from '../src/client.js'
+import { getSessionUsageHandler } from '../src/tools/get-session-usage.js'
 
 describe('session-usage accumulator', () => {
   beforeEach(() => {
@@ -128,3 +129,34 @@ describe('callApi records credit charges into session usage', () => {
     expect(getSessionUsage().billedCalls).toBe(0)
   })
 })
+
+// --- B2: get_session_usage reconciles against the authoritative balance ------
+describe('get_session_usage handler reconciliation (B2)', () => {
+  const originalFetch = globalThis.fetch
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+    resetSessionUsage(0)
+  })
+  afterEach(() => { globalThis.fetch = originalFetch })
+
+  it('attaches the live authoritative_balance and a best-effort note', async () => {
+    recordCharge('/email/find', 2, 500) // header-derived tally (may drift from real balance)
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ data: { balance: 480.5, usedThisMonth: 20 } }), { status: 200 }),
+    ) as typeof fetch
+
+    const res = await getSessionUsageHandler({})
+    const payload = JSON.parse(res.content[0].text).data
+    expect(payload.totalCreditsCharged).toBe(2)
+    expect(payload.authoritative_balance).toBe(480.5) // reconciliation source of truth
+    expect(payload.note).toMatch(/best-effort/i)
+  })
+
+  it('still returns the tally + note when the balance lookup fails (best-effort)', async () => {
+    globalThis.fetch = vi.fn(async () => new Response('nope', { status: 502 })) as typeof fetch
+    const res = await getSessionUsageHandler({})
+    const payload = JSON.parse(res.content[0].text).data
+    expect(payload.authoritative_balance).toBeUndefined()
+    expect(payload.note).toBeTruthy()
+  })
+})