Files

T

SaladDay 2589384e68 feat(core): add first-class Pi session indexing (#23 )

Pi cannot be read as another linear JSONL stream. Its history is a tree with
a durable leaf, orphan roots, branch summaries, and two compaction forms, so
the active context is something the format states rather than something line
order implies. The adapter keeps those semantics inside itself and projects
the result into the existing canonical tables.

Sessions are keyed by (normalized header cwd, header id) rather than by path,
because Pi's --session-id lookup is project-local: two projects may reuse an
id, while a move or an identical copy is still one session. Discovery covers
both layouts Pi writes and fingerprints each file by mtime, ctime, size and
inode, so a rewrite that preserves mtime is not read as unchanged.

Abandoned branches are preserved rather than dropped. Visibility becomes
three-state -- visible, inactive, hidden -- and helpers return only visible
rows until includeInactive asks for the superseded path, labeling every row
so a caller knows which it holds. Usage counts all three, because an
abandoned call still spent tokens; message_count reports only the visible
transcript.

A committed MIT-licensed oracle transcribed from Pi 0.83.0 pins the context
algorithms, and a fixed-seed differential runs 512 generated sessions against
it on every test run. Schema changes are additive.

2026-08-04 23:33:01 +08:00

2.7 KiB

Raw Permalink Blame History

Obelisk Pitfalls

Use this after a query error, suspicious empty result, over-large output, or unclear helper row shape. For query design, read retrieval-semantics.md first.

Missing Columns And Wrong Aliases

Common wrong guesses:

Summaries: use source and content; do not use summary_type or text.
Tool call name: use tool_calls.name. tool_name is only an alias in SELECT tc.name AS tool_name; tc.tool_name is not a column.
Tool call timestamps: tool_calls has no timestamp. Join messages m ON m.uuid = tc.message_uuid.
Tool result timestamps: tool_results has no timestamp. Join messages m ON m.uuid = tr.message_uuid.
Workflow agent message counts: workflowTree() returns messageCount for agents.

When uncertain, inspect a tiny sample instead of guessing:

const rows = summaries({ limit: 1 });
return rows.length ? Object.keys(rows[0]) : [];

FTS5 Syntax Errors

search(text) uses raw FTS5 MATCH. Hyphenated terms and punctuation can be parsed as syntax.

// tokenized phrase for FTS
search('"workflow script"', { limit: 10 })

For literal punctuation, use SQL LIKE under the same scope:

sql(`
  SELECT m.uuid, s.id AS session_id, s.title, substr(m.text,1,180) AS snippet
  FROM messages m
  JOIN sessions s ON s.id = m.session_id
  WHERE s.project LIKE ?
    AND m.text LIKE ?
    AND COALESCE(m.visibility, 'visible') = 'visible'
  ORDER BY m.timestamp DESC
  LIMIT 10
`, '%quiet-zero%', '%workflow-script%')

Over-Large Runtime JSON

If runtime stdout is large, fix the query instead of reading it in chunks.

Lower LIMIT.
Shorten snippets to 160-240 chars.
Group in SQL/JS and return counts plus sparse examples.
For fileHistory(), filter to Edit/Write before projecting evidence.
For workflowTree(), omit script, result_json, and full agent messages unless explicitly requested.
Use raw(uuid, { offset, limit }) only after identifying one specific message UUID.

Empty Results

An empty array can be the correct answer for exact scopes or sentinels.

When the user asks for a scoped project/file/session or exact term:

run the scoped query;
return [] or compact counts;
say no matching prior result was found;
do not call recent(), all-project summaries(), or thread() as fallback unless the user asks.

Counting From Snippets

If the user asks "how many", "counts", "top N", or "group by", compute it in SQL or in the query script. Do not infer counts from visible snippets.

sql(`
  SELECT tc.name AS tool_name, COUNT(*) AS n
  FROM tool_results tr
  JOIN tool_calls tc ON tc.id = tr.tool_use_id
  WHERE tr.is_error = 1
  GROUP BY tc.name
  ORDER BY n DESC
  LIMIT 10
`)

2.7 KiB Raw Permalink Blame History