agentel 0.2.5 → 0.2.8

package/docs/history-source-handling.md

@@ -77,6 +77,13 @@ without a specific archived model group as `claude-unknown`, because the model
 family is still known. Favorite-model stats still use known archived model
 metadata.
 
+SDK source types (`codex-sdk-history` and `claude-sdk-history`) are excluded from
+the primary stats totals, daily activity, streaks, folder rankings, and
+provider/model/company charts by default. The stats payload still exposes their
+own SDK aggregate fields plus `split_stats.sdk`, and the web view renders an SDK
+jobs card and heatmap. This keeps high-volume batch automation searchable and
+auditable without letting it swamp interactive usage stats.
+
 Cursor sessions that still lack provider-reported usage get a separate
 `estimatedUsage` metadata field instead of synthetic `usage`. The estimate uses
 empirical per-assistant-turn Cursor rates by model family, with visible
@@ -88,15 +95,20 @@ split as non-assistant input, assistant output, and Claude thinking output, not
 reconstructed billing context windows.
 
 ```sh
-agentlog update --yes --since all
+agentlog update --yes
 ```
 
 `agentlog update` preserves config preferences, redaction settings, web account
-labels, source histories, and recall integrations. It removes derived local
-archive/import/index state and reimports configured local sources. Manual web
-exports still need to be imported again from the original export file when those
-archives need to be rebuilt. `agentlog reset` is the heavier path: it removes
-agentlog state and archive objects, including config, while still leaving source
+labels, manually imported ChatGPT/Claude.ai archive objects, source histories,
+and recall integrations. It removes derived local agent archive/import/index
+state and reimports configured local sources. The default rebuild window is
+`imports.updateSince`, saved from the initial backfill or explicit all-source
+imports, falling back to `all` for legacy configs. The watcher's rolling
+`imports.defaultSinceDays` is not used by `agentlog update`; `--since` still
+overrides it for one run. Manual web exports only need to be
+imported again from the original export file when those chat archives themselves
+need to be rebuilt. `agentlog reset` is the heavier path: it removes agentlog
+state and archive objects, including config, while still leaving source
 application histories such as Cursor, Codex, Claude, Gemini, or Devin logs
 untouched.
 
@@ -130,7 +142,7 @@ agentlog does not blindly copy entire source directories.
 ## Canonical Events
 
 `events.jsonl` is the provider-independent archive/search substrate. It uses
-schema version `agentlog.events.v1` and these event kinds:
+schema version `agentlog.events.v2` and these event kinds:
 
 - `session.started`
 - `prompt.submitted`
@@ -150,9 +162,14 @@ events add viewer-facing display metadata:
 - `metadata.toolCalls[]`: `id`, `name`, `displayName`, `category`, `title`,
   `status`, `argument`, `rawInputSummary`, `inputPreview`, `target`, `icon`,
   `categoryLabel`, and `provider`.
-- `metadata.toolResult`: `provider`, `kind`, `title`, `summary`, `output`,
-  `lineCount`, `collapsed`, `category`, `categoryLabel`, `icon`, and optional
-  `status`.
+- `metadata.toolResult`: `id`, `name`, `provider`, `kind`, `title`, `summary`,
+  `output`, `lineCount`, `collapsed`, `category`, `categoryLabel`, `icon`, and
+  optional `status`.
+
+`tool.completed.parentEventId` links to the matching `tool.called` event when a
+provider exposes stable ids or matching tool names. When those are absent,
+canonical event derivation falls back to the next unmatched tool call so streams
+such as Devin CLI still preserve the call/result relationship.
 
 The viewer reads canonical events or normalized metadata first. Text patterns
 such as `Grep(...)` are legacy fallback only.
@@ -183,35 +200,36 @@ package-prefixed scheme.
 
 | Source type | Version |
 | --- | --- |
