agentel 0.2.8 → 0.3.1

package/docs/code-reference.md

@@ -17,6 +17,13 @@ binary.
 
 Runs the recall command surface used by installed skills and slash commands.
 
+### `scripts/postinstall.js`
+
+Runs the install-time onboarding helper for direct installs. It skips CI,
+`npx`/`npm exec`, and indirect dependency installs; when npm provides an
+interactive terminal, it offers `agentlog update` for existing configs and
+`agentlog init` for new installs.
+
 ## `src/archive.js`
 
 Archive storage, transcript normalization, canonical event persistence,
@@ -30,9 +37,13 @@ Exports:
 - `encodeSegment(value)`: URL-encodes an archive path segment.
 - `ensureConversationMarkdown(session, env)`: materializes a missing
   `conversation.md` from an existing transcript JSONL.
-- `listSessions(env)`: reads all archived metadata files and returns session
-  records sorted newest first, including derived raw source archive paths when
-  present.
+- `listSessions(env)`: returns archived session records sorted newest first,
+  using the persisted session-list index when available and rebuilding it from
+  metadata files when missing or invalid.
+- `listSessionsSnapshot(env)`: returns `{ sessions, fingerprint, count }` for
+  list-derived web endpoints and ETags.
+- `rebuildSessionListIndex(env)`: re-derives `agentlog/indexes/sessions` from
+  archived metadata files.
 - `normalizeMessages(messages)`: normalizes raw messages into indexed,
   timestamped transcript records; `writeSession` adds per-message visible-token
   estimates before archiving.
@@ -50,9 +61,10 @@ Exports:
   deterministic fallback session id.
 - `toIso(value)`: converts date-ish values to ISO strings.
 - `walk(dir, visit)`: recursively walks a directory tree.
-- `writeSession(input, env)`: redacts, normalizes, writes, indexes, computes
-  stats metadata (`messageCount`, `userMessageCount`, `usage`, `models`), and
-  copies declared raw source files for one archived session.
+- `writeSession(input, env)`: redacts, normalizes, writes, indexes, stamps the
+  configured device identity into session metadata, computes stats metadata
+  (`messageCount`, `userMessageCount`, `usage`, `models`), and copies declared
+  raw source files for one archived session.
 
 Internal helpers:
 
@@ -99,12 +111,14 @@ low-signal filtering.
 Exports:
 
 - `CANONICAL_EVENT_SCHEMA_VERSION`: current event schema id,
-  `agentlog.events.v2`.
+  `agentlog.events.v5`.
 - `EVENT_KINDS`: constants for `session.started`, `prompt.submitted`,
-  `response.generated`, `tool.called`, and `tool.completed`.
+  `response.generated`, `tool.called`, `tool.completed`, `memory.read`,
+  `memory.write`, and `memory.loaded`.
 - `normalizeSessionEvents(session, messages, options)`: maps transcript
   messages into canonical events and links `tool.completed` events to matching
-  `tool.called` parents.
+  `tool.called` parents. Memory tool completions additionally emit
+  `memory.*` events that the viewer can render as memory activity.
 - `messageToCanonicalEvents(message, session, options)`: maps one message into
   zero or more canonical events.
 - `stableEventId(sessionId, messageIndex, kind, ordinal, content)`: creates a
