Investigator API reference

This page lists what a program the investigator writes can reach in the REPL: the globals of the code and sessions domains, the toolkit helpers, the scripts library and every ready-made script. The investigator reads the typed form of this page, the domain’s api.d.ts, through the help tool.

Sources: domains/code/api.d.ts, domains/code/repo.mjs (makeRepo), domains/sessions/api.d.ts, src/transcripts/index.mjs (makeHistory, cite), src/core/toolkit.mjs (toolkit) and src/server.mjs (scripts).

The REPL tools

The investigator’s server offers four tools. The calling agent never sees them.

Tool Parameters What it does
repl code (string); maxChars (200 to 100000, default 4000); timeoutSeconds (1 to 600, default 120) Runs JavaScript in a persistent context with top-level await. Top-level const, let, var, function and class become session globals. The last expression’s value comes back: a string as it is, anything else as JSON, clipped to maxChars with the shape of the whole value.
help none The scripts with their parameters, the typed API of the domain and the session’s variables.
reset none Clears the session’s variables and snapshot. Drafts and the journal stay.
load sessionId (string) Copies the saved variables of an earlier investigation for the same asking session into this one.

After the value, a cell’s output has a line [<ms> ms, <n> call(s)], and console output, load errors of scripts and repeat-cell warnings in front of it. The REPL describes snapshots, restore and the repeat-cell guard.

Globals in every domain

Global What it is
scripts The script library. See scripts.
tk The toolkit as one object.
the toolkit functions clip, shape, pick, omit, table, top, groupBy, countBy, sumBy, since, minutes, also as plain globals.
console log, info, warn and error are captured and shown ahead of the result (at most 4000 characters).
the domain’s own globals repo for code; history and cite for sessions.

A script gets the domain’s globals and tk. It does not get scripts or the bare toolkit functions, so it calls tk.table(...).

Toolkit

All functions are pure. rows is an array of objects unless noted.

Function Returns
clip(v, max = 400) null for null or undefined; a string cut to max characters with … [+N chars]; any other value as it is.
shape(x, depth = 3) The keys, types and array lengths of a value, a few levels deep: "string(12)", ["array(40)", {...first item...}].
pick(rows, ...keys) The rows (or one object) reduced to those keys.
omit(rows, ...keys) The rows (or one object) without those keys.
table(rows, cols, { width = 60 }) A compact text table. cols defaults to the first row’s keys. Cells are cut at width. "(no rows)" for an empty list.
top(rows, key, n = 10) The n rows with the largest key (a field name or a function returning a number).
groupBy(rows, key) An object of arrays, grouped by a field or by a function.
countBy(rows, key) An object of counts, largest first.
sumBy(rows, key) The sum of a field or function over the rows; non-numbers count as 0.
since(hours) The ISO time hours ago.
minutes(ms) Milliseconds as minutes, rounded to one decimal.

api.d.ts of each built-in domain declares only some of these (see the notes at the end); all of them work.

scripts

Member What it does
scripts.list() [{ name, purpose, params, returns, draft }] for the library and this session’s drafts.
scripts.show(name) The script’s source.
scripts.run(name, params = {}) Runs a script with the domain’s globals and tk, and returns its value. A script that throws fails the cell, and the failure is journaled with the script’s name.
scripts.draft(name, source) Saves source as a draft script for this investigation, in the state folder. name is lowercase letters, digits and dashes. It loads before the next cell, so run it in a new cell. Returns { name, file, note }.

The library is the scripts/ folder of the domain, one .mjs file per script, and the name is the file name without .mjs. A draft with the same name replaces the library script for that session. A file that fails to load (no default export function, a syntax error) is listed in the next cell’s output as [scripts that failed to load: ...]. The library reloads when a file’s modification time changes. Add a script to a domain shows how to write one.

A script file exports:

Export Type Used for
meta object purpose (string), params (name to description), returns (string), example (string, optional). help prints them. Missing fields print as empty.
default async function (globals, params) The script. globals holds the domain’s globals plus tk. params is the object given to scripts.run.

The code domain

Global repo, a read-only client for one repository. The repository is the git top level of ASK_KIT_CODE_ROOT, or of the directory the server started in when that variable is not set. If that is not a git checkout, it is the directory itself. Paths in results are relative to the root. A path that leaves the root throws <path> is outside the repository.