-| `codex-cli-history` | `0.2.5.0` |
-| `codex-desktop-history` | `0.2.5.0` |
-| `cli-history` | `0.2.5.0` |
-| `claude-sdk-history` | `0.2.5.0` |
-| `claude-code-desktop-metadata` | `0.2.5.0` |
-| `claude-workspace-desktop` | `0.2.5.0` |
-| `cursor-workspace-sqlite` | `0.2.5.0` |
-| `cursor-global-sqlite` | `0.2.5.0` |
-| `cursor-raw-sqlite-salvage` | `0.2.5.0` |
-| `cursor-agent-transcripts` | `0.2.5.0` |
-| `devin-cli-history` | `0.2.5.0` |
-| `gemini-cli-history` | `0.2.5.0` |
-| `cline-task-history` | `0.2.5.0` |
-| `opencode-cli-history` | `0.2.5.0` |
-| `opencode-cli-sqlite-history` | `0.2.5.0` |
-| `opencode-desktop-history` | `0.2.5.0` |
-| `opencode-desktop-sqlite-history` | `0.2.5.0` |
-| `opencode-web-sqlite-history` | `0.2.5.0` |
-| `opencode-history` | `0.2.5.0` |
-| `opencode-sqlite-history` | `0.2.5.0` |
-| `aider-chat-history` | `0.2.5.0` |
-| `antigravity-history` | `0.2.5.0` |
-| `antigravity-trajectory-summary` | `0.2.5.0` |
-| `windsurf-trajectory-export` | `0.2.5.0` |
-| `web-chat-export` | `0.2.5.0` |
-| `chatgpt-export` | `0.2.5.0` |
-| `claude-web-export` | `0.2.5.0` |
-| `claude-web-memory` | `0.2.5.0` |
-| `import` | `0.2.5.0` |
+| `codex-cli-history` | `0.2.8.0` |
+| `codex-desktop-history` | `0.2.8.0` |
+| `codex-sdk-history` | `0.2.8.0` |
+| `cli-history` | `0.2.8.0` |
+| `claude-sdk-history` | `0.2.8.0` |
+| `claude-code-desktop-metadata` | `0.2.8.0` |
+| `claude-workspace-desktop` | `0.2.8.0` |
+| `cursor-workspace-sqlite` | `0.2.8.0` |
+| `cursor-global-sqlite` | `0.2.8.0` |
+| `cursor-raw-sqlite-salvage` | `0.2.8.0` |
+| `cursor-agent-transcripts` | `0.2.8.0` |
+| `devin-cli-history` | `0.2.8.0` |
+| `gemini-cli-history` | `0.2.8.0` |
+| `cline-task-history` | `0.2.8.0` |
+| `opencode-cli-history` | `0.2.8.0` |
+| `opencode-cli-sqlite-history` | `0.2.8.0` |
+| `opencode-desktop-history` | `0.2.8.0` |
+| `opencode-desktop-sqlite-history` | `0.2.8.0` |
+| `opencode-web-sqlite-history` | `0.2.8.0` |
+| `opencode-history` | `0.2.8.0` |
+| `opencode-sqlite-history` | `0.2.8.0` |
+| `aider-chat-history` | `0.2.8.0` |
+| `antigravity-history` | `0.2.8.0` |
+| `antigravity-trajectory-summary` | `0.2.8.0` |
+| `windsurf-trajectory-export` | `0.2.8.0` |
+| `web-chat-export` | `0.2.8.0` |
+| `chatgpt-export` | `0.2.8.0` |
+| `claude-web-export` | `0.2.8.0` |
+| `claude-web-memory` | `0.2.8.0` |
+| `import` | `0.2.8.0` |
 
 `cursor-sqlite-history` and `antigravity-brain` are compatibility aliases for
 older labels. Fingerprints include the parser version prefix, so changing the
@@ -249,7 +267,7 @@ real-world query should reliably find a representative archived session.
 
 The setup UI, import defaults, and history source filters use this grouped order:
 
-1. OpenAI: Codex CLI, Codex Desktop, ChatGPT
+1. OpenAI: Codex CLI, Codex Desktop, Codex SDK jobs, ChatGPT
 2. Anthropic: Claude Code CLI, Claude Code Desktop, Claude Workspace,
    Claude.ai, Claude SDK jobs
 3. Google: Gemini CLI, Antigravity
@@ -260,10 +278,10 @@ The setup UI, import defaults, and history source filters use this grouped order
 `src/sources.js`: `codex-cli`, `codex-desktop`, `claude`,
 `claude-code-desktop`, `claude-workspace`, `gemini-cli`, `antigravity`,
 `devin-cli`, `cursor`, `cline`, `opencode-cli`, `opencode-desktop`,
