agentel 0.2.0 → 0.2.3

package/docs/code-reference.md

@@ -34,7 +34,8 @@ Exports:
   records sorted newest first, including derived raw source archive paths when
   present.
 - `normalizeMessages(messages)`: normalizes raw messages into indexed,
-  timestamped transcript records.
+  timestamped transcript records; `writeSession` adds per-message visible-token
+  estimates before archiving.
 - `objectPathForSession(session, env)`: computes the archive directory for one
   session using repo/scope, provider, and date.
 - `readTranscript(file)`: reads transcript JSONL into message objects.
@@ -118,12 +119,15 @@ Exports:
 
 ## `src/parser-versions.js`
 
-Central semantic parser-version table used by import fingerprints, archive
-metadata, and canonical events.
+Central package-prefixed parser-version table used by import fingerprints,
+archive metadata, and canonical events.
 
 Exports:
 
-- `PARSER_VERSIONS`: source-type to parser-version string map.
+- `PACKAGE_VERSION`: package version prefix used by parser versions.
+- `PARSER_VERSION_SUFFIXES`: source-type to development suffix map.
+- `PARSER_VERSIONS`: source-type to `<package-version>.<suffix>` parser-version
+  string map.
 - `SOURCE_TYPE_ALIASES`: compatibility aliases for older source labels.
 - `canonicalSourceType(sourceType)`: resolves an alias to the canonical source
   type.
@@ -185,17 +189,26 @@ Command handlers:
   discovery, optional imports, and next-step output.
 - `startCommand(env)`: starts the supervisor, detached unless `--foreground`
   already routed to the foreground runner.
+- `watcherCommand(args, flags, env)`: canonical watcher command group for
+  start, stop, status, logs, and login startup.
 - `stopCommand(env)`: stops the supervisor process.
 - `statusCommand(flags, env)`: prints or returns home, storage, supervisor,
   session, index, collector, sync, and recent archive state.
 - `recentArchivedSessions(env, limit)`: returns recently written session
   metadata for status output.
-- `configCommand(args, env)`: handles `config get` and `config set`.
-- `migrateCommand(flags, env)`: updates storage backend configuration.
-- `syncCommand(flags, env)`: runs archive sync with configured or flag-provided
-  remote settings.
-- `autostartCommand(action)`: enables, disables, or reports autostart.
+- `configCommand(args, flags, env)`: handles config summaries, path display,
+  `get`/`set`, the no-import setup flow, and watcher source list updates
+  without rerunning init.
+- `migrateCommand(flags, env)`: compatibility alias for remote sync
+  configuration.
+- `syncCommand(args, flags, env)`: runs normal archive sync or the explicit
+  remote configure, snapshot, replace, or upload flow with configured or
+  flag-provided remote settings.
+- `autostartCommand(action)`: compatibility helper behind
+  `agentlog watcher login`.
 - `resetCommand(flags, env)`: removes agentlog local state and archive objects.
+- `updateCommand(flags, env)`: preserves preferences, removes derived local
+  archive/import state, reimports configured sources, and rebuilds the index.
 - `uninstallCommand(flags, env)`: stops services, removes autostart, and
   optionally removes data.
 - `revealCommand(sessionId, env)`: prints unredacted reveal-cache JSONL.
@@ -203,6 +216,9 @@ Command handlers:
 - `indexCommand(action, env)`: pauses, resumes, rebuilds, or reports the search
   index.
 - `doctorCommand(flags, env)`: runs diagnostics.
+- `integrationsCommand(args, env)`: canonical integration command group for
+  recall surfaces.
+- `mcpCommand(args, flags, env)`: canonical MCP server command group.
 - `importCommand(args, flags, env)`: imports local sources or web export files.
 - `recallCommand(args, env)`: handles recall server/install/show/reindex flows.
 - `showRecallSession(sessionId, env)`: prints a session through the recall path.
@@ -227,7 +243,8 @@ Reset and process helpers:
 - `pidAlive(pid)`: checks whether a process id is alive.
 - `sleep(ms)`: promise-based timeout.
 - `resetTargets(env)`: lists filesystem targets removed by reset.