@@ -208,8 +222,14 @@ Command handlers:
 - `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.
+- `updateCommand(flags, env)`: preserves preferences and unrecoverable local
+  archives, removes derived local archive/import state, reimports configured
+  sources, restores sessions whose original source files are gone, and rebuilds
+  the index.
+- `statsPayload(filters, env, sessionsInput)`: builds normalized stats totals
+  and range-shaped chart series; default web payloads include the current chart
+  window and recent activity, while all-time daily series are requested
+  explicitly.
 - `uninstallCommand(flags, env)`: stops services, removes autostart, and
   optionally removes data.
 - `revealCommand(sessionId, env)`: prints unredacted reveal-cache JSONL.
@@ -289,24 +309,44 @@ Session display and API helpers:
 
 Recall integration helpers:
 
-- `addRecallToAgent(target, env)`: installs MCP config or recall command files
-  for one agent.
+- `addRecallToAgent(target, env)`: installs MCP config plus recall and
+  continue-from command files for one agent.
 - `installRecallSurface(target, env, options)`: installs slash-command/skill
-  recall surfaces.
+  recall and continue-from surfaces.
 - `normalizeRecallTarget(target)`: maps common source/client aliases to recall
   installer targets.
 - `writeTextFile(file, text)`: writes a text file after ensuring its directory.
 - `genericRecallInstructions()`: common recall workflow text for agents.
+- `genericContinueFromInstructions()`: common continue-from workflow text for
+  agents.
 - `claudeRecallCommand()`: generated Claude `/recall` command body.
+- `claudeContinueFromCommand()`: generated Claude `/continue-from` command body.
 - `geminiRecallCommand()`: generated Gemini recall command config.
+- `geminiContinueFromCommand()`: generated Gemini continue-from command config.
 - `antigravityRecallSkill()`: generated Antigravity recall skill body.
+- `antigravityContinueFromSkill()`: generated Antigravity continue-from skill
+  body.
 - `cursorRecallCommand()`: generated Cursor project `/recall` command body.
 - `cursorRecallRule()`: generated Cursor rule that advertises agentlog recall.
+- `cursorContinueFromCommand()`: generated Cursor project `/continue-from`
+  command body.
+- `cursorContinueFromRule()`: generated Cursor rule that advertises agentlog
+  continue-from.
 - `devinRecallSkill()`: generated Devin `/recall` skill body.
+- `devinContinueFromSkill()`: generated Devin `/continue-from` skill body.
 - `opencodeRecallCommand()`: generated OpenCode `/recall` command body.
+- `opencodeContinueFromCommand()`: generated OpenCode `/continue-from` command
+  body.
 - `clineRecallWorkflow()`: generated Cline `/recall.md` workflow body.
+- `clineContinueFromWorkflow()`: generated Cline `/continue-from.md` workflow
+  body.
 - `aiderRecallInstructions()`: generated Aider loadable recall instructions.
+- `aiderContinueFromInstructions()`: generated Aider loadable continue-from
+  instructions.
 - `codexRecallSkill()`: generated Codex skill body.
+- `codexContinueFromSkill()`: generated Codex continue-from skill body.
+- `continueFromSurfaceTemplates()`: returns generated continue-from
+  command/skill templates.
 - `recallArchiveHints()`: shared archive path and filter hints.
 - `commandOnPath(command)`: finds an executable on `PATH`.
 - `shellQuote(value)`: quotes a shell argument.
@@ -482,6 +522,19 @@ Internal helpers:
 - `safeJson(body)`: parses JSON or wraps raw text.
 - `looksLikeJson(body)`: cheaply detects JSON-looking request bodies.
 
+## `src/pricing.js`
+
+Versioned model pricing lookup used by stats spend estimates. Provider-reported
+costs remain authoritative; this module only prices known token splits when no
+actual cost is archived.
+
+Exports:
+
+- `PRICING_SOURCE`: stable label for the bundled pricing table.
+- `PRICING_VERSION`: version stamp emitted in stats payloads.
+- `pricingForSession(provider, model)`: returns per-million-token input,
+  output, cache-read, and cache-write rates for known models.
+
 ## `src/config.js`
 
 Config defaults, persistence, and key access.
@@ -901,14 +954,19 @@ Gemini and Antigravity helpers:
 - `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.
