Workflow · Primary write path

Share a trace

A developer turns a session sitting on their machine into a link anyone in the team can open. One command does the parsing, cleaning, and uploading; a background pass then writes the title and summary that make the trace discoverable later.

Goal, trigger, and result

Goal: publish one agent session under a durable URL. Trigger: an explicit share command, an automatic hook firing while the agent works, or a "follow" mode that keeps uploading as the session grows. What enters: the raw session files of one coding agent, plus the sharer's identity. What leaves: a shareable link; minutes later, a titled, summarized trace in the library. Re-sharing the same session updates the same link — it never creates a duplicate.

The upload, step by step

The command-line tool first works out which session the developer means — from an explicit flag, from hints the agent's own integration left behind, from the project directory, or simply the most recent session for that agent. It then parses the agent's storage format into the tool's flat event stream, refuses to publish an empty session, and scrubs secrets before anything leaves the machine.

sequenceDiagram
  autonumber
  actor Dev as Developer
  participant CLI as Command-line tool
  participant Files as Agent session files
  participant API as Platform API
  participant Meta as Metadata store
  participant Ana as Analytics store

  Dev->>CLI: share (or hook fires)
  CLI->>Files: locate the intended session
  Files-->>CLI: raw session records
  CLI->>CLI: parse into ordered events
  CLI->>CLI: refuse if empty · scrub secrets
  CLI->>API: create or update the trace record
(identity + title, agent, project, git info)
  API->>Meta: insert or patch the trace row
  API->>Ana: mirror the display row
  API-->>CLI: the trace's durable ID
  loop size-capped batches, in order
    CLI->>API: upload a batch of messages with typed parts
    API->>Ana: append the conversation bodies
    API->>Meta: bump the trace's ingest counters
    API-->>CLI: batch acknowledged
  end
  CLI-->>Dev: shareable link (/s/<id>)

Two properties of this path are worth holding onto. Batches go up sequentially and size-capped, so a huge session uploads in ordered chunks and a dropped connection is retried without scrambling the conversation. And every write is idempotent: repeating any step — the record, a batch, the whole share — converges to the same state, which is what makes automatic, hook-driven sharing safe to run constantly in the background.

What happens after the upload goes quiet

The upload does not wait for enrichment. Instead, each batch leaves behind a durable "this trace needs analysis" note, and a background process waits until writes settle before spending an expensive model call. An actively-growing trace is therefore summarized once, at a natural pause, rather than after every batch. See AI analysis and the analysis outbox for the vocabulary.

sequenceDiagram
  autonumber
  participant Meta as Metadata store
  participant Queue as Durable request queue
  participant Worker as Analysis worker
  participant Ana as Analytics store
  participant LLM as Language model

  Note over Meta: ingest counters say "new messages,
never analyzed (or past threshold)"
  Meta->>Queue: leave one coalesced analysis request
with a not-before time
  loop every second
    Queue->>Queue: hand due requests to the worker pool
  end
  Queue->>Worker: run analysis for this trace
  Worker->>Meta: has the trace gone quiet long enough?
  alt still being written to
    Worker->>Queue: defer; re-check later (bounded backoff)
  else quiet
    Worker->>Ana: read the recent conversation highlights
    Worker->>LLM: summarize into title + structured summary
    alt model call succeeds
      LLM-->>Worker: title, summary, steps, keywords
    else model unavailable
      Worker->>Worker: fall back to a deterministic heuristic
    end
    Worker->>Ana: store the analysis (keeps any earlier good result)
    Worker->>Meta: reset the ingest counters, stamp "analyzed"
  end

If the model is down, the trace still gets a usable title from the heuristic fallback — and a later failure never overwrites a previously successful analysis. Nothing in this second diagram blocks the developer; the link from the first diagram works the moment it is printed.

Where it can hurt

The realistic failure modes are all designed for: an unauthenticated CLI is told to log in before anything uploads; oversized single messages are truncated rather than rejected; and a crash mid-share simply means the next share re-sends what is missing. The one delay a user can notice is that the generated title and summary trail the upload by the quiet-period wait.