sentinelayer-cli 0.31.4 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.31.4",
+  "version": "0.32.0",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/ai/client.js

@@ -146,6 +146,70 @@ function extractTextFromResponse(provider, payload) {
   return "";
 }
 
+function normalizeUsageNumber(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return 0;
+  }
+  return Math.floor(parsed);
+}
+
+function buildUsagePayload({ provider, model, inputTokens = 0, outputTokens = 0, totalTokens = 0 } = {}) {
+  const input = normalizeUsageNumber(inputTokens);
+  const output = normalizeUsageNumber(outputTokens);
+  const total = normalizeUsageNumber(totalTokens) || input + output;
+  if (total <= 0 && input + output <= 0) {
+    return null;
+  }
+  return {
+    inputTokens: input,
+    outputTokens: output,
+    totalTokens: total,
+    model,
+    provider,
+  };
+}
+
+function extractUsageFromResponse(provider, payload, model) {
+  if (!payload || typeof payload !== "object") {
+    return null;
+  }
+
+  if (provider === "openai") {
+    const usage = payload.usage || {};
+    return buildUsagePayload({
+      provider,
+      model,
+      inputTokens: usage.prompt_tokens ?? usage.input_tokens,
+      outputTokens: usage.completion_tokens ?? usage.output_tokens,
+      totalTokens: usage.total_tokens,
+    });
+  }
+
+  if (provider === "anthropic") {
+    const usage = payload.usage || {};
+    return buildUsagePayload({
+      provider,
+      model,
+      inputTokens: usage.input_tokens,
+      outputTokens: usage.output_tokens,
+    });
+  }
+
+  if (provider === "google") {
+    const usage = payload.usageMetadata || payload.usage_metadata || {};
+    return buildUsagePayload({
+      provider,
+      model,
+      inputTokens: usage.promptTokenCount ?? usage.prompt_token_count,
+      outputTokens: usage.candidatesTokenCount ?? usage.candidates_token_count,
+      totalTokens: usage.totalTokenCount ?? usage.total_token_count,
+    });
+  }
+
+  return null;
+}
+
 function buildProviderRequest({ provider, apiKey, model, prompt, stream }) {
   const normalizedProvider = normalizeProvider(provider);
   const normalizedPrompt = normalizePrompt(prompt);
@@ -527,6 +591,13 @@ export class MultiProviderApiClient {
         } else {
           const payload = await response.json();
           text = extractTextFromResponse(resolvedProvider, payload);
+          const usage = extractUsageFromResponse(resolvedProvider, payload, resolvedModel);
+          return {
+            provider: resolvedProvider,
+            model: resolvedModel,
+            text,
+            usage: usage || undefined,
+          };
         }
 
         return {

package/src/commands/session.js

@@ -87,6 +87,7 @@ import {
 import { readSessionPreview } from "../session/preview.js";
 import {
   createSessionMessageAction,
+  fetchSessionUsageLedger,
   fetchSessionPinnedMessages,
   listSessionMessageActions,
   listSessionsFromApi,
@@ -108,6 +109,12 @@ import {
 } from "../session/rotating-log.js";
 import { buildSessionRecap } from "../session/recap.js";
 import { computeTranscriptStats } from "../session/transcript.js";
+import {
+  buildSessionUsageReport,
+  buildSessionUsageReportFromLedgerPayload,
+  renderSessionUsageMarkdown,
+  renderSessionUsageSummary,
+} from "../session/usage-report.js";
 import { deriveSessionTitle } from "../session/senti-naming.js";
 import { pushSessionTitleToApi } from "../session/title-sync.js";
 import {
@@ -6487,6 +6494,120 @@ export function registerSessionCommand(program) {
       }
     });
 
+  session
+    .command("usage <sessionId>")
+    .description(
+      "Show a sanitized token/cost usage report for a session without raw prompts, responses, or config values",
+    )
+    .option(
+      "--remote",
+      "Hydrate from the SentinelLayer API before rendering (uses the authenticated account-scoped session events endpoint)",
+    )
+    .option("--recent <n>", "Recent ledger entries to include in the report (0-50)", "10")
+    .option("--format <format>", "Output format: summary, markdown, or json", "summary")
+    .option("--out <file>", "Write the selected report format to a file")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable JSON output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const emitJson = shouldEmitJson(options, command);
+      const requestedFormat = emitJson
+        ? "json"
+        : normalizeString(options.format || "summary").toLowerCase();
+      if (!["summary", "markdown", "json"].includes(requestedFormat)) {
+        throw new Error("--format must be one of: summary, markdown, json.");
+      }
+
+      let hydration = null;
+      let hostedUsage = null;
+      let events = [];
+      let dedupedEvents = [];
+      let report = null;
+      if (options.remote) {
+        hostedUsage = await fetchSessionUsageLedger(normalizedSessionId, {
+          targetPath,
+          limit: 500,
+        });
+        if (hostedUsage.ok) {
+          report = buildSessionUsageReportFromLedgerPayload({
+            sessionId: normalizedSessionId,
+            payload: hostedUsage.payload,
+            recentLimit: options.recent,
+          });
+        } else {
+          hydration = await hydrateSessionFromRemote({
+            sessionId: normalizedSessionId,
+            targetPath,
+          }).catch((error) => ({ ok: false, reason: error?.message || "hydrate_failed" }));
+        }
+      }
+
+      if (!report) {
+        const sessionPayload = await getSession(normalizedSessionId, { targetPath });
+        if (!sessionPayload) {
+          throw new Error(`Session '${normalizedSessionId}' was not found.`);
+        }
+
+        events = await readStream(normalizedSessionId, { targetPath, tail: 0 });
+        dedupedEvents = dedupeSessionEvents(events);
+        report = buildSessionUsageReport({
+          sessionId: normalizedSessionId,
+          events: dedupedEvents,
+          recentLimit: options.recent,
+        });
+      }
+
+      const payload = {
+        command: "session usage",
+        targetPath,
+        source: hostedUsage?.ok ? "remote_usage" : "local_events",
+        remote: {
+          usage: hostedUsage
+            ? {
+                ok: Boolean(hostedUsage.ok),
+                reason: hostedUsage.reason || "",
+                status: hostedUsage.status || 0,
+              }
+            : null,
+          hydration,
+        },
+        rawEventCount: events.length,
+        eventCount: dedupedEvents.length,
+        ...report,
+      };
+
+      const output =
+        requestedFormat === "json"
+          ? `${JSON.stringify(payload, null, 2)}\n`
+          : requestedFormat === "markdown"
+            ? renderSessionUsageMarkdown(report)
+            : renderSessionUsageSummary(report);
+
+      const outArg = normalizeString(options.out);
+      if (outArg) {
+        const outPath = path.resolve(process.cwd(), outArg);
+        await fsp.mkdir(path.dirname(outPath), { recursive: true });
+        await fsp.writeFile(outPath, output, "utf-8");
+        if (emitJson || requestedFormat === "json") {
+          console.log(JSON.stringify({ ...payload, outPath }, null, 2));
+          return;
+        }
+        console.log(pc.bold(`Wrote session usage ${normalizedSessionId} -> ${outPath}`));
+        console.log(
+          pc.gray(
+            `${report.totals.acceptedEntries} entries - ${report.totals.totalTokens} tokens - provider cost=$${report.totals.providerCostUsd.toFixed(4)}`,
+          ),
+        );
+        return;
+      }
+
+      process.stdout.write(output);
+    });
+
   session
     .command("leave <sessionId>")
     .description("Leave a session")

package/src/session/daemon.js

@@ -44,6 +44,7 @@ import { stopRuntimeRunsForSession } from "./runtime-bridge.js";
 import { getSession, renewSession } from "./store.js";
 import { appendToStream, readStream, tailStream } from "./stream.js";
 import { handleTaskDirective } from "./tasks.js";
+import { emitLLMInteraction } from "./usage.js";
 
 const DAEMON_TICK_INTERVAL_MS = 30_000;
 const HELP_REQUEST_TIMEOUT_MS = 1_200;
@@ -653,6 +654,28 @@ async function maybeRespondToHelpRequest(
       nowIso,
     }
   );
