MiniMax Code Trajectory Studio
Read-only trajectory inspection for local MiniMax Code sessions. The Plugin reads the runtime's own SQLite projection and never writes to session storage.
Pick the detail level first
| Level | Returns | When |
|---|---|---|
summary (default) |
roles, turn IDs, timings, token usage, tool names and statuses | Any question about duration, cost, turns, failures, structure |
full |
additionally message text, thinking, tool arguments, tool results | Only after the user explicitly asks to see content |
Never widen to full on your own. The user's session content is theirs; ask before returning it.
Tools
trajectory_list— find a session. Returns metadata only, newest first. Filter byagent,kind,parentSessionId, orsinceMs.parentSessionIdreaches the sub-agent sessions a session dispatched, and"root"gives the top-level ones. Every row carriesparentSessionId, so you will often see a parent that has children and then want to look inside them — filter rather than paging the whole machine and picking them out, which on a busy machine is several calls over hundreds of rows to find what one call returns. It composes withagentandkind, so "the explore sub-agents of this session" is one call. An id that matches nothing returns an empty page; a blank or omitted one is no filter at all.agentis an exact, case-sensitive match against the agent names this machine actually used (Exploredoes not match a session stored asexplore) — read theagentslist ontrajectory_list's reply ({name, count}entries) rather than guessing. It is not narrowed by the page's filters, so it is still complete on a reply whosesessionslist is empty — which is what tells you a filter value was wrong rather than that the machine is quiet. Eachcountis how many sessions match that name under this reply's ownincludeArchived, so it is thetotalyou get after filtering on it, not a machine-wide tally. Archived sessions are hidden unless you passincludeArchived: true.sinceMsis a lower bound; pair it withuntilMsfor a range, because "the session from March" is a range and a lower bound alone answers it with everything since March. Both take epoch milliseconds, and the exact shape is on every row:updatedAtMsis the same clock, so read the format off any reply rather than guessing it. To turn a calendar day into the pair, compute local midnight of that day and of the next one and pass them assinceMs/untilMs—untilMsis inclusive, so the day's own sessions are inside the range rather than excluded by an off-by-one at midnight.totalis how many sessions the filter matches, andnextCursoris how to reach the rest. A single page is a slice, not the machine: a busy one holds hundreds of sessions and the page holds- When looking for an older session — "last week's", "the one where I touched the parser" — pass
nextCursorback ascursoruntil it isnullrather than concluding from page one that no such session exists.sinceMscannot help here: it only moves the window forward. Do not page these tools by position. There is nooffsetargument, and the reason is not tidiness: the list is newest-first by the same column the runtime rewrites when it writes to a session, so a walk by row number silently drops any session that moves while you are walking and still reports that it finished. Hand back the cursor verbatim. Every page of one walk describes the same instant,walkPinnedAtMs, sototaland the rows agree; a session written to after page one is newer than that instant, leaves both the rows and the count, and is found by starting the walk again. A cursor belongs to the walk that produced it — the same query and the same filters. Handing one back after changingagent,kind,parentSessionId,sinceMs,untilMsorincludeArchivedreturns page one of the new question with anotesaying so, rather than a page that looks like a continuation and is not. Changinglimitis fine: it decides how much is carried, not which rows match.
- When looking for an older session — "last week's", "the one where I touched the parser" — pass
trajectory_summary— the dshsessionStatsequivalent for one session:turns,steps,llmMs,toolMs,decodeMs,thinkingMs,inputTokens/cacheReadTokens/totalTokens,toolCalls/toolFailures,compactions,subagentTasks,assets, and asourcesbreakdown. OmitsessionIdfor the most recently updated session. A non-zerounreadableRowsmeans these totals describe fewer records thantrajectory_getlists — say so if the two disagree. Checkwarningsbefore readingsubagentTasks,backgroundTasksorassets: those are counts, so a total that could not be computed still arrives as0, and the warning is what separates "none ran" from "not counted".toolMsisnullonly when it is unavailable.errorMessageis present only when the run stopped badly, and it is the reason — the status word alone is not one. A session that failed on its first turn has one message row andturns: 1, so its numbers all read as "it started and did nothing" while the whole story is in this field:ENOSPC: no space left on device, write,Mandatory V2 Agent prompt is missing: …,BYOK provider … upstream error: …,Local runtime restarted before this turn completed.When someone asks why a session failed, read this before reading anything else — it is the same texttrajectory_listandtrajectory_searchpublish on the row, so you never have to page back to the list to find out.objectiveis what the run was actually asked to do, and it is not the title restated. The runtime records it in its own table and it was unreachable from here. On a measured machine the two share almost no vocabulary in 13 of 15 goal-bearing sessions — one is titled 同步本地与远程分支代码 and was asked to 继续深挖当前插件的方方面面可能存在的问题; another is titled 查询项目前后端架构 and was asked to 整理并落地一套更好的动画效果集成方案. A reader who infers the task from the title is wrong two times out of three, with nothing on any reply to say so.turnsFailedOrAbortedis how a session that looks clean admits it is not. A turn that fails at intake writes no message row at all, so neitherturnsnorerrorMessagenorwarningsmoves when one dies: on a measured machine 7 sessions carry 14 such turns and every one of them reads as a finished run with no error.trajectory_ingressis where to look;ingressAvailable: falsemeans this runtime records no intake, and the two counts are thennullrather than0. Absent is the common case (618 of 633 sessions record no goal) and is never the title:goalAvailable: falsemeans this runtime has no such table, which is a different answer again.goalTokensUsed/goalTimeUsedSecondsare what the goal itself cost.assetsandchangedTurnsare different facts and neither stands in for the other.assetscounts files the session delivered or attached;changedTurnscounts its turns that recorded edits. Measured on a machine where 351 sessions carry change records, 329 of them delivered zero assets — soassets: 0is the usual answer for a session that rewrote a repository, and where both exist the two counts differ 19 times out of 22, in both directions. Never readassets: 0as "the session did nothing." CheckchangedTurns; when the question is about files, pick the tool by which of the two is meant.changesAvailable: falsemeans the runtime records no change sets at all, sochangedTurns: 0there means "not recorded", and the warning says so as well.unmatchedTurnsis the third number and it is not awarning: how many of those change sets name a turn no message row carries. Both numbers are correct and they do not have to reconcile withtrajectory_turns— see entry 5. Subtract it before paging byturnId.trajectory_turns— the progress view. One row per turn:turnId,count(records in that turn),llmMs,failureCount(tool calls in that turn that failed),firstMs(when the turn started) and output tokens.firstMsis what makes this a timeline. The rows are in chronological order, so before it existed you could see that turn 40 came after turn 39 and could not say when either happened — dating one turn meant pagingtrajectory_getuntil a record carried a timestamp, which on a large session is paging the whole session. Use it to answer "what happened last", "what did I do on Tuesday", "which turn was after the deploy".nullmeans the source records no time at all (an artifact with no timestamps), which is different from0.failureCountis how you find what went wrong.trajectory_summary'stoolFailuresis a session-wide number with no way to drill into: without the per-turn count, "which turn broke" meant paging the whole session and inspectingtoolCalls[].okon every record — twenty-two pages and 1.4 seconds on a 21992-record session. Page the turns, keep the ones where it is above zero, then read those withtrajectory_get'sturnId. It reconciles exactly: summed over every turn it equalstrajectory_summary'stoolFailures, on the same terms ascount/llmMsbelow. A turn that made no tool calls reads0;nullmeans the source does not record failures at all (the artifact path), which is a different answer from "nothing failed". Reach for this instead of pagingtrajectory_getto work out how a run broke down — that costs one call per thousand records where this costs one call in total.totalis how many turns the session has, so a one-turn page is not mistaken for a one-turn run. Summed over every turn,count/llmMs/outputTokensequal the session'sevents/llmMs/decodeTokensfromtrajectory_summary; bothoutputTokensand its aliasdecodeTokensare on each row so the reconciliation does not trip over a name. Checksource. A session the projection has not indexed yet is folded from its ownmessages.jsonl, and therellmMs/outputTokensarenull— the artifact recorded no duration and no usage, which is not the same as a turn that cost nothing. That path also has notrajectory_summaryto reconcile against, since that tool answerssession_not_indexedfor such a session.trajectory_assets— which files, not how many.trajectory_summaryreportsassets: N; this is the list behind that count —path,name,role,sourceTag,msgId,artifactId— one 2 ms query rather than a thousand event records scanned for paths that are already columns. Most sessions produced none, sototal: 0withavailable: trueis an ordinary answer. Checkavailablebefore reading an empty list:available: falsewith anotemeans this runtime exposes no assets table, or the query failed, so the empty list means "not listed", not "none exist".assetTypeis null for most real rows — do not read a type into a null, and do not infer one from the extension.pathis folded to~.trajectory_changes— what the run actually changed on disk, turn by turn. The runtime records a change set per turn: every file added, modified or deleted, the line counts, and indetailLevel: "full"the unified diff. This is what answers "what did that session do to my code" — the transcript only holds what the agent said it did, which is the shape it intended rather than the shape that landed. Recorded for sessions that edited a repo and absent for the rest, sototal: 0withavailable: trueis ordinary;available: falsewith anotemeans this runtime records no change sets, so the empty list means "not recorded". Files inside the workspace are stored relative to it and come back absolute;pathnarrows to a substring of the resolved path, andpathMatchedNothingsays a filter found nothing rather than leaving you to guess. ReadscratchFileson the turn, ormatchedScratchFilesfor the session: more than half the entries in a real busy turn are temp-dir apply scripts, and a reader who is not told will read an 82-file turn as 82 repository edits.statusandrevertedAtMsare carried through as recorded and carry no signal on any runtime measured so far.diffis capped per file withdiffTruncatedsaying when it was cut.changedTurnscounts change sets, not turns of the transcript, and they do not have to agree. The runtime writes the two tables independently, so a change set can name a turn no message row carries — 307 of 1,417 on a measured machine, 11.8% of every file entry — and on 7 of 351 sessionschangedTurnsis larger than the number of turnstrajectory_turnslists (worst case 165 against 2).unmatchedTurnson either reply is how many of those name a turn the transcript lacks, andturnInTranscripton each row says the same per turn. They are real edits and stay in the list; usechangedTurns - unmatchedTurnsas the number of change sets you can pagetrajectory_getbyturnIdfor. Atrajectory_getby one of the unmatched ids returns no events and says why —sessionTotalcarries the session's own record count, so an emptytotalthere means "that turn is not in the transcript", not "the session is empty".trajectory_ingress— the turns the runtime took in, including the ones the transcript never saw. One row per accepted turn: when it was accepted, in what order, what claimed it (claimSource), how long it sat in the queue (queuedMs), and how it ended (status). Reach for this whenever a session reads as clean but should not. On a measured machine 14 turns that failed or aborted appear in no message row at all, across 7 sessions that every other tool reports with no error, noerrorMessageandwarnings: []— the transcript genuinely does not contain them, so nothing else can surface them.failedOrAbortedis the count that ended badly;missingFromTranscriptis the count the projection does not carry, and the two answer different questions — 13 turns on that machine completed and are equally invisible, soinTranscript: falsealone does not mean "it died". There is no reason field, because the runtime records none: the table has sixteen columns and none says why a turn failed. This tool says that a turn died and when, never why, and areasonhere would be a guess wearing a field name.claimSourceis the only record of who asked: 668 of 2,466 turns on that machine came from a thread goal, and 1,603 carry no claim at all — reported asnull, never attributed to the user. Most sessions record none, sototal: 0withavailable: trueis ordinary;available: falsemeans this runtime cannot tell andfailedOrAbortedisnull, not0.statusnarrows to one recorded status whiletotalstays the session's own count.trajectory_find— find records in one session whose text contains a query. Scoped to a session because that is where it is cheap: the same search across the whole machine measures seconds, while inside one session it is tens of milliseconds. The query is literal —%and_are matched as characters, not wildcards. Every hit carries the record'sindexin the same numberingtrajectory_getpages in, so read the hit withoffset: hit.indexrather than paging to find it;fieldsays whether the text was the message (content), the thinking, or neither (other), and onotherthe excerpt is taken from the tool call too, withmatchedToolCallnaming which half held the needle —argsis what the model wrote,resultis what came back. A shell result usually echoes the command line, so both halves often hold the same term; the argument wins there, because it is the half that says what was being done. The parameter isdetailLevel;fullis what carries message text — there is no other way to ask for it, and the defaultsummaryreturns records withcontentLengthand nocontentat all. Any other value ('nope','FULL',detail,full: true) is ignored and the reply comes back atsummarywith anotesaying so; a guess that is not caught by the note looks exactly like a session that said nothing.snippetcomes only infulldetail, like every other message body, and it is quoted around the match on both sources — not from the start of the record, so on a long message the word you searched for is in it.unindexedCaseMatch: truemeans the session's rows were also folded in JavaScript, because the needle holds a non-ASCII letter with more than one case form (ş/Ş,é/É) and the indexedLIKEfolds ASCII only. It costs far more than an indexed lookup on a big session, and it is not an error — it is the reason a match exists that the index could not see. It is absent otherwise, so its presence is the report. A needle with no case variants (轨迹, plain ASCII) never pays for the scan. A session the indexer has not reached yet is searched in itsmessages.jsonlartifact, and the reply'ssourcesays which store answered.field,snippetandmatchedToolCallmean the same thing there as they do on the projection path, so a hit is not calledcontentmerely for coming off disk — the excerpt and the field describe the same text on either path. On that pathtotalisnullby design — the fold stops at the page boundary rather than paying for a whole-file count — sonextOffset, nottotal, is how you know whether more matches exist. Page until it isnullthere too.trajectory_get— page through records in insert order. Useoffset/limit; narrow withturnIdorrole, and passdetailLevel: 'full'for message text. Nothing else returnscontentorthinking:summarygivescontentLengthand omits both, so a reply you did not askfullfor is not evidence the session contained no words. A value outsidesummary/fullis ignored and the reply carries anotenaming the level actually used. ReadnextOffsetand keep paging when you need the whole session. A long session holds tens of thousands of records, so to read its end — "what happened at the end", "how did it finish" — do not page there:trajectory_summary'seventsequals this tool'stotal, so the last page is one call atoffset: summary.events - limit. That identity only holds unfiltered; under aturnIdfiltertotalis what matched, not the session.roleis the filter to reach for beforefull. Measured on the machine this was written against:assistantholds 112,290 of 116,304 rows anduserholds 2,388 — 2.1%. One session carried 5,272 assistant records and 9 user ones. Asking "what did this conversation actually ask for, and how far did it get" without the filter meant walking all 5,343 and discarding: 27 calls and 24.6 MiB for nine messages, atfulldetail, which is the level you are told not to widen to on your own. The same call withrole: 'user'is one call, 5.5 KiB, 5 ms.role: nullasks for the records carrying no role — a real group of 1,626 on that machine — and is not the same as omitting the argument.totalis always what matched the filter, so a walk that reachesnextOffset: nullhas seen every record of that role and no others. Each record carriesinputKind—human,injected, orunknown, andnullon every non-user role — so you can tell a person's own words from context the harness injected.unknownmeans the runtime did not classify it; do not fold it intoinjected. Each record also carriesfailureCountand atoolCallsarray where each entry hasname,ok,status, the measureddurationMs(null when the runtime recorded no task for that call),taskId,agentName,childSessionId, and — infulldetail —argsandresult.hasOutputsays whether the runtime recorded an output file for that call, sotrajectory_task_outputhas something to read; it is about the recording, not about whether the call succeeded, andtaskIdisnullon any call the runtime did not run as a background task — which is most calls in some sessions and none in others.trajectory_search— full-text search over session ids, titles, agent names, statuses, session kinds, workspace paths, and the per-sessionpurpose. A query is matched as a phrase, case-insensitively, inside one field. SoSpec reviewmatches that title and not a session whose title merely holds both words apart;Documentsmatches aworkspaceDircontaining it even though the reader typed a capital.purposeis why this can be a content search at all. The runtime writes the objective it dispatched a sub-agent with, and the index carries it — so a word from that objective matches a session whose title never mentions it. On a 633-session machine, 439 rows had one and 194 had none: the ones that do not are top-level sessions, and they are matched on their metadata alone. So a query drawn from a sub-agent's brief will find it, and the same query will not find a top-level session that merely discussed the same thing. That is the limit of the index, not a failed search, and the distinction is worth stating when a content query returns nothing. A run's ownobjectiveis searched too, on a channel that is not the index. The runtime's FTS table has no objective column at all, so this is a separate literal scan of the goal table, reported honestly as such:objectivesIndexedsays whether it ran, rows it found carryobjectiveMatched: trueand the matchingobjectivetext, andobjectiveMatchedSessionIdslists them. On a measured machine every goal match was invisible to FTS — five ordinary Chinese queries found 13 goal-matching sessions between them and the index found none of them, 0 of 15 goal-bearing sessions being reachable by a word from their own objective. So a query drawn from what a run was asked finds it even when its title says nothing about it. Objective rows ride on the page but never intotalor the cursor: the walk is an index walk, and a cursor whose meaning depended on which source matched would be unusable. It also works with no FTS5 at all, which is when a machine can least afford to lose the field. These queries are not selective. The index covers exactly the columns people reach for, so an agent name or a common word can still match most of a machine — on 614 sessionsidlematched 587 andmavis187.totalis the match count andnextCursoris the cursor for the rest, so pass it back ascursoruntil it is null before saying how many sessions match. A first page of 200 is a page, not an answer, and withouttotalit was indistinguishable from one. Page this tool by cursor, never by row position — see the same warning ontrajectory_list. CheckftsAvailableandnotebefore concluding anything from an empty result. There are four reasons forsessions: [], and only one of them is "nothing matches":- FTS5 missing from the bundled SQLite (22.13.0–22.18.x, and every 23.x) —
ftsAvailable: falsewith anote. That is "search is off", not "nothing matches". - the query failed —
ftsAvailable: true, anotesaying the search failed, and the result means "not searched". Report the failure; do not present it as an absence of matches. - this build's index does not carry the fields a match needs — a
notesaying so. Nothing was searched, and retrying will not help, because the cause is the schema rather than this call. Say the runtime cannot search, do not report a failure and do not retry. - the query ran and matched nothing — no
note, and only then is an empty list a finding.
- FTS5 missing from the bundled SQLite (22.13.0–22.18.x, and every 23.x) —
trajectory_tasks— background tasks and sub-agent dispatches owned by a session, with status, wall-clock duration, the command or objective, the sub-agent name, and the child session ID. This is the nested view. The list is newest-first and paginated:totalis what the session owns,returnedis what this page carried, andnextOffsetis the cursor for the rest. A single page is the newest slice, not the whole list —trajectory_tasks.failedand.subagentscount only the records this reply carried. ChecktasksAvailablebefore readingtotal: 0.truemeans this session dispatched nothing;falsemeans this installation has no task table at all and the question was never answered — a projection without one is not unusual on older runtimes, and the two answers look identical otherwise.warningson this reply carries anything the store said while answering, includingtask_count_failed, whose whole text is that a0means "not counted".trajectory_task_output— the tail of one task's captured output (bounded,maxBytesdefaults to 16384). Use it to explain a failure without opening the session directory by hand.available: falsewith an emptytextis a successful answer meaning no output was captured — not an error.bytesis the size of the file on disk, not of what came back — so on a truncated read it is far larger than thetextyou hold, and the amount you hold ismin(bytes, maxBytes). Do not read a longbytesbeside a shorttextas a contradiction.truncated: falsemeans you have the whole file;truncated: truemeans you have its lastmaxBytesbytes and nothing older. The text also passes a credential sweep on the way out, so its length is not the file's length either way — which is whybytesis the only size worth reading. That sweep bounds the text at 64000 characters, and what it drops comes off the front. So the text still ends where the log ends: raisingmaxBytesgives you more of the newest output, never less, and a… [truncated N chars]line at the end is how you know characters were dropped from the older end rather than the newer one.trajectory_studio— start the local web panel and return its URL.trajectory_agent— what a session was configured with: model, tool allowlist and denylist, MCP servers, skills, system prompt and project. It answerspresent: falsefor a session the runtime dispatched without an explicit definition, which is itself worth reporting: most sessions do carry one. Use this instead of opening the panel — the panel draws the same data for a human, but this is one call and stays in the conversation.
A session id that names nothing is an error, not an empty session
Every tool that takes a sessionId refuses an id that matches no session, with
session_not_found:<id>. A typo, or an id remembered wrong, used to come back as the empty result
of a quiet session — trajectory_find reported total: 0 for a session it had never searched.
Never present an empty list from one of these tools as "that session had nothing in it." The two
answers cannot both be true, and the error is how you tell them apart.
Two neighbouring cases that are not that error. A session the projection has not indexed yet is
read from its own messages.jsonl by trajectory_get and trajectory_find, and the reply's
source is jsonl — but trajectory_summary cannot fold timing or tokens out of a file that
never recorded them, so it answers session_not_indexed:<id> rather than a row of nulls.
And omitting sessionId means the most recently updated session, where an empty string is a
value you supplied and is refused rather than treated as "the latest".
A session with no records is not a session that did nothing
There is a third case, and it is the one most likely to be reported wrongly. The projection
stores a session row for every session the runtime has heard of, and message rows only
for the ones it has indexed — two separate decisions. A session can have the first and not the
second, and when it does, every number the tools return is a correct count of nothing:
trajectory_summary gives turns: 0, steps: 0, toolCalls: 0, and trajectory_get and
trajectory_turns give source: 'sqlite', total: 0. Nothing is flagged, because nothing was
read and there is no error to raise.
So check recordsUnavailable before reporting any session as empty, or before believing that
a search found nothing in it. It appears on trajectory_summary, trajectory_get,
trajectory_turns and trajectory_find when the session row exists, the
projection holds no rows for it, and there is no messages.jsonl beside it either. That is a
statement about this machine's records for this session, not about the session's own output —
the work may well have happened and been lost, been pruned, or never indexed. On the machine
this was found on, 18 sessions were in this state, the oldest 128 days old and 9 of them
archived, several titled after work that plainly happened.
trajectory_find is where this bites hardest. A total: 0 from a search is the one answer
that cannot be taken at face value, because "the query is absent from this session" and "no
record was ever searched" produce the identical reply. The tell is that the count does not move
with the query: on the machine above, the matches 22,207 records of a real session and zero of
an unreadable one.
The neighbouring case on the same session has its own field. When the projection has no rows but
the artifact is on disk, trajectory_get and trajectory_turns read it and answer
source: 'jsonl'; trajectory_summary still folds only the projection and so reports zeroes,
marked recordsInArtifact: true. That is not a contradiction to be resolved but a limit to
be stated: read the records with trajectory_get, and do not expect timings or token totals,
because an artifact never recorded them. Both fields are absent when records were read normally.
Every list can be partial — read the completeness fields
These tools are bounded on purpose: a reply that quietly dropped records would describe an incomplete read as a complete one. Each record list therefore carries fields saying what it left out, and an answer that ignores them can be confidently wrong:
| Field | On | Means |
|---|---|---|
truncated / omitted |
every list | records were dropped from this reply; omitted counts them |
nextOffset |
trajectory_get, trajectory_find, trajectory_turns, trajectory_tasks, trajectory_assets, trajectory_changes |
the cursor for the rest; null means you have them all |
nextCursor |
trajectory_list, trajectory_search |
the cursor for the rest, passed back as cursor; null means you have them all. It belongs to the walk that produced it — pass it back with the same query and filters, or a note says the walk restarted |
note |
every tool | something in the call did not do what you asked. Read it before quoting numbers: a paging argument the tool does not take (cursor given to one of the five that page by offset, or offset to trajectory_list/trajectory_search) is ignored, so that reply is the first page however the argument read. A note can carry two facts — this one and the level actually used — and they are joined with ;, so both must be read |
walkPinnedAtMs |
trajectory_list, trajectory_search |
the instant every page of one walk describes, so total and the rows agree. A session written to after page one is newer than it and appears in neither — start the walk again to see it |
total |
trajectory_list, trajectory_search, trajectory_turns, trajectory_assets, trajectory_changes |
how many the query or filter matches, independent of the page — compare against what you have paged through before concluding one does not exist. On trajectory_changes it stays the session's own change-set count even under a path filter, so the narrowing stays visible |
pageBytesTruncated |
trajectory_get |
the read stopped early on the byte budget — nothing was omitted from what was read |
sessionTotal |
trajectory_get |
only when a filter matched nothing — the session's own record count, so an empty total means "your filter is wrong", not "the session is empty" |
droppedOversized / malformedLines |
trajectory_get |
records that exist on disk but could not be delivered |
taskIndexTruncated |
trajectory_get |
the session owns more tasks than the index holds; older tool calls carry no timing |
ftsAvailable |
trajectory_search |
whether search can run at all |
objective, goalAvailable, goalStatus, goalTokensUsed, goalTimeUsedSeconds |
trajectory_summary |
what the run was asked to do, which is not the title — they share almost no vocabulary in 13 of 15 real pairs. Absent means no goal was recorded (the common case), never the title; goalAvailable: false means this runtime records none |
objectivesIndexed, objectiveMatched, objectiveMatchedSessionIds |
trajectory_search |
whether the recorded objectives were searched, which rows they reached, and which field a row matched on. The runtime's index carries no objective column, so this is a separate literal scan — the only way to find a run by what it was asked rather than what it is called |
recordsUnavailable |
trajectory_summary, trajectory_get, trajectory_turns, trajectory_find |
the session exists and its records are not readable anywhere — so every 0 in that reply counts nothing, and must not be reported as what the session did |
recordsInArtifact |
trajectory_summary |
the projection had no rows but messages.jsonl does; the fold saw neither, so read the records with trajectory_get and expect no timings |
warnings / warningsDropped |
trajectory_list |
reads that failed while building this answer — a <what>_failed: prefix and a note that a 0 in the same answer means "not counted", not "none" |
warnings |
trajectory_summary |
an aggregate that could not be computed, so its 0 is not a finding |
turnsFailedOrAborted / turnsMissingFromTranscript / ingressAvailable |
trajectory_summary |
accepted turns that ended badly, and accepted turns the transcript does not carry. null when the runtime records no intake — never 0, which is the clean bill of health these exist to withhold. On a measured machine 14 dead turns sit in 7 sessions that report no error and no warnings |
statusCounts / claimCounts / inTranscript / queuedMs / claimSource |
trajectory_ingress |
how the accepted turns ended, what claimed each one, whether the transcript carries it, and how long it waited. claimSource: null is an absent answer, not "the user"; inTranscript: false is not "it died" — 13 completed turns are equally invisible |
unmatchedTurns / turnInTranscript |
trajectory_summary, trajectory_changes |
how many of the session's change sets name a turn the transcript does not carry, and the same fact per row. changedTurns counts change sets and trajectory_turns counts the turns its records name; the runtime writes the two independently, so on a measured machine changedTurns exceeds the turn total on 7 of 351 sessions. Both numbers are correct, the change sets behind this one are real edits, and it is deliberately not a warnings entry. Subtract it before paging trajectory_get by turnId |
When one of these is set, say the answer is partial before giving the numbers. If the user needs
the whole session, page until the tool's cursor is null.
When a tool fails
A failed tool returns isError: true with a short code as its text. These are the ones you will
meet, and what each actually means:
| Code | Means |
|---|---|
unknown_session_id |
you passed an empty session id — fill the variable, do not retry empty |
invalid_session_id |
the session id was not a string |
session_not_found:<id> |
no session with that id exists at all; re-read trajectory_list, it may have been mistyped or archived |
session_not_indexed:<id> |
the session exists but the projection has not reached it yet, so its records are only in messages.jsonl — trajectory_get and trajectory_find still read it, but there are no timing or token totals to fold. Retry later rather than reporting the session as missing |
no_sessions_available |
the projection holds no sessions at all — a data-source problem, not a bad query |
unknown_tool:<name> |
you called a tool that does not exist; the thirteen above are the whole set |
studio_unavailable |
the panel could not start; the other twelve tools still work |
invalid_task_id |
the task id does not have the expected shape |
None of these mean "the session had no activity". That is a different claim, and trajectory_get's
source field is what tells the two apart.
Answering common questions
- "How long did this session take?" →
trajectory_summary, then reportllmMs,toolMs,decodeMs, andsteps. Say thatllmMs + toolMsis the machine time, not wall-clock elapsed. - "Why is it slow?" → compare
llmMsagainsttoolMs; if tools dominate, calltrajectory_tasks. That list is newest-first and paginated, so one page is a slice and not a ranking: before you call anything "the slowest", page onnextOffsetuntil it isnull(or say plainly that you are reporting the slowest of the newestreturnedoftotal). - "Why did this task fail?" →
trajectory_tasksto find the failed row, thentrajectory_task_outputfor its captured output. - "What tools ran / what failed?" →
trajectory_get(summary) and readtoolCalls[].nameplustoolCalls[].ok;ok !== truemeans the call did not succeed. A non-zero exit is not always a real failure —grepexits 1 on "no matches". Before reporting a failure, check the result text infulldetail for aTraceback,[stderr], oris_error: true; only those are hard failures. A call can also carryok: truewhile its output contains a Traceback, so read the text, not just the status. - "What did the sub-agents do?" →
trajectory_tasks, then filterkind === 'subagent'; each row carriesagentName,description, andchildSessionId. Pass that child ID back intotrajectory_summaryortrajectory_getto inspect the sub-agent's own trajectory. - "How was this session configured?" →
trajectory_agent. It returns the model, tool allowlist and denylist, MCP servers, skills, system prompt and project — the same data the Studio panel draws in itsAgent 与能力panel, in one call and without sending the user to a browser. A session dispatched without an explicit definition answerspresent: false, which is a real finding rather than a missing read; offer the panel only when the user wants to browse rather than to know. - "Which files did this session deliver / hand back?" →
trajectory_assets. Delivered, not edited — for "what did it change" the answer istrajectory_changes, andtrajectory_summaryreports the two counts separately for exactly this reason.trajectory_summary.assetsis the count and this is the list. Only a session that delivered or attached a file has any, sototal: 0is the usual answer and a short list is normal; checkavailablebefore reporting "nothing was produced" from an empty list.pathi
…(truncated)