-`opencode-web`, `aider`. Claude SDK jobs are
-intentionally opt-in. Windsurf local cache scanning is disabled for now because
-current Cascade transcripts are encrypted binary stores, but downloaded
-trajectory Markdown exports are importable with an explicit path.
+`opencode-web`, `aider`. Codex SDK jobs and Claude SDK jobs are intentionally
+opt-in. Windsurf local cache scanning is disabled for now because current
+Cascade transcripts are encrypted binary stores, but downloaded trajectory
+Markdown exports are importable with an explicit path.
 
 The background watcher polls the watcher source list selected near the end of
 `agentlog init`. New configs still support `imports.autoDiscoverSources=true`,
@@ -327,6 +345,7 @@ stable local command for the archived source.
 | --- | --- | --- |
 | Codex CLI | `codex resume <session-id>` | Uses the Codex thread id from `~/.codex/state_5.sqlite`. |
 | Codex Desktop | `codex resume <session-id>` | Uses the same Codex thread id. Codex decides whether the resumed session opens in the terminal flow. |
+| Codex SDK jobs | No interactive resume command. | These are Codex `exec`/SDK-style batch runs. |
 | Claude Code CLI | `claude -r <session-id>` | Uses the Claude Code JSONL session id. |
 | Devin CLI | `devin -r <session-id>` | agentlog archives these as `devin-<session-id>` and strips that prefix for the resume command, for example `devin -r selective-lotus`. |
 | Claude Code Desktop | No stable local resume command known. | Use Claude's own desktop/history surface or `agentlog show <session-id>`. |
@@ -346,29 +365,72 @@ stable local command for the archived source.
 - Import selector: `codex-cli`
 - Provider: `codex`
 - Source type: `codex-cli-history`
-- Primary store: `~/.codex/state_5.sqlite`
+- Primary stores: `~/.codex/state_5.sqlite` and
+  `~/.codex/session_index.jsonl`
 - Session files: rollout paths referenced by the `threads` table, plus
   unindexed `rollout-*.jsonl` files under `sessions` and `archived_sessions`
 - Source split: `threads.source = "cli"`
 - Overrides:
   - `CODEX_STATE_DB` overrides the state database path.
+  - `CODEX_SESSION_INDEX` overrides the session index path.
   - `CODEX_HOME` is used for the fallback sessions root.
 
 The importer reads `id`, `rollout_path`, `created_at`, `updated_at`, `source`,
-`cwd`, and `title` from the Codex state database using `sqlite3`. When the
-database has the newer `stage1_outputs` table, agentlog also reads
+`cwd`, `title`, and available subagent metadata columns from the Codex state
+database using `sqlite3`. It also reads `thread_spawn_edges` when present. It then
+prefers `~/.codex/session_index.jsonl` when a matching `thread_name` entry is
+present, because Codex Desktop can now keep the sidebar title there while
+leaving `threads.title` as the full first prompt. If the index has no title for
+a session, the parser falls back to the rollout `thread_name_updated` event
+when Codex emits one, then to non-prompt-shaped state titles and finally to
+first-user-message inference. When a prompt starts with `$agentlog-recall` and
+then continues with a separate task paragraph, fallback title inference skips
+the recall lookup line and titles the session from the task body. If existing
+Codex archives show long context titles, recall-query titles, or stale first
+prompts instead of the Codex sidebar title, reimport them with
+`agentlog import --source codex-desktop --since all` or
+`agentlog import --source codex-cli --since all`. When the database has the
+newer `stage1_outputs` table, agentlog also reads
 `rollout_summary` and `raw_memory` as supplementary Codex summary documents and
 adds them to the archived transcript. The importer also scans
 `~/.codex/sessions` and `~/.codex/archived_sessions` for `rollout-*.jsonl` and
 `rollout-*.jsonl.zst` files that are not referenced by the state database, so
 older archived rollouts still get backed up.
 
