Module grok_bot 

Grok Bot (desktop assistant) transcripts: append-only JSONL under agent-transcripts/<agent-uuid>/<agent-uuid>.jsonl.

Distinct from the existing grok harness (Grok CLI / Grok Build at ~/.grok/sessions). Discovery unions agents/<uuid>/profile.json (title = profile name) with agent-transcripts JSONL dirs (including sand-subagent-*). Load prefers JSONL, then non-empty store.db transcript_entries, then the local gateway openAgent when reachable. Grok Bot writes one JSON object per line with no session header:

{"role":"user"|"assistant"|"tool","message":{"content":[…blocks…]}}

Content blocks are Anthropic-shaped (text, tool_use, tool_result). Tool results ride on native role: "tool" records and project onto Role::User in Common. User prompts are often tagged with a message-address prefix such as [t0u]\n; that prefix is stripped when projecting text into Common and is not regenerated on from_common.

send_message frequently duplicates the preceding assistant text. Both the readable text block and the send_message tool call are kept in Common — no deliberate dedupe — so a same-harness round trip can rebuild the native shape.

Tool names shell / read normalize to Claude-canonical Bash / Read (with timeout→timeout_ms, path→file_path); denormalize is the inverse. Other tools (send_message, web_search, web_fetch, …) pass through as Tool::Raw. A toolCallId inside tool input becomes the Common tool-use id and is re-inserted on write.

Continue-into mints a new box-harness agent through the live local gateway (POST /api/createAgent with harness: "box"), seeds store.db transcript_entries from Common, writes agent-transcripts JSONL, and openAgents so the UI shows history. If seeding fails after createAgent, mint best-effort rolls back via POST /api/deleteAgent so half-created bots are not left in the sidebar. A root override to local::write still writes JSONL only (tests / offline). Cloning an existing agent with full blob history is the separate duplicateAgent + DB-restore path documented in docs/formats/grok-bot.md.

Known representational losses through Common:

• address prefixes ([t0u]) on user text;
• per-record timestamps, model, usage, and stop reasons (absent natively);
• shell bookkeeping keys that survive only while the call stays Tool::Raw (parsingResult, simpleCommands, sandbox flags, …);
• thinking / image / artifact blocks (no observed native slots);
• the optional .journal-mode sidecar (ignored; not part of the body).

Structs

Body

Native body: the JSONL records as raw JSON values so unknown keys and unmodeled roles survive same-format round trips.

GrokBot

The Grok Bot harness marker.

GrokBotStore

File-backed access to Grok Bot transcripts and agent profiles.

Functions

agent_profile_from

Resolve createAgent name/description from --metadata and transcript meta.

agents_root

Resolve TXCRIPT_GROK_BOT_AGENTS, then $HOME/agent-data/agents.

common_to_transcript_entries

Project Common messages into the UI ledger shape used by store.db.

mint_with_history

Mint a new Grok Bot agent whose UI transcript matches common.

open_in_ui

Open an existing agent in the Grok Bot UI (no CLI resume binary).

preflight_live_roots

Ensure the live Grok Bot layout exists and is writable before minting.

ui_entries_to_common

Project UI ledger entries (store.db / gateway openAgent) into Common.