+  if (normalizeUsageNumber(response.usage.inputTokens) + normalizeUsageNumber(response.usage.outputTokens) > 0) {
+    // The managed proxy already records the durable API billing/v1 row for
+    // this same idempotency key. Keep this copy local for immediate transcript
+    // and recap usage without double-counting Session.total_cost_usd remotely.
+    await emitLLMInteraction(daemonState.sessionId, {
+      agentId: SENTI_IDENTITY.id,
+      agentModel: response.usage.model || daemonState.model,
+      role: SENTI_IDENTITY.role,
+      inputTokens: response.usage.inputTokens,
+      outputTokens: response.usage.outputTokens,
+      costUsd: response.usage.costUsd,
+      durationMs: response.usage.latencyMs,
+      action: "proxy_llm",
+      provider: response.usage.provider || "sentinelayer",
+      billingTier: "internal",
+      prompt: normalizeString(requestEvent?.payload?.message) || normalizeString(requestEvent?.payload?.request),
+      response: response.message,
+      interactionId: `senti:${daemonState.sessionId}:help:${requestId}`,
+      targetPath,
+      syncRemote: false,
+    });
+  }
   return responseEvent;
 }
 

package/src/session/sync.js

@@ -1816,6 +1816,96 @@ export async function listSessionMessageActions(
   }
 }
 