+Codex subagents are stored as ordinary rollout threads whose `threads.source`
+can be a JSON `subagent.thread_spawn` object, with parent/child relationships in
+`thread_spawn_edges` and optional `agent_nickname`, `agent_role`, and
+`agent_path` columns. Agentlog resolves those rows back to the parent's source
+split (`codex-cli-history`, `codex-desktop-history`, or `codex-sdk-history`),
+imports each child as `conversationKind = "codex_subagent"` with
+`parentComposerId` set to the parent thread id, and attaches compact run
+metadata to the parent as `metadata.sessionSummary.codexSubagentRuns`. The web
+viewer renders those runs inline and opens the child transcript in the same
+subagent modal used for Claude Code. Existing Codex archives need a full
+reimport, for example `agentlog import --source codex-desktop --since all`, to
+gain the child-session links.
+
 The rollout JSONL parser captures readable `response_item` reasoning summaries,
 Codex `event_msg` assistant/user messages, task and compaction markers, local
 shell calls, web search calls, custom tool calls such as `apply_patch`, tool
 outputs, and token-count usage deltas. Shell calls that run `apply_patch`
 through a heredoc are promoted to edit tool calls with `patch`, `diff`, and
-target path metadata. The working directory comes from the parsed transcript
+target path metadata. Codex token totals are normalized
+from `event_msg.token_count.info.total_token_usage`: `input_tokens` is split
+into fresh input and `cached_input_tokens`, output tokens are preserved, and
+`reasoning_output_tokens` is stored as a visible sub-count that is already
+included in Codex output totals. When the Codex state database exposes
+`threads.tokens_used`, agentlog stores it as the session-level provider total so
+the stats page can reconcile rollout splits with Codex's own thread counter.
+Because these fields are import-time metadata, changing Codex token semantics
+requires a full reimport, for example:
+
+```bash
+agentlog import --source codex-desktop --since all
+agentlog import --source codex-cli --since all
+```
+
+The working directory comes from the parsed transcript
 first, then the `threads.cwd` column. If neither is available, the session is
 archived under `codex/uncategorized` instead of inheriting the supervisor's
 current directory. Repo attribution is computed from the resolved directory.
@@ -379,35 +441,85 @@ Reading `.zst` sessions requires `zstd` or `unzstd`.
 - Import selector: `codex-desktop`
 - Provider: `codex`
 - Source type: `codex-desktop-history`
-- Primary store: `~/.codex/state_5.sqlite`
+- Primary stores: `~/.codex/state_5.sqlite` and
+  `~/.codex/session_index.jsonl`
 - Session files: rollout paths referenced by the `threads` table
 - Source split: `threads.source = "vscode"`
 - Overrides: same as Codex CLI
 
-Codex Desktop uses the same state database, summary-document handling, and
-rollout parser as Codex CLI. The only distinction is the `threads.source` value.
-This is why the web source dropdown can split Codex CLI and Codex Desktop even
-though both archive under the same `codex` provider.
+Codex Desktop uses the same state database, session-index title handling,
+summary-document handling, and rollout parser as Codex CLI. The only distinction
+is the `threads.source` value. This is why the web source dropdown can split
+Codex CLI and Codex Desktop even though both archive under the same `codex`
+provider.
+
+## Codex SDK Jobs
+
+- Import selector: `codex-sdk`
+- Provider: `codex`
+- Source type: `codex-sdk-history`
+- Primary store: `~/.codex/state_5.sqlite`
+- Session files: rollout paths referenced by the `threads` table
+- Source split: `threads.source = "exec"`
+- Overrides: same as Codex CLI
+
+Codex SDK jobs use the same rollout parser as Codex CLI/Desktop, but they are
+shown as a separate opt-in source because `codex exec` batch traffic can produce
+hundreds or thousands of short prompt/response sessions. They are useful for
+programmatic jobs such as Siftly bookmark enrichment and Polymarket vote
+labeling, but should not be silently mixed into the default interactive import.
+When imported, these sessions remain searchable, but the stats view keeps them
+in the separate SDK jobs aggregate instead of primary interactive totals.
 
 ## ChatGPT Export
 
-- Import command: `agentlog import chatgpt --file <path> [--scope local|team]`
+- Instructions command: `agentlog import chatgpt`
+- Import command: `agentlog import chatgpt <path> [--scope local|team]`
 - Provider: `chatgpt`
 - Source type: `chatgpt-export`
-- Source file: ChatGPT JSON export or ZIP containing a JSON export
+- Source file: ChatGPT JSON export, OpenAI export ZIP, extracted
+  `OpenAI-export`, or `User Online Activity` folder
 - Default archive scope: `chatgpt`
 