-- `coalesceTargets(targets)`: removes duplicate/nested reset targets.
+- `updateTargets(env)`: lists derived filesystem targets removed by update.
+- `coalesceTargets(targets)`: removes duplicate/nested filesystem targets.
 - `isSameOrInside(value, parent)`: checks path containment.
 - `assertSafeResetTarget(targetPath)`: prevents reset from deleting unsafe
   filesystem roots.
@@ -236,7 +253,11 @@ Session display and API helpers:
 
 - `readSessionMarkdown(sessionId, env)`: finds a session and returns its
   Markdown, metadata, and transcript.
-- `sessionViewPayload(view)`: builds the web/API payload for one session.
+- `readSessionView(sessionId, env)`: finds a session without reading rendered
+  Markdown, for fast readable-view API loads.
+- `sessionViewPayload(view, env, options)`: builds the web/API payload for one
+  session, optionally omitting Markdown and compacting duplicate tool/event
+  bodies for browser loads.
 - `dedupeTranscriptMessages(messages)`: removes duplicate messages for readable
   view payloads.
 - `normalizedTranscriptContent(value)`: whitespace-normalizes transcript content.
@@ -260,7 +281,8 @@ Session display and API helpers:
 - `parseFilterExpression(filter)`: parses combined filter expressions.
 - `clampLimit(value, fallback)`: bounds list/search limits.
 - `historyTitle(base, filters)`: formats terminal history subtitles.
-- `writeJsonResponse(res, payload, status)`: writes a JSON HTTP response.
+- `writeJsonResponse(res, payload, status, options)`: writes a compact JSON
+  HTTP response unless `options.pretty` is set.
 
 Recall integration helpers:
 
@@ -363,15 +385,25 @@ Embedded history web app functions:
 - `formatWhen(value)`: browser-side timestamp formatting.
 - `renderTree(payload)`: renders the session tree.
 - `renderSearchResults(items)`: renders search result rows.
-- `sessionNode(item, includeExcerpt)`: creates one session button.
+- `sessionNode(item, includeExcerpt)`: creates one session/search-result
+  button; search rows render as title/date plus folder/provider.
+- `searchResultFolderPath(item)`: chooses the visible folder path for a search
+  result row.
+- `compactBrowserPath(value)`: shortens `/Users/<name>` paths in browser UI.
 - `loadMoreNode(group)`: creates a repo/group pagination button.
 - `loadMoreRepo(repoKey, marker)`: loads more sessions for one group.
-- `loadSession(id)`: fetches and renders one session.
-- `setLoadingSession(id)`: shows loading state in the detail pane.
+- `fetchSessionPayload(id)`: fetches one compact session payload with a small
+  ETag-backed browser cache for revisits and live refresh polling.
+- `loadSession(id, options)`: fetches and renders one session; search rows can
+  preserve the current transcript until the new payload is ready.
+- `setLoadingSession(id)`: schedules a delayed loading state in the detail pane.
 - `setEmptySession(message)`: shows empty/error state in the detail pane.
 - `renderSession(payload)`: renders session header, Markdown, messages, and
   copy controls.
-- `renderMessages(messages)`: renders readable transcript messages.
+- `ensureMarkdownLoaded()`: lazily fetches rendered Markdown when source view is
+  opened.
+- `renderMessages(messages)`: renders readable transcript messages in small
+  browser chunks so very large sessions can paint progressively.
 - `messageElement(message)`: creates one readable message row.
 - `copyIconSvg()`: returns the copy icon SVG.
 - `messageCopyButton(content)`: creates per-message copy controls.
@@ -404,6 +436,7 @@ Embedded history web app functions:
 - `copySessionDetails()`: copies session metadata for pasting into agents.
 - `loadTree()`: fetches and renders the tree.
 - `search()`: runs a search and renders results.
+- `scheduleSearch()`: debounces search input for search-as-you-type.
 - `setupCustomSelects()`: wires custom select dropdown behavior.
 - `setSidebarCollapsed(collapsed)`: collapses or expands the tree pane.
 