+  Windsurf "Download trajectory" Markdown exports. With `options.claim`, a
+  single Markdown export replaces the matching zero-message Windsurf protobuf
+  repair stub.
 - `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,
-  imports partial trajectory summaries from Antigravity global state when
-  artifacts are absent, and counts binary stores.
+- `readWindsurfSessions(options, env)`: reads local Windsurf Cascade brain
+  artifacts from `.codeium/windsurf/brain`, preserves matching Cascade
+  protobufs as raw files when present, enriches session IDs from Windsurf's ACP
+  metadata cache, and emits binary-only protobuf stores as repair stubs.
+- `readAntigravitySessions(options, env)`: reads Antigravity transcript logs and
+  Markdown artifacts, links `INVOKE_SUBAGENT` child transcripts into
+  `antigravitySubagentRuns`, 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.
@@ -1042,9 +1100,11 @@ 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 BM25 JSON index plus the
-  SQLite FTS5 sidecar when `sqlite3` is available.
+- `buildIndex(env)`: reads canonical events, chunks searchable text, and writes
+  the compatibility BM25 JSON index plus the SQLite FTS5 sidecar. The index is
+  keyed by the session-list fingerprint.
+- `buildIndexSummary(env)`: writes the normal summary JSON index and SQLite FTS5
+  sidecar without retaining all docs/postings in the parent process.
 - `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.
@@ -1052,30 +1112,33 @@ Exports:
   `null` for missing/stale/incompatible indexes without parsing obsolete JSON.
 - `readIndexSummary(indexPath)`: reads only the JSON index header fields needed
   for status displays.
+- `rebuildIndexSummary(env)`: rebuilds the summary/FTS index, usually in a
+  short-lived child process.
 - `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. 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.
+- `searchPastSessions(query, options, env)`: searches the canonical event index.
+  Legacy BM25 JSON search requires `legacyJsonIndex`/`allowJsonIndex`, and
+  legacy markdown/transcript scanning requires `markdownFallback`; interactive
+  callers pass `noRebuild`, `skipJsonIndex`, `allowStaleFts`, and
+  `skipMarkdownFallback` to keep typing paths bounded.
 - `tokenize(text)`: lowercases and tokenizes searchable text.
 
 Internal helpers:
 
 - `docsForEvents(session, events)`: converts canonical events into index
   documents with event ids, event kinds, message indexes, and rendered text.
-- `docsForTranscript(session, messages)`: builds legacy transcript index
-  documents when no event file exists.
+- `docsForTranscript(session, messages)`: builds legacy transcript documents for
+  explicit markdown/transcript recovery paths.
 - `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
-  FTS5 sidecar or JSON index and aggregates hits by session.
+- `searchMarkdownSessions(query, options, env)`: explicit legacy conversation
+  Markdown search with `rg`/JS fallback.
+- `searchIndexedSessions(query, options, env)`: searches the canonical-event
+  FTS5 sidecar, optionally falling back to the legacy JSON index when requested,
+  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
@@ -1128,7 +1191,11 @@ Exports:
   log lines.
 - `stopSupervisor(env)`: sends SIGTERM to the recorded supervisor process.
 - `supervisorStatus(env)`: reports supervisor PID and running state.
-- `tick(env)`: runs one import, reindex, and sync cycle.
+- `tick(env, state)`: runs one import, reindex, and sync cycle.
+- `applyWatchedSourceImportOutcome(sourceState, now)`: rests a watched source
+  until the 15-minute heartbeat after an import.
+- `sourceEligibleForImport(sourceState, pending, now)`: pending filesystem
+  activity bypasses idle/heartbeat scheduling but not error backoff.
 
 Internal helpers:
 
@@ -1136,6 +1203,67 @@ Internal helpers:
 - `isAlive(pid)`: checks whether a PID is alive.
 - `log(message, env)`: appends to supervisor log.
 