-ChatGPT is not scanned automatically from a desktop app. The user provides an
-official export file. ZIP imports prefer `conversations.json`, then another JSON
-file with `chat` in the name, then the first JSON file in the ZIP.
+ChatGPT is not scanned automatically from a desktop app. In a terminal, the
+import command without a path starts a walkthrough that asks for the export path
+or paths, account username/email, and display name.
+Use `agentlog import chatgpt --instructions` for static Privacy Portal and
+ChatGPT Data Controls instructions. Older ChatGPT exports usually contain a
+single `conversations.json`. Newer OpenAI privacy exports can arrive as
+`OpenAI-export/User Online Activity` with conversation data split across ZIPs or
+folders such as
+`Conversations__<account-hash>-chatgpt-0001-part-0001` and
+`...part-0002`. Import the parent `User Online Activity` folder when possible.
+The walkthrough also accepts each split `Conversations__...chatgpt...part`
+folder one at a time, ending on a blank line, so agentlog sees all split JSON
+files, manifests, `chat.html`, conversation ZIPs, and attached files together. Very large outer
+`OpenAI-export.zip` files should be unzipped first because Node and unzip tooling
+can hit multi-gigabyte file limits.
+
+ChatGPT attachment files are preserved in the shared raw export archive and are
+shown from normalized message metadata in the readable transcript. Fresh imports
+render image/file attachment cards instead of folding `[Attachment: ...]`
+placeholders into message text. Reimport ChatGPT exports after upgrading to
+populate the attachment metadata and viewer URLs.
+File cards are only linked when the exported raw archive actually contains the
+file bytes; ChatGPT privacy exports may list some uploaded PDFs or documents in
+conversation metadata without including the original file. ChatGPT tool calls
+such as `web.run` are normalized into tool-call cards, uploaded-file parsing
+messages are normalized as file tool results, and private-use citation markers
+including file citations render as citation labels instead of unsupported glyph
+boxes.
 
 For OpenAI export mappings, agentlog reads each node message, normalizes
-`author.role`, extracts `content.parts`, and uses `create_time` or `update_time`
-as the timestamp. Web imports are scope-based by default because they generally
-do not have a reliable local working directory. Since official exports do not
-usually include usage, the importer archives estimated per-message
-`metadata.usage` from native message content and marks the resulting session
-usage as estimated.
+`author.role`, extracts `content.parts`, records attachment and asset-pointer
+metadata, and uses `create_time` or `update_time` as the timestamp. Non-chat JSON
+such as `user_settings.json` is available for account metadata but is not counted
+as a conversation. Extensionless binary attachment files are preserved as raw
+files rather than parsed as JSON. Web imports are scope-based by default because
+they generally do not have a reliable local working directory. Since official
+exports do not usually include usage, the importer archives estimated
+per-message `metadata.usage` from native message content and marks the resulting
+session usage as estimated.
 
 ## Claude Code CLI
 
@@ -419,15 +531,60 @@ usage as estimated.
 Claude Code CLI files are discovered under `~/.claude/projects`. Each JSONL file
 is classified before import. A file is treated as an interactive conversation
 when the initial records include `type = "user"` or `type = "assistant"` with a
-`message` object and no `entrypoint = "sdk-cli"`.
+`message` object and no `entrypoint = "sdk-cli"`. Remote Control transcripts
+also use `entrypoint = "sdk-cli"`, but include a deferred tool delta with
+Remote Control tool names such as `RemoteTrigger`, `TaskOutput`, `TaskStop`,
+`PushNotification`, `AskUserQuestion`, task tools, cron tools, or monitor tools;
+those are imported as interactive Claude Code conversations rather than SDK
+jobs.
 
 The Claude-specific JSONL parser extracts session ids, titles, cwd fields,
 message roles, text content, timestamps, assistant thinking summaries,
 `tool_use` calls, `tool_result` outputs, model, request id, stop status, and
-token usage. Tool calls and results are normalized into the shared
+token usage. It also preserves Claude JSONL lineage fields (`uuid`,
+`parentUuid`, `logicalParentUuid`, `leafUuid`, `promptId`,
+`sourceToolAssistantUUID`, `sourceToolUseID`, `parentToolUseID`, `toolUseID`,
+`agentId`, `slug`, `isSidechain`), execution metadata (`entrypoint`,
+`userType`, Claude Code version, git branch, permission mode), attribution skill,
+MCP structured-content metadata, API error metadata, Remote Control
+queue/tool-surface summaries, and richer usage extras such as service tier,
+speed, server-tool usage, and cache creation detail.
+Tool calls and results are normalized into the shared
 `metadata.toolCalls[]`, `metadata.toolResult`, and `metadata.usage` shapes.
 Bash or shell tool calls that invoke `apply_patch` are reclassified as edit
 calls and retain the patch text under `arguments.diff`.