Member Signature and behaviour
repo.root Absolute path of the repository (symlinks resolved).
repo.rg(pattern, o) Runs ripgrep with --json, lines cut at 300 columns. pattern is a regex. Options: fixed (literal), ignoreCase, word, context (lines around each match), glob (string or array), type (ripgrep type, string or array), path (folder inside the repository), hidden, max (default 200). Returns [{ file, line, text, context? }] with .total (matches, context lines excluded) and .complete (total <= max). Context lines have context: true.
repo.files(glob, o) The files ripgrep would search (rg --files), sorted. Options: path, hidden, max (default 2000). Returns paths with .total and .complete.
repo.read(file, { from, to }) Lines from to to, 1-based and inclusive, at most 400 lines (to defaults to from + 399). Returns { file, from, to, lines, text }; text has each line as N<tab>line, and lines is the file’s length.
repo.git(sub, ...args) Runs git --no-pager -c core.pager=cat <sub> <args> in the root and returns stdout. sub must be one of log, show, blame, diff, ls-files, grep, rev-parse, status, shortlog, branch, tag. Arguments starting --output, --ext-diff, --textconv, -c, --exec, --upload-pack, --git-dir, --work-tree, -C, --config, -O or --open-files-in-pager are refused.

ripgrep is the system’s rg when there is one, else the copy that came with @vscode/ripgrep. Each command runs without a shell, with a 60 second timeout and 32 MB of output. ripgrep respects .gitignore.

Each call is reported to the journal as { kind, detail, ms, size }.

The sessions domain

history

One API over every enabled source. Window options, used by sessions and grep:

Option Type Meaning
since number or string A number is hours ago. A string is an ISO date. Keeps sessions updated at or after it.
until number or string Same forms. Keeps sessions started at or before it.
source string or string[] One or more of claude-code, codex, copilot-cli, gemini-cli, opencode.
project string Substring of the project name or the working directory, any case.
cwd string Prefix of the working directory.
Method Behaviour
history.sources() [{ name, label, where, available }] for the sources the config enables.
history.sessions({ ...Window, limit }) Sessions, newest first, default limit 50. Returns the sessions with .total, the count before the limit.
history.session(ref) One session. ref is an id, an id prefix, <source>:<id> or a session object. An ambiguous prefix throws matches N sessions; give more of the id; none throws no session <ref>.
history.events(ref, { roles, from, to, maxText }) The session’s events. roles is a role or an array; from and to bound the event number i; maxText clips each text and drops input. Returns the events with .total (count before filters) and .session.
history.usage(ref) Tokens by model, as the agent recorded them. See Usage shapes.
history.grep(query, o) Search events. query is words (all must appear in one event, any case) or a RegExp. Options: a Window, session (search only this one), roles (default user, assistant, tool_call, tool_result), max (hits kept, default 100), snippet (characters per snippet, default 300), budgetMs (default 40000). Returns hits with .total, .complete, .scanned (sessions parsed) and, on a timeout, .stoppedEarly.
cite(x) "<source> <first 8 chars of the session id> #<i>" from a hit or from { source, session or id, i }.

The list of all sessions is cached for 30 seconds. ask-kit’s own investigator sessions (working directory in the state folder or ending /warm/cwd) are left out.

A Session:

Field Meaning
source, id The agent and its own session id.
cwd, project Where it ran, and the last folder name of that (null where the agent does not record it; Gemini CLI uses gemini:<hash prefix> as the project).
title The summary or first prompt, clipped to 120 characters.
startedAt, updatedAt ISO times. updatedAt is the file’s last write.
kb Size of the transcript file in KB (not for opencode).
extra Some sources add one: originator (Codex), model (Copilot CLI, opencode).

An Event:

Field Meaning
i Position in the session. It is the citation.
ts Time, when the agent records one.
role user (typed by the person), assistant, tool_call, tool_result, system (context the agent injected).
text The text. For a tool_call it is the arguments as JSON.
tool, toolId The tool’s name; the id pairing a call with its result.
input A tool_call’s parsed arguments, where the agent stores them parsed.
ok A tool_result: false when the tool reported failure.
model The model, on assistant text and tool calls where known.

A Hit has source, session, project, title, i, ts, role, tool and snippet. The snippet starts 120 characters before the first match.

Usage shapes

Source Fields per model
claude-code calls, input, cacheRead, cacheWrite, output
codex input, cacheRead, cacheWrite (always 0), output, reasoning
copilot-cli calls, input, cacheRead, cacheWrite, output, premiumRequests
gemini-cli calls, input, cacheRead, cacheWrite (always 0), output
opencode input, output, cacheRead, cacheWrite, costUsd