+export async function fetchSessionUsageLedger(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    limit = 500,
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    forceCircuitProbe = false,
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+    nowMs = Date.now,
+  } = {}
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return {
+      ok: false,
+      reason: "invalid_session_id",
+      status: 0,
+      payload: null,
+    };
+  }
+  const normalizedNowMs = Number(nowMs()) || Date.now();
+  if (!forceCircuitProbe && isCircuitOpen(inboundCircuit, normalizedNowMs)) {
+    return {
+      ok: false,
+      reason: "circuit_breaker_open",
+      status: 0,
+      payload: null,
+    };
+  }
+
+  let session = null;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return { ok: false, reason: "no_session", status: 0, payload: null };
+  }
+  if (!session || !session.token) {
+    return { ok: false, reason: "not_authenticated", status: 0, payload: null };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const query = new URLSearchParams();
+  query.set(
+    "limit",
+    String(Math.max(1, Math.min(500, normalizePositiveInteger(limit, 500))))
+  );
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/usage?${query.toString()}`;
+
+  try {
+    const { response, payload } = await fetchJsonWithFullTimeout(
+      endpoint,
+      {
+        method: "GET",
+        headers: { Authorization: `Bearer ${session.token}` },
+      },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      fetchImpl,
+    );
+    if (!response || !response.ok) {
+      recordCircuitFailure(inboundCircuit, normalizedNowMs);
+      return {
+        ok: false,
+        reason: `api_${response ? response.status : "no_response"}`,
+        status: response?.status || 0,
+        payload: null,
+      };
+    }
+    recordCircuitSuccess(inboundCircuit);
+    return {
+      ok: true,
+      reason: "",
+      status: response.status || 200,
+      payload: payload && typeof payload === "object" ? payload : {},
+    };
+  } catch (error) {
+    recordCircuitFailure(inboundCircuit, normalizedNowMs);
+    return {
+      ok: false,
+      reason: normalizeString(error?.message) || "usage_read_failed",
+      status: 0,
+      payload: null,
+    };
+  }
+}
+
 function pinnedEventContentText(event = {}) {
   const payload = event && typeof event === "object" ? event.payload || {} : {};
   return (

package/src/session/usage-report.js

@@ -0,0 +1,382 @@
+import { createHash } from "node:crypto";
+
+import { buildSessionUsageLedger } from "./pricing-ledger.js";
+
+export const SESSION_USAGE_REPORT_SCHEMA = "session_usage_report/v1";
+const DEFAULT_RECENT_LIMIT = 10;
+const MAX_RECENT_LIMIT = 50;
+
+function normalize(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function object(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function nonNegativeNumber(value) {
+  if (value == null || value === "") return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+
+function nonNegativeInt(value) {
+  const parsed = nonNegativeNumber(value);
+  return parsed == null ? 0 : Math.floor(parsed);
+}
+
+function money(value) {
+  const parsed = nonNegativeNumber(value);
+  return parsed == null ? null : Math.round(parsed * 1_000_000) / 1_000_000;
+}
+
+function clampRecentLimit(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_RECENT_LIMIT;
+  return Math.min(MAX_RECENT_LIMIT, Math.floor(parsed));
+}
+
+function intCell(value) {
+  return Math.max(0, Math.floor(Number(value || 0))).toLocaleString("en-US");
+}
+
+function usdCell(value) {
+  return `$${Number(value || 0).toFixed(6)}`;
+}
+
+function tableText(value, { maxLength = 160 } = {}) {
+  const escaped = normalize(value)
+    .replace(/\r?\n/g, " ")
+    .replace(/\|/g, "\\|")
+    .replace(/`/g, "'");
+  if (!maxLength || escaped.length <= maxLength) return escaped;
+  const head = Math.max(24, Math.floor((maxLength - 3) * 0.7));
+  const tail = Math.max(12, maxLength - 3 - head);
+  return `${escaped.slice(0, head)}...${escaped.slice(-tail)}`;
+}
+
+function codeCell(value) {
+  const text = tableText(value);
+  return text ? `\`${text}\`` : "-";
+}
+
+function optionalUsdCell(value, hasValue) {
+  return hasValue ? usdCell(value) : "-";
+}
+
+function timestampOnly(iso) {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return iso;
+  return date.toISOString().replace("T", " ").replace(/\..+/, " UTC");
+}
+
+function hashOpaque(value) {
+  const text = normalize(value);
+  if (!text) return "";
+  return `sha256:${createHash("sha256").update(text).digest("hex").slice(0, 16)}`;
+}
+
+function sortRollups(map) {
+  return [...map.values()].sort((a, b) => (
+    b.providerCostUsd - a.providerCostUsd ||
+    b.totalTokens - a.totalTokens ||
+    b.entries - a.entries ||
+    tableText(a.label).localeCompare(tableText(b.label))
+  ));
+}
+
+function recentUsageEntries(entries, limit) {
+  return entries
+    .map((entry, index) => ({ entry, index }))
+    .sort((a, b) => {
+      const aSequence = Number.isFinite(a.entry.sequenceId) ? a.entry.sequenceId : null;
+      const bSequence = Number.isFinite(b.entry.sequenceId) ? b.entry.sequenceId : null;
+      if (aSequence != null && bSequence != null && aSequence !== bSequence) {
+        return bSequence - aSequence;
+      }
+      const aTime = Date.parse(a.entry.timestamp);
+      const bTime = Date.parse(b.entry.timestamp);
+      if (Number.isFinite(aTime) && Number.isFinite(bTime) && aTime !== bTime) {
+        return bTime - aTime;
+      }
+      return b.index - a.index;
+    })
+    .slice(0, limit)
+    .map(({ entry }) => entry);
+}
+
+function rollupToJson(rollup) {
+  return {
+    label: rollup.label,
+    entries: rollup.entries,
+    inputTokens: rollup.inputTokens,
+    outputTokens: rollup.outputTokens,
+    totalTokens: rollup.totalTokens,
+    providerCostUsd: rollup.providerCostUsd,
+    customerCostUsd: rollup.hasCustomerCost ? rollup.customerCostUsd : null,
+    unpriced: rollup.unpriced,
+  };
+}
+
+function hostedRollupToJson(rollup, fallbackLabel = "") {
+  const bag = object(rollup);
+  const hasCustomerCost = Boolean(bag.hasCustomerCost ?? bag.has_customer_cost ?? bag.customerCostUsd != null ?? bag.customer_cost_usd != null);
+  return {
+    label: normalize(bag.label ?? bag.agentId ?? bag.agent_id ?? bag.action ?? fallbackLabel) || "unknown",
+    entries: nonNegativeInt(bag.entries ?? bag.count),
+    inputTokens: nonNegativeInt(bag.inputTokens ?? bag.input_tokens),
+    outputTokens: nonNegativeInt(bag.outputTokens ?? bag.output_tokens),
+    totalTokens: nonNegativeInt(bag.totalTokens ?? bag.total_tokens),
+    providerCostUsd: money(bag.providerCostUsd ?? bag.provider_cost_usd ?? bag.costUsd ?? bag.cost_usd) ?? 0,
+    customerCostUsd: hasCustomerCost
+      ? money(bag.customerCostUsd ?? bag.customer_cost_usd ?? bag.billableCostUsd ?? bag.billable_cost_usd) ?? 0
+      : null,
+    unpriced: nonNegativeInt(bag.unpriced),
+  };
+}
+
+function entryToJson(entry) {
+  return {
+    timestamp: normalize(entry.timestamp) || null,
+    sequenceId: Number.isFinite(entry.sequenceId) ? entry.sequenceId : null,
+    ledgerEntryId: entry.ledgerEntryId,
+    idempotencyKeyHash: hashOpaque(entry.idempotencyKey),
+    schema: entry.schema,
+    agentId: entry.agentId,
+    action: entry.action,
+    model: entry.model,
+    provider: normalize(entry.provider) || null,
+    billingTier: entry.billingTier,
+    priceBookVersion: entry.priceBookVersion,
+    inputTokens: entry.inputTokens,
+    outputTokens: entry.outputTokens,
+    totalTokens: entry.totalTokens,
+    providerCostUsd: entry.providerCostUsd,
+    customerCostUsd: entry.customerCostUsd,
+    unpriced: entry.unpriced,
+  };
+}
+
+function hostedEntryToJson(entry) {
+  const bag = object(entry);
+  const idempotencyKey = normalize(bag.idempotencyKey ?? bag.idempotency_key ?? bag.runKey ?? bag.run_key);
+  return {
+    timestamp: normalize(bag.timestamp ?? bag.createdAt ?? bag.created_at ?? bag.occurredAt ?? bag.occurred_at) || null,
+    sequenceId: nonNegativeNumber(bag.sequenceId ?? bag.sequence_id ?? bag.sequence) == null
+      ? null
+      : nonNegativeInt(bag.sequenceId ?? bag.sequence_id ?? bag.sequence),
+    ledgerEntryId: normalize(bag.ledgerEntryId ?? bag.ledger_entry_id ?? bag.billingEventId ?? bag.billing_event_id) || "",
+    idempotencyKeyHash: hashOpaque(idempotencyKey),
+    schema: normalize(bag.schema) || "billing/v1",
+    agentId: normalize(bag.agentId ?? bag.agent_id) || "unknown",
+    action: normalize(bag.action ?? bag.operation ?? bag.kind ?? bag.billingAction ?? bag.billing_action) || "agent_message",
+    model: normalize(bag.model ?? bag.modelId ?? bag.model_id) || "unknown",
+    provider: normalize(bag.provider ?? bag.providerName ?? bag.provider_name) || null,
+    billingTier: normalize(bag.billingTier ?? bag.billing_tier ?? bag.tier) || "unknown",
+    priceBookVersion: normalize(bag.priceBookVersion ?? bag.price_book_version ?? bag.pricingVersion ?? bag.pricing_version) || "unknown",
+    inputTokens: nonNegativeInt(bag.inputTokens ?? bag.input_tokens),
+    outputTokens: nonNegativeInt(bag.outputTokens ?? bag.output_tokens),
+    totalTokens: nonNegativeInt(bag.totalTokens ?? bag.total_tokens ?? bag.tokens),
+    providerCostUsd: money(bag.providerCostUsd ?? bag.provider_cost_usd ?? bag.costUsd ?? bag.cost_usd ?? bag.cost) ?? 0,
+    customerCostUsd: money(bag.customerCostUsd ?? bag.customer_cost_usd ?? bag.billableCostUsd ?? bag.billable_cost_usd),
+    unpriced: Boolean(bag.unpriced),
+  };
+}
+
+function sourceArray(value) {
+  if (Array.isArray(value)) return value;
+  if (value && typeof value === "object") return Object.values(value);
+  return [];
+}
+
+function recentReportEntries(entries, limit) {
+  return entries
+    .map((entry, index) => ({ entry, index }))
+    .sort((a, b) => {
+      const aSequence = Number.isFinite(a.entry.sequenceId) ? a.entry.sequenceId : null;
+      const bSequence = Number.isFinite(b.entry.sequenceId) ? b.entry.sequenceId : null;
+      if (aSequence != null && bSequence != null && aSequence !== bSequence) {
+        return bSequence - aSequence;
+      }
+      const aTime = Date.parse(a.entry.timestamp);
+      const bTime = Date.parse(b.entry.timestamp);
+      if (Number.isFinite(aTime) && Number.isFinite(bTime) && aTime !== bTime) {
+        return bTime - aTime;
+      }
+      return b.index - a.index;
+    })
+    .slice(0, limit)
+    .map(({ entry }) => entry);
+}
+
+export function buildSessionUsageReport({
+  sessionId = "",
+  events = [],
+  recentLimit = DEFAULT_RECENT_LIMIT,
+} = {}) {
+  const ledger = buildSessionUsageLedger(events, { sessionId: normalize(sessionId) });
+  const limit = clampRecentLimit(recentLimit);
+  return {
+    schema: SESSION_USAGE_REPORT_SCHEMA,
+    sessionId: normalize(sessionId),
+    generatedAt: new Date().toISOString(),
+    totals: {
+      acceptedEntries: ledger.entries.length,
+      duplicatesSkipped: ledger.duplicatesSkipped,
+      inputTokens: ledger.totals.inputTokens,
+      outputTokens: ledger.totals.outputTokens,
+      totalTokens: ledger.totals.totalTokens,
+      providerCostUsd: ledger.totals.providerCostUsd,
+      customerCostUsd: ledger.totals.hasCustomerCost ? ledger.totals.customerCostUsd : null,
+      unpriced: ledger.totals.unpriced,
+      priceBookVersions: ledger.priceBookVersions,
+    },
+    perAgent: sortRollups(ledger.perAgent).map(rollupToJson),
+    perAction: sortRollups(ledger.perAction).map(rollupToJson),
+    recentEntries: recentUsageEntries(ledger.entries, limit).map(entryToJson),
+  };
+}
+
+export function buildSessionUsageReportFromLedgerPayload({
+  sessionId = "",
+  payload = {},
+  recentLimit = DEFAULT_RECENT_LIMIT,
+} = {}) {
+  const root = object(payload);
+  const embedded = root.usageLedger || root.usage_ledger || root.ledger;
+  const source = embedded && typeof embedded === "object" && !Array.isArray(embedded)
+    ? embedded
+    : root;
+  const entries = sourceArray(source.entries).map(hostedEntryToJson);
+  const totals = hostedRollupToJson(object(source.totals), "session");
+  const priceBookVersions = sourceArray(source.priceBooks || source.price_books || source.priceBookVersions || source.price_book_versions)
+    .map(normalize)
+    .filter(Boolean)
+    .sort();
+  const limit = clampRecentLimit(recentLimit);
+  return {
+    schema: SESSION_USAGE_REPORT_SCHEMA,
+    sessionId: normalize(root.sessionId ?? root.session_id ?? source.sessionId ?? source.session_id ?? sessionId),
+    generatedAt: new Date().toISOString(),
+    totals: {
+      acceptedEntries: totals.entries || entries.length,
+      duplicatesSkipped: nonNegativeInt(source.duplicatesSkipped ?? source.duplicates_skipped),
+      inputTokens: totals.inputTokens,
+      outputTokens: totals.outputTokens,
+      totalTokens: totals.totalTokens,
+      providerCostUsd: totals.providerCostUsd,
+      customerCostUsd: totals.customerCostUsd,
+      unpriced: totals.unpriced,
+      priceBookVersions,
+    },
+    perAgent: sourceArray(source.agents || source.perAgent || source.per_agent || source.agentsById || source.agents_by_id)
+      .map((rollup) => hostedRollupToJson(rollup))
+      .sort((a, b) => b.providerCostUsd - a.providerCostUsd || b.totalTokens - a.totalTokens || a.label.localeCompare(b.label)),
+    perAction: sourceArray(source.actions || source.perAction || source.per_action || source.actionsById || source.actions_by_id)
+      .map((rollup) => hostedRollupToJson(rollup))
+      .sort((a, b) => b.providerCostUsd - a.providerCostUsd || b.totalTokens - a.totalTokens || a.label.localeCompare(b.label)),
+    recentEntries: recentReportEntries(entries, limit),
+  };
+}
+
+function appendRollupTable(lines, { title, labelHeader, rollups }) {
+  lines.push(`### ${title}`);
+  lines.push("");
+  lines.push(`| ${labelHeader} | Entries | Input | Output | Total | Provider cost | Customer cost | Unpriced |`);
+  lines.push("|---|---:|---:|---:|---:|---:|---:|---:|");
+  if (!rollups.length) {
+    lines.push(`| - | 0 | 0 | 0 | 0 | ${usdCell(0)} | - | 0 |`);
+  } else {
+    for (const rollup of rollups) {
+      lines.push(
+        `| ${codeCell(rollup.label)} | ${intCell(rollup.entries)} | ${intCell(rollup.inputTokens)} | ${intCell(rollup.outputTokens)} | ${intCell(rollup.totalTokens)} | ${usdCell(rollup.providerCostUsd)} | ${optionalUsdCell(rollup.customerCostUsd, rollup.customerCostUsd != null)} | ${intCell(rollup.unpriced)} |`,
+      );
+    }
+  }
+  lines.push("");
+}
+
+export function renderSessionUsageMarkdown(report = {}) {
+  const totals = report.totals || {};
+  const lines = [];
+  lines.push(`# Session Usage ${normalize(report.sessionId) || "unknown"}`);
+  lines.push("");
+  lines.push(`Generated: ${normalize(report.generatedAt) || new Date().toISOString()}`);
+  lines.push("");
+  lines.push("## Totals");
+  lines.push("");
+  lines.push(`Accepted entries: ${intCell(totals.acceptedEntries)}`);
+  lines.push(
+    `Tokens: ${intCell(totals.totalTokens)} (input ${intCell(totals.inputTokens)} / output ${intCell(totals.outputTokens)})`,
+  );
+  lines.push(
+    `Provider cost: ${usdCell(totals.providerCostUsd)} - Customer cost: ${optionalUsdCell(totals.customerCostUsd, totals.customerCostUsd != null)}`,
+  );
+  lines.push(`Price books: ${(totals.priceBookVersions || []).map(tableText).filter(Boolean).join(", ") || "-"}`);
+  lines.push(`Duplicates skipped: ${intCell(totals.duplicatesSkipped)} - Unpriced entries: ${intCell(totals.unpriced)}`);
+  lines.push("");
+
+  appendRollupTable(lines, {
+    title: "Per Agent",
+    labelHeader: "Agent",
+    rollups: Array.isArray(report.perAgent) ? report.perAgent : [],
+  });
+  appendRollupTable(lines, {
+    title: "Per Action",
+    labelHeader: "Action",
+    rollups: Array.isArray(report.perAction) ? report.perAction : [],
+  });
+
+  lines.push("### Recent Entries");
+  lines.push("");
+  lines.push("| Time | Agent | Action | Model | Tokens | Provider cost | Customer cost | Ledger | Idempotency hash |");
+  lines.push("|---|---|---|---|---:|---:|---:|---|---|");
+  const entries = Array.isArray(report.recentEntries) ? report.recentEntries : [];
+  if (!entries.length) {
+    lines.push(`| - | - | - | - | 0 | ${usdCell(0)} | - | - | - |`);
+  } else {
+    for (const entry of entries) {
+      lines.push(
+        `| ${tableText(timestampOnly(entry.timestamp)) || "-"} | ${codeCell(entry.agentId)} | ${codeCell(entry.action)} | ${codeCell(entry.model)} | ${intCell(entry.totalTokens)} | ${usdCell(entry.providerCostUsd)} | ${optionalUsdCell(entry.customerCostUsd, entry.customerCostUsd != null)} | ${codeCell(entry.ledgerEntryId)} | ${codeCell(entry.idempotencyKeyHash)} |`,
+      );
+    }
+  }
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderSessionUsageSummary(report = {}) {
+  const totals = report.totals || {};
+  const lines = [];
+  lines.push(`Session usage ${normalize(report.sessionId) || "unknown"}`);
+  lines.push(
+    `${intCell(totals.acceptedEntries)} entries - ${intCell(totals.totalTokens)} tokens (${intCell(totals.inputTokens)} in / ${intCell(totals.outputTokens)} out) - provider ${usdCell(totals.providerCostUsd)}${
+      totals.customerCostUsd == null ? "" : ` - customer ${usdCell(totals.customerCostUsd)}`
+    }`,
+  );
+  lines.push(
+    `priceBooks=${(totals.priceBookVersions || []).map(tableText).filter(Boolean).join(",") || "-"} duplicatesSkipped=${intCell(totals.duplicatesSkipped)} unpriced=${intCell(totals.unpriced)}`,
+  );
+  const agents = Array.isArray(report.perAgent) ? report.perAgent.slice(0, 8) : [];
+  if (agents.length) {
+    lines.push("");
+    lines.push("Per agent:");
+    for (const agent of agents) {
+      lines.push(
+        `- ${agent.label}: ${intCell(agent.totalTokens)} tokens, ${intCell(agent.entries)} entries, provider ${usdCell(agent.providerCostUsd)}`,
+      );
+    }
+  }
+  const entries = Array.isArray(report.recentEntries) ? report.recentEntries.slice(0, 5) : [];
+  if (entries.length) {
+    lines.push("");
+    lines.push("Recent:");
+    for (const entry of entries) {
+      lines.push(
+        `- ${timestampOnly(entry.timestamp) || "-"} ${entry.agentId} ${entry.action} ${intCell(entry.totalTokens)} tokens ${usdCell(entry.providerCostUsd)} ledger=${entry.ledgerEntryId}`,
+      );
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/session/usage.js

@@ -111,6 +111,7 @@ function computedCost({ model, inputTokens, outputTokens }) {
  * @param {string} [params.response]          full response text (clipped)
  * @param {string} [params.interactionId]     opaque id for cross-event correlation
  * @param {string} [params.targetPath]        workspace path (default cwd)
+ * @param {boolean} [params.syncRemote]       sync local usage event to API (default true)
  * @returns {Promise<{ event: string, interactionId: string, totalTokens: number, costUsd: number }>}
  */
 export async function emitLLMInteraction(
@@ -132,6 +133,7 @@ export async function emitLLMInteraction(
     response = "",
     interactionId = "",
     targetPath = process.cwd(),
+    syncRemote = true,
   } = {},
 ) {
   const sid = n(sessionId);
@@ -219,7 +221,7 @@ export async function emitLLMInteraction(
     ts,
   });
 
-  await appendToStream(paths.sessionId, envelope, { targetPath });
+  await appendToStream(paths.sessionId, envelope, { targetPath, syncRemote });
   return {
     event: SESSION_USAGE_EVENT,
     interactionId: id,