JavaScript command handlers run in a Goja-powered runtime with access to a minitrace module, Goja NodeJS-style helper modules, and scanner markers that turn .js files into typed go-minitrace query commands verbs.

The current API is builder-composed. Use fluent Go-backed builders to construct typed sources, policies, cache settings, query recipes, views, and session handles. The builders keep construction and validation on the Go side while view/query outputs remain plain JSON-serializable rows.

const mt = require("minitrace");

In xgoja apps this provider can be aliased as require("mt"). Query-command examples in this repository still use require("minitrace") because that is the provider's registered module name.

Quick patterns

Query-command default

function sessionList(filters) {
  const mt = require("minitrace");
  const db = mt.db()
    .RuntimeArchives()
    .QueryCommandDefaults()
    .Build();
  try {
    return db.query(`
      SELECT session_id, title, agent_framework, turn_count, tool_call_count
      FROM sessions
      WHERE 1=1
      ${filters.framework?.length ? `AND agent_framework IN (${mt.sql.stringIn(filters.framework)})` : ""}
      ORDER BY started_at DESC
      LIMIT ${filters.limit ?? 25}
    `);
  } finally {
    db.close();
  }
}

Explicit staged construction

const sources = mt.sources()
  .RuntimeArchives()
  .Build();

const cache = mt.cache()
  .Memory()
  .Build();

const limits = mt.limits()
  .Rows(500)
  .CellChars(8000)
  .Build();

const db = mt.db()
  .Sources(sources)
  .Cache(cache)
  .Limits(limits)
  .Build();

Session-oriented app flow

const session = mt.session()
  .File(sessionPath)
  .InteractiveCache(cacheDir)
  .Open();
try {
  const transcript = session.view().Transcript().IncludeTools().Run();
  const timeline = session.view().Timeline().Run();
  const usage = session.view().TokenUsage().ByTurn().Run();
  return { summary: session.summary(), transcript, timeline, usage };
} finally {
  session.close();
}

Upload/import flow

const saved = mt.importer()
  .Content(uploadText)
  .Name(filename)
  .Into(sessionsDir)
  .SessionID(sessionId)
  .AutoDetect()
  .Strict()
  .Convert()
  .Save();

Builder factories

mt.importer()

Methods:

mt.sources()

Methods: .File(path), .Archive(path), .Files(paths), .Dir(path), .Glob(pattern), .Content(text), .Name(name), .RuntimeArchives(), .Validate(), .Build().

Build() returns a Go-owned SourceSet. Pass it to mt.db().Sources(...) or mt.session().Sources(...).

const sources = mt.sources()
  .Dir("./output/active")
  .Glob("./extra/*.minitrace.json")
  .Build();

Policy subbuilders

const importPolicy = mt.importPolicy()
  .AutoConvert()
  .Strict()
  .Build();

const cache = mt.cache()
  .Auto()
  .Dir("./.cache/minitrace")
  .Build();

const limits = mt.limits()
  .Rows(1000)
  .Columns(128)
  .CellChars(6000)
  .TimeoutMs(5000)
  .Build();

mt.importPolicy()

• .AutoConvert(true|false)
• .NativeOnly()
• .Strict(true|false)
• .Lenient()
• .Format(format)
• .Build()

mt.cache()

• .None()
• .Memory()
• .Disk()
• .Auto()
• .Dir(path)
• .ForceRebuild(true|false)
• .Build()

mt.limits()

• .Rows(n)
• .Columns(n)
• .CellChars(n)
• .TimeoutMs(n)
• .RequireOrderBy(true|false)
• .Build()

mt.db()

mt.db() composes source sets and policies into a normalized SQLite DB handle.

Composition methods:

• .Sources(sourceSet)
• .Import(importPolicy)
• .Cache(cachePolicy) or legacy .Cache("auto")
• .Limits(queryLimits)
• .Build()

Convenience methods:

• source: .File, .Archive, .Files, .Dir, .Glob, .Content, .RuntimeArchives
• conversion: .AutoConvert, .StrictConversion, .Strict
• cache/storage: .SQLiteMemory, .SQLiteDiskCache, .CacheAuto, .CacheDir, .ForceRebuild
• limits: .MaxRows, .MaxColumns, .MaxCellChars, .Timeout, .RequireOrderBy
• presets: .QueryCommandDefaults(), .InteractiveDefaults(cacheDir?)
• introspection: .Validate(), .CacheKey(), .sources()

DB handle

Build() returns a handle with:

Queries are validated as read-only SQL and bounded by row, column, cell, and timeout limits.

mt.query()

mt.query() builds SQL recipes. A recipe is a Go-owned object with name(), sql(), args(), description(), output(), and toJSON().

Recipe selectors:

• .SessionSummary()
• .TurnRows()
• .ToolRows()
• .EventRows()
• .TurnBlockRows()
• .TokenUsageRows()
• .TranscriptRows()
• .TimelineRows()

Modifiers:

• .SessionID(id)
• .IncludeTools(true|false)
• .BySession()
• .ByTurn()
• .ByRole()
• .ByTool()

Example:

const recipe = mt.query()
  .TranscriptRows()
  .SessionID("sess-123")
  .IncludeTools()
  .Build();
const rows = db.query(recipe.sql(), ...recipe.args());

mt.view() and session.view()

View builders run query recipes and return plain rows/frames.

Standalone view plans use .DB(db):

const frames = mt.view()
  .DB(db)
  .SessionID(sessionId)
  .TurnFrames()
  .IncludeThinking()
  .IncludeToolResults()
  .Run();

Session-bound view plans already know the DB and session id:

const transcript = session.view()
  .Transcript()
  .IncludeTools()
  .Run();

Selectors:

• .Transcript()
• .TurnFrames()
• .Timeline()
• .TokenUsage()
• .SessionSummary()

Modifiers:

• .IncludeTools(true|false)
• .IncludeThinking(true|false)
• .IncludeToolResults(true|false)
• .CollapseLongTextAt(chars)
• .BySession() / .ByTurn() / .ByRole() / .ByTool()
• .Plan() to inspect the underlying query recipe
• .Run() to execute

mt.session()

mt.session() is the high-level transcript workflow. It applies transcript-friendly defaults and returns a lifecycle-bound session handle.

Builder methods:

• .Sources(sourceSet) / .Source(sourceSet)
• .Import(importPolicy)
• .Cache(cachePolicy)
• .Limits(queryLimits)
• .SessionID(id)
• .File(path)
• .Content(text)
• .Name(name)
• .InteractiveCache(dir?)
• .Strict(true|false)
• .Open()

Session handle methods:

• id()
• summary()
• diagnostics()
• cacheInfo()
• db()
• query(sql, ...args)
• view()
• close()

Always call close() in a finally block.

SQL helpers

mt.sql contains string-literal helpers for building safe SQL fragments when query parameters are not ergonomic in generated SQL.

mt.sql.string("O'Reilly")       // => "'O''Reilly'"
mt.sql.stringIn(["codex", "pi"]) // => "'codex', 'pi'"
mt.sql.like("tool fail")        // => "'%tool fail%'"

Runtime metadata

mt.runtime includes query-command runtime settings:

Troubleshooting

Related help

• go-minitrace help structured-query-commands — scanner markers and command metadata.
• go-minitrace help query — query subsystem overview.
• go-minitrace help query-duckdb — older raw DuckDB workflow for ad hoc exploration.
• testdata/query-repositories/js-showcase/ — worked JavaScript command examples.