+## `src/slack-notify.js`
+
+Slack notify layer (`notify.slack` config block; see
+`docs/agentlog-slack-scope.md`). `writeSession` appends changed sessions to a
+state-dir queue; the supervisor tick drains it in a child process and posts
+one completion summary per session after it goes quiet.
+
+Exports:
+
+- `slackNotifySettings(cfg, env)`: resolved settings with independent
+  `summary` (channel, quietMinutes) and `stream` (channel, batchSeconds)
+  blocks; legacy single-channel configs map onto `summary`. Token falls back
+  to `AGENTLOG_SLACK_BOT_TOKEN`/`SLACK_BOT_TOKEN`, API base URL to
+  `AGENTLOG_SLACK_API_BASE_URL` (test override).
+- `enqueueSlackNotification(session, cfg, env)`: gated hot-path append from
+  `writeSession`; honors the per-repo allowlist.
+- `runSlackNotify(env, options)`: drains the queue into tracked state,
+  streams new events for firehose sessions (one thread per session, event
+  cursor per session, batched per `batchSeconds`), posts summaries for quiet
+  sessions (also closing the firehose thread), and returns
+  `{ posted, streamed, tracked, skipped, errors, nextCheckMs }`. Sessions
+  older than 24h never post (reimport-flood guard); failed posts stay tracked
+  for retry; `options.dryRun` collects messages without posting.
+- `streamMessagesForEvents(events, opts)`: per-turn firehose rendering —
+  each prompt/response becomes its own Slack post under a per-speaker
+  identity: the agent as its model name (`modelDisplayName`) with the
+  company logo as avatar (GitHub org avatar PNGs; Slack's `icon_url` needs a
+  public raster, and the viewer's brand logos are inline SVGs). Needs
+  chat:write.customize; falls back to plain bot posts and remembers via
+  `state.customizeUnsupported`. Whole messages, formatting preserved; tool
+  calls only with `stream.includeTools`. Long in-flight sessions replay only
+  the most recent turns on first attach.
+- Thread lifecycle: going quiet closes the session's thread (the recap, when
+  summaries are on, doubles as the close), keeping the event cursor; a
+  session picked back up later opens a fresh thread marked "(resumed)" and
+  streams only the new turns.
+- `buildCompletionMessage(meta, tracked)`: summary text from session metadata.
+- `buildSlackAppManifest(appName)` / `slackAppCreationUrl(appName)`: app
+  manifest (chat:write only) and the pre-filled api.slack.com creation link
+  used by the `agentlog notify slack setup` wizard.
+- `postSlackMessage(settings, payload)` / `slackAuthTest(settings)`: Slack Web
+  API via built-in fetch.
+- `queuePath(env)` / `statePath(env)`: state-dir file locations.
+
+## `src/source-watch.js`
+
+Filesystem-event layer for the supervisor. Maps each import source to its
+on-disk history roots (mirroring importer path resolution and env overrides
+without loading `src/importers.js`) and watches them with `fs.watch`.
+
+Exports:
+
+- `watchRootsForSource(source, env)`: watch roots
+  (`{ dir, recursive, filter, coalesceMs }`) for a source; empty for sources
+  that stay on polling (for example Aider project folders).
+- `startSourceWatchers(sources, env, onSourceDirty, options)`: dedupes shared
+  roots into one OS watch each, coalesces events per source in a fixed-delay
+  window (3s default, 20s for SQLite-backed stores), retries missing or dead
+  watches every 5 minutes, and reports dirty sources. Returns
+  `{ isWatched, activeWatchCount, refresh, close }`.
+
 ## `src/sync.js`
 
 Remote archive sync to file targets or S3-compatible object storage. Sync is
@@ -1150,8 +1278,8 @@ Exports:
 - `configureRemoteFromFlags(flags, env)`: persists remote sync settings from CLI
   flags.
 - `hasRemoteTarget(cfg, env)`: reports whether a remote target is configured.
-- `listLocalArchiveObjects(env, prefix)`: lists local archive objects as remote
-  keys with hashes.
+- `listLocalArchiveObjects(env, prefix)`: lists canonical local archive objects
+  as remote keys with hashes, excluding derived `indexes/` caches.
 - `listRemoteSnapshots(options, env)`: lists snapshot folders and object counts
   for the configured/flag remote target.
 - `parseListBucketResult(xml)`: parses S3 ListObjectsV2 XML.