smartchats-sessions

Session export and analysis for SmartChats. It pulls a session’s insights events from a SurrealDB-backed deployment into a SessionBundle, runs analyzers over it (errors, transcript, traces, performance, executions), and merges failures across many sessions for triage. A second set of analyzers (analysis_db) queries the database directly for cost, errors, slow calls and other audits.

The bundle analyzers do no I/O. Each is a pure function over a SessionBundle, paired with a formatter, so you can call them from your own scripts as well as through the npm scripts.

What’s in the package

Module	Purpose
`export.ts`	`buildSessionBundle(client, filter)`, `findSessions`, `findCandidateSessions`, `exportSessionToFile`, `exportRecentSessionsToFiles`
`analysis/transcript.ts`	User/agent transcript reconstruction, optionally with thoughts + code
`analysis/errors.ts`	Error extraction + per-session signature grouping
`analysis/performance.ts`	LLM/exec/voice latency stats, cache hit rate, turn pacing
`analysis/traces.ts`	Causality trees built from `trace_id` / `parent_event_id`
`analysis/executions.ts`	Per-execution detail (code, function calls, result)
`analysis/inspect.ts`	Drill into a specific event or trace
`analysis/triage_errors.ts`	Cross-session signature merge and handled state
`analysis_db/`	Database-side audits: `queryCostBy`, `queryErrors`, `querySlowFunctionCalls`, `queryFunctionCallHistogram`, `queryFunctionCallsByArgs`, `queryUsersActivity`, `queryContextGrowth`, `queryIssues`, `queryTtsTiming`, and `liveMonitor` for polling
`queries.ts`	Query specs for session events and session search
`cli/find_cli.ts`	The `find-sessions` argument parser and runner
`scripts/`	The npm script entry points

Quick start: CLI

# Pull bundles from the local instance (from the repo root)
bin/save_session --app smartchats                 # latest session
bin/save_session --app smartchats --tag simi      # filter by tag
bin/save_session --app smartchats --last 5        # several sessions
 
cd packages/smartchats-sessions
 
# Single-session deep dive
npm run analyze:summary      -- <bundle.json>
npm run analyze:transcript   -- <bundle.json>     # --with-code, --markdown
npm run analyze:errors       -- <bundle.json>
npm run analyze:performance  -- <bundle.json>
npm run analyze:traces       -- <bundle.json>
npm run analyze:inspect      -- <bundle.json> --event=<id>

Quick start: programmatic

import {
  analyzeErrors, formatErrors,
  analyzeTranscript, formatTranscript,
  buildTraceTrees, formatTraces,
} from 'smartchats-sessions';
import fs from 'node:fs';
 
const bundle = JSON.parse(fs.readFileSync('bundle.json', 'utf8'));
 
// Pure analysis: returns structured data
const errors = analyzeErrors(bundle);
console.log(errors);  // { session_id, total, by_signature: {...}, records: [...] }
 
// Formatter renders it for humans
console.log(formatErrors(errors));

Every analyzer follows the same shape: analyzeX(bundle) returns a typed result and formatX(result) returns a string. The trace analyzer is named buildTraceTrees, and inspectEvent / inspectTrace drill into one event or trace.

Cross-session error triage

Across many sessions: what is failing, grouped by signature, with already-fixed signatures hidden?

cd packages/smartchats-sessions
 
npm run triage:errors                              # ~/.smartchats/session_bundles → ./triage/<ts>/
npm run triage:errors -- --since 7d --min-count 2
npm run triage:errors -- --dry-run                 # preview without writing
 
# Once you ship a fix:
npm run triage:mark -- <report-slug> --status fixed --commit <sha>
 
# View handled-state:
npm run triage:mark -- --list

State file: data/triage/handled.json at the repo root, tracked in git so the “already fixed” record is shared. Override the path with --state or SMARTCHATS_TRIAGE_STATE_FILE. Statuses are fixed, wontfix and investigating.

Regression rule: signatures marked fixed re-surface as REGRESSION: reports when a session whose end_time > fixed_at hits the same signature. Catches stale fixes that didn’t reach production. wontfix entries land in wontfix_summary.md so they’re not silently invisible.

Discovering sessions to pull

Before you pull a bundle, you usually want to find candidates:

cd packages/smartchats-sessions
npm run find-sessions -- --has-error --since 7d
 
# Filter flags:
#   --app, --tag, --has-error, --has-event-tag, --has-event-type,
#   --missing-event-type, --min-events, --max-events, --min-duration,
#   --max-duration, --since, --until, --limit
# Formats:
#   --format=table | json | ids   (pipe ids to save_session)

Pair with bin/save_session:

npm run find-sessions -- --has-error --since 7d --format=ids \
  | xargs -I{} bin/save_session --session-id {}

Adding a new analyzer

The pattern is documented in packages/smartchats-sessions/src/analysis/README.md. Briefly:

Write analyzeX(bundle: SessionBundle): XResult, a pure function.
Write formatX(result: XResult, opts?): string, a pure formatter.
Add a script in scripts/ and an npm run analyze:x entry if you want one.
Re-export from index.ts.

The analyzers don’t share state. They don’t need to be ordered. Each one is independently testable with a fixture bundle.

Open vs closed boundary

This package never imports cloud credentials. The hosted service keeps its own admin export tool for cross-user triage, because it needs root credentials. It reuses findCandidateSessions and buildSessionBundle from this package.

When to use this package directly

You want a custom analyzer (latency distribution, knowledge graph write patterns, anything not in the default set)
You’re building a dashboard that reads SmartChats session data
You’re automating triage (a CI job that pulls fresh failures)