+Tool results are matched back to prior `tool_use` ids when possible so result
+cards inherit the tool name instead of displaying only the raw tool-use id.
+Remote Control lifecycle records are also converted into provider-generated
+system/context messages for queue operations, deferred tool catalog changes,
+MCP instruction updates, skill listings, nested memories, queued commands,
+command permissions, edited text files, date changes, max-turn notices,
+file-history snapshots, hook progress, and stop-hook summaries. These messages
+carry compact metadata and previews rather than copying large attachment bodies;
+the byte-perfect source records remain in the raw archive. Session summaries
+also include Remote Control attachment counts/details, available tool names,
+MCP server names, queue timing/content, agent ids, slugs, API error counts, and
+MCP structured-content counts.
+
+For each Claude Code session with a working directory, agentlog also snapshots
+Claude subagent definitions from the user-level `~/.claude/agents` directory and
+the nearest project `.claude/agents` directory. It parses the Markdown
+frontmatter fields that Claude uses for subagents (`name`, `description`,
+`tools`, and `model`), records the effective project-over-user definition set in
+`metadata.sessionSummary.claudeSubagents`, and preserves the source `.md` files
+in the session raw manifest. The transcript is not padded with full subagent
+instructions; use the raw archive when the complete definition body is needed.
+
+Claude Code subagent run transcripts stored under
+`~/.claude/projects/<project>/<parent-session-id>/subagents/*.jsonl` are also
+attached to the parent session as `metadata.sessionSummary.claudeSubagentRuns`
+and imported as child sessions with `conversationKind = "claude_subagent"` and
+`parentComposerId` set to the parent Claude Code session id. The parent summary
+keeps compact run metadata, prompts, result previews, model names, usage totals,
+and tool counts; the child session carries the full normalized transcript and
+preserves both the JSONL and any sibling `.meta.json` file in raw storage. The
+web viewer renders run summaries inline at their transcript timestamps and links
+to the child session instead of dumping every subagent run at the top.
 
 When the Claude desktop app has a matching
 `~/Library/Application Support/Claude/claude-code-sessions/**/local_*.json`
@@ -436,7 +593,8 @@ record with `cliSessionId`, the CLI importer uses that sidecar's generated
 archive storage. This is the source of Claude's readable auto names such as
 "Fix cursor import paths handling"; the transcript JSONL itself may only contain
 the user prompt ("Can you fix these?"). Without a sidecar title, the importer
-falls back to the first real user prompt. Repo attribution uses sidecar
+uses Claude JSONL `ai-title` events when present, then falls back to the first
+real user prompt. Repo attribution uses sidecar
 `originCwd` when available, otherwise the parsed `cwd`; Claude-created
 `.claude/worktrees/<name>` directories are attributed to their parent project
 when that project still exists, even if the temporary worktree has been deleted.
@@ -468,7 +626,8 @@ sessions. agentlog separates them by scanning the initial JSONL records for
 batch runs can be much higher volume than interactive sessions.
 
 When imported, SDK jobs use the same Claude-specific JSONL parser as Claude Code
-CLI but archive under `claude_sdk`.
+CLI but archive under `claude_sdk`. Stats keep them in the separate SDK jobs
+aggregate instead of primary interactive totals.
 
 ## Claude Code Desktop
 
@@ -520,16 +679,18 @@ uncategorized.
 
 ## Claude.ai Export
 
-- Import command: `agentlog import claude-web --file <path> [--scope local|team]`
+- Instructions command: `agentlog import claude-web`
+- Import command: `agentlog import claude-web <path> [--scope local|team]`
 - Provider: `claude_web`
 - Source types: `claude-web-export`, `claude-web-memory`
 - Source file: Claude.ai JSON export or ZIP containing a JSON export
 - Default archive scope: `claude_web`
 