How each source’s files become events is in Transcripts.

Ready-made scripts

Every script is a file in the domain’s scripts/ folder. Defaults below are the ones in the code. All results are plain data. A required parameter that is missing throws an error naming the script.

code scripts

Script Parameters Returns
where name (required): an identifier or words, searched under every spelling (fooBar, FooBar, foo_bar, FOO_BAR, foo-bar, foobar); path: folder; uses: usage lines returned, default 25 { spellings, definitions: [{file,line,text}] (at most 40), usesTotal, usesComplete, usesByFile: [{file,count}] (top 20), uses: [{file,line,text}] }
knobs topic (required): words, at least one longer than two letters that is not a stop word; path; max: hits per kind, default 25 { words, envReads, cliFlags, constants, configFiles, settingsFields, scanned, complete, checked }, each list holding {file,line,text} and checked naming what was looked at. Words are shortened to stems so embedding also finds EMBED_. Markdown and test files are left out.
history term: text added or removed in a diff (git log -S); path: file or folder; limit: default 15; regex: true makes term a regex (-G). One of term or path is required. { commits: [{sha,date,author,subject}], complete }, newest first
outline path (required): file or folder; max: default 120 { path, files, definitions: [{file,line,text}], complete }: top-level definitions in Rust, TypeScript, JavaScript, Python, Go and SQL, and markdown headings
overview depth: folder depth counted, default 2 { root, files, dirs: [{dir,files}] (top 40), docs: [{file,headings}] (README, AGENTS.md, CLAUDE.md and docs/ architecture files, at most 8), manifests (at most 30), recent: [8 commit lines] }

The code scripts leave out node_modules, target, dist, build, .git, vendor, lock files, minified files, source maps, .sqlx and snapshot files unless the investigator searches for them directly. The list is NOISE in domains/code/lib.mjs.

sessions scripts

Script Parameters Returns
find-sessions topic (required): a few distinctive words; hours: window, default 720 (30 days); project; source; tools: also search tool calls and results, default false; any: see the note below { query, total, complete, sessions: [{ source, id, project, title, startedAt, hits, userHits, first: {i, role, snippet} }] }, at most 15 sessions, ranked by userHits * 3 + hits. When no event holds every word it searches the two longest words, then each word alone, and query says which. startedAt is the time of the session’s first hit.
grep query: words; regex: a regex source, case-insensitive, instead of words (one of the two is required); hours: default 720; session: one session (then no time window); project; source; roles; max: default 40 { window, total, complete, scanned, stoppedEarly?, hits: [{source,session,project,i,ts,role,tool,snippet}] }. window says the period searched ({ since: "YYYY-MM-DD" } or { session }), so an answer that counts things names its period. Snippets are cut at 240 characters.
recent hours: default 24; project; source; limit: default 30 { total, bySource: {source: n}, sessions: [{source,id,project,title,startedAt,updatedAt}] }
session-digest session (required): id or prefix; from, to: event range; focus: keep only replies holding this word (every prompt stays); reply: characters kept per reply, default 500 { session: {source,id,project,title,startedAt,updatedAt}, events, prompts: [{i,ts,text}] (text cut at 800), replies: [{i,text}], tools: {name: {calls, failed}} }. More than 40 replies become the first 10, { skipped: n } and the last 20.
session-tools session (required); tool: only tools whose name holds this text; failedOnly: default false; max: default 60 { session, source, counts: {tool: {calls, failed}}, usage, calls: [{i, tool, input, ok, error?}], more }. ok is null when no result was found. input is cut at 200 characters.
session-changes session (required) { session, source, files: [{path, edits, tools, firstI, lastI}], shellWrites: [{i, text}] }. Files come from edit-style tool calls (names starting edit, write, multiedit, notebookedit, apply_patch, create, str_replace, insert, write_file, replace, patch) and from *** Update File: lines of patches. shellWrites (at most 20) are shell commands that look like writes.

find-sessions with any: true skips the search for all words in one event. With one word it therefore returns no sessions; with two words it searches each word alone; with three or more it searches the two longest words together first.

Differences between the code and the API files

The API files are what the investigator reads, so a function that is missing from one is a function the investigator does not know about. Today:

  • domains/code/api.d.ts does not declare omit, sumBy, since or minutes.
  • domains/sessions/api.d.ts does not declare omit or minutes.
  • scripts.draft is declared as returning { name, file }; it also returns note.

Related: Write a domain, Domains, The ask tool.