@@ -423,7 +456,7 @@ Compatibility command for MCP startup.
 Exports:
 
 - `serverCommand(flags, env, deps)`: runs the same MCP stdio server used by
-  `agentlog recall start`.
+  `agentlog mcp serve`.
 
 ## `src/collector.js`
 
@@ -467,7 +500,9 @@ Diagnostic checks for installation, dependencies, config, and source coverage.
 
 Export:
 
-- `runDoctor(env)`: returns checks, warnings, and source coverage details.
+- `runDoctor(env, options)`: returns checks, warnings, parser-version drift,
+  source coverage details, and actionable recommendations. `options.onProgress`
+  receives discovery-style progress events during long scans.
 
 Internal helpers:
 
@@ -564,8 +599,10 @@ Generic parsing helpers:
   summary for tool-call metadata.
 - `normalizeWebConversations(provider, data)`: normalizes web export
   conversations.
-- `chatgptMessages(conversation)`: parses ChatGPT export conversation nodes.
-- `claudeMessages(conversation)`: parses Claude.ai export messages.
+- `chatgptMessages(conversation)`: parses ChatGPT export conversation nodes
+  and attaches provider or estimated message usage.
+- `claudeMessages(conversation)`: parses Claude.ai export messages, separating
+  thinking parts and attaching provider or estimated message usage.
 - `genericConversationMessages(conversation, source)`: fallback web-export
   parser.
 
@@ -753,11 +790,20 @@ Cline helpers:
 
 OpenCode helpers:
 
+- `openCodeDatabaseFiles(env)`: resolves normalized OpenCode `opencode.db`
+  files from data-root defaults and database override env vars.
 - `openCodeStorageRoots(env)`: resolves global and project-scoped OpenCode
   `storage` directories, plus override env vars.
+- `readOpenCodeSqliteSessionsFromDb(dbPath)`: reads the `session`, `message`,
+  `part`, and `project` tables from `opencode.db` and emits
+  `opencode-sqlite-history` sessions.
 - `openCodeSessionFiles(root)`: finds session JSON files.
+- `openCodeMessageSessionIds(root)`: finds message-only OpenCode session
+  directories when session metadata is missing.
 - `parseOpenCodeSessionFile(file, storageRoot)`: normalizes one OpenCode
   session plus its messages, parts, project metadata, and session diff.
+- `parseOpenCodeMessageOnlySession(storageRoot, sessionId)`: reconstructs a
+  best-effort OpenCode session from message/part files without session metadata.
 - `openCodeMessageFiles(storageRoot, sessionId)`: finds message JSON files for
   a session.
 - `openCodePartFiles(storageRoot, messageId)`: finds part JSON files for a
@@ -803,6 +849,8 @@ Devin helpers:
   alternate branches.
 - `devinMessagesFromNode(row)`: parses `chat_message` JSON into agentlog
   messages.
+- `devinUsage(message)`: normalizes Devin `chat_message.metadata.metrics`
+  token counts into agentlog usage metadata.
 - `devinVisibleContent(content, toolCalls)`: keeps visible prose while dropping
   Devin's `none` placeholders for tool-only assistant nodes.
 - `devinIsContextUserMessage(role, content)`: skips injected Devin context.
@@ -835,13 +883,19 @@ Gemini and Antigravity helpers:
 - `parseGeminiCliJsonl(text, options)` and `parseGeminiCliJson(data, options)`:
   normalize Gemini role/parts history, function calls/results, shell/code
   execution parts, native `toolCalls[].result` entries, usage metadata, and
-  checkpoint events.
+  checkpoint events, and derive session titles from Gemini `Update Topic
+  Context` tool-call arguments.
 - `parseGenericJsonHistory(file, source, fallbackTime)`: generic JSON parser.
 - `parseMarkdownChatFile(file, source, fallbackTime)`: Markdown chat parser.
+- `importWindsurfTrajectoryExport(target, options, env)`: imports downloaded
+  Windsurf "Download trajectory" Markdown exports.
+- `readWindsurfTrajectoryExport(target, options)`: reads Windsurf trajectory
+  Markdown files from a user-selected file or folder.
 - `readWindsurfSessions(options)`: disabled experimental helper retained for
   future Windsurf decoder work.