-Claude.ai is not scanned automatically from the desktop app. The user provides
-an official export file. agentlog reads `chat_messages`, `messages`, or
-`children`, normalizes sender/role fields, extracts text content, and uses
-`created_at`, `updated_at`, or `timestamp`.
+Claude.ai is not scanned automatically from the desktop app. The import command
+without a path prints official export instructions for Claude Settings >
+Privacy. The user then provides the downloaded official export file. agentlog
+reads `chat_messages`, `messages`, or `children`, normalizes sender/role fields,
+extracts text content, and uses `created_at`, `updated_at`, or `timestamp`.
 For official `conversations.json` exports, the top-level conversation `summary`
 is archived as both `sessionSummary.summary` and a supplementary transcript row.
 Assistant messages prefer structured `content[]` parts over the legacy top-level
@@ -555,7 +716,7 @@ are marked `recovered-time-unknown` in history views instead of being displayed
 as if they happened at import time. This keeps project folders from implying
 that account-level conversations were reliably tagged to Claude projects when
 the export did not preserve that relationship. Re-run
-`agentlog import claude-web --file <path>` after importing an export that
+`agentlog import claude-web <path>` after importing an export that
 contains conversation project ids or after Claude web parser semantics change.
 
 Like ChatGPT export imports, Claude.ai imports are scope-based by default because
@@ -821,8 +982,8 @@ per-message timestamp exists, it uses the source file's mtime with stable
 millisecond offsets so imports do not get stamped with the time of import.
 
 Cursor project slugs are decoded back to local paths when possible. For example,
-`Users-bzhou-Documents-GitHub-spring-next` resolves to
-`/Users/bzhou/Documents/GitHub/spring-next` if that directory exists. If no
+`Users-alex-Documents-GitHub-spring-next` resolves to
+`/Users/alex/Documents/GitHub/spring-next` if that directory exists. If no
 working directory can be resolved for a newer transcript, it archives under
 `cursor/uncategorized` instead of assigning the session to the current repo.
 
@@ -905,14 +1066,18 @@ created by Desktop, CLI, and Web clients, so agentlog classifies each SQLite
 session row individually. Desktop sessions are identified by session ids in
 OpenCode Desktop sidecar state such as `ai.opencode.desktop/*.dat`; sub-sessions
 inherit Desktop classification from a Desktop parent. CLI sessions are
-identified by session-level `agent` or `model` metadata. Remaining non-`local`
-shared core rows are labeled as Web sessions. Rows without reliable client
-evidence stay on the legacy `opencode-sqlite-history` source type. The
+identified by session-level `agent` or `model` metadata, or by CLI evidence in
+the sanitized message metadata when session rows omit those fields. Remaining
+non-`local` shared core rows are labeled as Web sessions. Rows without reliable
+client evidence stay on the legacy `opencode-sqlite-history` source type. The
 `session`, `message`, `part`, and `project` tables provide session
 metadata, working directory, user/assistant messages, reasoning text, tool
-calls, tool outputs, model/provider ids, cost, and token usage. Because the
-database is a multi-session source, raw preservation stores it as a shared raw
-source instead of duplicating the same file into every session archive.
+calls, tool outputs, model/provider ids, cost, and token usage. During SQLite
+reads, agentlog removes the bulky `message.data.summary` object before JSON
+transport; canonical transcript text still comes from the `part` table, and raw
+preservation keeps the original database byte-for-byte. Because the database is a
+multi-session source, raw preservation stores it as a shared raw source instead
+of duplicating the same file into every session archive.
 
 agentlog also reads OpenCode's JSON session store directly. Sessions provide the
 archive id and project id; message and part files provide role text, reasoning

package/docs/release.md

@@ -64,5 +64,5 @@ After tagging and pushing the release, sanity-check both public install forms:
 
 ```sh
 npm install -g agentel
-npm install -g brianlzhou/agentlog#v0.2.5
+npm install -g brianlzhou/agentlog#v0.2.8
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentel",
-  "version": "0.2.5",
+  "version": "0.2.8",
   "description": "Local-first archive and recall layer for agent coding sessions.",
   "type": "commonjs",
   "license": "MIT",
@@ -53,5 +53,8 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "npm@11.5.1"
+  "packageManager": "npm@11.5.1",
+  "dependencies": {
+    "better-sqlite3": "^12.9.0"
+  }
 }