-- `readAntigravitySessions(options, env)`: reads Antigravity Markdown artifacts and
-  counts binary stores.
+- `readAntigravitySessions(options, env)`: reads Antigravity Markdown artifacts,
+  imports partial trajectory summaries from Antigravity global state when
+  artifacts are absent, and counts binary stores.
 - `readMarkdownArtifactSessions({ ... })`: common Markdown artifact reader.
 - `markdownArtifactSession(provider, dir, artifactNames, sourceType, detailKey)`:
   converts one artifact directory into a session.
@@ -914,8 +968,10 @@ Exports:
 - `ensureDir(dir)`: creates one directory recursively.
 - `homeDir(env)`: resolves `AGENTLOG_HOME` or `~/.agentlog`.
 - `paths(env)`: returns all important agentlog paths.
+- `paths(env).ftsIndex`: SQLite FTS5 sidecar used by web search.
 - `readJson(file, fallback)`: reads JSON with fallback for missing files.
-- `writeJson(file, value)`: writes pretty JSON with private file mode.
+- `writeJson(file, value, options)`: writes private JSON files, pretty by
+  default and compact when `options.pretty === false`.
 
 ## `src/redaction.js`
 
@@ -925,13 +981,14 @@ Exports:
 
 - `loadEnvValues(cwd, names, env)`: loads configured env values from process env
   and `.env` files.
-- `loadRedactionConfig(env)`: reads `~/.agentlog/redaction.yaml`.
+- `loadRedactionConfig(env)`: reads opt-in `~/.agentlog/redaction.yaml`;
+  missing config disables redaction.
 - `mergeSummaries(target, source)`: merges redaction count summaries.
 - `parseRedactionYaml(text)`: parses the small supported YAML subset.
-- `redactText(input, options)`: applies built-in, env, high-entropy, and custom
-  redactions.
-- `styleRedactionMarkersForMarkdown(input)`: turns `[REDACTED:...]` markers into
-  styled Markdown HTML.
+- `redactText(input, options)`: when enabled, applies configured built-in, env,
+  high-entropy, and custom redactions.
+- `styleRedactionMarkersForMarkdown(input)`: turns `[REDACTED ...]` markers
+  into styled Markdown HTML, with legacy `[REDACTED:...]` support.
 
 Internal helpers:
 
@@ -973,16 +1030,23 @@ Recall search, history listing, filters, and the event-first keyword index.
 Exports:
 
 - `buildIndex(env)`: reads canonical events when present, falls back to
-  transcripts, chunks searchable text, and writes the search index.
+  transcripts, chunks searchable text, and writes the BM25 JSON index plus the
+  SQLite FTS5 sidecar when `sqlite3` is available.
 - `chunkText(text, maxTokens, overlap)`: chunks long content for indexing.
 - `listHistorySessions(options, env)`: returns filtered archived session rows.
 - `listRecentSessions(limit, options, env)`: returns recent session rows.
-- `loadIndex(env)`: loads or rebuilds the index.
+- `loadIndex(env, options)`: loads or rebuilds the index; `noRebuild` returns
+  `null` for missing/stale/incompatible indexes without parsing obsolete JSON.
+- `readIndexSummary(indexPath)`: reads only the JSON index header fields needed
+  for status displays.
 - `reindexIfNeeded(env)`: rebuilds the index when stale and not paused.
 - `sessionHistoryTime(session)`: returns display-safe session times, including
   hiding Cursor raw-salvage timestamps that were synthesized from SQLite mtimes.
 - `searchPastSessions(query, options, env)`: searches the event index first,
-  then legacy markdown/transcript fallback.
+  then legacy markdown/transcript fallback. Interactive callers can pass
+  `noRebuild`, `skipJsonIndex`, `allowStaleFts`, and `skipMarkdownFallback` to
+  avoid synchronous index rebuilds, large BM25 JSON parses, or full-archive
+  Markdown scans during typing.
 - `tokenize(text)`: lowercases and tokenizes searchable text.
 
 Internal helpers:
@@ -991,16 +1055,27 @@ Internal helpers:
   documents with event ids, event kinds, message indexes, and rendered text.
 - `docsForTranscript(session, messages)`: builds legacy transcript index
   documents when no event file exists.
+- `buildFtsIndex(index, env)`: writes the SQLite FTS5 sidecar from indexed
+  chunks, skipping the optional sidecar when `sqlite3` is unavailable.
+- `ftsIndexAvailable(env, options)`: validates FTS5 sidecar version/freshness
+  without loading the JSON index.
 - `searchMarkdownSessions(query, options, env)`: legacy conversation Markdown
   search with `rg`/JS fallback.
 - `searchIndexedSessions(query, options, env)`: searches the event/transcript
-  JSON index and aggregates hits by session.
+  FTS5 sidecar or JSON index and aggregates hits by session.
+- `searchFtsSessions(query, queryTokens, context, env)`: searches the SQLite
+  FTS5 sidecar with prefix matching and returns session-shaped results.
+- `candidateDocsForQuery(index, queryTokens, phrase)`: reads term postings to
+  narrow scoring to matching index documents.
 - `ripgrepMatches(queryTokens, files)`: runs `rg --json`.
 - `jsLineMatches(queryTokens, files)`: slow in-process line search fallback.
 - `readLineWindow(file, lineNumber, radius)`: reads context around a match.
 - `inferRoleFromMarkdown(file, lineNumber)`: finds nearest message heading.
 - `escapeRegex(value)`: escapes query tokens for regex.
-- `bm25Score(doc, queryTokens, index)`: scores one indexed chunk.
+- `bm25Score(doc, queryTokens, index, docIndex, termFrequencies)`: scores one
+  indexed chunk.
+- `termFrequencyForDoc(doc, token, docIndex, termFrequencies)`: reads query
+  term frequency from postings-backed candidates.
 - `excerpt(text, queryTokens)`: builds a compact result excerpt.
 - `inferCallingRepo(cwd)`: infers repo key from caller cwd.
 - `displayRepoLabel(session)`: chooses repo/scope/path display text.
@@ -1064,6 +1139,8 @@ Exports:
 - `hasRemoteTarget(cfg, env)`: reports whether a remote target is configured.
 - `listLocalArchiveObjects(env, prefix)`: lists local archive objects as remote
   keys with hashes.
+- `listRemoteSnapshots(options, env)`: lists snapshot folders and object counts
+  for the configured/flag remote target.
 - `parseListBucketResult(xml)`: parses S3 ListObjectsV2 XML.
 - `remoteTargetFromFlags(flags, cfg, env, options)`: resolves a remote target
   from flags, config, and env.
@@ -1071,14 +1148,23 @@ Exports:
   snapshot-scoped remote key prefix.
 - `snapshotArchive(options, env)`: uploads a point-in-time copy to the configured
   remote target.
+- `replaceRemoteArchive(options, env)`: explicit remote repair path that deletes
+  the current device namespace and uploads the current local archive.
 - `syncArchive(options, env)`: syncs archive objects to configured/flag target.
 - `syncArchiveIfConfigured(env, options)`: no-ops unless a remote target exists.
+- `wipeRemoteArchive(options, env)`: delete-only remote repair path scoped to
+  this device namespace, one snapshot, all snapshots, the configured prefix, or
+  the entire bucket.
 
 Internal helpers:
 
 - `syncArchiveToS3(target, options, env)`: uploads changed objects to S3/R2.
 - `syncArchiveToDirectory(target, options, env)`: copies changed objects to a
   local/file URL target.
+- `replaceRemoteS3(target, options, env)`: deletes the current device-scoped
+  remote prefix from S3/R2 and then force-uploads local archive objects.
+- `replaceRemoteDirectory(target, options, env)`: removes a file:// device
+  namespace and then recopies local archive objects.
 - `listS3Objects(target, prefix)`: lists existing remote S3 objects.
 - `putS3Object(target, key, body)`: uploads one S3 object.
 - `s3Request(target, request)`: signs and sends one S3-compatible HTTP request.